@piagent/platform 1.37.1 → 1.38.2

package/packages/piagent-webui/gateway/gateway-protocol-service.ts

@@ -1,3 +1,5 @@
+import type { TerminalStreamPort } from "../server/terminal-websocket-stream.ts";
+import { parseTerminalCommand } from "../server/terminal-command.ts";
 import type { PiagentGatewayCapabilityHandshakeV1 } from "../contracts/generated/gateway-capabilities-v1.ts";
 import type { Catalog, SessionDetail } from "../contracts/generated/session-catalog-v1.ts";
 import type { GatewayProtocolHandler, GatewayRequest } from "../server/gateway-websocket.ts";
@@ -13,19 +15,24 @@ export class GatewayProtocolFailure extends Error {
 
 export class GatewayProtocolService implements GatewayProtocolHandler {
   readonly events: GatewayEventStore;
+  readonly terminalEvents?: TerminalStreamPort;
   readonly #capabilities: () => PiagentGatewayCapabilityHandshakeV1;
   readonly #catalog: () => Promise<Catalog>;
+  readonly #terminals?: { state(sessionRef: string): Promise<unknown>; execute(command: unknown): Promise<unknown> };
   readonly #command?: { execute(command: unknown): Promise<unknown> };
 
   constructor(options: {
     capabilities(): PiagentGatewayCapabilityHandshakeV1;
     catalog(): Promise<Catalog>;
     events?: GatewayEventStore;
+    terminalEvents?: TerminalStreamPort;
     command?: { execute(command: unknown): Promise<unknown> };
+    terminals?: { state(sessionRef: string): Promise<unknown>; execute(command: unknown): Promise<unknown> };
   }) {
     this.#capabilities = options.capabilities;
     this.#catalog = options.catalog;
     this.#command = options.command;
+    this.#terminals = options.terminals; this.terminalEvents = options.terminalEvents;
     this.events = options.events ?? new GatewayEventStore();
   }
 
@@ -38,6 +45,11 @@ export class GatewayProtocolService implements GatewayProtocolHandler {
       try { return await this.#command.execute(request.params.command); }
       catch (error) { throw new GatewayProtocolFailure(error instanceof Error ? error.message : "invalid-session-command"); }
     }
+    if (request.method === "terminals.state" || request.method === "terminals.command") {
+      if (!this.#terminals) throw new GatewayProtocolFailure("terminals-unavailable");
+      return request.method === "terminals.state" ? this.#terminals.state(String(request.params.sessionRef))
+        : this.#terminals.execute(parseTerminalCommand(request.params.command));
+    }
     const catalog = await this.#catalog();
     if (catalog.state !== "ready") throw new GatewayProtocolFailure(catalog.reasonCode ?? "catalog-unavailable", true);
     if (request.method === "sessions.get") {

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -1,3 +1,12 @@
+import { attachTerminalMentions } from "./terminal-mentions.ts";
+import { PersonalTerminalSessions } from "./personal-terminal-sessions.ts";
+import { ManagedTerminalSessions } from "./managed-terminal-sessions.ts";
+import type { ManagedTerminalRuntime } from "./managed-terminal-binding.ts";
+import { terminalRouter } from "./terminal-router.ts";
+import { ManagedSourceRevertSessions, type ManagedSourceRuntime } from "./managed-source-revert-sessions.ts";
+import { SourceRevertSessions } from "./source-revert-sessions.ts";
+import { WorkspaceWriteSessions, type ManagedWorkspaceWriter } from './workspace-write-sessions.ts';
+import { CheckpointSessions, type ManagedCheckpointRuntime } from './checkpoint-sessions.ts';
 import { managedProjection } from './managed-projection.ts';
 import { randomBytes } from "node:crypto";
 import fs from "node:fs";
@@ -100,7 +109,7 @@ export async function startPiagentGateway(options: {
   agentDir?: string;
   staticRoot?: string;
   scopedBrokerRouter?: ScopedBrokerRouter;
-  managed?: { host: any; models: any; runtimeFactory: RuntimeFactory; project: string | null };
+  managed?: { host: any; models: any; runtimeFactory: RuntimeFactory; project: string | null; managedCheckpoint?: (id: string) => ManagedCheckpointRuntime; managedTerminal?: (id: string) => ManagedTerminalRuntime; managedSource?: (id: string) => ManagedSourceRuntime; workspaceWrite?: ManagedWorkspaceWriter; workspaceRead?: (id: string, request: { kind: string; path: string }) => Promise<unknown> };
   // Company sessions relayed into this dashboard (the dashboard entry passes
   // the Agent Watch binding; omitted: none).
   company?: CompanyConnector;
@@ -118,6 +127,7 @@ export async function startPiagentGateway(options: {
   let loopback: Awaited<ReturnType<typeof startLoopbackServer>> | null = null;
   let control: Awaited<ReturnType<typeof startGatewayControlSocket>> | null = null;
   let runtimes: SessionRuntimeSupervisor | null = null;
+  let terminals: PersonalTerminalSessions | ManagedTerminalSessions | null = null;
   let mcpAuth: McpAuthBroker | null = null;
   let attachments: SessionAttachmentRegistry | null = null;
   let relay: CompanyRelay | null = null;
@@ -138,6 +148,7 @@ export async function startPiagentGateway(options: {
       // run once this process is gone.
       try { attachments?.close(); } catch { /* shutdown never fails on cleanup */ }
       await mcpAuth?.close().catch(() => undefined);
+      await terminals?.dispose().catch(() => undefined);
       await runtimes?.close().catch(() => undefined);
       await control?.close().catch(() => undefined);
       settleWait?.();
@@ -187,10 +198,13 @@ export async function startPiagentGateway(options: {
       gatewayInstanceRef, key, leases, listSessions: cachedSessionLister((dir) => host.SessionManager.listAll(dir), path.join(state.agentDir, 'sessions'), Boolean(options.managed)),
       host, agentDir: state.agentDir, packageRoot: options.packageRoot, modelRuntime: inspectionModels, events,
       runtimeFactory: options.managed?.runtimeFactory,
+      closeSessionResources: async sessionRef => { await terminals?.closeSession(sessionRef); },
       sessionDirectory: options.managed ? path.join(state.agentDir, 'sessions') : undefined,
       scopedBrokerRouter: options.scopedBrokerRouter,
       resolveProject: (projectRef) => projects.resolve(projectRef)
     });
+    terminals = options.managed ? new ManagedTerminalSessions({ key, gatewayInstanceRef, managed: true, runtimes,
+      managedTerminal: options.managed.managedTerminal }) : new PersonalTerminalSessions({ key, gatewayInstanceRef, managed: false, runtimes });
     const sessionFacts = (manager: { buildSessionContext(): any; getBranch(): any[] }) => {
       const context = manager.buildSessionContext();
       return { model: context.model ? { provider: String(context.model.provider), modelId: String(context.model.modelId) } : null,
@@ -247,14 +261,18 @@ export async function startPiagentGateway(options: {
       // controller, because it reads sessions through the inspection registry.
       prepareAttachments: (sessionRef, refs, messageRequestId, text) => {
         if (!attachments) throw new Error("session-attachment-unavailable");
-        return attachments.reserveForPrompt(sessionRef, refs, messageRequestId, text);
+        return attachments.reserveForPrompt(sessionRef, refs, messageRequestId, attachTerminalMentions(sessionRef, text, terminals));
       } });
     const runtimeCommands = new RuntimeCommandController({ catalog: readCatalog, runtimes, events });
+    const routedTerminals = terminalRouter(terminals, relay);
     const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true, !!options.managed), catalog: hubCatalog,
-      events, command: relay ? { execute: (command) => relay!.handles(command)
+      events, terminals: routedTerminals, terminalEvents: routedTerminals, command: relay ? { execute: (command) => relay!.handles(command)
         ? relay!.command(command as Record<string, unknown>, async () => (await hubCatalog()).catalogRevision) : commands.execute(command) } : commands });
     const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
-      models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
+      models: inspectionModels, managed: !!options.managed,
+      workspaceRead: options.managed?.workspaceRead ? async (sessionRef, id, kind, path) => {
+        await runtimes!.acquire(sessionRef); return options.managed!.workspaceRead!(id, { kind, path });
+      } : undefined, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
       openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef),
       operationLiveness: (sessionRef) => runtimes!.currentOperation(sessionRef) ? "running" : "idle" });
     // Staged bytes live beside the inspection projection they were checked
@@ -266,7 +284,33 @@ export async function startPiagentGateway(options: {
     updates = new UpdateCenter({ packageRoot: options.packageRoot, piVersion: options.expectedPiVersion, managed: Boolean(options.managed),
       busy: async () => runtimes!.currentOperations().length + (relay ? (await relay.operations()).length : 0) });
     updates.start();
+    const workspaceWrites = new WorkspaceWriteSessions({ root: state.root, key, gatewayInstanceRef, runtimes, managed: !!options.managed,
+      managedWrite: options.managed?.workspaceWrite, changed: sessionRef => events.publish("session.changed", { sessionRef }) });
+    const checkpoints = new CheckpointSessions({ root: state.root, key, gatewayInstanceRef, runtimes, managed: !!options.managed,
+      managedCheckpoint: options.managed?.managedCheckpoint,
+      changed: sessionRef => events.publish("session.changed", { sessionRef }) });
+    const sourceReverts = options.managed ? new ManagedSourceRevertSessions({ root: state.root, key, gatewayInstanceRef, runtimes,
+      managedSource: options.managed.managedSource, changed: sessionRef => events.publish("session.changed", { sessionRef }) }) : new SourceRevertSessions({ root: state.root, key, runtimes, managed: !!options.managed,
+      provider: sessionRef => inspections.provider(sessionRef), changed: sessionRef => events.publish("session.changed", { sessionRef }) });
     loopback = await startLoopbackServer({
+      checkpoints: {
+        state: sessionRef => company(sessionRef) ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/checkpoints`) : checkpoints.state(sessionRef),
+        preview: (sessionRef, target) => company(sessionRef) ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/checkpoints/${encodeURIComponent(target)}`) : checkpoints.preview(sessionRef, target),
+        execute: (sessionRef, command) => company(sessionRef) ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/checkpoints`, command) : checkpoints.execute(sessionRef, command)
+      },
+      sessionSourceRevert: {
+        sources: sessionRef => company(sessionRef) ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/source-review`) : sourceReverts.sources(sessionRef),
+        diff: (sessionRef, fileRef) => company(sessionRef) ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/source-review/${encodeURIComponent(fileRef)}`) : sourceReverts.diff(sessionRef, fileRef),
+        preview: (sessionRef, fileRef, hunkRef) => company(sessionRef)
+          ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/source-reverts/${encodeURIComponent(fileRef)}${hunkRef ? `?hunkRef=${encodeURIComponent(hunkRef)}` : ""}`)
+          : sourceReverts.preview(sessionRef, fileRef, hunkRef),
+        execute: (sessionRef, command) => company(sessionRef)
+          ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/source-reverts`, command) : sourceReverts.execute(sessionRef, command)
+      },
+      workspaceWrite: {
+        state: sessionRef => company(sessionRef) ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/workspace/write`) : workspaceWrites.state(sessionRef),
+        execute: (sessionRef, command) => company(sessionRef) ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/workspace/write`, command) : workspaceWrites.execute(sessionRef, command)
+      },
       staticRoot,
       mode: "gateway",
       readCapabilities: () => capabilities(gatewayInstanceRef, true, !!options.managed),

package/packages/piagent-webui/gateway/managed-gateway.mjs

@@ -1,14 +1,16 @@
 import { managedThinkingLevels, nearestLevel } from '../../piagent-core/managed/capabilities.mjs';
 import { ManagedBrokerClient } from '../../piagent-core/managed/broker-client.mjs';
 import { ManagedSession } from '../../piagent-core/managed/session.mjs';
+import { checkpointsOf } from '../../piagent-core/managed/checkpoints.mjs';
 import { fastAllowed } from '../../piagent-core/managed/fast-mode.mjs';
+import { bypassAllowed } from '../../piagent-core/managed/permission.mjs';
 import { PI_HOST_VERSION } from '../../piagent-core/managed/pi-host.mjs';
 import fs from 'node:fs';
 
 // A company model as the new chat page sees it: the thinking levels its
 // Harness allows, and whether the Harness allows Fast mode (the page shows
 // the Fast switch only then).
-export const managedModelOption=(manifest,models,model)=>({...model,managedThinkingLevels:managedThinkingLevels(manifest,models,model),managedFast:fastAllowed(manifest)});
+export const managedModelOption=(manifest,models,model)=>({...model,managedThinkingLevels:managedThinkingLevels(manifest,models,model),managedFast:fastAllowed(manifest),managedBypass:bypassAllowed(manifest)});
 
 // Only called by the pinned launcher with Watch's non-secret import manifest.
 // Each web session owns its own broker; no personal auth/model/resource loader.
@@ -30,6 +32,7 @@ export async function startManagedGateway({ config, configPath, cwd, agentDir, p
     const host=probe.api,models=probe.modelRuntime;
     const snapshot=models.getAvailableSnapshot.bind(models);
     models.getAvailableSnapshot=()=>snapshot().map(model=>managedModelOption(probe.manifest,models,model));
+    const workspaceRuntimes = new Map();
     const factory=async(info,_instance,manager,initial)=>{
       if(initial?.modelRef && initial.modelRef!==webUiModelRef('agent_watch_managed','agent-watch-auto')) throw Error('managed-personal-switch-requires-new-session');
       const broker=newBroker();
@@ -41,10 +44,34 @@ export async function startManagedGateway({ config, configPath, cwd, agentDir, p
         // changed it: the conversation takes the nearest level the Harness allows now.
         if(initial) runtime.session.setThinkingLevel(nearestLevel(initial.thinkingLevel,managedThinkingLevels(runtime.manifest,runtime.modelRuntime,runtime.session.model)));
         await runtime.session.bindExtensions({mode:'rpc',uiContext:rpcUiContext()});
-        return {session:runtime.session,dispose:()=>runtime.dispose()};
+        workspaceRuntimes.set(info.id, runtime);
+        return {session:runtime.session,dispose:async()=>{ workspaceRuntimes.delete(info.id); await runtime.dispose(); }};
       } catch(error) { if(runtime) await runtime.dispose(); else await broker.dispose(); throw error; }
     };
-    const gateway=await startPiagentGateway({packageRoot,agentDir,expectedPiVersion:PI_HOST_VERSION,managed:{host,models,runtimeFactory:factory,project:registerProject?cwd:null}});
+    const gateway=await startPiagentGateway({packageRoot,agentDir,expectedPiVersion:PI_HOST_VERSION,managed:{host,models,runtimeFactory:factory,project:registerProject?cwd:null,
+      managedCheckpoint: id => {
+        const runtime = workspaceRuntimes.get(id); if (!runtime) throw Error('checkpoint-runtime-unavailable');
+        const boundary = runtime.boundary, checkpoints = checkpointsOf(runtime);
+        const current = () => workspaceRuntimes.get(id) === runtime && runtime.boundary === boundary;
+        const check = () => { if (!current()) throw Error('checkpoint-runtime-replaced'); };
+        return { current, writable: async () => { check(); const state = await boundary.invoke('workspace', { kind: 'write-state' }); check(); return state.writable === true; },
+          port: { list: () => { check(); return checkpoints.list(); }, preview: target => { check(); return checkpoints.preview(target); },
+            restoreTo: (target, expected, guard) => checkpoints.restoreTo(target, expected, () => { check(); guard?.(); }) } };
+      },
+      managedTerminal: id => {
+        const runtime = workspaceRuntimes.get(id); if (!runtime) throw Error('terminal-runtime-unavailable');
+        const boundary = runtime.boundary;
+        return { terminals: boundary.terminals, current: () => workspaceRuntimes.get(id) === runtime && runtime.boundary === boundary };
+      },
+      managedSource: id => {
+        const runtime = workspaceRuntimes.get(id); if (!runtime) throw Error('source-runtime-unavailable');
+        const boundary = runtime.boundary;
+        return { controlRevision: boundary.sourceControlRevision,
+          current: () => workspaceRuntimes.get(id) === runtime && runtime.boundary === boundary,
+          source: (request, binding) => boundary.source(request, binding) };
+      },
+      workspaceWrite: (id, request) => { const runtime = workspaceRuntimes.get(id); if (!runtime) throw Error('workspace-runtime-unavailable'); return runtime.boundary.invoke('workspace', request); },
+      workspaceRead: (id, request) => { const runtime = workspaceRuntimes.get(id); if (!runtime) throw Error('workspace-runtime-unavailable'); return runtime.boundary.invoke('workspace', request); }}});
     return gateway;
   } finally { if(probe) await probe.dispose(); else await probeBroker.dispose(); }
 }

package/packages/piagent-webui/gateway/managed-projection.ts

@@ -30,11 +30,13 @@ export function managedProjection(context: any, entries: any[]) {
   // Helpers the Harness enables (up to four); a conversation recorded before
   // that was known says two.
   const maximum = Number.isInteger(counter?.maximum) && counter.maximum >= 0 && counter.maximum <= 4 ? counter.maximum : 2;
-  // The member's access choice: "trusted-full-access" is Bypass.
-  const permission = last('agent-watch-permission')?.mode === 'trusted-full-access' ? 'trusted-full-access' : 'workspace-write';
+  // The member's access choice; Bypass only while the Harness allows it, else
+  // it applies as Full access (permission.mjs).
+  const chosen = last('agent-watch-permission')?.mode, bypassAllowed = last('agent-watch-bypass')?.allowed === true;
+  const permission = chosen === 'bypass' ? (bypassAllowed ? 'bypass' : 'trusted-full-access') : chosen === 'trusted-full-access' ? 'trusted-full-access' : 'workspace-write';
   // Fast mode, only where the conversation's Harness allows it (fast-mode.mjs).
   const fast = last('agent-watch-fast');
-  return {modelLabel:'agent-watch-auto', managedPermission: permission, ...(fast?.allowed === true ? {managedFast: fast.enabled === true ? 'on' as const : 'off' as const} : {}), managedHelpers:{active:Number.isInteger(counter?.active) && counter.active>=0 && counter.active<=maximum ? counter.active : 0, maximum},
+  return {modelLabel:'agent-watch-auto', managedPermission: permission, ...(bypassAllowed ? {managedBypass: true as const} : {}), ...(fast?.allowed === true ? {managedFast: fast.enabled === true ? 'on' as const : 'off' as const} : {}), managedHelpers:{active:Number.isInteger(counter?.active) && counter.active>=0 && counter.active<=maximum ? counter.active : 0, maximum},
     ...(Array.isArray(capabilities)?{managedThinkingLevels:levels.filter(level=>capabilities.includes(level))}:{}),
     ...(steps ? {managedPlan:{steps}} : {}), ...(process ? {managedProcess:process} : {}), ...(turnEnd ? {managedTurnEnd:turnEnd} : {}), ...(review ? {managedReview:review} : {})};
 }

package/packages/piagent-webui/gateway/managed-source-revert-controller.ts

@@ -0,0 +1,45 @@
+import type { BridgeSnapshot, BridgeRevisions } from "../../piagent-core/runtime/inspection/session-identity.ts";
+import type { SourceRevertProjection, SourceRevertTarget, SourceIndexTransactionResult } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import { SourceRevertController, type SourceRevertEvidenceStore } from "../server/source-revert-controller.ts";
+
+export type ManagedSourceRequest = { kind: "preview"; fileRef: string; hunkRefs: string[] }
+  | { kind: "execute"; target: SourceRevertTarget } | { kind: "sources" } | { kind: "diff"; fileRef: string };
+export type ManagedSourceBinding = {
+  identity: NonNullable<BridgeSnapshot["identity"]>; rawSessionId: string; controlRevision: string;
+  current(): boolean; idle(): boolean;
+};
+export type ManagedSourcePort = (request: ManagedSourceRequest, binding: ManagedSourceBinding) => Promise<unknown>;
+
+// The company Gateway owns receipts and live session checks. Only the worker
+// resolves a preview into filesystem authority; no patch bytes cross this port.
+export function managedSourceRevertController(options: {
+  projectRoot: string; binding: ManagedSourceBinding; snapshot(): BridgeSnapshot;
+  revisions(): Promise<BridgeRevisions>; evidence: SourceRevertEvidenceStore; source: ManagedSourcePort;
+}) {
+  const { binding, source } = options;
+  const preview = async (fileRef: string, hunkRefs: string[]) => {
+    if (!binding.current() || !binding.idle()) throw new Error("source-session-unavailable");
+    const value = await source({ kind: "preview", fileRef, hunkRefs }, binding) as SourceRevertProjection;
+    if (!value || value.version !== "piagent-webui-source-revert-v1"
+      || ["projectRef", "sessionRef", "runtimeInstanceId", "taskId", "taskRunId"].some(key =>
+        value.identity?.[key as keyof typeof value.identity] !== binding.identity[key as keyof typeof binding.identity]))
+      throw new Error("source-preview-binding-mismatch");
+    return value;
+  };
+  const controller = new SourceRevertController<SourceRevertTarget>({ projectRoot: options.projectRoot,
+    allowSessionReverts: true, bridge: { snapshot: options.snapshot }, evidence: options.evidence, revisions: options.revisions,
+    resolve: async (fileRef, hunks) => {
+      const projection = await preview(fileRef, hunks);
+      return { projection, authority: projection.state === "ready" ? projection.target : null };
+    },
+    mutate: async request => {
+      const result = (state: "rejected" | "uncertain", reasonCode: string): SourceIndexTransactionResult => ({ state, reasonCode,
+        beforeIndexPreimage: request.expectedIndexPreimage, beforeWorkspacePreimage: request.expectedWorkspacePreimage,
+        afterIndexPreimage: null, afterWorkspacePreimage: null, executor: "pi-guard", directExecution: false });
+      if (!binding.current() || !binding.idle() || request.expectedControlRevision !== binding.controlRevision)
+        return result("rejected", "source-session-unavailable");
+      try { return await source({ kind: "execute", target: request.authority }, binding) as SourceIndexTransactionResult; }
+      catch { return result("uncertain", "source-boundary-effect-unknown"); }
+    } });
+  return { preview, execute: (command: unknown) => controller.execute(command) };
+}

package/packages/piagent-webui/gateway/managed-source-revert-sessions.ts

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { webUiProjectRef, webUiSessionRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import type { BridgeSnapshot, BridgeRevisions } from "../../piagent-core/runtime/inspection/session-identity.ts";
+import type { SourceChangeViews } from "../../piagent-core/runtime/inspection/source-change-projection.ts";
+import { managedSourceRevertController, type ManagedSourcePort, type ManagedSourceRequest } from "./managed-source-revert-controller.ts";
+import { SourceRevertStore } from "./source-revert-store.ts";
+import { sessionRefForPath } from "./session-catalog.ts";
+import { inspectionRuntimeRef } from "./session-inspection-registry.ts";
+import type { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+
+export type ManagedSourceRuntime = { controlRevision: string; current(): boolean; source: ManagedSourcePort };
+type Options = { root: string; key: Buffer; gatewayInstanceRef: string;
+  runtimes: Pick<SessionRuntimeSupervisor, "listSessions" | "acquire" | "liveSessionManager" | "currentOperation">;
+  managedSource?(id: string): ManagedSourceRuntime; changed(sessionRef: string): void };
+
+export class ManagedSourceRevertSessions {
+  readonly #options: Options; readonly #store: SourceRevertStore;
+  readonly #pending = new Map<string, Promise<unknown>>();
+  constructor(options: Options) { this.#options = options; this.#store = new SourceRevertStore(options.root, options.key); }
+  #serial<T>(sessionRef: string, action: () => Promise<T>): Promise<T> {
+    const run = (this.#pending.get(sessionRef) ?? Promise.resolve()).then(action, action);
+    this.#pending.set(sessionRef, run);
+    void run.finally(() => { if (this.#pending.get(sessionRef) === run) this.#pending.delete(sessionRef); }).catch(() => {});
+    return run;
+  }
+  async #controller(sessionRef: string) {
+    const { runtimes, key, managedSource, gatewayInstanceRef } = this.#options;
+    if (!managedSource) throw new Error("source-company-boundary-required");
+    const matches = (await runtimes.listSessions()).filter(info => sessionRefForPath(key, info.path) === sessionRef);
+    if (matches.length !== 1) throw new Error("source-session-unavailable");
+    const info = matches[0]; await runtimes.acquire(sessionRef);
+    const manager = runtimes.liveSessionManager(sessionRef), runtime = managedSource(info.id);
+    if (!manager || manager.getSessionId() !== info.id || !runtime.current()) throw new Error("source-session-unavailable");
+    const identity = { projectRef: webUiProjectRef(info.cwd), sessionRef: webUiSessionRef(info.id),
+      runtimeInstanceId: inspectionRuntimeRef(gatewayInstanceRef, sessionRef), taskId: null, taskRunId: null, agentOperationId: null, toolCallId: null };
+    const binding = { identity, rawSessionId: info.id, controlRevision: runtime.controlRevision,
+      current: () => runtimes.liveSessionManager(sessionRef) === manager && manager.getSessionId() === info.id && runtime.current(),
+      idle: () => !runtimes.currentOperation(sessionRef) };
+    const commandBinding = { controlRevision: binding.controlRevision,
+      runtimeRevision: `source-runtime.${createHash("sha256").update(JSON.stringify([identity, binding.controlRevision])).digest("hex")}` };
+    const revisions: BridgeRevisions = { ...commandBinding, taskRevision: null, workspaceRevision: null, indexRevision: null,
+      approvalRevision: null, sessionOptionRevision: null, queueRevision: null };
+    const snapshot = (): BridgeSnapshot => ({ state: binding.current() ? "ready" : "replacement-pending", identity, revisions,
+      taskState: "none", liveness: binding.idle() ? "idle" : "running", eventSequence: 0 });
+    const controller = managedSourceRevertController({ projectRoot: info.cwd, binding, snapshot, source: runtime.source,
+      evidence: this.#store.forSession(info.cwd, identity.projectRef, identity.sessionRef), revisions: async () => {
+        const views = await runtime.source({ kind: "sources" }, binding) as SourceChangeViews;
+        return { ...revisions, workspaceRevision: views.workingTree.viewRevision, indexRevision: views.staged.viewRevision };
+      } });
+    return { controller, commandBinding, read: (request: ManagedSourceRequest) => runtime.source(request, binding) };
+  }
+  sources(sessionRef: string) {
+    return this.#serial(sessionRef, async () => {
+      const { read } = await this.#controller(sessionRef);
+      return (await read({ kind: "sources" }) as SourceChangeViews).workingTree;
+    });
+  }
+  diff(sessionRef: string, fileRef: string) {
+    return this.#serial(sessionRef, async () => (await this.#controller(sessionRef)).read({ kind: "diff", fileRef }));
+  }
+  preview(sessionRef: string, fileRef: string, hunkRef: string | null) {
+    return this.#serial(sessionRef, async () => {
+      const { controller, commandBinding } = await this.#controller(sessionRef);
+      return { ...await controller.preview(fileRef, hunkRef ? [hunkRef] : []), commandBinding };
+    });
+  }
+  execute(sessionRef: string, command: unknown) {
+    return this.#serial(sessionRef, async () => {
+      const { controller } = await this.#controller(sessionRef), receipt = await controller.execute(command);
+      if (receipt.phase !== "rejected") this.#options.changed(sessionRef);
+      return receipt;
+    });
+  }
+}

package/packages/piagent-webui/gateway/managed-terminal-binding.ts

@@ -0,0 +1,30 @@
+import { sessionRefForPath } from './session-catalog.ts';
+import type { SessionRuntimeSupervisor } from './session-runtime-supervisor.ts';
+
+export type ManagedTerminalEvent = { kind: 'output'; data: string } | { kind: 'exit'; exitCode: number | null; signal: number | null };
+export type ManagedTerminalHandle = { id: string; input(data: string): Promise<void>;
+  resize(size: { cols: number; rows: number }): Promise<void>; close(): Promise<void> };
+export type ManagedTerminalRuntime = { current(): boolean; terminals: { reasonCode: string | null;
+  open(size: { cols: number; rows: number }, emit: (event: ManagedTerminalEvent) => void): Promise<ManagedTerminalHandle> } };
+export type ManagedTerminalOptions = { key: Buffer; gatewayInstanceRef: string; managed: boolean;
+  runtimes: Pick<SessionRuntimeSupervisor, 'listSessions' | 'acquire' | 'liveSessionManager' | 'ownership'>;
+  managedTerminal?(rawSessionId: string): ManagedTerminalRuntime };
+
+export async function managedTerminalBinding(options: ManagedTerminalOptions, sessionRef: string) {
+  if (!options.managed || !options.managedTerminal) throw Error('terminal-company-boundary-required');
+  const { runtimes } = options;
+  const matches = (await runtimes.listSessions()).filter(info => sessionRefForPath(options.key, info.path) === sessionRef);
+  if (matches.length !== 1) throw Error('terminal-session-unavailable');
+  const info = matches[0]!, lease = await runtimes.acquire(sessionRef), manager = runtimes.liveSessionManager(sessionRef);
+  const runtimeInstanceRef = lease.runtimeInstanceRef, runtime = options.managedTerminal(info.id);
+  if (!runtimeInstanceRef || !manager || manager.getSessionId() !== info.id || !runtime.current()) throw Error('terminal-session-unavailable');
+  const assertCurrent = () => {
+    const ownership = runtimes.ownership(sessionRef);
+    if (runtimes.liveSessionManager(sessionRef) !== manager || manager.getSessionId() !== info.id || !runtime.current()
+      || ownership.state !== 'gateway-owned' || ownership.owner.continuity !== 'exact'
+      || ownership.owner.gatewayInstanceRef !== options.gatewayInstanceRef || ownership.owner.runtimeInstanceRef !== runtimeInstanceRef
+      || ownership.owner.ownerEpoch !== lease.ownerEpoch) throw Error('terminal-runtime-replaced');
+  };
+  assertCurrent();
+  return { identity: { gatewayInstanceRef: options.gatewayInstanceRef, sessionRef, runtimeInstanceRef }, runtime, assertCurrent };
+}

package/packages/piagent-webui/gateway/managed-terminal-processes.ts

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import type { managedTerminalBinding, ManagedTerminalHandle, ManagedTerminalEvent } from './managed-terminal-binding.ts';
+import type { TerminalProcessEvent, TerminalProcessOwner } from './terminal-sessions.ts';
+
+type Binding = Awaited<ReturnType<typeof managedTerminalBinding>>;
+type Entry = { binding: Binding; terminalRef: string; handle: ManagedTerminalHandle | null; active: boolean;
+  pending: ManagedTerminalEvent[]; bytes: number; failed: boolean };
+
+// This adapter has no shell/native import. Effects only reach the captured
+// managed runtime's boundary, even if that boundary reports unavailable.
+export class ManagedTerminalProcesses implements TerminalProcessOwner<Binding> {
+  readonly #entries = new Map<string, Entry>();
+  readonly #emit: (event: TerminalProcessEvent) => void;
+  #closed = false;
+  constructor(emit: (event: TerminalProcessEvent) => void) { this.#emit = emit; }
+  reason(binding: Binding) { return binding.runtime.terminals.reasonCode; }
+  async open(binding: Binding, size: { cols: number; rows: number }) {
+    binding.assertCurrent();
+    if (this.#closed) throw Error('terminal-session-closed');
+    if (this.#entries.size >= 256 || [...this.#entries.values()].filter(entry => entry.binding.identity.sessionRef === binding.identity.sessionRef).length >= 4)
+      throw Error('terminal-limit');
+    const terminalRef = `terminal.${randomUUID()}`;
+    const entry: Entry = { binding, terminalRef, handle: null, active: false, pending: [], bytes: 0, failed: false };
+    this.#entries.set(terminalRef, entry);
+    try {
+      entry.handle = await binding.runtime.terminals.open(size, event => {
+        if (entry.failed) return;
+        if (entry.active) { this.#publish(entry, event); return; }
+        entry.bytes += event.kind === 'output' ? Buffer.byteLength(event.data) : 64;
+        if (entry.bytes > 512 * 1024 || entry.pending.length >= 256) { entry.failed = true; entry.pending = []; return; }
+        entry.pending.push(event);
+      });
+      binding.assertCurrent();
+      if (entry.failed || this.#closed) throw Error('terminal-start-unavailable');
+      return { terminalRef, activate: () => {
+        entry.active = true;
+        for (const event of entry.pending) this.#publish(entry, event);
+        entry.pending = []; entry.bytes = 0;
+      } };
+    } catch (error) {
+      try { await entry.handle?.close(); } finally { this.#entries.delete(terminalRef); }
+      throw error;
+    }
+  }
+  #publish(entry: Entry, event: ManagedTerminalEvent) {
+    try { entry.binding.assertCurrent(); } catch { return; }
+    this.#emit({ ...event, sessionRef: entry.binding.identity.sessionRef, terminalRef: entry.terminalRef });
+  }
+  #get(ref: string, terminalRef: string) {
+    const entry = this.#entries.get(terminalRef);
+    if (!entry?.handle || entry.binding.identity.sessionRef !== ref) throw Error('terminal-not-found');
+    return entry;
+  }
+  async input(ref: string, terminalRef: string, data: string) {
+    const entry = this.#get(ref, terminalRef); entry.binding.assertCurrent();
+    await entry.handle!.input(data);
+  }
+  async resize(ref: string, terminalRef: string, size: { cols: number; rows: number }) {
+    const entry = this.#get(ref, terminalRef); entry.binding.assertCurrent();
+    await entry.handle!.resize(size);
+  }
+  async close(ref: string, terminalRef: string) {
+    const entry = this.#get(ref, terminalRef);
+    await entry.handle!.close(); this.#entries.delete(terminalRef);
+  }
+  async closeSession(ref: string) {
+    await Promise.all([...this.#entries.values()].filter(entry => entry.binding.identity.sessionRef === ref)
+      .map(entry => this.close(ref, entry.terminalRef)));
+  }
+  async dispose() {
+    this.#closed = true;
+    await Promise.all([...this.#entries.values()].map(entry => this.close(entry.binding.identity.sessionRef, entry.terminalRef)));
+  }
+}

package/packages/piagent-webui/gateway/managed-terminal-sessions.ts

@@ -0,0 +1,9 @@
+import { managedTerminalBinding, type ManagedTerminalOptions } from './managed-terminal-binding.ts';
+import { ManagedTerminalProcesses } from './managed-terminal-processes.ts';
+import { TerminalSessions } from './terminal-sessions.ts';
+
+export class ManagedTerminalSessions extends TerminalSessions<Awaited<ReturnType<typeof managedTerminalBinding>>> {
+  constructor(options: ManagedTerminalOptions) {
+    super(ref => managedTerminalBinding(options, ref), emit => new ManagedTerminalProcesses(emit));
+  }
+}

package/packages/piagent-webui/gateway/path-suggestions.ts

@@ -1,124 +1 @@
-import { execFile } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-// What an @ in the composer offers, as Pi's terminal does: files and folders
-// of the project matched loosely by name (fd, which honours .gitignore), and,
-// after a folder and a slash (src/, ~/Documents/, /Volumes/), the names under
-// that folder anywhere on this Mac. Only names reach the browser; no file is
-// opened.
-export type PathSuggestion = { value: string; label: string; detail: string; kind: "file" | "directory" };
-type Entry = { path: string; directory: boolean };
-
-const LIMIT = 20;
-const SEARCH_RESULTS = 100;
-const LISTED_ENTRIES = 5_000;
-// Outside the project a search stays shallow and skips app data and
-// dependency folders: a home folder is far larger than a repository.
-const OUTSIDE_DEPTH = 4;
-const fold = (value: string) => value.normalize("NFC").toLowerCase();
-const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-// A name typed composed (Dự án) may be stored decomposed on disk: either form matches.
-const either = (value: string) => value.normalize("NFC") === value.normalize("NFD") ? escape(value)
-  : `(?:${escape(value.normalize("NFC"))}|${escape(value.normalize("NFD"))})`;
-const inside = (file: string, root: string) => file === root || file.startsWith(root + path.sep);
-
-// fd where it is commonly installed, then on PATH (Debian and Ubuntu name it
-// fdfind; Windows adds .exe).
-export function findFd(home = os.homedir()): string | null {
-  const names = process.platform === "win32" ? ["fd.exe"] : ["fd", "fdfind"];
-  const onPath = String(process.env.PATH ?? "").split(path.delimiter).filter(Boolean).flatMap((dir) => names.map((name) => path.join(dir, name)));
-  for (const candidate of ["/opt/homebrew/bin/fd", "/usr/local/bin/fd", path.join(home, ".pi/agent/bin", names[0]), ...onPath]) {
-    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* next */ }
-  }
-  return null;
-}
-// macOS: the system's git, always there; elsewhere git from PATH.
-const GIT = process.platform === "darwin" ? "/usr/bin/git" : "git";
-
-// Higher is better: the name itself, then its start, then anywhere in it,
-// then anywhere in the path; a folder before a file with the same score.
-function score(entry: string, query: string, directory: boolean): number {
-  const name = fold(path.basename(entry)), wanted = fold(query);
-  const value = name === wanted ? 100 : name.startsWith(wanted) ? 80 : name.includes(wanted) ? 50 : fold(entry).includes(wanted) ? 30 : 0;
-  return value && directory ? value + 10 : value;
-}
-
-function run(file: string, args: string[], signal?: AbortSignal, input?: string): Promise<string> {
-  return new Promise((resolve) => {
-    const child = execFile(file, args, { encoding: "utf8", timeout: 4_000, maxBuffer: 8 << 20, signal }, (error, stdout) => resolve(error ? "" : stdout));
-    child.stdin?.on("error", () => {}); child.stdin?.end(input ?? "");
-  });
-}
-
-// The folder's own names, without what its repository ignores (dist/,
-// node_modules/), as fd lists them for Pi.
-async function listed(folder: string, signal?: AbortSignal): Promise<Entry[]> {
-  const entries: Entry[] = [];
-  try {
-    for await (const entry of await fs.promises.opendir(folder)) {
-      let directory = entry.isDirectory();
-      if (entry.isSymbolicLink()) try { directory = fs.statSync(path.join(folder, entry.name)).isDirectory(); } catch { /* broken link */ }
-      entries.push({ path: entry.name, directory });
-      if (entries.length >= LISTED_ENTRIES) break;
-    }
-  } catch { /* unreadable */ }
-  if (!entries.length) return entries;
-  const ignored = new Set((await run(GIT, ["-C", folder, "check-ignore", "-z", "--stdin"], signal, entries.map((entry) => `${entry.path}\0`).join("")))
-    .split("\0").filter(Boolean));
-  return ignored.size ? entries.filter((entry) => !ignored.has(entry.path)) : entries;
-}
-
-// Names deeper down that match: fd as Pi runs it in the project; shallow and
-// without hidden folders elsewhere; without fd, the files git knows about.
-async function searched(folder: string, query: string, options: { fd: string | null; project: boolean; atRoot: boolean; signal?: AbortSignal }): Promise<Entry[]> {
-  if (options.fd) {
-    const args = ["--base-directory", folder, "--type", "f", "--type", "d", "--max-results", String(SEARCH_RESULTS), "--ignore-case", "--exclude", ".git",
-      ...(options.project ? ["--follow", "--hidden"] : ["--max-depth", String(OUTSIDE_DEPTH), "--exclude", "Library", "--exclude", "node_modules", ...(query.startsWith(".") ? ["--hidden"] : [])]),
-      ...(query.includes("/") ? ["--full-path", query.split("/").filter(Boolean).map(either).join("/")] : [either(query)])];
-    return (await run(options.fd, args, options.signal)).split("\n").filter(Boolean)
-      .map((line) => ({ path: line.replace(/^\.\//, "").replace(/\/$/, ""), directory: line.endsWith("/") }));
-  }
-  if (!options.atRoot) return [];
-  const files = (await run(GIT, ["-C", folder, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], options.signal))
-    .split("\0").filter(Boolean).slice(0, 50_000);
-  const folders = new Set<string>();
-  for (const file of files) for (let dir = path.posix.dirname(file); dir !== "."; dir = path.posix.dirname(dir)) folders.add(dir);
-  const wanted = fold(query);
-  return [...[...folders].map((dir) => ({ path: dir, directory: true })), ...files.map((file) => ({ path: file, directory: false }))]
-    .filter((entry) => fold(entry.path).includes(wanted));
-}
-
-export async function suggestPaths(options: { root: string; query: string; home?: string; fd?: string | null; signal?: AbortSignal }): Promise<{ suggestions: PathSuggestion[] }> {
-  const home = options.home ?? os.homedir(), fd = options.fd === undefined ? findFd(home) : options.fd;
-  const root = fs.realpathSync(options.root);
-  const typed = options.query.trim() === "~" ? "~/" : options.query.trim();
-  // Text up to the last slash names a folder: search under it (Pi's scoped
-  // search). When it is not a folder, the whole text is matched in the project.
-  const cut = typed.lastIndexOf("/") + 1;
-  let base = typed.slice(0, cut), name = typed.slice(cut), folder = root;
-  if (base) {
-    try {
-      const candidate = fs.realpathSync(base.startsWith("~/") ? path.join(home, base.slice(2)) : path.resolve(root, base));
-      if (fs.statSync(candidate).isDirectory()) folder = candidate; else { base = ""; name = typed; }
-    } catch { base = ""; name = typed; }
-  }
-  const project = inside(folder, root);
-  const near = await listed(folder, options.signal);
-  const deep = name ? await searched(folder, name, { fd, project, atRoot: folder === root, signal: options.signal }) : [];
-  const seen = new Set<string>(), entries: Array<Entry & { score: number }> = [];
-  for (const entry of [...near, ...deep]) {
-    if (seen.has(entry.path)) continue; seen.add(entry.path);
-    // Hidden entries (.github, .ssh, .zshrc) for a name typed with a dot, and
-    // in the project for any name typed, as Pi's search finds them there.
-    if (entry.path.split("/").some((part) => part.startsWith(".")) && !name.startsWith(".") && !(project && name)) continue;
-    const value = name ? score(entry.path, name.split("/").filter(Boolean).at(-1) ?? name, entry.directory) : 1;
-    if (value > 0) entries.push({ ...entry, score: value });
-  }
-  const depth = (entry: Entry) => entry.path.split("/").length;
-  entries.sort((a, b) => b.score - a.score || depth(a) - depth(b)
-    || (name ? a.path.length - b.path.length : Number(b.directory) - Number(a.directory)) || a.path.localeCompare(b.path));
-  return { suggestions: entries.slice(0, LIMIT).map((entry) => ({ value: `${base}${entry.path}${entry.directory ? "/" : ""}`,
-    label: path.basename(entry.path) + (entry.directory ? "/" : ""), detail: `${base}${entry.path}`, kind: entry.directory ? "directory" : "file" })) };
-}
+export { findFd, suggestPaths, type PathSuggestion } from "../../piagent-core/extensions/path-suggestions.ts";