@piagent/platform 1.4.1 → 1.5.2

package/packages/piagent-webui/dist/client/index.html

@@ -7,8 +7,8 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-bu7XpD9Q.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DwKCWbwd.css">
+    <script type="module" crossorigin src="/assets/index-CNbYWd-R.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BV-_03yl.css">
   </head>
   <body>
     <div id="root"></div>

package/packages/piagent-webui/extension/piagent-webui.ts

@@ -20,7 +20,7 @@ import { piSourceMutationGuard } from "../../piagent-core/runtime/policy/source-
 import { CoreInspectionProvider } from "../server/core-inspection-provider.ts";
 import type { SourceView } from "../server/read-model-provider.ts";
 import { SameSessionPiBridge, type BridgeTaskFacts } from "./same-session-bridge.ts";
-import { AttachmentStore } from "./attachment-store.ts";
+import { AttachmentStore } from "../../piagent-core/runtime/input/attachment-store.ts";
 import { HeldMessageQueue } from "./held-message-queue.ts";
 import { LifecycleController } from "./lifecycle-controller.ts";
 import { lifecycleRuntimeDraft } from "./lifecycle-event-adapter.ts";
@@ -78,6 +78,14 @@ function protectedPaths(ctx: ExtensionContext): string[] {
   } catch { return [".pi/piagent-state/**", ".pi/context-index.json"]; }
 }
 
+// The same profile grant `piagent_document_read` honours. Read from the profile
+// on every call rather than captured once, so an operator who adds a directory
+// mid-session sees it in the workspace without restarting Pi.
+function documentReadRoots(ctx: ExtensionContext): unknown {
+  try { return loadProjectContextIndexPolicy(PLATFORM_ROOT, ctx.cwd).profile.additionalReadRoots; }
+  catch { return []; }
+}
+
 function writeDescriptor(ctx: ExtensionContext, value: Record<string, unknown>): string {
   const directory = ensurePrivateStateDirectory(ctx.cwd, descriptorDirectory(ctx.cwd), "WebUI launcher directory");
   const target = resolveLocalStatePath(ctx.cwd, descriptorPath(ctx), { label: "WebUI launcher descriptor" });
@@ -144,6 +152,8 @@ function readMethod(provider: CoreInspectionProvider, queue: HeldMessageQueue, s
   if (method === "handoffHistory" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.handoffHistory(args[0]);
   if (method === "subagentTree" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.subagentTree(args[0]);
   if (method === "releaseMonitor" && args.length === 0) return provider.releaseMonitor();
+  if (method === "documents" && args.length === 0) return provider.documents();
+  if (method === "document" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.document(args[0]);
   if (method === "logPreview" && args.length === 1 && typeof args[0] === "string" && REF.test(args[0])) return provider.logPreview(args[0]);
   if (method === "transcript" && args.length === 2 && (args[0] === null || typeof args[0] === "string" && REF.test(args[0]))
     && Number.isInteger(args[1]) && Number(args[1]) >= 1 && Number(args[1]) <= 200) return provider.transcript(args[0] as string | null, Number(args[1]));
@@ -184,7 +194,9 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
   let approvalBinding: { key: string; unbind(): void; unsubscribe(): void } | null = null;
   const bridge = new SameSessionPiBridge(pi, { runtimeInstanceId, taskFacts,
     prepareAttachments: (refs, request, identity, text) => {
-      if (!attachments) throw new Error("attachment-store-unavailable"); return attachments.claim(refs, request, identity, text);
+      if (!attachments) throw new Error("attachment-store-unavailable");
+      const reservation = attachments.reserve(refs, request, identity, text);
+      return { ...reservation.prepared, commit: reservation.commit, release: reservation.release };
     } });
   try { attachments = new AttachmentStore({ runtimeInstanceId, bridgeSnapshot: () => bridge.snapshot(),
     modelSupportsImages: () => Array.isArray(currentContext?.model?.input) && currentContext.model.input.includes("image") }); }
@@ -301,6 +313,7 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
       task: () => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()),
       activityEvents: () => readContextTelemetry(ctx.cwd, { limit: 5_000 }) as unknown[],
       currentActivity: () => [], sessionEntries: () => ctx.sessionManager.getBranch(), protectedPaths: () => protectedPaths(ctx),
+      documentReadRoots: () => documentReadRoots(ctx),
       contextUsage: () => ctx.getContextUsage(), model: () => ctx.model,
       thinkingLevel: () => ctx.thinkingLevel ?? pi.getThinkingLevel(),
       queueProjection: () => queue.projection(),

package/packages/piagent-webui/extension/same-session-bridge.ts

@@ -5,11 +5,9 @@ import { webUiProjectRef, webUiSessionRef } from "../../piagent-core/runtime/ins
 export const WEBUI_CONTROL_ENTRY_TYPE = "piagent-webui-control-receipt-v1";
 const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/, PUBLIC_REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
 const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/, DIGEST = /^sha256:[a-f0-9]{64}$/;
-const IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/;
-const MAX_EVENTS = 256, MAX_SESSION_ENTRIES = 50_000; type NullableRef = string | null;
-export type BridgeIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null; agentOperationId: string | null; toolCallId: null };
-export type BridgeRevisions = { runtimeRevision: string; taskRevision: NullableRef; controlRevision: NullableRef; workspaceRevision: NullableRef;
-  indexRevision: NullableRef; approvalRevision: NullableRef; sessionOptionRevision: NullableRef; queueRevision: NullableRef };
+const IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/, MAX_EVENTS = 256, MAX_SESSION_ENTRIES = 50_000; type NullableRef = string | null;
+export type { BridgeIdentity, BridgeRevisions, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+import type { BridgeIdentity, BridgeRevisions, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
 export type BridgeTaskFacts = { taskId: string; taskRunId: string; taskRevision: string; controlRevision: string;
   controlState: "active" | "pause-requested" | "paused" | "terminal" | "unknown" } | null;
 export type NewOperationChatCommand = {
@@ -29,13 +27,11 @@ export type ChatReceipt = {
 };
 export type BridgeEvent = { sequence: number; at: string; kind: "binding.ready" | "binding.closed" | "operation.started" | "operation.settled" | "command.receipt";
   sessionRef: string | null; operationRef: string | null; commandId: string | null; resultCode: string | null };
-export type BridgeSnapshot = { state: "unbound" | "ready" | "replacement-pending" | "shutdown"; identity: BridgeIdentity | null; revisions: BridgeRevisions | null;
-  liveness: "idle" | "running" | "unknown"; taskState: "none" | "active" | "pause-requested" | "paused" | "terminal" | "unknown"; eventSequence: number };
 export type SessionOptionMutationPermit = { commitObservation(record: (before: BridgeRevisions, after: BridgeRevisions) => void): { before: BridgeRevisions; after: BridgeRevisions; recorded: boolean } | null; release(): void };
 type Binding = { ctx: ExtensionContext; rawSessionId: string; identity: BridgeIdentity; revisions: BridgeRevisions; state: BridgeSnapshot["state"] };
 type SessionOptionPermitState = { token: number; generation: number; rawSessionId: string; before: BridgeRevisions; externalConflict: boolean };
 type DispatchContent = Parameters<ExtensionAPI["sendUserMessage"]>[0];
-type PreparedDispatch = { content: DispatchContent; observedText: string };
+type PreparedDispatch = { content: DispatchContent; observedText: string; commit?(): void; release?(): void };
 type PendingDispatch = { command: NewOperationChatCommand; operationId: string; before: BridgeRevisions; leafBefore: string | null; correlationToken: string;
   observedText: string; resolve(receipt: ChatReceipt): void; timer: NodeJS.Timeout; inputObserved: boolean };
 type Stored = { receipt: ChatReceipt; messageRequestId?: string; contentDigest?: string; attachmentRefs?: string[] };
@@ -394,6 +390,7 @@ export class SameSessionPiBridge {
     this.#queueCounter += 1; const before = copy(binding.revisions); this.#refresh();
     const requested = this.#receipt(command, before, "requested", "dispatch-requested", null, false, operationId);
     if (!this.#record(requested, command.payload.messageRequestId, command.payload.contentDigest, command.payload.attachmentRefs)) {
+      prepared.release?.();
       if (delivery === "new-operation") {
         binding.identity.agentOperationId = null; this.#operationCounter += 1; this.#refresh();
       }
@@ -407,7 +404,10 @@ export class SameSessionPiBridge {
         correlationToken, observedText: prepared.observedText, resolve, timer, inputObserved: false };
       try { this.#dispatchContext.run(correlationToken, () => this.#pi.sendUserMessage(prepared.content,
         delivery === "new-operation" ? undefined : { deliverAs: delivery === "steer" ? "steer" : "followUp" })); }
-      catch { this.#settlePending("dispatch-rejected", "rejected", "pi-send-user-message-rejected", false); }
+      catch { prepared.release?.(); this.#messageRequests.delete(command.payload.messageRequestId);
+        this.#settlePending("dispatch-rejected", "rejected", "pi-send-user-message-rejected", false); return; }
+      try { prepared.commit?.(); }
+      catch { this.#settlePending("dispatch-unknown", "uncertain", "attachment-commit-unavailable", false); }
     });
   }
   #validate(command: NewOperationChatCommand): string | null {

package/packages/piagent-webui/gateway/ai-capability-inspection.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PACKAGE_NAME = "pi-web-access";
+const VERSION = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/;
+const MAX_PACKAGE_MANIFEST_BYTES = 32 * 1024;
+
+export type WebSearchCapabilityProjection = {
+  state: "configured" | "unavailable";
+  route: "codex-first" | "automatic" | null;
+  provider: "openai-codex" | null;
+  fallbackProvider: "exa" | null;
+  integration: { name: "pi-web-access"; version: string } | null;
+  reasonCode: string | null;
+};
+
+function installedWebAccess(agentDir: string | undefined): { name: "pi-web-access"; version: string } | null {
+  if (!agentDir) return null;
+  const root = path.resolve(agentDir), manifest = path.resolve(root, "npm", "node_modules", PACKAGE_NAME, "package.json");
+  if (path.relative(root, manifest).startsWith("..")) return null;
+  try {
+    const canonicalRoot = fs.realpathSync.native(root), canonicalManifest = fs.realpathSync.native(manifest);
+    const relative = path.relative(canonicalRoot, canonicalManifest);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+    const inspected = fs.lstatSync(manifest);
+    if (!inspected.isFile() || inspected.isSymbolicLink() || inspected.size < 2 || inspected.size > MAX_PACKAGE_MANIFEST_BYTES) return null;
+    const parsed = JSON.parse(fs.readFileSync(manifest, "utf8")) as { name?: unknown; version?: unknown };
+    if (parsed.name !== PACKAGE_NAME || typeof parsed.version !== "string" || parsed.version.length > 64 || !VERSION.test(parsed.version)) return null;
+    return { name: PACKAGE_NAME, version: parsed.version };
+  } catch {
+    return null;
+  }
+}
+
+export function inspectWebSearchCapability(input: {
+  agentDir?: string;
+  models: readonly Record<string, unknown>[];
+}): WebSearchCapabilityProjection {
+  const integration = installedWebAccess(input.agentDir);
+  if (!integration) return {
+    state: "unavailable", route: null, provider: null, fallbackProvider: null, integration: null,
+    reasonCode: "web-search-integration-not-installed"
+  };
+  const codexAvailable = input.models.some((model) => model.provider === "openai-codex");
+  return {
+    state: "configured",
+    route: codexAvailable ? "codex-first" : "automatic",
+    provider: codexAvailable ? "openai-codex" : null,
+    fallbackProvider: "exa",
+    integration,
+    reasonCode: codexAvailable ? null : "codex-auth-not-available"
+  };
+}

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

@@ -4,6 +4,7 @@ import path from "node:path";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import type { PiagentGatewayCapabilityHandshakeV1 } from "../contracts/generated/gateway-capabilities-v1.ts";
+import type { PiagentWebUICanonicalSnapshotV1 } from "../contracts/generated/snapshot-v1.ts";
 import { startLoopbackServer } from "../server/loopback-server.ts";
 import { startGatewayControlSocket, type GatewayControlResponse } from "./control-socket.ts";
 import { loadPinnedPiHost } from "./pi-host.ts";
@@ -24,6 +25,7 @@ import { SessionCommandStore } from "./session-command-store.ts";
 import { SessionCommandController } from "./session-command-controller.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionInspectionRegistry } from "./session-inspection-registry.ts";
+import { SessionAttachmentRegistry } from "./session-attachment-registry.ts";
 import { ProjectRegistry } from "./project-registry.ts";
 import { pickNativeProjectFolders } from "./native-project-picker.ts";
 import { ProviderAuthBroker } from "./provider-auth-broker.ts";
@@ -91,6 +93,7 @@ export async function startPiagentGateway(options: {
   let control: Awaited<ReturnType<typeof startGatewayControlSocket>> | null = null;
   let runtimes: SessionRuntimeSupervisor | null = null;
   let mcpAuth: McpAuthBroker | null = null;
+  let attachments: SessionAttachmentRegistry | null = null;
   let closing: Promise<void> | null = null;
   let settleWait: (() => void) | null = null;
   const waited = new Promise<void>((resolve) => { settleWait = resolve; });
@@ -100,6 +103,10 @@ export async function startPiagentGateway(options: {
     closing = (async () => {
       removeGatewayDescriptor(state, gatewayInstanceRef);
       await loopback?.close().catch(() => undefined);
+      // Staged bytes are private temp files. Closing deletes them rather than
+      // leaving a directory per session behind for the TTL sweep that will never
+      // run once this process is gone.
+      try { attachments?.close(); } catch { /* shutdown never fails on cleanup */ }
       await mcpAuth?.close().catch(() => undefined);
       await runtimes?.close().catch(() => undefined);
       await control?.close().catch(() => undefined);
@@ -161,11 +168,23 @@ export async function startPiagentGateway(options: {
       return { sessionRevision: session.sessionRevision, liveState: session.liveState };
     });
     const commands = new SessionCommandController({ catalog: readCatalog, runtimes, metadata,
-      store: new SessionCommandStore(state.root, key), events });
+      store: new SessionCommandStore(state.root, key), events,
+      // Resolved at call time: the attachment registry is built after this
+      // 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);
+      } });
     const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true), catalog: readCatalog,
       events, command: commands });
-    const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot,
-      models: inspectionModels, projects, mcpAuth });
+    const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
+      models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
+      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef) });
+    // Staged bytes live beside the inspection projection they were checked
+    // against, so both read the same session through the same registry.
+    attachments = new SessionAttachmentRegistry({
+      inspect: async (sessionRef) => await (await inspections.provider(sessionRef)).snapshot() as PiagentWebUICanonicalSnapshotV1
+    });
     loopback = await startLoopbackServer({
       staticRoot,
       mode: "gateway",
@@ -175,6 +194,7 @@ export async function startPiagentGateway(options: {
       readSessionModel: (sessionRef) => inspections.provider(sessionRef),
       readSessionConnections: (sessionRef) => inspections.connections(sessionRef),
       executeSessionConnection: (command) => inspections.executeConnectionCommand(command),
+      executeSessionAttachment: (sessionRef, command) => attachments.execute(sessionRef, command),
       executeApproval: (approvalRef, decision) => runtimes!.decideApproval(approvalRef, decision),
       readMcpAuthJob: (jobRef) => mcpAuth!.read(jobRef),
       cancelMcpAuthJob: (jobRef) => mcpAuth!.cancel(jobRef),

package/packages/piagent-webui/gateway/native-project-picker.ts

@@ -1,10 +1,27 @@
 import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-export function nativeProjectPickerAvailable(): boolean { return process.platform === "darwin"; }
+type PickerSpec = { executable: string; args: string[] };
+type PickerEnvironment = Readonly<Record<string, string | undefined>>;
 
-export function pickNativeProjectFolders(): Promise<string[]> {
-  if (!nativeProjectPickerAvailable()) return Promise.reject(new Error("native-project-picker-unavailable"));
-  return new Promise((resolve, reject) => {
+function executableOnPath(name: string, environment: PickerEnvironment): string | null {
+  for (const directory of String(environment.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(directory, name);
+    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* try the next PATH entry */ }
+  }
+  return null;
+}
+
+// The browser deliberately cannot reveal an absolute directory path. The
+// Gateway therefore uses the desktop's own picker and receives only the paths
+// the operator selected. macOS ships AppleScript; Linux desktops commonly ship
+// one of the freedesktop-facing dialog helpers below.
+export function resolveNativeProjectPicker(options: { platform?: NodeJS.Platform; environment?: PickerEnvironment } = {}): PickerSpec | null {
+  const platform = options.platform ?? process.platform, environment = options.environment ?? process.env;
+  if (platform === "darwin") {
+    try { fs.accessSync("/usr/bin/osascript", fs.constants.X_OK); } catch { return null; }
     const script = [
       'set chosenFolders to choose folder with prompt "Choose project folders for Piagent" with multiple selections allowed',
       'set output to ""',
@@ -13,9 +30,48 @@ export function pickNativeProjectFolders(): Promise<string[]> {
       'end repeat',
       'return output'
     ].join("\n");
-    execFile("/usr/bin/osascript", ["-e", script], { timeout: 5 * 60_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
-      if (error) { reject(new Error("project-import-cancelled")); return; }
-      const selected = [...new Set(stdout.split("\n").map((value) => value.trim()).filter(Boolean))].slice(0, 32);
+    return { executable: "/usr/bin/osascript", args: ["-e", script] };
+  }
+  if (platform !== "linux" || !(environment.DISPLAY || environment.WAYLAND_DISPLAY)) return null;
+  for (const name of ["zenity", "qarma"]) {
+    const executable = executableOnPath(name, environment);
+    if (executable) return { executable, args: ["--file-selection", "--directory", "--multiple", "--separator=\n",
+      "--title=Choose project folders for Piagent"] };
+  }
+  const kdialog = executableOnPath("kdialog", environment);
+  return kdialog ? { executable: kdialog, args: ["--getexistingdirectory", process.cwd(), "--title", "Choose a project folder for Piagent"] } : null;
+}
+
+export function nativeProjectPickerAvailable(options: { platform?: NodeJS.Platform; environment?: PickerEnvironment } = {}): boolean {
+  return resolveNativeProjectPicker(options) !== null;
+}
+
+function selectedFolders(stdout: string): string[] {
+  const selected: string[] = [];
+  for (const raw of stdout.split("\n")) {
+    const value = raw.trim(); if (!value) continue;
+    let candidate = value;
+    if (value.startsWith("file:")) {
+      try { candidate = fileURLToPath(value); } catch { continue; }
+    }
+    if (candidate.includes("\0") || /[\u0001-\u001f\u007f]/.test(candidate) || selected.includes(candidate)) continue;
+    selected.push(candidate);
+    if (selected.length === 32) break;
+  }
+  return selected;
+}
+
+export function pickNativeProjectFolders(): Promise<string[]> {
+  const picker = resolveNativeProjectPicker();
+  if (!picker) return Promise.reject(new Error("native-project-picker-unavailable"));
+  return new Promise((resolve, reject) => {
+    execFile(picker.executable, picker.args, { timeout: 5 * 60_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+      if (error) {
+        const exitCode = typeof (error as NodeJS.ErrnoException & { code?: unknown }).code === "number"
+          ? (error as unknown as { code: number }).code : null;
+        reject(new Error(exitCode === 1 ? "project-import-cancelled" : "project-import-picker-failed")); return;
+      }
+      const selected = selectedFolders(stdout);
       if (!selected.length) { reject(new Error("project-import-cancelled")); return; }
       resolve(selected);
     });

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

@@ -0,0 +1,165 @@
+import type { PiagentWebUICanonicalSnapshotV1 } from "../contracts/generated/snapshot-v1.ts";
+import { AttachmentStore, type DiscardReceipt, type PreparedAttachments,
+  type StageReceipt } from "../../piagent-core/runtime/input/attachment-store.ts";
+import type { AttachmentReservation } from "../../piagent-core/runtime/input/attachment-reservation.ts";
+import type { BridgeIdentity, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+
+// Attachments for sessions the Gateway drives.
+//
+// The in-session WebUI stages attachments against a live `SameSessionPiBridge`,
+// which knows the identity and revisions of the session it is bound to. The
+// Gateway has no such bridge: it owns many sessions and reads each one through
+// an inspection provider. What it does have is the exact snapshot the browser
+// was given, and that snapshot carries the same identity and revisions the
+// browser will quote back in a stage command.
+//
+// So the bridge the store needs is synthesised from that snapshot, immediately
+// before the store reads it. The store's identity and revision checks then
+// compare the browser's claim against the same projection the browser was
+// answering, which is the property those checks exist to enforce — a command
+// aimed at a session that has since changed is refused rather than applied to
+// whatever the session became.
+
+const MAX_SESSION_STORES = 16;
+
+function bridgeIdentity(snapshot: PiagentWebUICanonicalSnapshotV1): BridgeIdentity {
+  const identity = snapshot.identity;
+  return { projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId, sessionRef: identity.sessionRef,
+    taskId: identity.taskId ?? null, taskRunId: identity.taskRunId ?? null, agentOperationId: identity.agentOperationId ?? null,
+    toolCallId: null };
+}
+
+function bridgeSnapshotOf(snapshot: PiagentWebUICanonicalSnapshotV1): BridgeSnapshot {
+  const revision = snapshot.revision;
+  // A terminal session refuses staging inside the store. Everything else the
+  // Gateway can answer for is a session the operator may still attach to.
+  const controlState = snapshot.session.controlState;
+  return {
+    state: "ready",
+    identity: bridgeIdentity(snapshot),
+    revisions: { runtimeRevision: revision.runtimeRevision, taskRevision: revision.taskRevision ?? null,
+      controlRevision: revision.controlRevision ?? null, workspaceRevision: revision.workspaceRevision ?? null,
+      indexRevision: revision.indexRevision ?? null, approvalRevision: revision.approvalRevision ?? null,
+      sessionOptionRevision: revision.sessionOptionRevision ?? null, queueRevision: revision.queueRevision ?? null },
+    liveness: snapshot.session.operation.liveness === "running" ? "running" : "idle",
+    taskState: controlState === "terminal" ? "terminal" : controlState === "active" ? "active" : "unknown",
+    eventSequence: 0
+  };
+}
+
+function supportsImages(snapshot: PiagentWebUICanonicalSnapshotV1): boolean {
+  const model = snapshot.session.model;
+  // The contract types this as a tuple union to bound its length, which leaves
+  // includes() narrowed to never. The runtime value is a list of strings.
+  const capabilities = model.value?.inputCapabilities as readonly string[] | undefined;
+  return model.state === "known" && Boolean(capabilities?.includes("image"));
+}
+
+type Slot = { store: AttachmentStore; current: BridgeSnapshot; images: boolean };
+
+export class SessionAttachmentRegistry {
+  readonly #slots = new Map<string, Slot>();
+  readonly #inspect: (sessionRef: string) => Promise<PiagentWebUICanonicalSnapshotV1>;
+  readonly #tempRoot: string | undefined;
+  readonly #now: (() => Date) | undefined;
+  #closed = false;
+
+  constructor(options: { inspect: (sessionRef: string) => Promise<PiagentWebUICanonicalSnapshotV1>; tempRoot?: string; now?: () => Date }) {
+    this.#inspect = options.inspect;
+    this.#tempRoot = options.tempRoot;
+    this.#now = options.now;
+  }
+
+  // Every entry point refreshes the synthesised bridge first. A store that kept
+  // the snapshot it was created with would accept a command aimed at a revision
+  // the session has already moved past.
+  async #slot(sessionRef: string): Promise<Slot> {
+    if (this.#closed) throw new Error("session-attachment-registry-closed");
+    const snapshot = await this.#inspect(sessionRef);
+    const existing = this.#slots.get(sessionRef);
+    if (existing) {
+      existing.current = bridgeSnapshotOf(snapshot);
+      existing.images = supportsImages(snapshot);
+      // Refresh recency so the cap evicts the least recently used session.
+      this.#slots.delete(sessionRef); this.#slots.set(sessionRef, existing);
+      return existing;
+    }
+    const slot: Slot = { current: bridgeSnapshotOf(snapshot), images: supportsImages(snapshot), store: null as unknown as AttachmentStore };
+    slot.store = new AttachmentStore({
+      runtimeInstanceId: snapshot.identity.runtimeInstanceId,
+      bridgeSnapshot: () => slot.current,
+      modelSupportsImages: () => slot.images,
+      tempRoot: this.#tempRoot,
+      now: this.#now
+    });
+    this.#slots.set(sessionRef, slot);
+    // Each store owns a private directory and staged bytes, so an unbounded map
+    // is unbounded disk. The evicted store deletes what it held.
+    while (this.#slots.size > MAX_SESSION_STORES) {
+      const oldest = this.#slots.keys().next().value as string;
+      if (oldest === sessionRef) break;
+      this.#slots.get(oldest)?.store.close();
+      this.#slots.delete(oldest);
+    }
+    return slot;
+  }
+
+  async execute(sessionRef: string, command: unknown): Promise<StageReceipt | DiscardReceipt> {
+    return (await this.#slot(sessionRef)).store.execute(command);
+  }
+
+  async capability(sessionRef: string): Promise<{ kinds: Array<"file" | "image" | "document">; mimeTypes: string[] }> {
+    return (await this.#slot(sessionRef)).store.capability();
+  }
+
+  // Claimed at dispatch, from the send path, which already holds the identity it
+  // is sending under. Refs are one-shot: a claim consumes them.
+  async claim(sessionRef: string, refs: string[], messageRequestId: string, text: string): Promise<PreparedAttachments> {
+    const slot = await this.#slot(sessionRef);
+    if (!slot.current.identity) throw new Error("session-attachment-identity-unavailable");
+    return slot.store.claim(refs, messageRequestId, slot.current.identity, text);
+  }
+
+  async reserve(sessionRef: string, refs: string[], messageRequestId: string, text: string): Promise<AttachmentReservation<PreparedAttachments>> {
+    const slot = await this.#slot(sessionRef);
+    if (!slot.current.identity) throw new Error("session-attachment-identity-unavailable");
+    return slot.store.reserve(refs, messageRequestId, slot.current.identity, text);
+  }
+
+  // The shape the host prompt takes. Documents and text files were already
+  // turned into text when they were staged, so they join the prompt string;
+  // images ride the host's own `images` channel. Split here rather than in the
+  // supervisor so the knowledge of what a claim returns stays next to the store
+  // that produced it.
+  async claimForPrompt(sessionRef: string, refs: string[], messageRequestId: string, message: string):
+  Promise<{ text: string; images: unknown[] }> {
+    if (refs.length === 0) return { text: message, images: [] };
+    const prepared = await this.claim(sessionRef, refs, messageRequestId, message);
+    const parts = Array.isArray(prepared.content) ? prepared.content : [{ type: "text" as const, text: message }];
+    return {
+      text: parts.filter((part) => part.type === "text").map((part) => part.text).join("\n"),
+      images: parts.filter((part) => part.type === "image")
+    };
+  }
+
+
+  async reserveForPrompt(sessionRef: string, refs: string[], messageRequestId: string, message: string):
+  Promise<{ text: string; images: unknown[]; commit(): void; release(): void }> {
+    if (refs.length === 0) return { text: message, images: [], commit() {}, release() {} };
+    const reservation = await this.reserve(sessionRef, refs, messageRequestId, message);
+    const parts = Array.isArray(reservation.prepared.content) ? reservation.prepared.content
+      : [{ type: "text" as const, text: message }];
+    return {
+      text: parts.filter((part) => part.type === "text").map((part) => part.text).join("\n"),
+      images: parts.filter((part) => part.type === "image"),
+      commit: reservation.commit,
+      release: reservation.release
+    };
+  }
+
+  close(): void {
+    this.#closed = true;
+    for (const slot of this.#slots.values()) slot.store.close();
+    this.#slots.clear();
+  }
+}

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

@@ -13,6 +13,7 @@ export type PiSessionInfo = {
   id: string;
   cwd: string;
   name?: string;
+  parentSessionPath?: string;
   created: Date;
   modified: Date;
   messageCount: number;
@@ -20,6 +21,26 @@ export type PiSessionInfo = {
   allMessagesText: string;
 };
 
+const DELEGATED_TASK_MARKERS = [
+  "Task: You are a delegated subagent running from a fork of the parent session.",
+  "Task: You are reviving a previous subagent conversation."
+] as const;
+const INTERNAL_HELPER_NAME = /^(?:subagent(?:-|$)|piagent-(?:planner|worker|scout|reviewer|oracle)(?:-|$))/i;
+
+export function isUserConversationSession(info: PiSessionInfo): boolean {
+  const segments = path.resolve(info.path).split(path.sep);
+  const sessionsIndex = segments.lastIndexOf("sessions");
+  if (sessionsIndex >= 0 && segments[sessionsIndex + 1] === "subagent") return false;
+  const internalName = INTERNAL_HELPER_NAME.test(String(info.name ?? "").trim());
+  const hasParent = typeof info.parentSessionPath === "string" && info.parentSessionPath.length > 0;
+  const messages = typeof info.allMessagesText === "string" ? info.allMessagesText : "";
+  const internalPrompt = DELEGATED_TASK_MARKERS.some((marker) => messages.includes(marker));
+  // User-created forks also carry parentSessionPath, so lineage alone is not enough. A helper identity or the
+  // runtime-only delegation prompt plus lineage is high-confidence internal evidence. Keep this classification
+  // at the gateway boundary so catalog, read models, commands and live streams all fail closed together.
+  return !((internalName && (hasParent || internalPrompt)) || (hasParent && internalPrompt));
+}
+
 function catalogRef(key: Buffer, namespace: string, value: string): string {
   return `${namespace}_${createHmac("sha256", key).update(value).digest("base64url").slice(0, 43)}`;
 }
@@ -33,6 +54,43 @@ function display(value: unknown, maximum: number, fallback: string): string {
   return (clean || fallback).slice(0, maximum);
 }
 
+const INTERNAL_FRESH_TRANSITION = /(?:^|\b)(?:\/fresh\s+(?:task|scout|be-to-fe)|(?:task|scout|be-to-fe):)\b[\s\S]{0,180}\bRead task intake from \.pi\/task-inbox\//i;
+
+function atWordBoundary(value: string, maximum: number): string {
+  if (value.length <= maximum) return value;
+  const slice = value.slice(0, maximum + 1), boundary = slice.lastIndexOf(" ");
+  return `${slice.slice(0, boundary >= Math.floor(maximum * .6) ? boundary : maximum).trim()}…`;
+}
+
+// Session titles are a local deterministic projection. Asking a model to name
+// every chat would spend a turn and make opening the catalog non-deterministic.
+// Runtime routing commands are control-plane text, so they must never become a
+// title or preview merely because Pi records them as the first user entry.
+export function projectedSessionTitle(info: Pick<PiSessionInfo, "name" | "firstMessage" | "cwd">): { title: string; preview: string } {
+  const projectLabel = display(info.cwd ? path.basename(info.cwd) : "", 120, "Unknown project");
+  const first = info.firstMessage === "(no messages)" ? "" : display(info.firstMessage, 500, "");
+  const rawName = display(info.name, 500, ""), generatedName = /^pi:/i.test(rawName);
+  const suppliedName = rawName.replace(/^pi:\s*/i, "");
+  const normalizedName = suppliedName.toLowerCase();
+  const genericName = !suppliedName || normalizedName === projectLabel.toLowerCase()
+    || ["working", "pi agent platform", "new conversation"].includes(normalizedName);
+  const source = generatedName ? suppliedName || first : genericName ? first || suppliedName : suppliedName;
+  const internal = INTERNAL_FRESH_TRANSITION.test(source) || INTERNAL_FRESH_TRANSITION.test(first)
+    || /\.pi\/task-inbox\//i.test(source);
+  const cleaned = display(source, 500, "")
+    .replace(/^\/(?:fresh\s+)?(?:task|scout|be-to-fe)\s+/i, "")
+    .replace(/^(?:task|scout|be-to-fe):\s*/i, "")
+    .replace(/^[-#*>\s]+/, "")
+    // Keep underscores: the shared redactor deliberately emits
+    // [REDACTED_SECRET], and title cleanup must not mutate that proof marker.
+    .replace(/[`*~]+/g, "")
+    .trim();
+  const title = internal ? "Continued task" : atWordBoundary(cleaned || "New conversation", 72);
+  const preview = INTERNAL_FRESH_TRANSITION.test(first) || /\.pi\/task-inbox\//i.test(first)
+    ? "Continued in a fresh session" : atWordBoundary(first || title, 180);
+  return { title, preview };
+}
+
 function revision(key: Buffer, value: unknown): string {
   return `rev_${createHmac("sha256", key).update(JSON.stringify(value)).digest("hex")}`;
 }
@@ -40,18 +98,13 @@ function revision(key: Buffer, value: unknown): string {
 function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undefined, metadataReason: string | null,
   ownership?: SessionOwnerProjection, sessionOptions?: SessionOptionProjection): SessionRow {
   const projectLabel = display(info.cwd ? path.basename(info.cwd) : "", 120, "Unknown project");
-  const first = info.firstMessage === "(no messages)" ? "" : info.firstMessage;
-  const suppliedName = display(info.name, 500, "").replace(/^pi:\s*/i, "");
-  const normalizedName = suppliedName.toLowerCase();
-  const genericName = !suppliedName || normalizedName === projectLabel.toLowerCase()
-    || ["working", "pi agent platform", "new conversation"].includes(normalizedName);
-  const title = display(genericName && first ? first : suppliedName || first, 500, "New conversation").replace(/^pi:\s*/i, "") || "New conversation";
+  const projected = projectedSessionTitle(info);
   return {
     sessionRef: sessionRefForPath(key, info.path),
     projectRef: projectRefForCwd(key, info.cwd),
-    title,
+    title: projected.title,
     projectLabel,
-    preview: display(first, 280, "No messages yet"),
+    preview: projected.preview,
     createdAt: info.created.toISOString(),
     updatedAt: info.modified.toISOString(),
     state: metadata?.archived ? "archived" : ownership?.state ?? "offline",
@@ -87,7 +140,7 @@ export async function buildSessionCatalog(options: {
 }): Promise<Catalog> {
   const limit = Math.max(1, Math.min(200, options.limit ?? 200));
   try {
-    const found = await options.listSessions();
+    const found = (await options.listSessions()).filter(isUserConversationSession);
     const metadata = options.readMetadata?.() ?? { state: "ready", revision: null, sessions: new Map(), reasonCode: null };
     const sessions = found.map((info) => {
       const sessionRef = sessionRefForPath(options.key, info.path);