@piagent/platform 1.7.1 → 1.9.0

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

@@ -15,6 +15,7 @@ type RuntimeCommandOutput = {
 
 export async function executePermissionCommand(session: any,
   permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<void> {
+  if (session.managedExecution) throw new Error("managed-permissions-controlled-by-studio");
   const before = Array.isArray(session.messages) ? session.messages.length : 0;
   await session.prompt(`/permission ${permissionMode}`);
   const messages = Array.isArray(session.messages) ? session.messages.slice(before) : [];
@@ -28,17 +29,19 @@ export async function executeRuntimeCommand(session: any, command: string): Prom
   outputs: RuntimeCommandOutput[];
   modelCallObserved: boolean;
 }> {
+  if (session.managedExecution) throw new Error("managed-runtime-command-unavailable");
   const before = Array.isArray(session.messages) ? session.messages.length : 0;
   await session.prompt(command);
   const added = Array.isArray(session.messages) ? session.messages.slice(before) : [];
   const outputs = added.filter((message: any) => message?.role === "custom").slice(-8).map((message: any) => {
     const source = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? "");
-    const bounded = source.slice(0, 12_000), redacted = redactSensitiveText(bounded);
+    // Redact all of it, then bound it: cutting first can leave the front of a credential.
+    const full = redactSensitiveText(source), bounded = full.text.slice(0, 12_000), redacted = { text: bounded, redacted: full.redacted };
     const rawType = String(message.customType ?? "runtime-output");
     const details = rawType === PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE
       ? parseServiceTierReceipt(message.details) : null;
     return { customType: /^[A-Za-z0-9._-]{1,120}$/.test(rawType) ? rawType : "runtime-output", content: redacted.text,
-      truncated: source.length > bounded.length, redacted: redacted.redacted, ...(details ? { details } : {}) };
+      truncated: full.text.length > bounded.length, redacted: redacted.redacted, ...(details ? { details } : {}) };
   });
   return { outputs, modelCallObserved: added.some((message: any) => message?.role === "assistant") };
 }

package/packages/piagent-webui/gateway/session-approval-authority.ts

@@ -0,0 +1,28 @@
+import { createHmac } from "node:crypto";
+import { webUiTaskRevision } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
+import { inspectTaskControlState } from "../../piagent-core/runtime/inspection/task-control-journal.ts";
+import { projectRefForCwd } from "./session-catalog.ts";
+import type { ApprovalAuthority } from "../../piagent-core/runtime/inspection/approval-broker.ts";
+import type { ActiveRuntime } from "./session-runtime-state.ts";
+
+export function sessionApprovalAuthority(key: Buffer, sessionRef: string, active: ActiveRuntime): ApprovalAuthority {
+      if (!active.operationRef || active.lease.state !== "gateway-owned" || !active.lease.revision) return null;
+      const task = activeSessionTask(active.info.cwd, active.info.id);
+      const synthetic = (namespace: string) => `${namespace}_${createHmac("sha256", key)
+        .update(`${sessionRef}\0${namespace}`).digest("base64url").slice(0, 43)}`;
+      const control = task ? inspectTaskControlState(active.info.cwd, task) : null;
+      return {
+        identity: {
+          projectRef: projectRefForCwd(key, active.info.cwd), runtimeInstanceId: active.lease.runtimeInstanceRef!, sessionRef,
+          taskId: task?.taskId ?? synthetic("task"), taskRunId: task?.taskRunId ?? synthetic("task_run"),
+          agentOperationId: active.operationRef
+        },
+        revisions: {
+          runtimeRevision: active.lease.revision,
+          taskRevision: task ? webUiTaskRevision(task) : synthetic("task_rev"),
+          controlRevision: control?.controlRevision ?? synthetic("control_rev")
+        },
+        taskState: control?.state === "terminal" ? "terminal" : "active"
+      };
+    }

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

@@ -47,7 +47,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">;
+export type SessionOptionProjection = Pick<SessionRow, "modelLabel" | "thinkingLevel" | "managedHelpers" | "managedThinkingLevels" | "managedPlan" | "managedProcess">;
 
 function display(value: unknown, maximum: number, fallback: string): string {
   const clean = redactSensitiveText(String(value ?? "")).text
@@ -80,7 +80,10 @@ export function projectedSessionTitle(info: Pick<PiSessionInfo, "name" | "firstM
   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;
+  // The guard names every unnamed session `pi:<project>` at start. That is the
+  // project, not the conversation: like any generic name it yields to the first
+  // message, otherwise every chat in a folder reads as the folder name.
+  const source = generatedName || 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, "")
@@ -120,6 +123,11 @@ function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undef
     unread: metadata?.unread ?? false,
     composerAvailable: metadata?.archived ? false : ownership?.composerAvailable ?? false,
     needsAttention: metadata?.archived ? false : ownership?.needsAttention ?? false,
+    ...(sessionOptions?.managedHelpers ? {managedHelpers:{...sessionOptions.managedHelpers,
+      active: ownership?.liveState === 'idle' ? 0 : ownership?.liveState === 'running' || ownership?.liveState === 'waiting-approval' ? sessionOptions.managedHelpers.active : null}} : {}),
+    ...(sessionOptions?.managedThinkingLevels ? {managedThinkingLevels:sessionOptions.managedThinkingLevels} : {}),
+    ...(sessionOptions?.managedPlan ? {managedPlan:sessionOptions.managedPlan} : {}),
+    ...(sessionOptions?.managedProcess ? {managedProcess:sessionOptions.managedProcess} : {}),
     modelLabel: sessionOptions?.modelLabel ?? null,
     thinkingLevel: sessionOptions?.thinkingLevel ?? "unknown",
     contextUsage: { usedTokens: null, contextWindow: null, ratio: null, state: "unknown" },
@@ -128,7 +136,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?.modelLabel ?? null, sessionOptions?.thinkingLevel ?? "unknown", sessionOptions?.managedHelpers, sessionOptions?.managedThinkingLevels, sessionOptions?.managedPlan, sessionOptions?.managedProcess,
       metadata?.archived ? "archived" : ownership ? [ownership.state, ownership.liveState, ownership.owner.kind,
         ownership.owner.ownerEpoch, ownership.owner.runtimeInstanceRef, ownership.reasonCode] : "offline"]),
     reasonCode: metadata?.archived ? metadataReason : ownership?.reasonCode ?? metadataReason

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

@@ -139,8 +139,14 @@ export class SessionCommandController {
     const now = this.#now().getTime();
     if (Date.parse(command.requestedAt) > now + 30_000) return this.#rejected(command, current, row, "invalid-command", "requested-at-in-future");
     if (now > Date.parse(command.expiresAt)) return this.#rejected(command, current, row, "expired", "session-command-expired");
-    const stale = command.expectedCatalogRevision !== current.catalogRevision || (command.action === "session.create"
-      ? command.expectedSessionRevision !== null : !row || command.expectedSessionRevision !== row.sessionRevision);
+    // A command is outdated when its own conversation changed, not when another
+    // one did: with many conversations running the catalog changes every few
+    // seconds, and a new conversation depends on none of them.
+    // Stop names the exact operation, and the runtime refuses any other one: a
+    // running turn changes its conversation after every step, so Stop is not
+    // bound to the revision the page last read.
+    const stale = command.action === "session.create" ? command.expectedSessionRevision !== null
+      : command.action === "session.abort" ? !row : !row || command.expectedSessionRevision !== row.sessionRevision;
     if (stale) {
       return this.#rejected(command, current, row, "stale-revision", "session-revision-stale");
     }

package/packages/piagent-webui/gateway/session-file-facts.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+
+type Known<T> = { mtimeMs: number; size: number; ino: number; facts: T };
+const LIMIT = 20_000;
+
+// The catalog is rebuilt for every page refresh and every command, and each
+// build opened and parsed every conversation file to learn its model and
+// thinking level: about a second of blocked Gateway for 900 files, several
+// seconds on a busy machine, while Stop and Send waited behind it. What a file
+// says changes only when the file does, so its facts are kept until its size,
+// modification time or inode changes. The file is checked before it is read:
+// a write that lands during the read is seen as a change on the next call.
+export function cachedSessionFacts<T>(read: (file: string) => T): (file: string) => T {
+  const cache = new Map<string, Known<T>>();
+  return (file) => {
+    let stat: fs.Stats;
+    try { stat = fs.statSync(file); } catch { cache.delete(file); return read(file); }
+    const known = cache.get(file);
+    if (known && known.mtimeMs === stat.mtimeMs && known.size === stat.size && known.ino === stat.ino) return known.facts;
+    const facts = read(file);
+    if (cache.size >= LIMIT) cache.clear();
+    cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, ino: stat.ino, facts });
+    return facts;
+  };
+}

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

@@ -37,7 +37,7 @@ type ModelRuntime = {
   getAvailableSnapshot(): readonly Record<string, unknown>[];
 };
 
-type ProjectSource = { list(): Array<{ projectRef: string; placeRef: string; label: string }> };
+type ProjectSource = { list(): Array<{ projectRef: string; placeRef: string; label: string }>; resolve?(projectRef: string): string | null };
 
 const CACHE_LIMIT = 32;
 const PUBLIC_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
@@ -57,6 +57,18 @@ function safeRead<T>(read: () => T, fallback: T): T {
   try { return read(); } catch { return fallback; }
 }
 
+// Parent folders as a member reads them: under the home folder with "~", and
+// the last two of their folders, or as many as it takes to tell them apart.
+export function projectLocations(parents: readonly string[]): string[] {
+  const home = process.env.HOME ?? "";
+  const parts = parents.map((parent) => (home && (parent === home || parent.startsWith(`${home}/`)) ? `~${parent.slice(home.length)}` : parent)
+    .split("/").filter(Boolean));
+  const longest = Math.max(1, ...parts.map((list) => list.length));
+  let take = Math.min(2, longest);
+  while (take < longest && new Set(parts.map((list) => list.slice(-take).join("/"))).size < parts.length) take += 1;
+  return parts.map((list) => (list.length > take ? `…/${list.slice(-take).join("/")}` : list[0] === "~" ? list.join("/") : `/${list.join("/")}`));
+}
+
 function safeName(value: unknown): string {
   return redactSensitiveText(String(value ?? "")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 120)
     || "Unnamed connection";
@@ -184,15 +196,26 @@ export class SessionInspectionRegistry {
 
   async creationOptions(): Promise<unknown> {
     const sessions = (await this.#listSessions()).filter(isUserConversationSession);
-    const projects = new Map<string, { projectRef: string; placeRef: string; label: string }>();
+    const projects = new Map<string, { projectRef: string; placeRef: string; label: string; hint?: string }>(), folders = new Map<string, string>();
     for (const info of sessions) {
       if (!info.cwd) continue;
       const projectRef = projectRefForCwd(this.#key, info.cwd);
       if (!projects.has(projectRef)) projects.set(projectRef, { projectRef, placeRef: projectRef,
         label: safeName(path.basename(info.cwd) || "Project") });
+      folders.set(projectRef, info.cwd);
     }
     for (const project of safeRead(() => this.#projects?.list() ?? [], [])) {
-      if (!projects.has(project.projectRef)) projects.set(project.projectRef, project);
+      if (!projects.has(project.projectRef)) projects.set(project.projectRef, { ...project });
+      const cwd = safeRead(() => this.#projects?.resolve?.(project.projectRef) ?? null, null);
+      if (cwd && !folders.has(project.projectRef)) folders.set(project.projectRef, cwd);
+    }
+    // Two folders with the same name are told apart by where they are.
+    const byLabel = new Map<string, Array<{ projectRef: string; hint?: string }>>();
+    for (const project of projects.values()) byLabel.set(project.label, [...(byLabel.get(project.label) ?? []), project]);
+    for (const group of byLabel.values()) {
+      if (group.length < 2) continue;
+      const hints = projectLocations(group.map((project) => path.dirname(folders.get(project.projectRef) ?? "")));
+      group.forEach((project, index) => { if (folders.has(project.projectRef)) project.hint = safeName(hints[index]); });
     }
     const availableModels = (this.#models?.getAvailableSnapshot() ?? []).slice(0, 300);
     const profiles = safeRead(() => fs.readdirSync(path.join(this.#packageRoot, "adapters")).flatMap((entry) => {
@@ -211,21 +234,21 @@ export class SessionInspectionRegistry {
       if (!provider || !modelId || typeof value.reasoning !== "boolean") return [];
       const mapping = value.thinkingLevelMap && typeof value.thinkingLevelMap === "object"
         ? value.thinkingLevelMap as Record<string, unknown> : {};
-      const thinkingLevels = value.reasoning ? ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+      const thinkingLevels = provider === "agent_watch_managed" && Array.isArray(value.managedThinkingLevels) ? value.managedThinkingLevels.filter((v): v is string => typeof v === "string") : value.reasoning ? ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
         .filter((level) => mapping[level] !== null && !(["xhigh", "max"].includes(level) && mapping[level] === undefined)) : ["off"];
       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 }];
     });
-    // Keep the WebUI new-session baseline deterministic and visible. If the
-    // preferred model is not authenticated, the host's own default remains the
-    // safe fallback instead of silently substituting another catalog entry.
-    const defaultModel = models.find((value) => value.provider === "openai-codex" && value.modelId === "gpt-5.6-sol");
+    // Only offer a default present in the authenticated host catalog. Retain
+    // the previous Sol baseline for accounts that have not received GPT-6 yet.
+    const managed = models.length === 1 && models[0].provider === 'agent_watch_managed';
+    const defaultModel = managed ? models[0] : ["gpt-6-sol", "gpt-5.6-sol"].map((id) => models.find((value) => value.provider === "openai-codex" && value.modelId === id)).find(Boolean);
     return { schemaVersion: 1, version: "piagent-session-creation-options-v1", generatedAt: new Date().toISOString(),
       projects: [...projects.values()].slice(0, 200), models,
-      defaultModelRef: defaultModel?.modelRef ?? null, defaultThinkingLevel: defaultModel ? "high" : null,
-      profiles, workflows: WEBUI_WORKFLOW_OPTIONS,
-      runtimeActions: WEBUI_RUNTIME_ACTIONS,
+      defaultModelRef: defaultModel?.modelRef ?? null, defaultThinkingLevel: defaultModel ? (defaultModel.thinkingLevels.includes("high") ? "high" : defaultModel.thinkingLevels[0] ?? null) : null,
+      profiles: managed ? [] : profiles, workflows: [],
+      runtimeActions: managed ? [] : WEBUI_RUNTIME_ACTIONS,
       webSearch: inspectWebSearchCapability({ agentDir: this.#agentDir, models: availableModels }),
       projectImport: nativeProjectPickerAvailable() ? { status: "available", reasonCode: null }
         : { status: "unavailable", reasonCode: "native-project-picker-unavailable" },
@@ -242,8 +265,15 @@ export class SessionInspectionRegistry {
     try { manager = this.#openLiveSession?.(sessionRef) ?? this.#host.SessionManager.open(info.path); }
     catch { throw new ReadModelNotFound(); }
     const context = safeRead(() => manager.buildSessionContext(), { model: null, thinkingLevel: "unknown", messages: [] });
-    const model = context.model ? this.#models?.getModel(context.model.provider, context.model.modelId) : undefined;
     const entries = safeRead(() => manager.getBranch(), []);
+    const catalogModel = context.model ? this.#models?.getModel(context.model.provider, context.model.modelId) : undefined;
+    const managedModel = context.model?.provider === 'agent_watch_managed'
+      ? (entries as Array<{type?: string; customType?: string; data?: Record<string, unknown>}>).filter(entry => entry.type === 'custom' && entry.customType === 'agent-watch-model').at(-1)?.data
+      : undefined;
+    const model = managedModel?.provider === 'agent_watch_managed' && managedModel.id === 'agent-watch-auto'
+      && Number.isInteger(managedModel.contextWindow) && Number(managedModel.contextWindow) > 0
+      && Number.isInteger(managedModel.maxTokens) && Number(managedModel.maxTokens) > 0
+      ? {...catalogModel, ...managedModel} as typeof catalogModel : catalogModel;
     const contextUsage = safeRead(() => persistedContextUsage(this.#host, entries, context.messages, model), undefined);
     const eventStore = {
       retention: () => ({ eventRetentionCount: 0, eventRetentionSeconds: 0 }),

package/packages/piagent-webui/gateway/session-list-cache.ts

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import type { PiSessionInfo } from "./session-catalog.ts";
+
+type ListAll = (sessionDir: string) => Promise<PiSessionInfo[]>;
+type Cached = { mtimeMs: number; size: number; info: PiSessionInfo | null };
+
+// Pi lists sessions by reading every session file in full. With hundreds of
+// conversations that is seconds of CPU for every catalog the dashboard asks
+// for, and its answers slip past the page's 30-second wait. A file whose size
+// and modification time are unchanged keeps the info read before; changed and
+// new files are read again by Pi itself, through a private folder of links to
+// them, so the info is always what Pi would have produced.
+//
+// `flat`: the sessions are files directly in `root` (a company store);
+// otherwise each project has a folder of them under `root` (Pi's own layout).
+export function cachedSessionLister(listAll: ListAll, root: string, flat: boolean): () => Promise<PiSessionInfo[]> {
+  const cache = new Map<string, Cached>();
+  let running: Promise<PiSessionInfo[]> | null = null;
+
+  const discover = async (): Promise<string[]> => {
+    if (!fs.existsSync(root)) return [];
+    const entries = await fs.promises.readdir(root, { withFileTypes: true });
+    if (flat) return entries.filter((entry) => entry.name.endsWith(".jsonl")).map((entry) => path.join(root, entry.name));
+    const folders = entries.filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map((entry) => path.join(root, entry.name));
+    const files = await Promise.all(folders.map(async (folder) => {
+      try { return (await fs.promises.readdir(folder)).filter((name) => name.endsWith(".jsonl")).map((name) => path.join(folder, name)); }
+      catch { return []; }
+    }));
+    return files.flat();
+  };
+
+  const refresh = async (): Promise<PiSessionInfo[]> => {
+    const files = await discover(), seen = new Set(files), changed: string[] = [];
+    const stats = new Map<string, fs.Stats>();
+    await Promise.all(files.map(async (file) => {
+      try {
+        const stat = await fs.promises.stat(file); stats.set(file, stat);
+        const known = cache.get(file);
+        if (!known || known.mtimeMs !== stat.mtimeMs || known.size !== stat.size) changed.push(file);
+      } catch { seen.delete(file); }
+    }));
+    for (const file of cache.keys()) if (!seen.has(file)) cache.delete(file);
+    if (changed.length) {
+      const links = await fs.promises.mkdtemp(path.join(os.tmpdir(), "piagent-session-list-"));
+      try {
+        await Promise.all(changed.map((file, index) => fs.promises.symlink(file, path.join(links, `${index}.jsonl`))));
+        const read = new Map<number, PiSessionInfo>();
+        for (const info of await listAll(links)) read.set(Number(path.basename(info.path, ".jsonl")), info);
+        changed.forEach((file, index) => {
+          const stat = stats.get(file)!, info = read.get(index);
+          cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, info: info ? { ...info, path: file } : null });
+        });
+      } finally { await fs.promises.rm(links, { recursive: true, force: true }); }
+    }
+    const infos: PiSessionInfo[] = [];
+    for (const file of seen) { const info = cache.get(file)?.info; if (info) infos.push(info); }
+    return infos.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+  };
+
+  // Callers at the same moment share one refresh.
+  return () => {
+    running ??= refresh().finally(() => { running = null; });
+    return running;
+  };
+}

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

@@ -1,6 +1,6 @@
 import { createHmac } from "node:crypto";
 import type { SessionOwnerProjection } from "./session-catalog.ts";
-import type { SessionLeaseSnapshot } from "./session-lease-store.ts";
+import { terminalOwnerGone, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 
 type ActiveOwnership = {
   lease: SessionLeaseSnapshot;
@@ -32,6 +32,13 @@ export function projectSessionRuntimeOwnership(options: {
     owner: { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "unknown" },
     reasonCode: lease.reasonCode ?? "session-lease-unavailable"
   };
+  if (lease.state === "terminal-owned" && terminalOwnerGone(lease)) return {
+    state: "recovery-required", liveState: "uncertain", composerAvailable: false, needsAttention: true,
+    owner: { kind: "terminal", ownerEpoch: lease.ownerEpoch!,
+      gatewayInstanceRef: `terminal_${createHmac("sha256", key).update(lease.gatewayInstanceRef!).digest("base64url").slice(0, 43)}`,
+      runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "uncertain" },
+    reasonCode: "terminal-owner-process-exited"
+  };
   if (lease.state === "terminal-owned") return {
     state: "terminal-owned", liveState: "uncertain", composerAvailable: false, needsAttention: false,
     owner: { kind: "terminal", ownerEpoch: lease.ownerEpoch!,

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

@@ -1,10 +1,11 @@
+import { sessionApprovalAuthority } from "./session-approval-authority.ts";
 import { closeSessionRuntimes } from "./session-runtime-close.ts";
-import { createHmac, randomBytes } from "node:crypto";
-import { webUiModelRef, webUiTaskRevision } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import { randomBytes } from "node:crypto";
+import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
 import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
 import { createSessionOperationSettlement } from "./session-operation-settlement.ts";
 import { inspectTaskControlState } from "../../piagent-core/runtime/inspection/task-control-journal.ts";
-import { piApprovalBroker, type ApprovalAuthority, type ApprovalBrokerEvent } from "../../piagent-core/runtime/inspection/approval-broker.ts";
+import { piApprovalBroker, type ApprovalBrokerEvent } from "../../piagent-core/runtime/inspection/approval-broker.ts";
 import { isUserConversationSession, projectRefForCwd, sessionRefForPath, type SessionOwnerProjection, type PiSessionInfo } from "./session-catalog.ts";
 import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
@@ -27,9 +28,10 @@ export type CurrentOperationProjection = { operationRef: string; state: "running
 export class SessionRuntimeSupervisor {
   readonly #gatewayInstanceRef: string; readonly #key: Buffer;
   readonly #leases: SessionLeaseStore; readonly #listSessions: () => Promise<PiSessionInfo[]>;
-  readonly #runtimeFactory: RuntimeFactory; readonly #events: GatewayEventStore;
+  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 #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;
@@ -44,6 +46,7 @@ export class SessionRuntimeSupervisor {
     packageRoot?: string;
     modelRuntime?: any;
     scopedBrokerRouter?: ScopedBrokerRouter;
+    sessionDirectory?: string;
     events?: GatewayEventStore;
     operationWatchdog?: SessionOperationWatchdogOptions;
     resolveProject?(projectRef: string): string | null;
@@ -57,6 +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.#settleOperation = createSessionOperationSettlement(options);
     if (options.runtimeFactory) this.#runtimeFactory = options.runtimeFactory;
     else {
@@ -85,7 +89,7 @@ export class SessionRuntimeSupervisor {
     const candidates = [...new Set([...sessions.filter((info) => projectRefForCwd(this.#key, info.cwd) === projectRef).map((info) => info.cwd),
       ...(imported ? [imported] : [])])];
     if (candidates.length !== 1 || !candidates[0]) throw new Error(candidates.length ? "session-project-ambiguous" : "session-project-not-found");
-    const manager = this.#host.SessionManager.create(candidates[0]);
+    const manager = this.#host.SessionManager.create(candidates[0], this.#sessionDirectory);
     const sessionFile = manager.getSessionFile();
     if (!sessionFile || typeof manager.getSessionId?.() !== "string") throw new Error("session-create-unavailable");
     const createdAt = new Date();
@@ -198,8 +202,16 @@ export class SessionRuntimeSupervisor {
     return result;
   }
   ownership(sessionRef: string): SessionOwnerProjection {
-    return projectSessionRuntimeOwnership({ lease: this.#leases.inspect(sessionRef), active: this.#active.get(sessionRef),
-      gatewayInstanceRef: this.#gatewayInstanceRef, key: this.#key });
+    let lease = this.#leases.inspect(sessionRef);
+    // An owner that no longer exists (the Gateway was killed, the machine went
+    // down) holds nothing: the conversation is offline again and takes the
+    // next message without an explicit restart. Asked once per lease state.
+    if (lease.revision && lease.gatewayInstanceRef && lease.gatewayInstanceRef !== this.#gatewayInstanceRef && !this.#active.has(sessionRef)
+      && ["gateway-owned", "terminal-owned", "recovery-required"].includes(lease.state) && !this.#settledOwners.has(lease.revision)) {
+      this.#settledOwners.add(lease.revision);
+      try { lease = this.#leases.releaseDeadOwnerForExplicitRecovery(sessionRef); } catch { /* alive or unprovable: stays authoritative */ }
+    }
+    return projectSessionRuntimeOwnership({ lease, active: this.#active.get(sessionRef), gatewayInstanceRef: this.#gatewayInstanceRef, key: this.#key });
   }
   async send(sessionRef: string, payload: { delivery: "new-operation" | "follow-up" | "steer"; message: string;
     expectedOperationRef: string | null; messageRequestId?: string; images?: unknown[] }, sessionRevision: string, options: { deferDispatch?: boolean } = {}):
@@ -298,26 +310,7 @@ export class SessionRuntimeSupervisor {
     await boundedResult(Promise.resolve().then(() => active.runtime.dispose()), this.#operationDeadlinePolicy.terminationTimeoutMs);
   }
   #bindApproval(sessionRef: string, active: ActiveRuntime): void {
-    const authority = (): ApprovalAuthority => {
-      if (!active.operationRef || active.lease.state !== "gateway-owned" || !active.lease.revision) return null;
-      const task = activeSessionTask(active.info.cwd, active.info.id);
-      const synthetic = (namespace: string) => `${namespace}_${createHmac("sha256", this.#key)
-        .update(`${sessionRef}\0${namespace}`).digest("base64url").slice(0, 43)}`;
-      const control = task ? inspectTaskControlState(active.info.cwd, task) : null;
-      return {
-        identity: {
-          projectRef: projectRefForCwd(this.#key, active.info.cwd), runtimeInstanceId: active.lease.runtimeInstanceRef!, sessionRef,
-          taskId: task?.taskId ?? synthetic("task"), taskRunId: task?.taskRunId ?? synthetic("task_run"),
-          agentOperationId: active.operationRef
-        },
-        revisions: {
-          runtimeRevision: active.lease.revision,
-          taskRevision: task ? webUiTaskRevision(task) : synthetic("task_rev"),
-          controlRevision: control?.controlRevision ?? synthetic("control_rev")
-        },
-        taskState: control?.state === "terminal" ? "terminal" : "active"
-      };
-    };
+    const authority = () => sessionApprovalAuthority(this.#key, sessionRef, active);
     active.unbindApproval = piApprovalBroker.bind({ cwd: active.info.cwd, rawSessionId: active.info.id,
       runtimeInstanceId: active.lease.runtimeInstanceRef!, authority });
     active.unsubscribeApproval = piApprovalBroker.subscribe(active.info.cwd, active.info.id, (event: ApprovalBrokerEvent) => {

package/packages/piagent-webui/ownership/managed-terminal-lease.ts

@@ -0,0 +1,27 @@
+import { randomBytes } from "node:crypto";
+
+import { gatewayProfileState, readOrCreateCatalogKey } from "./profile-state.ts";
+import { sessionRefForPath } from "./session-refs.ts";
+import { SessionLeaseStore } from "./session-lease-store.ts";
+
+export type ManagedSessionHold = { sessionRef: string; release(): void };
+
+/**
+ * A company conversation run outside the Gateway (the company Terminal,
+ * `piagent studio --prompt`, scripts) holds the same lease the Gateway uses.
+ * The WebUI then shows it running elsewhere and offers neither sending nor
+ * "continue" until it is released. A conversation the Gateway holds is
+ * refused (`session-owner-conflict`): two writers never share one JSONL.
+ */
+export function holdManagedSession(agentDir: string, sessionFile: string): ManagedSessionHold {
+  const state = gatewayProfileState(agentDir), key = readOrCreateCatalogKey(state), leases = new SessionLeaseStore(state.root, key);
+  const sessionRef = sessionRefForPath(key, sessionFile);
+  const owner = `terminal_${process.pid}_${randomBytes(16).toString("base64url")}`, runtime = `runtime_${randomBytes(16).toString("base64url")}`;
+  const lease = leases.acquireTerminal(sessionRef, owner, runtime);
+  let held = true;
+  return { sessionRef, release() {
+    if (!held || !lease.ownerEpoch) return;
+    held = false;
+    try { leases.releaseTerminal(sessionRef, lease.ownerEpoch, owner, runtime); } catch { /* a dead owner is recovered by the next acquirer */ }
+  } };
+}

package/packages/piagent-webui/ownership/profile-state.ts

@@ -13,6 +13,8 @@ export type GatewayDescriptor = {
   origin: string;
   controlSocket: string;
   profileRef: string;
+  // Installed Piagent version of this Gateway (absent before 1.9).
+  packageVersion?: string;
 };
 
 export type GatewayProfileState = {

package/packages/piagent-webui/ownership/session-lease-store.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { createHmac, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -45,11 +46,30 @@ function gatewayOwnerPid(value: string | null): number | null {
   return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
 }
 
+// A terminal owner whose process is gone left its lease behind (crash, closed
+// window): it is not running anything any more.
+export function terminalOwnerGone(snapshot: Pick<SessionLeaseSnapshot, "state" | "gatewayInstanceRef">): boolean {
+  if (snapshot.state !== "terminal-owned") return false;
+  const pid = terminalOwnerPid(snapshot.gatewayInstanceRef);
+  return pid !== null && !processAlive(pid);
+}
+
 function processAlive(pid: number): boolean {
   try { process.kill(pid, 0); return true; }
   catch (error) { return !(error && typeof error === "object" && "code" in error && error.code === "ESRCH"); }
 }
 
+// After a restart of the machine the owner's process number may belong to
+// something else. A process that started after the lease was taken cannot be
+// its owner.
+function startedAfter(pid: number, since: string): boolean {
+  try {
+    const started = Date.parse(execFileSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)],
+      { encoding: "utf8", timeout: 2000, env: { ...process.env, LC_ALL: "C" } }).trim());
+    return Number.isFinite(started) && started > Date.parse(since) + 2000;
+  } catch { return false; }
+}
+
 function exactTimestamp(value: unknown): value is string {
   return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
     && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
@@ -242,7 +262,8 @@ export class SessionLeaseStore {
       const pid = terminalOwner ? terminalOwnerPid(current.gatewayInstanceRef)
         : current.state === "gateway-owned" || current.state === "recovery-required"
           ? gatewayOwnerPid(current.gatewayInstanceRef) : null;
-      if (!pid || processAlive(pid)) throw new Error("session-owner-not-proven-dead");
+      const since = this.#read(sessionRef).filter((record) => record.event === "acquired" && record.ownerEpoch === current.ownerEpoch).at(-1)?.recordedAt;
+      if (!pid || (processAlive(pid) && !(since && startedAfter(pid, since)))) throw new Error("session-owner-not-proven-dead");
       this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "recovery-required", ownerEpoch: current.ownerEpoch!,
         gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: "owner-process-exited" });
       this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "released", ownerEpoch: current.ownerEpoch!,

package/packages/piagent-webui/server/approval-projection.ts

@@ -0,0 +1,9 @@
+// Gateway and extension sessions publish the same approval contract.
+export function projectApprovalState(snapshot: any, approval?: { revision: string | null; summary: Record<string, unknown> }) {
+  if (!approval?.revision) return;
+  snapshot.revision.approvalRevision = approval.revision;
+  snapshot.approvals = structuredClone(approval.summary);
+  snapshot.session.approvalState = approval.summary.state;
+  snapshot.capabilities.capabilities.approve = { status: "available", version: 1, reason: null,
+    decisions: ["allow", "deny"], arbitration: "first-valid-cas" };
+}

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

@@ -1,3 +1,4 @@
+import { projectApprovalState } from "./approval-projection.ts";
 import { randomBytes } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
@@ -193,14 +194,6 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
           : { status: "unavailable", version: null, reason: { code: lifecycle.actions.resume ? "agent-not-idle" : `control-state-${lifecycle.state}`,
             message: "Resume & Continue requires a paused task and an idle Pi session." } };
       }
-      const approval = this.#input.approvalProjection?.();
-      if (approval?.revision) {
-        value.snapshot.revision.approvalRevision = approval.revision;
-        value.snapshot.approvals = structuredClone(approval.summary);
-        value.snapshot.session.approvalState = (approval.summary as any).state;
-        value.snapshot.capabilities.capabilities.approve = { status: "available", version: 1, reason: null,
-          decisions: ["allow", "deny"], arbitration: "first-valid-cas" };
-      }
       if (control.identity.taskId && control.identity.taskRunId && control.revisions.taskRevision && value.snapshot.revision.workspaceRevision
         && !sourceIdentityAligned) {
         value.snapshot.capabilities.capabilities.reviewActions = { status: "unavailable", version: null,
@@ -225,6 +218,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
         } };
       }
     }
+    projectApprovalState(value.snapshot, this.#input.approvalProjection?.());
     if (sourceIdentityAligned) {
       const binding = sourceBinding(value.snapshot);
       for (const document of Object.values(value.sourceViews)) {
@@ -289,7 +283,8 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       eventCursor: snapshot.revision.eventCursor, entries: this.#input.sessionEntries?.() ?? [], beforeCursor, limit,
       terminalDeliveryReceipt: readTerminalDeliveryReceipt(this.#input.cwd, activeTask),
       terminalDeliveryEntries: terminalDeliverySessionEntries(this.#input.sessionFile?.(), this.#input.sessionId),
-      generatedAt: snapshot.generatedAt, taskOutcome: typeof activeTask?.trace?.outcome === "string" ? activeTask.trace.outcome : null });
+      generatedAt: snapshot.generatedAt, taskOutcome: typeof activeTask?.trace?.outcome === "string" ? activeTask.trace.outcome : null,
+      cwd: this.#input.cwd });
   }
   async queue(): Promise<unknown> {
     if (!this.#input.queueProjection) throw new ReadModelNotFound();