@piagent/platform 1.37.1 → 1.38.1

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

@@ -0,0 +1,36 @@
+import { sessionRefForPath } from "./session-catalog.ts";
+import type { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+
+type Options = {
+  key: Buffer;
+  managed: boolean;
+  gatewayInstanceRef: string;
+  runtimes: Pick<SessionRuntimeSupervisor, "listSessions" | "acquire" | "liveSessionManager" | "ownership">;
+};
+
+// Browser refs select catalog entries, never host paths or shell environments.
+// Keep a synchronous authority check for the instant before each native effect.
+export async function personalTerminalBinding(options: Options, sessionRef: string) {
+  if (options.managed) throw new Error("company-boundary-required");
+  const { runtimes } = options;
+  const matches = (await runtimes.listSessions()).filter(info => sessionRefForPath(options.key, info.path) === sessionRef);
+  if (matches.length !== 1) throw new Error("terminal-session-unavailable");
+  const info = matches[0]!;
+  const lease = await runtimes.acquire(sessionRef);
+  const manager = runtimes.liveSessionManager(sessionRef);
+  const runtimeInstanceRef = lease.runtimeInstanceRef;
+  if (!runtimeInstanceRef || !manager || manager.getSessionId() !== info.id)
+    throw new Error("terminal-session-unavailable");
+  const assertCurrent = () => {
+    const current = runtimes.liveSessionManager(sessionRef), ownership = runtimes.ownership(sessionRef);
+    if (current !== manager || current.getSessionId() !== info.id || ownership.state !== "gateway-owned"
+      || ownership.owner.continuity !== "exact" || ownership.owner.gatewayInstanceRef !== options.gatewayInstanceRef
+      || ownership.owner.runtimeInstanceRef !== runtimeInstanceRef || ownership.owner.ownerEpoch !== lease.ownerEpoch)
+      throw new Error("terminal-runtime-replaced");
+    if (current.buildSessionContext().model?.provider === "agent_watch_managed")
+      throw new Error("company-boundary-required");
+  };
+  assertCurrent();
+  return { scope: { sessionRef, mode: "personal" as const, cwd: info.cwd },
+    identity: { gatewayInstanceRef: options.gatewayInstanceRef, sessionRef, runtimeInstanceRef }, assertCurrent };
+}

package/packages/piagent-webui/gateway/personal-terminal-diagnostic.mjs

@@ -0,0 +1,16 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export function loadPersonalPty(load = () => require('@lydell/node-pty'), platform = process.platform) {
+  if (platform === 'win32') return { pty: null, reason: 'terminal-platform-unavailable' };
+  try {
+    const pty = load();
+    if (typeof pty?.spawn !== 'function') throw Error('invalid-pty-module');
+    return { pty, reason: null };
+  } catch { return { pty: null, reason: 'terminal-native-module-unavailable' }; }
+}
+export function personalTerminalDiagnostic(load, platform = process.platform) {
+  const { reason } = loadPersonalPty(load, platform);
+  return { available: reason === null, reasonCode: reason, platform,
+    scope: 'personal', nativeModule: '@lydell/node-pty', probe: 'module-load',
+    shellSpawnVerified: false };
+}

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

@@ -0,0 +1,119 @@
+import { loadPersonalPty } from "./personal-terminal-diagnostic.mjs";
+import { randomUUID } from "node:crypto";
+import { userInfo } from "node:os";
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { execFileSync } from "node:child_process";
+import type { IPty } from "@lydell/node-pty";
+import { ProcessTreeWatch } from "../../piagent-core/runtime/process-tree-watch.mjs";
+
+type PtyModule = { spawn: typeof import("@lydell/node-pty").spawn };
+type Scope = { sessionRef: string; mode: "personal" | "company"; cwd: string };
+type Size = { cols: number; rows: number };
+export type PersonalTerminalEvent = { sessionRef: string; terminalRef: string } &
+  ({ kind: "output"; data: string } | { kind: "exit"; exitCode: number; signal: number | null });
+type Entry = { sessionRef: string; terminalRef: string; process: IPty; exited: boolean; cleanup?: Promise<void>; closing?: Promise<void> };
+const dimensions = ({ cols, rows }: Size) => {
+  if (!Number.isInteger(cols) || cols < 2 || cols > 500 || !Number.isInteger(rows) || rows < 1 || rows > 200)
+    throw new Error("terminal-invalid-size");
+};
+function descendants(pid: number): number[] {
+  const rows = execFileSync("/bin/ps", ["-axo", "pid=,ppid="], { encoding: "utf8", timeout: 2000, maxBuffer: 4 * 1024 * 1024 })
+    .trim().split("\n").map(line => line.trim().split(/\s+/).map(Number));
+  const found = new Set<number>(), queue = [pid];
+  for (const parent of queue) for (const [child, owner] of rows) {
+    if (owner === parent && child > 1 && child !== process.pid && !found.has(child)) { found.add(child); queue.push(child); }
+  }
+  return [...found].reverse();
+}
+const signal = (pid: number, name: NodeJS.Signals) => { try { process.kill(pid, name); } catch { /* already exited */ } };
+
+// This owns personal native processes only. The protocol/controller must resolve
+// the trusted session scope before calling it; company never falls back here.
+export class PersonalTerminalProcesses {
+  readonly #entries = new Map<string, Entry>();
+  readonly #closingSessions = new Set<string>();
+  readonly #emit: (event: PersonalTerminalEvent) => void;
+  readonly #pty: PtyModule | null;
+  readonly #watch = new ProcessTreeWatch();
+  readonly unavailableReason: string | null;
+  #closed = false;
+  constructor(emit: (event: PersonalTerminalEvent) => void, load?: () => PtyModule) {
+    this.#emit = emit;
+    const { pty, reason } = loadPersonalPty(load);
+    this.#pty = pty; this.unavailableReason = reason;
+  }
+  open(scope: Scope, size: Size, shell = userInfo().shell || process.env.SHELL || "/bin/sh") {
+    if (scope.mode !== "personal") throw new Error("company-boundary-required");
+    if (this.#closed || this.#closingSessions.has(scope.sessionRef)) throw new Error("terminal-session-closed");
+    if (!this.#pty) throw new Error(this.unavailableReason!);
+    dimensions(size);
+    if (!isAbsolute(scope.cwd) || !statSync(scope.cwd, { throwIfNoEntry: false })?.isDirectory()) throw new Error("terminal-project-unavailable");
+    if (!isAbsolute(shell) || shell.includes("\0")) throw new Error("terminal-shell-unavailable");
+    if (this.list(scope.sessionRef).length >= 4 || this.#entries.size >= 256) throw new Error("terminal-limit");
+    const terminalRef = `terminal.${randomUUID()}`;
+    // The member's own environment, without what only this Gateway uses
+    // (its agent folder, transform root, update switches).
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(PI|PIAGENT)_/.test(key)));
+    let child: IPty;
+    try { child = this.#pty.spawn(shell, [], { ...size, cwd: scope.cwd, env: { ...env, TERM: "xterm-256color" }, name: "xterm-256color" }); }
+    catch { throw new Error("terminal-spawn-failed"); }
+    this.#watch.watch(child.pid);
+    const entry: Entry = { sessionRef: scope.sessionRef, terminalRef, process: child, exited: false };
+    this.#entries.set(terminalRef, entry);
+    child.onData(data => { if (!entry.closing) this.#notify({ sessionRef: scope.sessionRef, terminalRef, kind: "output", data }); });
+    child.onExit(({ exitCode, signal: exitSignal }) => {
+      entry.exited = true;
+      entry.cleanup ??= this.#stop(entry);
+      this.#notify({ sessionRef: scope.sessionRef, terminalRef, kind: "exit", exitCode, signal: exitSignal ?? null });
+    });
+    return { terminalRef, pid: child.pid };
+  }
+  list(sessionRef: string) { return [...this.#entries.values()].filter(entry => entry.sessionRef === sessionRef)
+    .map(entry => ({ terminalRef: entry.terminalRef, exited: entry.exited })); }
+  input(sessionRef: string, terminalRef: string, data: string) {
+    if (typeof data !== "string" || Buffer.byteLength(data) > 16 * 1024) throw new Error("terminal-input-limit");
+    const entry = this.#get(sessionRef, terminalRef);
+    if (entry.exited || entry.closing) throw new Error("terminal-exited");
+    entry.process.write(data);
+  }
+  resize(sessionRef: string, terminalRef: string, size: Size) {
+    dimensions(size); const entry = this.#get(sessionRef, terminalRef);
+    if (entry.exited || entry.closing) throw new Error("terminal-exited");
+    entry.process.resize(size.cols, size.rows);
+  }
+  pause(sessionRef: string, terminalRef: string) { const entry = this.#get(sessionRef, terminalRef); if (!entry.exited) entry.process.pause(); }
+  resume(sessionRef: string, terminalRef: string) { const entry = this.#get(sessionRef, terminalRef); if (!entry.exited) entry.process.resume(); }
+  async close(sessionRef: string, terminalRef: string) {
+    const entry = this.#get(sessionRef, terminalRef);
+    if (!entry.closing) { entry.cleanup ??= this.#stop(entry); entry.closing = entry.cleanup.finally(() => this.#entries.delete(terminalRef)); }
+    await entry.closing;
+  }
+  async closeSession(sessionRef: string) {
+    this.#closingSessions.add(sessionRef);
+    try { await Promise.all(this.list(sessionRef).map(entry => this.close(sessionRef, entry.terminalRef))); }
+    finally { this.#closingSessions.delete(sessionRef); }
+  }
+  async dispose() {
+    this.#closed = true;
+    await Promise.all([...new Set([...this.#entries.values()].map(entry => entry.sessionRef))].map(ref => this.closeSession(ref)));
+  }
+  #get(sessionRef: string, terminalRef: string) {
+    const entry = this.#entries.get(terminalRef);
+    if (!entry || entry.sessionRef !== sessionRef) throw new Error("terminal-not-found");
+    return entry;
+  }
+  #notify(event: PersonalTerminalEvent) { try { this.#emit(event); } catch { /* a disconnected consumer cannot own process lifetime */ } }
+  async #stop(entry: Entry) {
+    const pid = entry.process.pid;
+    let tree: number[] = [];
+    try { if (!entry.exited) tree = descendants(pid); } catch { /* still signal the PTY process group */ }
+    for (const child of tree) signal(child, "SIGTERM");
+    try { if (!entry.exited) entry.process.kill("SIGHUP"); } catch { /* already exited */ }
+    signal(-pid, "SIGTERM");
+    await new Promise(resolve => setTimeout(resolve, 100));
+    for (const child of tree) signal(child, "SIGKILL");
+    signal(-pid, "SIGKILL");
+    await this.#watch.stop(pid);
+  }
+}

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

@@ -0,0 +1,22 @@
+import { personalTerminalBinding } from "./personal-terminal-binding.ts";
+import { PersonalTerminalProcesses, type PersonalTerminalEvent } from "./personal-terminal-processes.ts";
+import { TerminalSessions } from "./terminal-sessions.ts";
+export type { TerminalMessage as PersonalTerminalMessage } from "./terminal-sessions.ts";
+type Binding = Awaited<ReturnType<typeof personalTerminalBinding>>;
+type Options = Parameters<typeof personalTerminalBinding>[0];
+
+// Personal authority is resolved here. This adapter never accepts a company boundary.
+export class PersonalTerminalSessions extends TerminalSessions<Binding> {
+  constructor(options: Options, createProcesses = (emit: (event: PersonalTerminalEvent) => void) => new PersonalTerminalProcesses(emit)) {
+    super(ref => personalTerminalBinding(options, ref), emit => {
+      const processes = createProcesses(emit);
+      return { reason: () => processes.unavailableReason,
+        open: (binding, size) => processes.open(binding.scope, size),
+        input: (ref, terminal, data) => processes.input(ref, terminal, data),
+        resize: (ref, terminal, size) => processes.resize(ref, terminal, size),
+        close: (ref, terminal) => processes.close(ref, terminal),
+        pause: (ref, terminal) => processes.pause(ref, terminal), resume: (ref, terminal) => processes.resume(ref, terminal),
+        closeSession: ref => processes.closeSession(ref), dispose: () => processes.dispose() };
+    });
+  }
+}

package/packages/piagent-webui/gateway/runtime-session-controls.ts

@@ -14,11 +14,12 @@ type RuntimeCommandOutput = {
 };
 
 export async function executePermissionCommand(session: any,
-  permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<void> {
+  permissionMode: "read-only" | "workspace-write" | "trusted-full-access" | "bypass"): Promise<void> {
   // A company conversation: "Ask first" or "Bypass" (no read-only mode); the
   // runtime keeps the choice in the conversation and reads it at each command,
   // so it may change while a turn runs (the supervisor lets it).
   if (session.managedExecution) {
+    // Bypass where the team's Harness allows it; the runtime refuses otherwise.
     if (typeof session.managedSetPermission !== "function" || permissionMode === "read-only") throw new Error("managed-permission-unavailable");
     session.managedSetPermission(permissionMode);
     return;

package/packages/piagent-webui/gateway/session-catalog.ts

@@ -49,7 +49,7 @@ function catalogRef(key: Buffer, namespace: string, value: string): string {
 }
 
 export type SessionOwnerProjection = Pick<SessionRow, "state" | "liveState" | "composerAvailable" | "needsAttention" | "owner" | "reasonCode">;
-export type SessionOptionProjection = Pick<SessionRow, "modelLabel" | "thinkingLevel" | "managedHelpers" | "managedThinkingLevels" | "managedPermission" | "managedFast" | "managedPlan" | "managedProcess" | "managedTurnEnd" | "managedReview">;
+export type SessionOptionProjection = Pick<SessionRow, "modelLabel" | "thinkingLevel" | "managedHelpers" | "managedThinkingLevels" | "managedPermission" | "managedBypass" | "managedFast" | "managedPlan" | "managedProcess" | "managedTurnEnd" | "managedReview">;
 
 function display(value: unknown, maximum: number, fallback: string): string {
   const clean = redactSensitiveText(String(value ?? "")).text
@@ -136,6 +136,7 @@ function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undef
     ...(sessionOptions?.managedThinkingLevels ? {managedThinkingLevels:sessionOptions.managedThinkingLevels} : {}),
     ...(sessionOptions?.managedPermission ? {managedPermission:sessionOptions.managedPermission} : {}),
     ...(sessionOptions?.managedFast ? {managedFast:sessionOptions.managedFast} : {}),
+    ...(sessionOptions?.managedBypass ? {managedBypass:true as const} : {}),
     ...(sessionOptions?.managedPlan ? {managedPlan:sessionOptions.managedPlan} : {}),
     ...(sessionOptions?.managedProcess ? {managedProcess:sessionOptions.managedProcess} : {}),
     ...(sessionOptions?.managedTurnEnd ? {managedTurnEnd:sessionOptions.managedTurnEnd} : {}),
@@ -148,7 +149,7 @@ function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undef
       ? { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "released" }
       : ownership?.owner ?? { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "unknown" },
     sessionRevision: revision(key, [info.path, info.modified.toISOString(), info.messageCount, info.name ?? null, metadata?.revision ?? null,
-      sessionOptions?.modelLabel ?? null, sessionOptions?.thinkingLevel ?? "unknown", sessionOptions?.managedHelpers, sessionOptions?.managedThinkingLevels, sessionOptions?.managedPermission ?? null, sessionOptions?.managedFast ?? null, sessionOptions?.managedPlan, sessionOptions?.managedProcess, sessionOptions?.managedTurnEnd, sessionOptions?.managedReview,
+      sessionOptions?.modelLabel ?? null, sessionOptions?.thinkingLevel ?? "unknown", sessionOptions?.managedHelpers, sessionOptions?.managedThinkingLevels, sessionOptions?.managedPermission ?? null, sessionOptions?.managedBypass ?? null, sessionOptions?.managedFast ?? null, sessionOptions?.managedPlan, sessionOptions?.managedProcess, sessionOptions?.managedTurnEnd, sessionOptions?.managedReview,
       gitBranch, gitRepositories,
       metadata?.archived ? "archived" : ownership ? [ownership.state, ownership.liveState, ownership.owner.kind,
         ownership.owner.ownerEpoch, ownership.owner.runtimeInstanceRef, ownership.reasonCode] : "offline"]),

package/packages/piagent-webui/gateway/session-command-controller.ts

@@ -57,7 +57,7 @@ function validPayload(action: SessionAction, payload: Record<string, unknown>):
   if (action === "session.set-thinking") return exactKeys(payload, ["thinkingLevel"])
     && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel));
   if (action === "session.set-permission") return exactKeys(payload, ["permissionMode"])
-    && ["read-only", "workspace-write", "trusted-full-access"].includes(String(payload.permissionMode));
+    && ["read-only", "workspace-write", "trusted-full-access", "bypass"].includes(String(payload.permissionMode));
   if (action === "session.set-fast") return exactKeys(payload, ["fast"]) && typeof payload.fast === "boolean";
   if (action === "session.rename") return exactKeys(payload, ["title"]) && typeof payload.title === "string"
     && payload.title.length >= 1 && payload.title.length <= 500 && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(payload.title);
@@ -71,7 +71,7 @@ function validPayload(action: SessionAction, payload: Record<string, unknown>):
     && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel))
     && typeof payload.message === "string" && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0")
     && REF.test(String(payload.messageRequestId)) && (payload.deferInitialMessage === undefined || typeof payload.deferInitialMessage === "boolean")
-    && (payload.permissionMode === undefined || ["read-only", "workspace-write", "trusted-full-access"].includes(String(payload.permissionMode)))
+    && (payload.permissionMode === undefined || ["read-only", "workspace-write", "trusted-full-access", "bypass"].includes(String(payload.permissionMode)))
     && (payload.fast === undefined || typeof payload.fast === "boolean")
     && (payload.workflow === undefined || isWebUiWorkflowId(payload.workflow));
 }
@@ -180,7 +180,7 @@ export class SessionCommandController {
         }
         if (command.payload.permissionMode !== undefined) {
           await this.#runtimes.setPermission(targetSessionRef, String(command.payload.permissionMode) as
-            "read-only" | "workspace-write" | "trusted-full-access");
+            "read-only" | "workspace-write" | "trusted-full-access" | "bypass");
         }
         // Fast mode chosen on the new chat page is on before the first message
         // runs; a Harness that does not allow it refuses the create.
@@ -232,7 +232,7 @@ export class SessionCommandController {
         resultCode = await this.#runtimes.setThinking(command.sessionRef!, String(command.payload.thinkingLevel));
       } else if (command.action === "session.set-permission") {
         resultCode = await this.#runtimes.setPermission(command.sessionRef!, String(command.payload.permissionMode) as
-          "read-only" | "workspace-write" | "trusted-full-access");
+          "read-only" | "workspace-write" | "trusted-full-access" | "bypass");
       } else if (command.action === "session.set-fast") {
         resultCode = await this.#runtimes.setFast(command.sessionRef!, command.payload.fast === true);
       } else if (command.action === "session.rename") {

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -1,3 +1,5 @@
+import { piSourceMutationGuard } from "../../piagent-core/runtime/policy/source-mutation-guard.ts";
+import { personalWorkspaceReader } from "../server/workspace-reader.ts";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -49,7 +51,7 @@ const EMPTY_REPLAY = {
   reasonCode: null
 };
 
-function inspectionRuntimeRef(gatewayInstanceRef: string, sessionRef: string): string {
+export function inspectionRuntimeRef(gatewayInstanceRef: string, sessionRef: string): string {
   return `runtime.${createHash("sha256").update(`${gatewayInstanceRef}\0${sessionRef}`).digest("hex")}`;
 }
 
@@ -118,13 +120,16 @@ export class SessionInspectionRegistry {
   readonly #packageRoot: string;
   readonly #agentDir?: string;
   readonly #models?: ModelRuntime;
+  readonly #managed: boolean;
+  readonly #workspaceRead?: (sessionRef: string, id: string, kind: string, path: string) => Promise<unknown>;
   readonly #projects?: ProjectSource;
   readonly #mcpAuth?: McpAuthBroker;
   readonly #operationLiveness: ((sessionRef: string) => "idle" | "running" | "unknown") | null;
   readonly #providers = new Map<string, { modifiedAt: string; provider: CoreInspectionProvider }>();
 
   constructor(options: { gatewayInstanceRef: string; host: PiHost; key: Buffer; packageRoot: string; agentDir?: string; models?: ModelRuntime; projects?: ProjectSource;
-    mcpAuth?: McpAuthBroker; listSessions?: () => Promise<PiSessionInfo[]>;
+    workspaceRead?: (sessionRef: string, id: string, kind: string, path: string) => Promise<unknown>;
+    managed?: boolean; mcpAuth?: McpAuthBroker; listSessions?: () => Promise<PiSessionInfo[]>;
     openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null;
     operationLiveness?: (sessionRef: string) => "idle" | "running" | "unknown" }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
@@ -135,6 +140,8 @@ export class SessionInspectionRegistry {
     this.#packageRoot = options.packageRoot;
     this.#agentDir = options.agentDir;
     this.#models = options.models;
+    this.#managed = options.managed === true;
+    this.#workspaceRead = options.workspaceRead;
     this.#projects = options.projects;
     this.#mcpAuth = options.mcpAuth;
     this.#operationLiveness = options.operationLiveness ?? null;
@@ -225,7 +232,7 @@ export class SessionInspectionRegistry {
       if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) return [];
       const value = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
       return [{ id: entry, displayName: safeName(value.displayName ?? entry),
-        permissionMode: ["read-only", "workspace-write", "trusted-full-access"].includes(String(value.permissionProfile))
+        permissionMode: ["read-only", "workspace-write", "trusted-full-access", "bypass"].includes(String(value.permissionProfile))
           ? String(value.permissionProfile) : null }];
     }).slice(0, 100), []);
     const models = availableModels.flatMap((value) => {
@@ -239,7 +246,8 @@ export class SessionInspectionRegistry {
       const inputs = Array.isArray(value.input) ? value.input.filter((item): item is string => typeof item === "string") : null;
       return [{ modelRef: webUiModelRef(provider, modelId), provider, modelId, displayName: safeName(value.name ?? modelId),
         reasoning: value.reasoning, imageInput: inputs ? inputs.includes("image") : null, thinkingLevels,
-        ...(provider === "agent_watch_managed" && value.managedFast === true ? { managedFast: true } : {}) }];
+        ...(provider === "agent_watch_managed" && value.managedFast === true ? { managedFast: true } : {}),
+        ...(provider === "agent_watch_managed" && value.managedBypass === true ? { managedBypass: true } : {}) }];
     });
     // Only offer a default present in the authenticated host catalog. Retain
     // the previous Sol baseline for accounts that have not received GPT-6 yet.
@@ -256,7 +264,7 @@ export class SessionInspectionRegistry {
       reasonCode: projects.size ? null : "no-known-project" };
   }
 
-  async provider(sessionRef: string): Promise<WebUiReadModelProvider> {
+  async provider(sessionRef: string): Promise<CoreInspectionProvider> {
     const info = await this.#sessionInfo(sessionRef);
     const modifiedAt = info.modified.toISOString();
     const cached = this.#providers.get(sessionRef);
@@ -288,6 +296,11 @@ export class SessionInspectionRegistry {
       runtimeInstanceId: inspectionRuntimeRef(this.#gatewayInstanceRef, sessionRef),
       eventStore,
       task: () => safeRead(() => activeSessionTask(info.cwd, info.id), undefined),
+      ...(!this.#managed && context.model?.provider !== "agent_watch_managed" ? {
+        sourceMutationGuardAvailable: () => piSourceMutationGuard.available(info.cwd, info.id),
+        sourceSessionControlRevision: () => piSourceMutationGuard.sessionControlRevision(info.cwd, info.id),
+        sourceSessionObservation: (file: string) => piSourceMutationGuard.sessionObservation(info.cwd, info.id, file)
+      } : {}),
       activityEvents: () => safeRead(() => readContextTelemetry(info.cwd, { limit: 5_000 }), []),
       // A provider can outlive the turn that created it (notably while a new
       // session has not reached the host index yet). Read the branch at request
@@ -312,6 +325,17 @@ export class SessionInspectionRegistry {
       approvalProjection: () => piApprovalBroker.projection(info.cwd, info.id),
       approvalDetail: (approvalRef) => piApprovalBroker.detail(info.cwd, info.id, approvalRef)
     });
+    if (this.#managed && this.#workspaceRead) {
+      Object.assign(provider, { workspace: async (kind: string, relative: string) => {
+        const value = await this.#workspaceRead!(sessionRef, info.id, kind, relative);
+        return { schemaVersion: 1, version: `piagent-webui-workspace-${kind}-v1`, generatedAt: new Date().toISOString(),
+          identity: (await provider.snapshot() as { identity: unknown }).identity, ...(value as object) };
+      } });
+    }
+    if (!this.#managed && context.model?.provider !== "agent_watch_managed") {
+      Object.assign(provider, { workspace: personalWorkspaceReader({ cwd: info.cwd, packageRoot: this.#packageRoot,
+        identity: async () => (await provider.snapshot() as { identity: Record<string, unknown> }).identity }) });
+    }
     this.#providers.delete(sessionRef);
     this.#providers.set(sessionRef, { modifiedAt, provider });
     while (this.#providers.size > CACHE_LIMIT) this.#providers.delete(this.#providers.keys().next().value as string);

package/packages/piagent-webui/gateway/session-runtime-supervisor.ts

@@ -32,22 +32,21 @@ export class SessionRuntimeSupervisor {
   readonly #runtimeFactory: RuntimeFactory; readonly #events: GatewayEventStore; readonly #settledOwners = new Set<string>();
   readonly #host: any | null; readonly #operationDeadlinePolicy: SessionOperationDeadlinePolicy;
   readonly #resolveProject: ((projectRef: string) => string | null) | null;
-  readonly #sessionDirectory?: string;
+  readonly #sessionDirectory?: string; readonly #closeSessionResources: (sessionRef: string) => Promise<void>;
   readonly #settleOperation: ReturnType<typeof createSessionOperationSettlement>;
   readonly #active = new Map<string, ActiveRuntime>(); readonly #opening = new Map<string, Promise<SessionLeaseSnapshot>>();
   readonly #created = new Map<string, PiSessionInfo>(); #closed = false; #closing: Promise<void> | null = null; #readProjection: ((sessionRef: string) => Promise<Projection>) | null = null;
   constructor(options: {
-    gatewayInstanceRef: string;
-    key: Buffer;
+    gatewayInstanceRef: string; key: Buffer;
     leases: SessionLeaseStore;
     listSessions(): Promise<PiSessionInfo[]>;
     runtimeFactory?: RuntimeFactory;
     host?: any;
-    agentDir?: string;
-    packageRoot?: string;
+    agentDir?: string; packageRoot?: string;
     modelRuntime?: any;
     scopedBrokerRouter?: ScopedBrokerRouter;
     sessionDirectory?: string;
+    closeSessionResources?(sessionRef: string): Promise<void>;
     events?: GatewayEventStore;
     operationWatchdog?: SessionOperationWatchdogOptions;
     resolveProject?(projectRef: string): string | null;
@@ -61,7 +60,7 @@ export class SessionRuntimeSupervisor {
     this.#host = options.host ?? null;
     this.#operationDeadlinePolicy = sessionOperationDeadlinePolicy(options.operationWatchdog);
     this.#resolveProject = options.resolveProject ?? null;
-    this.#sessionDirectory = options.sessionDirectory;
+    this.#sessionDirectory = options.sessionDirectory; this.#closeSessionResources = options.closeSessionResources ?? (async () => {});
     this.#settleOperation = createSessionOperationSettlement(options);
     if (options.runtimeFactory) this.#runtimeFactory = options.runtimeFactory;
     else {
@@ -169,7 +168,7 @@ export class SessionRuntimeSupervisor {
     if (active.operationRef || active.settling) throw new Error("session-runtime-busy");
     this.#active.delete(sessionRef);
     bestEffortUnsubscribe(active.unsubscribeApproval); bestEffortUnsubscribe(active.unbindApproval);
-    try { await active.runtime.dispose(); }
+    try { await this.#closeSessionResources(sessionRef); await active.runtime.dispose(); }
     catch (error) {
       try { this.#leases.requireRecovery(sessionRef, active.lease.ownerEpoch!, this.#gatewayInstanceRef,
         active.lease.runtimeInstanceRef!, "session-runtime-dispose-failed"); } catch { /* remains fail closed */ }
@@ -308,6 +307,7 @@ export class SessionRuntimeSupervisor {
     if (active.lastSessionRevision) this.#events.publish("runtime.changed", { sessionRef,
       sessionRevision: active.lastSessionRevision, liveState: "uncertain", operationRef: null,
       ...(messageRequestId ? { messageRequestId } : {}), reasonCode });
+    await this.#closeSessionResources(sessionRef);
     await boundedResult(Promise.resolve().then(() => active.runtime.dispose()), this.#operationDeadlinePolicy.terminationTimeoutMs);
   }
   #bindApproval(sessionRef: string, active: ActiveRuntime): void {
@@ -362,7 +362,7 @@ export class SessionRuntimeSupervisor {
     if (effective !== thinkingLevel) throw new Error("session-thinking-mismatch");
     this.#touchCreated(sessionRef); return "thinking-changed";
   }
-  async setPermission(sessionRef: string, permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<"permission-changed"> {
+  async setPermission(sessionRef: string, permissionMode: "read-only" | "workspace-write" | "trusted-full-access" | "bypass"): Promise<"permission-changed"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");

package/packages/piagent-webui/gateway/signed-session-journal.ts

@@ -0,0 +1,77 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX_BYTES = 8 * 1024 * 1024, MAX_RECORDS = 4000;
+type SessionRecord = { identity: { sessionRef: string }; idempotencyKeyDigest: string };
+type Journal<T> = { version: 1; sequence: number; records: Array<{ sequence: number; receipt: T }> };
+
+// Gateway-owned receipts survive a runtime eviction or an empty conversation
+// that Pi has not persisted yet. No source contents or raw idempotency keys.
+export class SignedSessionJournal<T extends SessionRecord> {
+  readonly #namespace: string;
+  readonly #root: string;
+  readonly #key: Buffer;
+  readonly #directory: fs.Stats;
+  constructor(root: string, key: Buffer, namespace: string) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(namespace) || key.length < 32) throw new Error("session-journal-config-invalid");
+    this.#namespace = namespace;
+    this.#root = path.join(fs.realpathSync(root), namespace); this.#key = Buffer.from(key);
+    try { fs.mkdirSync(this.#root, { mode: 0o700 }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    const stat = fs.lstatSync(this.#root);
+    this.#directory = stat; this.#checkDirectory();
+  }
+  #checkDirectory(): void {
+    const stat = fs.lstatSync(this.#root);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)
+      || typeof process.getuid === "function" && stat.uid !== process.getuid()
+      || stat.dev !== this.#directory.dev || stat.ino !== this.#directory.ino) throw new Error("workspace-journal-unsafe");
+  }
+  #file(sessionRef: string): string {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/.test(sessionRef)) throw new Error("workspace-session-invalid");
+    return path.join(this.#root, `${sessionRef}.json`);
+  }
+  #sign(sessionRef: string, value: Journal<T>): string {
+    return createHmac("sha256", this.#key).update(`${this.#namespace}-v1\0${sessionRef}\0`).update(JSON.stringify(value)).digest("hex");
+  }
+  #read(sessionRef: string): Journal<T> {
+    this.#checkDirectory();
+    let descriptor: number;
+    try { descriptor = fs.openSync(this.#file(sessionRef), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, sequence: 0, records: [] }; throw error; }
+    try {
+      const stat = fs.fstatSync(descriptor);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES || (stat.mode & 0o077)
+        || typeof process.getuid === "function" && stat.uid !== process.getuid()) throw new Error("workspace-journal-unsafe");
+      const { value, mac } = JSON.parse(fs.readFileSync(descriptor, "utf8")) as { value: Journal<T>; mac: string };
+      if (!value || typeof mac !== "string" || !/^[a-f0-9]{64}$/.test(mac) || !timingSafeEqual(Buffer.from(mac, "hex"), Buffer.from(this.#sign(sessionRef, value), "hex"))
+        || value.version !== 1 || !Number.isSafeInteger(value.sequence) || value.sequence < 0 || !Array.isArray(value.records) || value.records.length > MAX_RECORDS
+        || value.records.some(record => !record || !Number.isSafeInteger(record.sequence) || record.sequence < 1 || record.sequence > value.sequence
+          || !record.receipt || record.receipt.identity?.sessionRef !== sessionRef || !/^sha256:[a-f0-9]{64}$/.test(record.receipt.idempotencyKeyDigest)))
+        throw new Error("workspace-journal-invalid");
+      return value;
+    } finally { fs.closeSync(descriptor); }
+  }
+  history(sessionRef: string): T[] {
+    return this.#read(sessionRef).records.sort((a, b) => a.sequence - b.sequence).map(record => record.receipt);
+  }
+  append(sessionRef: string, receipt: T): void {
+    if (receipt.identity.sessionRef !== sessionRef) throw new Error("workspace-session-invalid");
+    const value = this.#read(sessionRef), sequence = value.sequence + 1;
+    const records = value.records.filter(record => record.receipt.idempotencyKeyDigest !== receipt.idempotencyKeyDigest);
+    records.push({ sequence, receipt });
+    if (records.length > MAX_RECORDS || !Number.isSafeInteger(sequence)) throw new Error("workspace-journal-full");
+    const next: Journal<T> = { version: 1, sequence, records }, bytes = JSON.stringify({ value: next, mac: this.#sign(sessionRef, next) }) + "\n";
+    if (Buffer.byteLength(bytes) > MAX_BYTES) throw new Error("workspace-journal-full");
+    const temporary = path.join(this.#root, `.write-${randomBytes(16).toString("hex")}`);
+    let descriptor: number | undefined;
+    try {
+      descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+      fs.writeFileSync(descriptor, bytes); fs.fsyncSync(descriptor); fs.closeSync(descriptor); descriptor = undefined;
+      this.#checkDirectory(); fs.renameSync(temporary, this.#file(sessionRef));
+      const directory = fs.openSync(this.#root, fs.constants.O_RDONLY);
+      try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); }
+    } finally { if (descriptor !== undefined) fs.closeSync(descriptor); fs.rmSync(temporary, { force: true }); }
+  }
+}

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

@@ -0,0 +1,74 @@
+import type { SourceRevertProjection } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import { piSourceMutationGuard } from "../../piagent-core/runtime/policy/source-mutation-guard.ts";
+import type { BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+import { SourceRevertController } from "../server/source-revert-controller.ts";
+import type { CoreInspectionProvider } from "../server/core-inspection-provider.ts";
+import { SourceRevertStore } from "./source-revert-store.ts";
+import { sessionRefForPath } from "./session-catalog.ts";
+import type { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+
+type Options = { root: string; key: Buffer; managed: boolean;
+  runtimes: Pick<SessionRuntimeSupervisor, "listSessions" | "acquire" | "liveSessionManager" | "currentOperation">;
+  provider(sessionRef: string): Promise<CoreInspectionProvider>; changed(sessionRef: string): void };
+
+// The catalog ref selects a runtime. The inspection identity inside commands
+// remains independently bound to that runtime; the two refs need not be equal.
+export class SourceRevertSessions {
+  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 #live(sessionRef: string) {
+    const { runtimes, key } = this.#options;
+    if (this.#options.managed) 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);
+    if (!manager || manager.getSessionId() !== info.id) throw new Error("source-session-unavailable");
+    if (manager.buildSessionContext().model?.provider === "agent_watch_managed") throw new Error("source-company-boundary-required");
+    const provider = await this.#options.provider(sessionRef); provider.invalidate();
+    const snapshot = await provider.snapshot() as { identity: NonNullable<BridgeSnapshot["identity"]>; revision: NonNullable<BridgeSnapshot["revisions"]> };
+    if (snapshot.identity.taskId !== null || snapshot.identity.taskRunId !== null) throw new Error("source-session-binding-unavailable");
+    const binding = (): BridgeSnapshot => {
+      const current = runtimes.liveSessionManager(sessionRef), same = current === manager && current?.getSessionId() === info.id;
+      return { state: same ? "ready" : "replacement-pending", identity: snapshot.identity,
+        revisions: { ...snapshot.revision, controlRevision: piSourceMutationGuard.sessionControlRevision(info.cwd, info.id) },
+        taskState: "none", liveness: same ? runtimes.currentOperation(sessionRef) ? "running" : "idle" : "unknown", eventSequence: 0 };
+    };
+    return { info, provider, snapshot, binding };
+  }
+  sources(sessionRef: string) {
+    return this.#serial(sessionRef, async () => (await this.#live(sessionRef)).provider.sourceChanges("working-tree"));
+  }
+  diff(sessionRef: string, fileRef: string) {
+    return this.#serial(sessionRef, async () => (await this.#live(sessionRef)).provider.diff("working-tree", fileRef));
+  }
+  preview(sessionRef: string, fileRef: string, hunkRef: string | null) {
+    return this.#serial(sessionRef, async () => {
+      const { provider } = await this.#live(sessionRef);
+      const preview = await provider.sourceRevert(fileRef, hunkRef) as SourceRevertProjection;
+      const snapshot = await provider.snapshot() as { revision: { runtimeRevision: string; controlRevision: string | null } };
+      return { ...preview, ...(snapshot.revision.controlRevision ? { commandBinding: {
+        runtimeRevision: snapshot.revision.runtimeRevision, controlRevision: snapshot.revision.controlRevision } } : {}) };
+    });
+  }
+  execute(sessionRef: string, command: unknown) {
+    return this.#serial(sessionRef, async () => {
+      const { info, provider, snapshot, binding } = await this.#live(sessionRef);
+      const controller = new SourceRevertController({ allowSessionReverts: true, projectRoot: info.cwd, bridge: { snapshot: binding },
+        evidence: this.#store.forSession(info.cwd, snapshot.identity.projectRef, snapshot.identity.sessionRef),
+        resolve: (file, hunks) => provider.sourceRevertAuthority(file, hunks),
+        revisions: async () => { provider.invalidate(); return (await provider.snapshot() as typeof snapshot).revision; },
+        mutate: request => piSourceMutationGuard.executeRevert({ cwd: info.cwd, rawSessionId: info.id, ...request }) });
+      const receipt = await controller.execute(command);
+      if (receipt.phase !== "rejected") { provider.invalidate(); this.#options.changed(sessionRef); }
+      return receipt;
+    });
+  }
+}