@piagent/platform 1.17.0 → 1.19.0

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

@@ -7,7 +7,7 @@
     <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-BNQK7rHr.js"></script>
+    <script type="module" crossorigin src="/assets/index-CM9cs-gP.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Z91z6SlN.css">
   </head>
   <body>

package/packages/piagent-webui/gateway/company-relay.ts

@@ -4,6 +4,8 @@ import { WebSocket } from "ws";
 import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
 import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
 import { requestGatewayControl } from "./control-socket.ts";
+import { gitHeadReader } from "./git-head.ts";
+import { childRepositoryReader } from "./git-repositories.ts";
 import type { GatewayEventKind, GatewayEventStore } from "./gateway-events.ts";
 
 // The personal dashboard lists and drives company sessions through this relay.
@@ -250,12 +252,22 @@ export class CompanyRelay {
     const company = await this.catalog();
     if (personal.state !== "ready" || !personal.catalogRevision) return personal;
     const ready = this.#state === "ready";
+    // The Git facts of a company conversation's folder are read here, on the
+    // same Mac: the company Gateway may run an earlier release (Agent Watch
+    // restarts it only now and then) that does not report them.
+    const readHead = gitHeadReader(), readRepositories = childRepositoryReader();
     const rows: SessionRow[] = (company?.state === "ready" ? company.sessions : []).map((row) => {
       const folder = this.#paths.get(row.projectRef);
-      return { ...row, projectRef: folder ? this.#hubProject(folder) : row.projectRef, composerAvailable: ready && row.composerAvailable };
+      const { gitBranch: _branch, gitRepositories: _repositories, ...rest } = row;
+      const head = folder ? readHead(folder) : null, repositories = folder && !head ? readRepositories(folder) : [];
+      return { ...rest, projectRef: folder ? this.#hubProject(folder) : row.projectRef, composerAvailable: ready && row.composerAvailable,
+        ...(folder ? {} : _branch ? { gitBranch: _branch } : {}), ...(folder ? {} : _repositories ? { gitRepositories: _repositories } : {}),
+        ...(head ? { gitBranch: head } : {}),
+        ...(repositories.length ? { gitRepositories: repositories.map((repository) => ({ name: repository.name, branch: repository.head })) } : {}) };
     });
     const sessions = [...personal.sessions, ...rows].sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
-    const digest = createHash("sha256").update(JSON.stringify([personal.catalogRevision, company?.catalogRevision ?? null, ready])).digest("hex");
+    const digest = createHash("sha256").update(JSON.stringify([personal.catalogRevision, company?.catalogRevision ?? null, ready,
+      rows.map((row) => [row.gitBranch ?? null, row.gitRepositories ?? null])])).digest("hex");
     return { ...personal, catalogRevision: `rev_${digest}`, sessions,
       page: { ...personal.page, returned: sessions.length, total: personal.page.total + rows.length } };
   }

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

@@ -20,6 +20,8 @@ import {
 } from "./profile-state.ts";
 import { buildSessionCatalog, projectRefForCwd } from "./session-catalog.ts";
 import { suggestPaths } from "./path-suggestions.ts";
+import { GitBranchError, listBranches, switchBranch, type SwitchRequest } from "./git-branches.ts";
+import { childRepositories, childRepositoryFolder } from "./git-repositories.ts";
 import { listAgentCommands } from "../../piagent-core/runtime/resources/agent-resources.mjs";
 import { sessionRefForPath } from "../ownership/session-refs.ts";
 import { SessionMetadataStore } from "./session-metadata-store.ts";
@@ -229,6 +231,8 @@ export async function startPiagentGateway(options: {
       ?? (await runtimes!.listSessions()).find((info) => typeof info.cwd === "string" && projectRefForCwd(key, info.cwd) === projectRef)?.cwd
       ?? (relay ? (await relay.folders()).find((folder) => projectRefForCwd(key, folder) === projectRef) : undefined);
     const relayPost = (path: string, body: unknown) => relay!.json("POST", path, body);
+    const runningInProject = async (projectRef: string) => (await hubCatalog()).sessions.filter((row) => row.projectRef === projectRef
+      && !row.archived && ["running", "waiting-approval", "paused"].includes(row.liveState)).length;
     const commands = new SessionCommandController({ catalog: hubCatalog, runtimes, metadata,
       store: new SessionCommandStore(state.root, key), events,
       // Resolved at call time: the attachment registry is built after this
@@ -303,6 +307,40 @@ export async function startPiagentGateway(options: {
         const root = await projectFolder(projectRef);
         return root ? { commands: listAgentCommands({ cwd: root }) } : null;
       },
+      // The project's Git branches and a switch between them. A switch waits
+      // until no conversation in the folder runs (company ones included): the
+      // agent would find its files changed under it.
+      // A folder that is not a repository answers with the repositories one
+      // level down; `repository` then names the one to read or switch.
+      listBranches: async (projectRef, repository) => {
+        const root = await projectFolder(projectRef);
+        if (!root) return null;
+        const folder = repository === null ? root : childRepositoryFolder(root, repository);
+        if (!folder) throw new GitBranchError("not-a-git-repository");
+        const [list, running] = await Promise.all([listBranches(folder), runningInProject(projectRef)]);
+        if (list) return { ...list, running, ...(repository === null ? {} : { name: repository }) };
+        const repositories = repository === null ? await Promise.all(childRepositories(root).map(async (child) => {
+          const branches = await listBranches(path.join(root, child.name));
+          return { name: child.name, head: child.head, changedFiles: branches?.changedFiles ?? 0 };
+        })) : [];
+        return { repository: false, running, repositories };
+      },
+      switchBranch: async (projectRef, request) => {
+        const root = await projectFolder(projectRef);
+        if (!root) return null;
+        const value = request as (Partial<SwitchRequest> & { repository?: string }) | null;
+        if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.branch !== "string"
+          || Object.keys(value).some((name) => !["branch", "create", "remote", "repository"].includes(name))
+          || (value.repository !== undefined && typeof value.repository !== "string")
+          || (value.create !== undefined && typeof value.create !== "boolean")
+          || (value.remote !== undefined && value.remote !== null && typeof value.remote !== "string")) throw new GitBranchError("branch-request-invalid");
+        const folder = value.repository === undefined ? root : childRepositoryFolder(root, value.repository);
+        if (!folder || !(await listBranches(folder))) throw new GitBranchError("not-a-git-repository");
+        if (await runningInProject(projectRef) > 0) throw new GitBranchError("branch-switch-blocked-running");
+        const head = await switchBranch(folder, { branch: value.branch, create: value.create === true, remote: value.remote ?? null });
+        events.publish("catalog.changed", { reasonCode: "git-branch-switched" });
+        return { head, branches: await listBranches(folder) };
+      },
       updates: { status: () => updates!.status(), check: () => updates!.check(), apply: (request) => updates!.apply(request) },
       answerSessionQuestion: (sessionRef, questionRef, answer) => company(sessionRef)
         ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/questions/${encodeURIComponent(questionRef)}/answer`, answer)

package/packages/piagent-webui/gateway/git-branches.ts

@@ -0,0 +1,94 @@
+import { execFile } from "node:child_process";
+
+import { readGitHead, type GitHead } from "./git-head.ts";
+
+// The branches of a project folder and a switch between them, for the branch
+// menu in the dashboard. Git itself does the switch (`git switch`), so it
+// refuses exactly what it refuses in a Terminal: local changes a checkout
+// would overwrite, a name that already exists, a branch that is not there.
+export type Branch = { name: string; current: boolean; remote: string | null; committedAt: string | null };
+export type BranchList = { repository: true; head: GitHead | null; branches: Branch[]; truncated: boolean; changedFiles: number };
+export type SwitchRequest = { branch: string; create?: boolean; remote?: string | null };
+
+const GIT = process.platform === "darwin" ? "/usr/bin/git" : "git";
+const LIMIT = 200;
+const SEP = "\u0000";
+
+export class GitBranchError extends Error {
+  readonly detail: string | null;
+  constructor(code: string, detail: string | null = null) { super(code); this.detail = detail; }
+}
+
+function git(cwd: string, args: string[], timeout = 15_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(GIT, ["-C", cwd, ...args], { timeout, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" } }, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(error, { stderr: String(stderr ?? "") }));
+      else resolve(String(stdout));
+    });
+  });
+}
+
+// A branch name git accepts that cannot be read as an option.
+export async function validBranchName(cwd: string, name: string): Promise<boolean> {
+  if (!name || name.length > 200 || name.startsWith("-") || /[\u0000-\u001f\u007f]/.test(name)) return false;
+  try { await git(cwd, ["check-ref-format", "--branch", name], 5_000); return true; } catch { return false; }
+}
+
+export async function listBranches(cwd: string): Promise<BranchList | null> {
+  const head = readGitHead(cwd);
+  if (!head) {
+    try { await git(cwd, ["rev-parse", "--git-dir"], 5_000); } catch { return null; }
+  }
+  let refs: string;
+  try {
+    refs = await git(cwd, ["for-each-ref", "--sort=-committerdate", `--count=${LIMIT * 2}`,
+      "--format=%(refname)%00%(committerdate:iso-strict)", "refs/heads", "refs/remotes"]);
+  } catch { return null; }
+  const local = new Map<string, Branch>(), remote: Branch[] = [];
+  for (const line of refs.split("\n")) {
+    const [ref, date] = line.split(SEP);
+    if (!ref) continue;
+    const committedAt = date && Number.isFinite(Date.parse(date)) ? new Date(date).toISOString() : null;
+    if (ref.startsWith("refs/heads/")) {
+      const name = ref.slice("refs/heads/".length);
+      local.set(name, { name, current: !head?.detached && head?.name === name, remote: null, committedAt });
+    } else if (ref.startsWith("refs/remotes/")) {
+      const rest = ref.slice("refs/remotes/".length), slash = rest.indexOf("/");
+      if (slash <= 0 || rest.endsWith("/HEAD")) continue;
+      remote.push({ name: rest.slice(slash + 1), current: false, remote: rest.slice(0, slash), committedAt });
+    }
+  }
+  // A remote branch shows only when no local branch has its name: switching
+  // to it creates the local branch that tracks it.
+  const offered = remote.filter((item) => !local.has(item.name)).filter((item, index, all) =>
+    all.findIndex((other) => other.name === item.name) === index);
+  const all = [...local.values(), ...offered];
+  let changedFiles = 0;
+  try { changedFiles = (await git(cwd, ["status", "--porcelain=v1", "--untracked-files=no"], 10_000)).split("\n").filter(Boolean).length; }
+  catch { /* the count is advisory */ }
+  return { repository: true, head, branches: all.slice(0, LIMIT), truncated: all.length > LIMIT, changedFiles };
+}
+
+function failure(error: unknown): GitBranchError {
+  const stderr = String((error as { stderr?: unknown })?.stderr ?? "");
+  const detail = stderr.split("\n").map((line) => line.trim()).filter(Boolean).slice(0, 6).join("\n").slice(0, 600) || null;
+  if (/would be overwritten by checkout|Please commit your changes or stash them/i.test(stderr)) return new GitBranchError("branch-switch-local-changes", detail);
+  if (/already exists/i.test(stderr)) return new GitBranchError("branch-exists", detail);
+  if (/invalid reference|did not match any|not a commit|no such branch/i.test(stderr)) return new GitBranchError("branch-not-found", detail);
+  if (/you need to resolve your current index first|unmerged|in the middle of/i.test(stderr)) return new GitBranchError("branch-switch-unfinished-merge", detail);
+  if ((error as { killed?: boolean })?.killed) return new GitBranchError("branch-switch-timeout", detail);
+  return new GitBranchError("branch-switch-failed", detail);
+}
+
+export async function switchBranch(cwd: string, request: SwitchRequest): Promise<GitHead | null> {
+  const name = request.branch.trim();
+  if (!(await validBranchName(cwd, name))) throw new GitBranchError("branch-name-invalid");
+  const remote = request.remote ?? null;
+  if (remote !== null && (!/^[A-Za-z0-9._-]{1,100}$/.test(remote) || request.create)) throw new GitBranchError("branch-request-invalid");
+  const args = request.create ? ["switch", "-c", name]
+    : remote ? ["switch", "-c", name, "--track", `${remote}/${name}`]
+      : ["switch", name];
+  try { await git(cwd, args, 60_000); } catch (error) { throw failure(error); }
+  return readGitHead(cwd);
+}

package/packages/piagent-webui/gateway/git-repositories.ts

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readGitHead, type GitHead } from "./git-head.ts";
+
+// A project folder that is not itself in a repository may hold several (a
+// workspace folder with the front end, the back end and other projects side
+// by side, each its own repository). Like an editor's source control view,
+// the dashboard looks one level down for them: each child folder with its
+// own `.git` (a folder, or a worktree's file) is a repository, shown with
+// its branch. Hidden folders and dependency folders are skipped.
+export type ChildRepository = { name: string; path: string; head: GitHead | null };
+
+const MAX_REPOSITORIES = 30;
+const SKIPPED = new Set(["node_modules", "vendor", "target", "dist", "build", "Pods", "venv", "__pycache__"]);
+
+export function childRepositories(cwd: string): ChildRepository[] {
+  if (!cwd || readGitHead(cwd)) return [];
+  let entries: fs.Dirent[];
+  try { entries = fs.readdirSync(cwd, { withFileTypes: true }); } catch { return []; }
+  const found: ChildRepository[] = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || SKIPPED.has(entry.name)) continue;
+    const folder = path.join(cwd, entry.name);
+    try { fs.lstatSync(path.join(folder, ".git")); } catch { continue; }
+    found.push({ name: entry.name, path: entry.name, head: readGitHead(folder) });
+    if (found.length === MAX_REPOSITORIES) break;
+  }
+  return found;
+}
+
+// The folder of one child repository, or null when `name` is not one: a
+// single folder name, never a path that climbs out of the project.
+export function childRepositoryFolder(cwd: string, name: string): string | null {
+  if (!name || name.length > 255 || name.startsWith(".") || name.includes("/") || name.includes("\\") || /[\u0000-\u001f\u007f]/.test(name)) return null;
+  return childRepositories(cwd).some((repository) => repository.name === name) ? path.join(cwd, name) : null;
+}
+
+// One read per project folder while a catalog is built.
+export function childRepositoryReader(): (cwd: string) => ChildRepository[] {
+  const seen = new Map<string, ChildRepository[]>();
+  return (cwd) => {
+    if (!seen.has(cwd)) seen.set(cwd, childRepositories(cwd));
+    return seen.get(cwd)!;
+  };
+}

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

@@ -1,5 +1,6 @@
+import { turnEndOf } from '../shared/turn-end.ts';
 // Public managed state contains no provider/model route or credential.
-const STATUS = ['pending', 'in_progress', 'completed'];
+const STATUS = ['pending', 'in_progress', 'completed', 'deferred'];
 const OUTCOMES = ['no_change', 'interrupted', 'disputed', 'blocking_open', 'unverified', 'review_unavailable', 'unreviewed', 'clean'];
 export function managedProjection(context: any, entries: any[]) {
   if (context?.model?.provider !== 'agent_watch_managed') return {};
@@ -14,6 +15,12 @@ export function managedProjection(context: any, entries: any[]) {
   const final = entries.filter(e => e.type === 'custom_message' && e.customType === 'agent-watch-process' && e.details?.phase === 'final').at(-1)?.details;
   const process = final && OUTCOMES.includes(final.outcome) ? { outcome: final.outcome, verified: final.verified === true, reviewed: final.reviewed === true,
     blockingOpen: Number.isInteger(final.blockingOpen) && final.blockingOpen >= 0 ? Math.min(final.blockingOpen, 1000) : 0, ...(final.planSkipped === true ? { planSkipped: true as const } : {}) } : null;
+  // How the member's last message ended, unless a newer message is running.
+  const lastIndex = (match: (e: any) => boolean) => { for (let i = entries.length - 1; i >= 0; i -= 1) if (match(entries[i])) return i; return -1; };
+  const lastUser = lastIndex(e => e.type === 'message' && e.message?.role === 'user');
+  const endAt = lastIndex(e => e.type === 'custom' && e.customType === 'agent-watch-turn-end');
+  const end = endAt > lastUser ? turnEndOf(entries[endAt].data) : null;
+  const turnEnd = end ? { state: end.state, planSteps: end.planSteps, planDone: end.planDone, ...(end.planDeferred ? { planDeferred: end.planDeferred } : {}), ...(end.reason ? { reason: end.reason } : {}) } : null;
   // Helpers the Harness enables (up to four); a conversation recorded before
   // that was known says two.
   const maximum = Number.isInteger(counter?.maximum) && counter.maximum >= 0 && counter.maximum <= 4 ? counter.maximum : 2;
@@ -21,5 +28,5 @@ export function managedProjection(context: any, entries: any[]) {
   const permission = last('agent-watch-permission')?.mode === 'trusted-full-access' ? 'trusted-full-access' : 'workspace-write';
   return {modelLabel:'agent-watch-auto', managedPermission: permission, managedHelpers:{active:Number.isInteger(counter?.active) && counter.active>=0 && counter.active<=maximum ? counter.active : 0, maximum},
     ...(Array.isArray(capabilities)?{managedThinkingLevels:levels.filter(level=>capabilities.includes(level))}:{}),
-    ...(steps ? {managedPlan:{steps}} : {}), ...(process ? {managedProcess:process} : {})};
+    ...(steps ? {managedPlan:{steps}} : {}), ...(process ? {managedProcess:process} : {}), ...(turnEnd ? {managedTurnEnd:turnEnd} : {})};
 }

package/packages/piagent-webui/gateway/project-registry.ts

@@ -78,12 +78,16 @@ export class ProjectRegistry {
     if (!stat.isDirectory() || stat.isSymbolicLink() || cwd === path.parse(cwd).root) throw new Error("project-import-folder-invalid");
     const current = this.#read(), projectRef = projectRefForCwd(this.#key, cwd);
     const existing = current.projects.find((item) => item.projectRef === projectRef);
-    if (!existing) {
-      if (current.projects.length >= MAX_PROJECTS) throw new Error("project-registry-limit");
-      current.projects.push({ projectRef, cwd, label: cleanLabel(path.basename(cwd)), importedAt: now.toISOString() });
-      this.#write(current);
-    }
-    const item = existing ?? current.projects.at(-1)!;
+    // Added again: it moves to the newest place, so it outlives older folders.
+    const others = current.projects.filter((item) => item.projectRef !== projectRef);
+    const item = { projectRef, cwd, label: existing?.label ?? cleanLabel(path.basename(cwd)), importedAt: now.toISOString() };
+    // The list is the menu's memory of added folders, not where conversations
+    // live (their folders come from the sessions): a full list makes room by
+    // forgetting folders gone from the disk, then the folders added longest ago.
+    const kept = others.length < MAX_PROJECTS ? others : others.filter((other) => {
+      try { return fs.realpathSync(other.cwd) === other.cwd && fs.lstatSync(other.cwd).isDirectory(); } catch { return false; }
+    }).sort((left, right) => Date.parse(left.importedAt) - Date.parse(right.importedAt)).slice(-(MAX_PROJECTS - 1));
+    this.#write({ ...current, projects: [...kept, item] });
     return { projectRef: item.projectRef, placeRef: item.projectRef, label: item.label };
   }
 

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

@@ -7,6 +7,7 @@ import type { Catalog, SessionRow } from "../contracts/generated/session-catalog
 import type { MetadataSnapshot, SessionMetadata } from "./session-metadata-store.ts";
 import { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
 import { gitHeadReader, type GitHead } from "./git-head.ts";
+import { childRepositoryReader, type ChildRepository } from "./git-repositories.ts";
 
 export { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
 
@@ -48,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" | "managedPlan" | "managedProcess">;
+export type SessionOptionProjection = Pick<SessionRow, "modelLabel" | "thinkingLevel" | "managedHelpers" | "managedThinkingLevels" | "managedPermission" | "managedPlan" | "managedProcess" | "managedTurnEnd">;
 
 function display(value: unknown, maximum: number, fallback: string): string {
   const clean = redactSensitiveText(String(value ?? "")).text
@@ -106,8 +107,11 @@ function revision(key: Buffer, value: unknown): string {
 }
 
 function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undefined, metadataReason: string | null,
-  ownership?: SessionOwnerProjection, sessionOptions?: SessionOptionProjection, gitHead?: GitHead | null): SessionRow {
+  ownership?: SessionOwnerProjection, sessionOptions?: SessionOptionProjection, gitHead?: GitHead | null, repositories: ChildRepository[] = []): SessionRow {
   const gitBranch = gitHead ? { name: display(gitHead.name, 200, "HEAD"), detached: gitHead.detached } : null;
+  // A folder that is not a repository but holds some (front end, back end…).
+  const gitRepositories = gitBranch ? [] : repositories.map((repository) => ({ name: display(repository.name, 255, "repository").replace(/[/\\]/g, "-"),
+    branch: repository.head ? { name: display(repository.head.name, 200, "HEAD"), detached: repository.head.detached } : null }));
   const projectLabel = display(info.cwd ? path.basename(info.cwd) : "", 120, "Unknown project");
   const projected = projectedSessionTitle(info);
   return {
@@ -126,12 +130,14 @@ function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undef
     composerAvailable: metadata?.archived ? false : ownership?.composerAvailable ?? false,
     needsAttention: metadata?.archived ? false : ownership?.needsAttention ?? false,
     ...(gitBranch ? { gitBranch } : {}),
+    ...(gitRepositories.length ? { gitRepositories } : {}),
     ...(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?.managedPermission ? {managedPermission:sessionOptions.managedPermission} : {}),
     ...(sessionOptions?.managedPlan ? {managedPlan:sessionOptions.managedPlan} : {}),
     ...(sessionOptions?.managedProcess ? {managedProcess:sessionOptions.managedProcess} : {}),
+    ...(sessionOptions?.managedTurnEnd ? {managedTurnEnd:sessionOptions.managedTurnEnd} : {}),
     modelLabel: sessionOptions?.modelLabel ?? null,
     thinkingLevel: sessionOptions?.thinkingLevel ?? "unknown",
     contextUsage: { usedTokens: null, contextWindow: null, ratio: null, state: "unknown" },
@@ -140,8 +146,8 @@ 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?.managedPlan, sessionOptions?.managedProcess,
-      gitBranch,
+      sessionOptions?.modelLabel ?? null, sessionOptions?.thinkingLevel ?? "unknown", sessionOptions?.managedHelpers, sessionOptions?.managedThinkingLevels, sessionOptions?.managedPermission ?? null, sessionOptions?.managedPlan, sessionOptions?.managedProcess, sessionOptions?.managedTurnEnd,
+      gitBranch, gitRepositories,
       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
@@ -156,17 +162,18 @@ export async function buildSessionCatalog(options: {
   readOwnership?(sessionRef: string): SessionOwnerProjection;
   readSessionOptions?(info: PiSessionInfo): SessionOptionProjection;
   readGitHead?(cwd: string): GitHead | null;
+  readChildRepositories?(cwd: string): ChildRepository[];
   limit?: number;
 }): Promise<Catalog> {
   const limit = Math.max(1, Math.min(200, options.limit ?? 200));
   try {
     const found = (await options.listSessions()).filter(isUserConversationSession);
-    const readHead = options.readGitHead ?? gitHeadReader();
+    const readHead = options.readGitHead ?? gitHeadReader(), readRepositories = options.readChildRepositories ?? childRepositoryReader();
     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);
       return row(options.key, info, metadata.sessions.get(sessionRef), metadata.reasonCode, options.readOwnership?.(sessionRef),
-        options.readSessionOptions?.(info), readHead(info.cwd));
+        options.readSessionOptions?.(info), readHead(info.cwd), readRepositories(info.cwd));
     }).sort((left, right) => Number(right.pinned) - Number(left.pinned)
       || Date.parse(right.updatedAt) - Date.parse(left.updatedAt)).slice(0, limit);
     return {

package/packages/piagent-webui/gateway/session-operation-lifecycle.ts

@@ -18,9 +18,10 @@ export type SessionOperationObservation = Readonly<{
 
 const DEFAULT_RETRY_POLICY: SessionOperationRetryPolicy = Object.freeze({
   // Pi's provider retry is useful before a response exists, but a long retry
-  // chain burns quota and keeps the browser in Working. One automatic retry
-  // absorbs an ordinary transient failure without replaying a persistent one.
-  maximumAttempts: 1,
+  // chain burns quota and keeps the browser in Working. Two automatic retries
+  // (the company turn retry's budget, managed/request-stream.mjs) absorb a transient
+  // failure without replaying a persistent one for long.
+  maximumAttempts: 2,
   maximumDelayMs: 8_000
 });
 
@@ -145,6 +146,12 @@ export class SessionOperationLifecycle {
       if (this.#phase === "pending") this.#phase = "running";
     }
 
+    // Replay safety belongs to the model call that failed: Pi retries only
+    // that call, after the tools of earlier ones ran once. A new answer
+    // starts clean; output or a tool of this answer makes it unsafe.
+    if (type === "message_start" && event?.message?.role === "assistant") {
+      this.#visibleAssistantOutput = false; this.#toolCallObserved = false;
+    }
     if (type === "message_update") {
       const update = event?.assistantMessageEvent;
       if (update?.type === "text_delta" && hasVisibleText(update.delta)) this.#visibleAssistantOutput = true;

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

@@ -72,9 +72,15 @@ export async function startLoopbackServer(options: {
   answerSessionQuestion?: (sessionRef: string, questionRef: string, answer: unknown) => unknown | Promise<unknown>;
   suggestPaths?: (projectRef: string, query: string) => unknown | Promise<unknown>;
   listCommands?: (projectRef: string) => unknown | Promise<unknown>;
+  listBranches?: (projectRef: string, repository: string | null) => unknown | Promise<unknown>;
+  switchBranch?: (projectRef: string, request: unknown) => unknown | Promise<unknown>;
   updates?: UpdateRoutes;
   bootstrapTtlMs?: number;
   sessionTtlMs?: number;
+  // Requests a minute from one address before it has a browser session (the
+  // page, its assets, the bootstrap). A test harness opening dozens of fresh
+  // pages from one address raises it; Piagent itself never does.
+  anonymousRequestsPerMinute?: number;
 }): Promise<LoopbackServer> {
   const assets = new Map(loadStaticBundle(options.staticRoot));
   const styleNonce = randomBytes(16).toString("base64");
@@ -112,7 +118,7 @@ export async function startLoopbackServer(options: {
     if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstrapFailures: 0 });
     rate.requests += 1; rates.set(rateKey, rate);
     while (rates.size > 128) rates.delete(rates.keys().next().value as string);
-    if (rate.requests > (browserSession ? SESSION_REQUESTS_PER_MINUTE : REQUESTS_PER_MINUTE)) return errorResponse(response, 429, "rate-limit");
+    if (rate.requests > (browserSession ? SESSION_REQUESTS_PER_MINUTE : options.anonymousRequestsPerMinute ?? REQUESTS_PER_MINUTE)) return errorResponse(response, 429, "rate-limit");
     let url: URL;
     try { url = new URL(request.url ?? "/", origin); }
     catch { return errorResponse(response, 400, "invalid-url"); }
@@ -294,7 +300,8 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
     }
 
-    // The main agent's questions to the member, and Piagent's own updates.
+    // The main agent's questions to the member, a project's Git branches, and
+    // Piagent's own updates.
     if (await routeMemberRequest({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options)) return;
 
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/approvals/") && url.pathname.endsWith("/decision") && options.executeApproval) {

package/packages/piagent-webui/server/member-routes.ts

@@ -12,6 +12,7 @@ const MAX_CONTROL_BODY_BYTES = 70_000;
 const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 const QUESTION_PATH = /^\/api\/v1\/sessions\/([^/]+)\/questions(?:\/([^/]+)\/answer)?$/;
 const PROJECT_PATH = /^\/api\/v1\/projects\/([^/]+)\/(paths|commands)$/;
+const BRANCH_PATH = /^\/api\/v1\/projects\/([^/]+)\/branches(\/switch)?$/;
 
 export type UpdateRoutes = {
   // What is installed, what is available, and the last update run.
@@ -34,6 +35,10 @@ type Options = {
   suggestPaths?: (projectRef: string, query: string) => unknown | Promise<unknown>;
   // The project's and the member's commands and skills; null as above.
   listCommands?: (projectRef: string) => unknown | Promise<unknown>;
+  // The project's Git branches, and a switch to one of them (or a new one);
+  // null as above.
+  listBranches?: (projectRef: string, repository: string | null) => unknown | Promise<unknown>;
+  switchBranch?: (projectRef: string, request: unknown) => unknown | Promise<unknown>;
   updates?: UpdateRoutes;
 };
 
@@ -53,6 +58,11 @@ async function jsonBody(context: Context, code: string): Promise<{ ok: true; val
   catch (error) { errorResponse(context.response, (error as Error).message === "body-limit" ? 413 : 400, code); return { ok: false }; }
 }
 
+const BRANCH_STATUS: Record<string, number> = {
+  "branch-request-invalid": 400, "branch-name-invalid": 400, "not-a-git-repository": 404, "branch-not-found": 404,
+  "branch-switch-blocked-running": 409, "branch-switch-local-changes": 409, "branch-exists": 409, "branch-switch-unfinished-merge": 409
+};
+
 const UPDATE_STATUS: Record<string, number> = {
   "update-not-installable": 409, "update-blocked-running": 409, "update-already-running": 409,
   "update-version-changed": 409, "update-not-available": 409, "update-request-invalid": 400
@@ -96,6 +106,37 @@ export async function routeMemberRequest(context: Context, options: Options): Pr
     return true;
   }
 
+  const branches = BRANCH_PATH.exec(url.pathname);
+  if (branches && (request.method === "GET" && !branches[2] && options.listBranches || request.method === "POST" && branches[2] && options.switchBranch)) {
+    const projectRef = decodeURIComponent(branches[1]);
+    if (request.method === "GET") {
+      if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+      const repository = url.searchParams.get("repository");
+      if (!CURSOR.test(projectRef) || repository !== null && (repository.length === 0 || repository.length > 255 || /[\x00-\x1f/\\]/.test(repository))) {
+        errorResponse(response, 400, "invalid-project-ref"); return true;
+      }
+      try {
+        const value = await options.listBranches!(projectRef, repository);
+        if (value === null) errorResponse(response, 404, "project-not-found"); else jsonResponse(response, 200, value);
+      } catch { errorResponse(response, 503, "branches-unavailable"); }
+      return true;
+    }
+    if (!authorizeChange(context)) return true;
+    if (!CURSOR.test(projectRef)) { errorResponse(response, 400, "invalid-project-ref"); return true; }
+    const body = await jsonBody(context, "branch-request-invalid");
+    if (!body.ok) return true;
+    try {
+      const value = await options.switchBranch!(projectRef, body.value);
+      if (value === null) errorResponse(response, 404, "project-not-found"); else jsonResponse(response, 200, value);
+    } catch (error) {
+      const code = error instanceof Error ? error.message : "branch-switch-failed";
+      const detail = (error as { detail?: unknown })?.detail;
+      jsonResponse(response, BRANCH_STATUS[code] ?? 500, { error: { code: BRANCH_STATUS[code] || code === "branch-switch-failed" || code === "branch-switch-timeout" ? code : "branch-switch-failed",
+        ...(typeof detail === "string" ? { detail } : {}) } });
+    }
+    return true;
+  }
+
   if (!options.updates || !url.pathname.startsWith("/api/v1/updates")) return false;
   const updates = options.updates;
   if (request.method === "GET" && url.pathname === "/api/v1/updates") {

package/packages/piagent-webui/server/tool-call-summary.ts

@@ -8,7 +8,7 @@ import { redactSensitiveText } from "../../piagent-core/extensions/redaction-cor
 // and a bounded result preview. Every string is ANSI-stripped and redacted;
 // raw arguments and results never leave the server.
 export type ToolKind = "read" | "write" | "edit" | "command" | "search" | "list" | "web-search" | "web-fetch"
-  | "subagent" | "network" | "git" | "plan" | "other";
+  | "subagent" | "network" | "docker" | "git" | "plan" | "other";
 export type ToolSummary = { kind: ToolKind; target: string | null; detail: string | null };
 export type ToolChange = { added: number; removed: number; preview: string; truncated: boolean };
 export type ToolResult = { text: string; truncated: boolean; isError: boolean };
@@ -139,6 +139,8 @@ export function summarizeToolCall(name: unknown, input: unknown, cwd?: string):
     }
     case "run_with_network":
       return { summary: { kind: "network", target: commandParts(args.command, cwd).target, detail: clean(args.reason, DETAIL_CHARS) } };
+    case "run_with_docker":
+      return { summary: { kind: "docker", target: commandParts(args.command, cwd).target, detail: clean(args.reason, DETAIL_CHARS) } };
     case "grep": case "find": {
       const where = [displayPath(args.path, cwd), clean(args.glob, 120)].filter(Boolean).join(" · ");
       return { summary: { kind: "search", target: clean(args.pattern, TARGET_CHARS), detail: where || null } };

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

@@ -5,6 +5,7 @@ import { looksLikeCompletionClaim } from "../../piagent-core/runtime/session/com
 import { isLightweightNonAuthorizingChangeLanguage } from "../../piagent-core/runtime/workflows/change-clarification.ts";
 import { workflowCommandPattern } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import { hasVisibleText } from "../shared/text-visibility.ts";
+import { turnEndOf, type TurnEnd } from "../shared/turn-end.ts";
 import { effectiveStopReason } from "./message-stop-reason.ts";
 import { WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE, webUiMessageCorrelationEntry,
   type WebUiMessageCorrelation } from "../shared/message-correlation.ts";
@@ -33,11 +34,11 @@ type TranscriptItem = { messageRef: string; parentMessageRef: string | null; rol
   agentOperationId: string | null; messageRequestId?: string; turnIndex: number | null; content: TranscriptContent;
   attachments?: TranscriptAttachment[];
   toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown";
-    summary?: ToolSummary; change?: ToolChange; result?: ToolResult }>; usage?: TurnUsage; model?: string; process?: HarnessProcess };
+    summary?: ToolSummary; change?: ToolChange; result?: ToolResult }>; usage?: TurnUsage; model?: string; process?: HarnessProcess; turnEnd?: TurnEnd };
 type HarnessFinding = { severity: "blocking" | "major" | "minor"; file: string; line: number | null; issue: string };
 type HarnessIssue = { kind: "wrong_premise" | "conflicts_with_request" | "ambiguous" | "out_of_scope"; detail: string };
-type HarnessProcess = { phase: "plan" | "verify" | "review" | "final" | "objection" | "answer" | "claims" | "rejudge" | "dispute"; outcome?: string; loop?: number; maxLoops?: number;
-  verified?: boolean; reviewed?: boolean; blockingOpen?: number; planOpen?: number; planSkipped?: true; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string;
+type HarnessProcess = { phase: "plan" | "verify" | "review" | "final" | "objection" | "answer" | "claims" | "rejudge" | "dispute" | "continue"; outcome?: string; loop?: number; maxLoops?: number;
+  verified?: boolean; reviewed?: boolean; blockingOpen?: number; planOpen?: number; planDone?: number; planSteps?: number; round?: number; maxRounds?: number; idle?: number; planSkipped?: true; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string;
   findings?: HarnessFinding[]; role?: "scout" | "research" | "verify" | "review"; by?: "main" | "harness"; disputes?: number; unchanged?: true; issues?: HarnessIssue[]; claims?: { claim: string }[] };
 export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
   revision: TranscriptRevision; eventCursor: string; state: "ready" | "unavailable"; items: TranscriptItem[];
@@ -173,7 +174,8 @@ function toolCalls(message: any, sessionRef: string, role: TranscriptItem["role"
 // agent before a code-changing turn ended, and how that turn ended.
 const PROCESS_OUTCOMES = ["no_change", "interrupted", "disputed", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"];
 // A helper's objection to its brief, a failed claim, a disagreement handed to the member.
-const PROCESS_PHASES = ["plan", "verify", "review", "final", "objection", "answer", "claims", "rejudge", "dispute"];
+// "continue": the harness sent the agent back to a checklist with open steps.
+const PROCESS_PHASES = ["plan", "verify", "review", "final", "objection", "answer", "claims", "rejudge", "dispute", "continue"];
 const ISSUE_KINDS = ["wrong_premise", "conflicts_with_request", "ambiguous", "out_of_scope"], HELPER_ROLES = ["scout", "research", "verify", "review"];
 const POLICY_MODES = ["off", "suggest", "require"];
 function harnessProcess(details: any): HarnessProcess | null {
@@ -187,6 +189,12 @@ function harnessProcess(details: any): HarnessProcess | null {
   if (typeof details.reviewed === "boolean") out.reviewed = details.reviewed;
   if (Number.isInteger(details.blockingOpen) && details.blockingOpen >= 0) out.blockingOpen = Math.min(details.blockingOpen, 1000);
   if (Number.isInteger(details.planOpen) && details.planOpen >= 1 && details.planOpen <= 30) out.planOpen = details.planOpen;
+  const upTo = (n: unknown, low: number, high: number): n is number => Number.isInteger(n) && (n as number) >= low && (n as number) <= high;
+  if (upTo(details.planDone, 0, 30)) out.planDone = details.planDone;
+  if (upTo(details.planSteps, 1, 30)) out.planSteps = details.planSteps;
+  if (upTo(details.round, 1, 30)) out.round = details.round;
+  if (upTo(details.maxRounds, 1, 30)) out.maxRounds = details.maxRounds;
+  if (upTo(details.idle, 1, 2)) out.idle = details.idle;
   if (details.planSkipped === true) out.planSkipped = true;
   if (POLICY_MODES.includes(details.policy?.verify)) out.verifyPolicy = details.policy.verify;
   if (POLICY_MODES.includes(details.policy?.review)) out.reviewPolicy = details.policy.review;
@@ -262,6 +270,14 @@ function correlatedTranscriptItems(entries: unknown[], identity: TranscriptIdent
       pending = webUiMessageCorrelationEntry(entry);
       continue;
     }
+    // How the member's message ended: an entry, not a message the model reads.
+    if (entry?.type === "custom" && entry.customType === "agent-watch-turn-end") {
+      const turnEnd = turnEndOf(entry.data);
+      const projected = turnEnd && item({ ...entry, type: "message", message: { role: "custom", content: "" } }, identity, true);
+      if (projected) values.push({ entry, item: { ...projected, turnEnd, ...(turn ? { agentOperationId: turn.operationRef, messageRequestId: turn.messageRequestId } : {}) },
+        cursor: opaque("transcript", [identity.sessionRef, entry.id]) });
+      continue;
+    }
     if (entry?.type === "custom_message" && entry.customType === "agent-watch-process") {
       const process = harnessProcess(entry.details);
       const projected = process && item({ ...entry, type: "message", message: { role: "custom", content: entry.content } }, identity, true);

package/packages/piagent-webui/shared/process-copy.ts

@@ -4,7 +4,7 @@ import { failureRoleText, type CopyLocale, type FailureRole } from "./company-co
 
 export type ProcessCopyInput = {
   phase?: string; outcome?: string; loop?: number; maxLoops?: number; verified?: boolean; reviewed?: boolean; blockingOpen?: number;
-  planOpen?: number; planSkipped?: boolean; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string; role?: FailureRole;
+  planOpen?: number; planDone?: number; planSteps?: number; round?: number; maxRounds?: number; idle?: number; planSkipped?: boolean; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string; role?: FailureRole;
   disputes?: number; unchanged?: boolean;
   findings?: Array<{ severity: string; file?: string; line?: number | null; issue: string }>;
   claims?: Array<{ claim: string }>; issues?: Array<{ kind: string; detail: string }>;
@@ -41,6 +41,8 @@ export function headlineText(process: ProcessCopyInput, locale: CopyLocale): str
   const round = process.loop && process.maxLoops ? pick(locale, ` (vòng ${process.loop}/${process.maxLoops})`, ` (round ${process.loop}/${process.maxLoops})`) : "";
   const who = failureRoleText(process.role ?? "review", locale), count = (process.findings ?? process.claims ?? process.issues ?? []).length;
   switch (process.phase) {
+    case "continue": return pick(locale, `Harness: checklist còn ${process.planOpen ?? 0} bước (${process.planDone ?? 0}/${process.planSteps ?? 0} xong), cho main agent làm tiếp · vòng ${process.round ?? 1}${process.idle ? " (vòng trước không xong thêm bước nào)" : ""}`,
+      `Harness: the checklist has ${process.planOpen ?? 0} open step(s) (${process.planDone ?? 0}/${process.planSteps ?? 0} done); sent the main agent on · round ${process.round ?? 1}${process.idle ? " (the previous round finished no step)" : ""}`);
     case "plan": return pick(locale, `Harness: plan còn ${process.planOpen ?? 0} bước chưa đánh dấu xong, yêu cầu agent cập nhật`, `Harness: ${process.planOpen ?? 0} plan step(s) not marked completed; asked the agent to update the plan`);
     case "verify": return pick(locale, `Harness: chưa có check nào pass trên code hiện tại, yêu cầu agent chạy check${round}`, `Harness: no check has passed on the current code; asked the agent to run checks${round}`);
     case "review": return pick(locale, `Harness: review tìm thấy ${count} lỗi blocking, gửi lại agent để fix hoặc giải thích${round}`, `Harness: the review found ${count} blocking issue(s); sent back to the agent to fix or answer${round}`);