@piagent/platform 1.10.0 → 1.11.1

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

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

@@ -9,6 +9,7 @@ import type { PiagentWebUICanonicalSnapshotV1 } from "../contracts/generated/sna
 import { startLoopbackServer } from "../server/loopback-server.ts";
 import { startGatewayControlSocket, type GatewayControlResponse } from "./control-socket.ts";
 import { loadPinnedPiHost } from "./pi-host.ts";
+import { UpdateCenter } from "./update-center.ts";
 import {
   gatewayProfileState,
   profileRef,
@@ -113,6 +114,7 @@ export async function startPiagentGateway(options: {
   let mcpAuth: McpAuthBroker | null = null;
   let attachments: SessionAttachmentRegistry | null = null;
   let relay: CompanyRelay | null = null;
+  let updates: UpdateCenter | null = null;
   let closing: Promise<void> | null = null;
   let settleWait: (() => void) | null = null;
   const waited = new Promise<void>((resolve) => { settleWait = resolve; });
@@ -121,7 +123,7 @@ export async function startPiagentGateway(options: {
     if (closing) return await closing;
     closing = (async () => {
       removeGatewayDescriptor(state, gatewayInstanceRef);
-      relay?.close();
+      relay?.close(); updates?.close();
       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
@@ -242,6 +244,10 @@ export async function startPiagentGateway(options: {
     attachments = new SessionAttachmentRegistry({
       inspect: async (sessionRef) => await (await inspections.provider(sessionRef)).snapshot() as PiagentWebUICanonicalSnapshotV1
     });
+    // Piagent's own updates: Pi and Piagent together, never while a turn runs.
+    updates = new UpdateCenter({ packageRoot: options.packageRoot, piVersion: options.expectedPiVersion, managed: Boolean(options.managed),
+      busy: async () => runtimes!.currentOperations().length + (relay ? (await relay.operations()).length : 0) });
+    updates.start();
     loopback = await startLoopbackServer({
       staticRoot,
       mode: "gateway",
@@ -280,6 +286,7 @@ export async function startPiagentGateway(options: {
       // conversation runs (the company Gateway for a company conversation).
       readSessionQuestions: (sessionRef) => company(sessionRef)
         ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/questions`) : runtimes!.questions(sessionRef),
+      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)
         : runtimes!.answerQuestion(sessionRef, questionRef, answer),

package/packages/piagent-webui/gateway/update-center.ts

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+
+import { compareReleaseVersions, releaseVersion, writeUpdateCache } from "../../piagent-core/extensions/update-check.js";
+
+// Piagent updates from the dashboard: what is installed, what the registry
+// offers, and one click that moves the machine to it. Pi is never offered
+// past the version the newest Piagent pins (its peer dependency): that is the
+// host its managed runtime is qualified on. A newer Pi is shown as untested.
+//
+// The registry is asked in the background, at most every 6 hours unless the
+// member asks now; the dashboard reads the cached answer. Everything read from
+// outside (registry answers, the cache and job files any local process could
+// write) is accepted only as release versions and known codes.
+const PLATFORM = "@piagent/platform";
+const HOST = "@earendil-works/pi-coding-agent";
+export const CHECK_EVERY_MS = 6 * 60 * 60 * 1000;
+const FORCED_CHECK_GAP_MS = 30_000;
+const PROBE_TIMEOUT_MS = 20_000;
+const MAX_FILE_BYTES = 4096;
+const STATUS_FILE = "piagent-update-status.json", JOB_FILE = "piagent-update-job.json";
+// A run that has not finished in this time died with its process.
+const JOB_STALE_MS = 45 * 60 * 1000;
+// A finished run is reported for a day, then no longer.
+const JOB_REPORTED_MS = 24 * 60 * 60 * 1000;
+const JOB_STATES = new Set(["starting", "running", "succeeded", "failed"]);
+const JOB_REASONS = new Set(["update-command-failed", "update-version-mismatch", "dashboard-restart-failed", "update-interrupted", "update-start-failed"]);
+
+export type Registry = { latest?: string; latestHost?: string; hostLatest?: string; checkedAt?: number };
+export type UpdateJob = { state: "starting" | "running" | "succeeded" | "failed"; from: string; to: string; startedAt: string;
+  finishedAt?: string; pid?: number; reason?: string; installed?: string; bindingChanged?: boolean };
+export type UpdateStatus = {
+  schemaVersion: 1; version: "piagent-update-status-v1";
+  installable: boolean; reason: "working-copy" | "company-runtime" | null;
+  checkedAt: string | null; checking: boolean; checkEveryHours: number;
+  piagent: { installed: string | null; latest: string | null; updateAvailable: boolean };
+  pi: { installed: string | null; required: string | null; latest: string | null; updateAvailable: boolean; newerUntested: boolean };
+  updateAvailable: boolean; runningConversations: number; job: UpdateJob | null;
+};
+
+const stateDirectory = (home: string) => path.join(home, ".pi");
+function readSmallJson(file: string): any {
+  try { if (fs.statSync(file).size > MAX_FILE_BYTES) return undefined; return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch { return undefined; }
+}
+function writeJson(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+const version = (value: unknown) => releaseVersion(value) ?? undefined;
+
+export function readRegistryCache(home: string): Registry {
+  const value = readSmallJson(path.join(stateDirectory(home), STATUS_FILE)), checkedAt = Date.parse(value?.checkedAt);
+  return { latest: version(value?.latest), latestHost: version(value?.latestHost), hostLatest: version(value?.hostLatest),
+    checkedAt: Number.isFinite(checkedAt) ? checkedAt : undefined };
+}
+export function writeRegistryCache(home: string, registry: Registry, now: number): void {
+  writeJson(path.join(stateDirectory(home), STATUS_FILE), { schemaVersion: 1, latest: registry.latest ?? null, latestHost: registry.latestHost ?? null,
+    hostLatest: registry.hostLatest ?? null, checkedAt: new Date(now).toISOString() });
+  // The Terminal's own notice reads the shared cache: keep both on one answer.
+  if (registry.latest) writeUpdateCache(home, registry.latest, now);
+}
+
+export function readUpdateJob(home: string, now = Date.now(), alive = processAlive): UpdateJob | null {
+  const value = readSmallJson(path.join(stateDirectory(home), JOB_FILE));
+  const from = version(value?.from), to = version(value?.to), startedAt = Date.parse(value?.startedAt);
+  if (!value || !JOB_STATES.has(value.state) || !from || !to || !Number.isFinite(startedAt)) return null;
+  const job: UpdateJob = { state: value.state, from, to, startedAt: new Date(startedAt).toISOString() };
+  const finishedAt = Date.parse(value.finishedAt);
+  if (Number.isFinite(finishedAt)) job.finishedAt = new Date(finishedAt).toISOString();
+  if ((job.state === "succeeded" || job.state === "failed") && Number.isFinite(finishedAt) && now - finishedAt > JOB_REPORTED_MS) return null;
+  if (Number.isSafeInteger(value.pid) && value.pid > 0) job.pid = value.pid;
+  if (JOB_REASONS.has(value.reason)) job.reason = value.reason;
+  if (version(value.installed)) job.installed = version(value.installed);
+  if (value.bindingChanged === true) job.bindingChanged = true;
+  // A run whose process is gone (or never reported one) did not finish.
+  if ((job.state === "running" || job.state === "starting") && (now - startedAt > JOB_STALE_MS || (job.pid ? !alive(job.pid) : now - startedAt > 120_000)))
+    return { ...job, state: "failed", reason: "update-interrupted" };
+  return job;
+}
+export function writeUpdateJob(home: string, job: UpdateJob): void { writeJson(path.join(stateDirectory(home), JOB_FILE), job); }
+function processAlive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; } }
+
+// The npm helper this dashboard runs from can update itself; a working copy
+// is updated with git, and a company runtime by the dashboard that owns it.
+export function updateTarget(packageRoot: string, managed: boolean): { installable: boolean; reason: UpdateStatus["reason"] } {
+  if (managed) return { installable: false, reason: "company-runtime" };
+  const parts = path.resolve(packageRoot).split(path.sep);
+  const installed = parts.includes("node_modules") && !parts.some((part) => part === "_npx" || part === "_cacache");
+  return installed ? { installable: true, reason: null } : { installable: false, reason: "working-copy" };
+}
+
+export function composeUpdateStatus(input: { installedPiagent?: string; installedPi?: string; target: ReturnType<typeof updateTarget>;
+  registry: Registry; job: UpdateJob | null; runningConversations: number; checking: boolean }): UpdateStatus {
+  const installedPiagent = version(input.installedPiagent) ?? null, installedPi = version(input.installedPi) ?? null;
+  const { latest, latestHost, hostLatest } = input.registry;
+  const piagentNewer = Boolean(installedPiagent && latest && compareReleaseVersions(latest, installedPiagent) > 0);
+  // The Pi update is the version the newest Piagent pins, whichever way it
+  // moves; it is only offered together with that Piagent.
+  const piChange = Boolean(latestHost && installedPi !== latestHost && (piagentNewer || installedPiagent === latest));
+  return { schemaVersion: 1, version: "piagent-update-status-v1", installable: input.target.installable, reason: input.target.reason,
+    checkedAt: input.registry.checkedAt ? new Date(input.registry.checkedAt).toISOString() : null, checking: input.checking,
+    checkEveryHours: CHECK_EVERY_MS / 3_600_000,
+    piagent: { installed: installedPiagent, latest: latest ?? null, updateAvailable: piagentNewer },
+    pi: { installed: installedPi, required: latestHost ?? null, latest: hostLatest ?? null, updateAvailable: piChange,
+      newerUntested: Boolean(hostLatest && latestHost && compareReleaseVersions(hostLatest, latestHost) > 0) },
+    updateAvailable: piagentNewer || piChange, runningConversations: input.runningConversations, job: input.job };
+}
+
+type NpmView = (spec: string, field: string) => Promise<unknown>;
+const npmView: NpmView = (spec, field) => new Promise((resolve) => {
+  execFile("npm", ["view", spec, field, "--json"], { timeout: PROBE_TIMEOUT_MS, windowsHide: true, maxBuffer: 256 * 1024 },
+    (error, stdout) => { if (error) return resolve(undefined); try { const value = JSON.parse(String(stdout).trim() || "null"); resolve(Array.isArray(value) && value.length === 1 ? value[0] : value); } catch { resolve(undefined); } });
+});
+
+// One answer from the registry, or null when it could not be read.
+export async function probeRegistry(view: NpmView = npmView): Promise<Registry | null> {
+  const latest = version(await view(PLATFORM, "version"));
+  if (!latest) return null;
+  const peers = await view(`${PLATFORM}@${latest}`, "peerDependencies") as Record<string, unknown> | undefined;
+  return { latest, latestHost: version(peers?.[HOST]), hostLatest: version(await view(HOST, "version")) };
+}
+
+export class UpdateCenter {
+  #home: string; #packageRoot: string; #piVersion?: string; #target: ReturnType<typeof updateTarget>;
+  #busy: () => Promise<number>; #view: NpmView; #now: () => number; #spawnJob: (args: string[]) => number | undefined;
+  #probe: Promise<void> | null = null; #lastForced = 0; #timer: NodeJS.Timeout | null = null;
+
+  constructor(options: { packageRoot: string; piVersion?: string; managed: boolean; busy: () => Promise<number>; home?: string;
+    view?: NpmView; now?: () => number; spawnJob?: (args: string[]) => number | undefined }) {
+    this.#home = options.home ?? os.homedir(); this.#packageRoot = options.packageRoot; this.#piVersion = options.piVersion;
+    this.#target = updateTarget(options.packageRoot, options.managed); this.#busy = options.busy;
+    this.#view = options.view ?? npmView; this.#now = options.now ?? Date.now;
+    this.#spawnJob = options.spawnJob ?? ((args) => {
+      const child = spawn(process.execPath, args, { detached: true, stdio: "ignore", windowsHide: true, cwd: this.#home,
+        env: { ...process.env, PIAGENT_NO_UPDATE_CHECK: "1" } });
+      child.unref(); return child.pid;
+    });
+  }
+
+  // Only a machine that can update itself asks the registry (a working copy
+  // or a company runtime never does, nor any run with PIAGENT_NO_UPDATE_CHECK).
+  #asks(): boolean { return this.#target.installable && !process.env.PIAGENT_NO_UPDATE_CHECK?.trim(); }
+  // Checks now when the cached answer is older than the period, then on it.
+  start(): void {
+    if (this.#timer || !this.#asks()) return;
+    void this.#refreshIfStale();
+    this.#timer = setInterval(() => void this.#refreshIfStale(), 15 * 60 * 1000); this.#timer.unref();
+  }
+  close(): void { if (this.#timer) clearInterval(this.#timer); this.#timer = null; }
+
+  #installedPiagent(): string | undefined {
+    try { return version(JSON.parse(fs.readFileSync(path.join(this.#packageRoot, "package.json"), "utf8")).version); } catch { return undefined; }
+  }
+  async #refreshIfStale(): Promise<void> {
+    const checkedAt = readRegistryCache(this.#home).checkedAt;
+    if (!checkedAt || this.#now() - checkedAt >= CHECK_EVERY_MS) await this.#refresh();
+  }
+  #refresh(): Promise<void> {
+    this.#probe ??= (async () => {
+      try { const registry = await probeRegistry(this.#view); if (registry) writeRegistryCache(this.#home, registry, this.#now()); }
+      catch { /* the next period tries again */ }
+      finally { this.#probe = null; }
+    })();
+    return this.#probe;
+  }
+
+  async status(): Promise<UpdateStatus> {
+    return composeUpdateStatus({ installedPiagent: this.#installedPiagent(), installedPi: this.#piVersion, target: this.#target,
+      registry: readRegistryCache(this.#home), job: readUpdateJob(this.#home, this.#now()), runningConversations: await this.#busy().catch(() => 0),
+      checking: this.#probe !== null });
+  }
+  async check(): Promise<UpdateStatus> {
+    if (!this.#asks()) return this.status();
+    if (this.#now() - this.#lastForced >= FORCED_CHECK_GAP_MS) { this.#lastForced = this.#now(); await this.#refresh(); }
+    else if (this.#probe) await this.#probe;
+    return this.status();
+  }
+  // `request.version`: the Piagent version the member chose to install.
+  async apply(request: unknown): Promise<{ job: UpdateJob }> {
+    const wanted = version((request as { version?: unknown } | null)?.version);
+    if (!wanted) throw new Error("update-request-invalid");
+    const status = await this.status();
+    if (!status.installable) throw new Error("update-not-installable");
+    if (status.job && (status.job.state === "running" || status.job.state === "starting")) throw new Error("update-already-running");
+    if (status.runningConversations > 0) throw new Error("update-blocked-running");
+    if (!status.updateAvailable) throw new Error("update-not-available");
+    if (wanted !== status.piagent.latest) throw new Error("update-version-changed");
+    const from = status.piagent.installed ?? wanted;
+    const job: UpdateJob = { state: "starting", from, to: wanted, startedAt: new Date(this.#now()).toISOString() };
+    writeUpdateJob(this.#home, job);
+    const pid = this.#spawnJob([path.join(this.#packageRoot, "scripts", "dashboard-update-job.mjs"), "--from", from, "--to", wanted]);
+    if (!pid) { const failed: UpdateJob = { ...job, state: "failed", reason: "update-start-failed", finishedAt: new Date(this.#now()).toISOString() }; writeUpdateJob(this.#home, failed); return { job: failed }; }
+    const started: UpdateJob = { ...job, pid }; writeUpdateJob(this.#home, started);
+    return { job: started };
+  }
+}

package/packages/piagent-webui/server/http-security.ts

@@ -1,4 +1,4 @@
-import type { ServerResponse } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 
 export const SECURITY_HEADERS = Object.freeze({
   "Cross-Origin-Opener-Policy": "same-origin",
@@ -25,3 +25,17 @@ export function jsonResponse(response: ServerResponse, status: number, value: un
 export function errorResponse(response: ServerResponse, status: number, code: string): void {
   jsonResponse(response, status, { error: { code } });
 }
+
+export function requestBody(request: IncomingMessage, maximumBytes: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []; let bytes = 0, failed = false;
+    request.on("data", (chunk: Buffer) => {
+      if (failed) return;
+      bytes += chunk.length;
+      if (bytes > maximumBytes) { failed = true; reject(new Error("body-limit")); }
+      else chunks.push(chunk);
+    });
+    request.on("end", () => { if (!failed) resolve(Buffer.concat(chunks)); });
+    request.on("error", (error) => { if (!failed) reject(error); });
+  });
+}

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

@@ -1,7 +1,8 @@
-import http, { type IncomingMessage, type ServerResponse } from "node:http";
+import http, { type ServerResponse } from "node:http";
 import { randomBytes } from "node:crypto";
 
-import { errorResponse, applySecurityHeaders, jsonResponse } from "./http-security.ts";
+import { errorResponse, applySecurityHeaders, jsonResponse, requestBody } from "./http-security.ts";
+import { routeMemberRequest, type UpdateRoutes } from "./member-routes.ts";
 import { ReadModelNotFound, type WebUiReadModelProvider } from "./read-model-provider.ts";
 import { routeReadOnlyRequest } from "./read-only-router.ts";
 import { SessionAuthority } from "./session-auth.ts";
@@ -32,20 +33,6 @@ export type LoopbackServer = {
   close(): Promise<void>;
 };
 
-function requestBody(request: IncomingMessage, maximumBytes: number): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = []; let bytes = 0, failed = false;
-    request.on("data", (chunk: Buffer) => {
-      if (failed) return;
-      bytes += chunk.length;
-      if (bytes > maximumBytes) { failed = true; reject(new Error("body-limit")); }
-      else chunks.push(chunk);
-    });
-    request.on("end", () => { if (!failed) resolve(Buffer.concat(chunks)); });
-    request.on("error", (error) => { if (!failed) reject(error); });
-  });
-}
-
 function serveAsset(response: ServerResponse, asset: StaticAsset): void {
   response.statusCode = 200;
   response.setHeader("Cache-Control", "no-store");
@@ -83,6 +70,7 @@ export async function startLoopbackServer(options: {
   executeApproval?: (approvalRef: string, decision: unknown) => unknown | Promise<unknown>;
   readSessionQuestions?: (sessionRef: string) => unknown | Promise<unknown>;
   answerSessionQuestion?: (sessionRef: string, questionRef: string, answer: unknown) => unknown | Promise<unknown>;
+  updates?: UpdateRoutes;
   bootstrapTtlMs?: number;
   sessionTtlMs?: number;
 }): Promise<LoopbackServer> {
@@ -304,32 +292,8 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
     }
 
-    // The main agent's questions to the member of a conversation, and the answer.
-    const questionPath = /^\/api\/v1\/sessions\/([^/]+)\/questions(?:\/([^/]+)\/answer)?$/.exec(url.pathname);
-    if (request.method === "GET" && questionPath && !questionPath[2] && options.readSessionQuestions) {
-      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
-      const sessionRef = decodeURIComponent(questionPath[1]);
-      if (!CURSOR.test(sessionRef)) return errorResponse(response, 400, "invalid-session-ref");
-      try { return jsonResponse(response, 200, await options.readSessionQuestions(sessionRef)); }
-      catch { return errorResponse(response, 503, "questions-unavailable"); }
-    }
-    if (request.method === "POST" && questionPath && questionPath[2] && options.answerSessionQuestion) {
-      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
-      const mutationSession = auth.authorizeMutation(request);
-      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
-      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
-      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
-      const sessionRef = decodeURIComponent(questionPath[1]), questionRef = decodeURIComponent(questionPath[2]);
-      if (!CURSOR.test(sessionRef) || !/^question\.[0-9a-f-]{36}$/.test(questionRef)) return errorResponse(response, 400, "invalid-question-ref");
-      let answer: unknown;
-      try { answer = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
-      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-question-answer"); }
-      try { return jsonResponse(response, 200, await options.answerSessionQuestion(sessionRef, questionRef, answer)); }
-      catch (error) {
-        const code = error instanceof Error ? error.message : "questions-unavailable";
-        return errorResponse(response, code === "question-not-pending" ? 409 : code === "question-answer-invalid" ? 400 : 503, code);
-      }
-    }
+    // The main agent's questions to the member, 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) {
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");

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

@@ -0,0 +1,99 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { errorResponse, jsonResponse, requestBody } from "./http-security.ts";
+import type { SessionAuthority } from "./session-auth.ts";
+
+// Requests a member makes beside a conversation: answering the main agent's
+// questions, and keeping Piagent itself up to date. Reads need the browser
+// session; every change also needs this origin, the session's CSRF token and
+// a share of the control rate.
+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)?$/;
+
+export type UpdateRoutes = {
+  // What is installed, what is available, and the last update run.
+  status(): unknown | Promise<unknown>;
+  // Asks the registry now instead of waiting for the next periodic check.
+  check(): unknown | Promise<unknown>;
+  // Starts the update to the version the member saw; refused when it moved.
+  apply(request: unknown): unknown | Promise<unknown>;
+};
+
+type Context = {
+  request: IncomingMessage; response: ServerResponse; url: URL; origin: string; requestOrigin: string | undefined;
+  auth: SessionAuthority; now: number; consumeControl(sessionId: string, now: number): boolean;
+};
+type Options = {
+  readSessionQuestions?: (sessionRef: string) => unknown | Promise<unknown>;
+  answerSessionQuestion?: (sessionRef: string, questionRef: string, answer: unknown) => unknown | Promise<unknown>;
+  updates?: UpdateRoutes;
+};
+
+// The checks every change shares; a refusal is answered here and false returned.
+function authorizeChange(context: Context): boolean {
+  const { request, response, origin, requestOrigin, auth, now, consumeControl } = context;
+  if (requestOrigin !== origin) { errorResponse(response, 403, "origin-required"); return false; }
+  const session = auth.authorizeMutation(request);
+  if (!session) { errorResponse(response, 403, "mutation-authority-rejected"); return false; }
+  if (!consumeControl(session.id, now)) { errorResponse(response, 429, "control-rate-limit"); return false; }
+  if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) { errorResponse(response, 415, "content-type"); return false; }
+  return true;
+}
+
+async function jsonBody(context: Context, code: string): Promise<{ ok: true; value: unknown } | { ok: false }> {
+  try { return { ok: true, value: JSON.parse((await requestBody(context.request, MAX_CONTROL_BODY_BYTES)).toString("utf8")) }; }
+  catch (error) { errorResponse(context.response, (error as Error).message === "body-limit" ? 413 : 400, code); return { ok: false }; }
+}
+
+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
+};
+
+// True when the request was one of these routes (answered, or refused).
+export async function routeMemberRequest(context: Context, options: Options): Promise<boolean> {
+  const { request, response, url, auth } = context;
+  const question = QUESTION_PATH.exec(url.pathname);
+  if (request.method === "GET" && question && !question[2] && options.readSessionQuestions) {
+    if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+    const sessionRef = decodeURIComponent(question[1]);
+    if (!CURSOR.test(sessionRef)) { errorResponse(response, 400, "invalid-session-ref"); return true; }
+    try { jsonResponse(response, 200, await options.readSessionQuestions(sessionRef)); }
+    catch { errorResponse(response, 503, "questions-unavailable"); }
+    return true;
+  }
+  if (request.method === "POST" && question && question[2] && options.answerSessionQuestion) {
+    if (!authorizeChange(context)) return true;
+    const sessionRef = decodeURIComponent(question[1]), questionRef = decodeURIComponent(question[2]);
+    if (!CURSOR.test(sessionRef) || !/^question\.[0-9a-f-]{36}$/.test(questionRef)) { errorResponse(response, 400, "invalid-question-ref"); return true; }
+    const body = await jsonBody(context, "invalid-question-answer");
+    if (!body.ok) return true;
+    try { jsonResponse(response, 200, await options.answerSessionQuestion(sessionRef, questionRef, body.value)); }
+    catch (error) {
+      const code = error instanceof Error ? error.message : "questions-unavailable";
+      errorResponse(response, code === "question-not-pending" ? 409 : code === "question-answer-invalid" ? 400 : 503, code);
+    }
+    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") {
+    if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+    try { jsonResponse(response, 200, await updates.status()); }
+    catch { errorResponse(response, 503, "update-status-unavailable"); }
+    return true;
+  }
+  const action = request.method === "POST" ? /^\/api\/v1\/updates\/(check|apply)$/.exec(url.pathname)?.[1] : undefined;
+  if (!action) { errorResponse(response, 404, "not-found"); return true; }
+  if (!authorizeChange(context)) return true;
+  const body = await jsonBody(context, "update-request-invalid");
+  if (!body.ok) return true;
+  try { jsonResponse(response, action === "apply" ? 202 : 200, action === "apply" ? await updates.apply(body.value) : await updates.check()); }
+  catch (error) {
+    const code = error instanceof Error ? error.message : "update-unavailable";
+    errorResponse(response, UPDATE_STATUS[code] ?? 503, UPDATE_STATUS[code] ? code : "update-unavailable");
+  }
+  return true;
+}

package/scripts/dashboard-update-job.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// One update started from the dashboard, run apart from it: the dashboard is
+// restarted at the end, so this process must outlive it. It moves Pi and
+// Piagent to the chosen release with `piagent-update` (Pi first, to the
+// version that release pins), restarts the dashboard on the new code, and
+// leaves the outcome in ~/.pi/piagent-update-job.json for the new dashboard to
+// show. The full output goes to ~/.pi/piagent-update-job.log.
+//
+//   dashboard-update-job.mjs --from 1.10.0 --to 1.11.0
+//     [--updater <script>] [--dashboard <script>] [--home <dir>]   (tests)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const RELEASE = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function option(name, fallback) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index > 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+const from = option("from"), to = option("to");
+const home = path.resolve(option("home", os.homedir()));
+const updater = option("updater", path.join(packageRoot, "scripts", "update-global.mjs"));
+const dashboard = option("dashboard", path.join(packageRoot, "scripts", "piagent-dashboard.mjs"));
+if (!RELEASE.test(from ?? "") || !RELEASE.test(to ?? "")) {
+  process.stderr.write("usage: dashboard-update-job.mjs --from X.Y.Z --to X.Y.Z\n");
+  process.exit(2);
+}
+
+const directory = path.join(home, ".pi"), jobFile = path.join(directory, "piagent-update-job.json");
+fs.mkdirSync(directory, { recursive: true });
+const startedAt = (() => {
+  try { const value = JSON.parse(fs.readFileSync(jobFile, "utf8")); return value?.to === to && Number.isFinite(Date.parse(value.startedAt)) ? value.startedAt : undefined; }
+  catch { return undefined; }
+})() ?? new Date().toISOString();
+function record(fields) {
+  const temporary = `${jobFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify({ from, to, startedAt, pid: process.pid, ...fields }, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, jobFile);
+}
+const finish = (state, fields = {}) => { record({ state, finishedAt: new Date().toISOString(), ...fields }); process.exit(state === "succeeded" ? 0 : 1); };
+
+record({ state: "running" });
+const log = fs.openSync(path.join(directory, "piagent-update-job.log"), "w", 0o600);
+const env = { ...process.env, PIAGENT_NO_UPDATE_CHECK: "1" };
+fs.writeSync(log, `Piagent update ${from} -> ${to} (${new Date().toISOString()})\n`);
+const update = spawnSync(process.execPath, [updater, "--version", to], { stdio: ["ignore", log, log], env, timeout: 30 * 60 * 1000 });
+if (update.status !== 0) finish("failed", { reason: "update-command-failed" });
+
+let installed;
+try { installed = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version; } catch { installed = undefined; }
+if (installed !== to) finish("failed", { reason: "update-version-mismatch", ...(RELEASE.test(installed ?? "") ? { installed } : {}) });
+
+// Agent Watch pins the company launcher it starts; a release that changed
+// the launcher needs the binding imported again in Agent Watch.
+let bindingChanged = false;
+try {
+  const agentDir = process.env.PI_CODING_AGENT_DIR?.trim() || path.join(home, ".pi", "agent");
+  const binding = JSON.parse(fs.readFileSync(path.join(agentDir, "agent-watch-managed.json"), "utf8"));
+  if (typeof binding?.entrypoint === "string" && typeof binding?.entrypoint_sha256 === "string")
+    bindingChanged = crypto.createHash("sha256").update(fs.readFileSync(binding.entrypoint)).digest("hex") !== binding.entrypoint_sha256;
+} catch { /* no company binding on this machine */ }
+
+// The new dashboard opens in a new browser tab: the old tab's browser session
+// ends with the old dashboard. Its launch link is never written to the log.
+fs.writeSync(log, "\nRestarting the dashboard on the new release\n");
+// Like the \`piagent\` command, with the package's TypeScript loader: an npm
+// install sits under node_modules, where Node does not strip types itself.
+const loader = path.join(packageRoot, "scripts", "register-typescript-loader.mjs");
+const restart = spawnSync(process.execPath, ["--disable-warning=ExperimentalWarning", "--import", loader, dashboard, "restart", "--json"],
+  { stdio: ["ignore", "ignore", log], env, timeout: 3 * 60 * 1000 });
+finish("succeeded", { installed, ...(bindingChanged ? { bindingChanged } : {}), ...(restart.status === 0 ? {} : { reason: "dashboard-restart-failed" }) });

package/scripts/piagent-dashboard.mjs

@@ -155,6 +155,14 @@ async function waitForGatewayStopped(previous, timeoutMs = 8_000) {
 }
 
 async function ensureStarted() {
+  // After an update the Gateway still running is the earlier release, with
+  // its pages loaded: it is replaced rather than reused.
+  const running = readGatewayDescriptor(gatewayProfileState(agentDir));
+  if (running && processAlive(running.pid) && typeof running.packageVersion === "string" && running.packageVersion !== packageJson.version) {
+    process.stderr.write(`Piagent ${running.packageVersion} is still running; restarting the dashboard on ${packageJson.version}.\n`);
+    try { await control("stop"); } catch { /* already stopping */ }
+    await waitForGatewayStopped(running);
+  }
   const existing = await currentLaunchUrl() ?? await waitForRunningGateway();
   if (existing) return existing;
   const effectiveAgentDir = path.resolve(agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"));

package/scripts/update-global.mjs

@@ -526,6 +526,8 @@ function main() {
   console.log(options.dryRun
     ? `\nDRY RUN: nothing was installed. Rerun without --dry-run to apply v${targetHelper}.`
     : `\nPASS: updated to v${targetHelper}.`);
+  // A dashboard started before the update still serves the earlier release.
+  if (!options.dryRun && helperNeedsChange) console.log("Open the dashboard with `piagent dashboard`: one still running an earlier release is restarted on the new one.");
 }
 
 main();