pwragent 1.3.9 → 1.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pwragent",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "private": false,
   "type": "module",
   "description": "Experimental headless PwrAgent daemon and command-line client.",
@@ -53,7 +53,8 @@
   "devDependencies": {
     "@pwragent/federation": "workspace:*",
     "@pwragent/shared": "workspace:*",
-    "esbuild": "0.28.1",
+    "@pwragent/owner-core": "workspace:*",
+    "esbuild": "0.28.2",
     "@pwragent/agent-tools": "workspace:*"
   },
   "dependencies": {
@@ -63,7 +64,7 @@
     "node-pty"
   ],
   "pwragentRelease": {
-    "tag": "v1.3.9",
-    "commit": "0fc28acd4318e55e172427b5a694c1a1dd096c15"
+    "tag": "v1.3.11",
+    "commit": "7b787f4a90bfff4811f1d41b04ae025f0cfe6ebf"
   }
 }

package/src/cli.js

@@ -6,6 +6,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { call } from "./client.js";
 import { serve } from "./daemon.js";
 import { ACTIVE } from "./store.js";
+import { formatVersion, installedVersion, packageVersion, restartRequired } from "./version.js";
 
 const help = `PwrAgent Headless (experimental, Linux/macOS, Node >=22)
 
@@ -16,6 +17,7 @@ const help = `PwrAgent Headless (experimental, Linux/macOS, Node >=22)
   pwragent project-add|project-remove --path /workspace/project
   pwragent git-auth-configure --config-file /outpost/git-auth-settings.json
   pwragent status | list
+  pwragent --version | version
   pwragent submit --id JOB --prompt-file /task.txt [--sandbox read-only|workspace-write]
                   [--model MODEL] [--thread THREAD_ID] [--cwd /workspace/project]
   pwragent show|read|interrupt|wait --id JOB
@@ -36,6 +38,7 @@ No provisioning, login, queue, automatic replay, or local messaging providers.
 export async function main(args) {
   const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
     help: { type: "boolean", short: "h" },
+    version: { type: "boolean" },
     profile: { type: "string" },
     workspace: { type: "string" },
     "codex-home": { type: "string" },
@@ -52,7 +55,9 @@ export async function main(args) {
     peer: { type: "string" },
     name: { type: "string" }, remote: { type: "string" }, path: { type: "string" }, cwd: { type: "string" }, "config-file": { type: "string" },
   } });
-  if (values.help || !positionals.length) { console.log(help); return 0; }
+  if (values.help) { console.log(help); return 0; }
+  if (values.version) { console.log(formatVersion(packageVersion())); return 0; }
+  if (!positionals.length) { console.log(help); return 0; }
   if (positionals.length !== 1) throw new Error("Expected one command; see --help");
   const command = positionals[0];
   const allowed = {
@@ -60,7 +65,7 @@ export async function main(args) {
     submit: ["id", "prompt-file", "thread", "model", "sandbox", "cwd"],
     "project-list": [], "project-create": ["name", "label"], "project-clone": ["name", "remote", "label"],
     "project-add": ["path", "label"], "project-remove": ["path"], "git-auth-configure": ["config-file"],
-    show: ["id"], read: ["id"], interrupt: ["id"], wait: ["id"], status: [], list: [],
+    show: ["id"], read: ["id"], interrupt: ["id"], wait: ["id"], status: [], list: [], version: [],
     "federation-join": ["invite-file", "gateway", "label"],
     "federation-invite": ["port", "label"],
     "federation-status": [], "federation-leave": [], "federation-revoke": ["peer"],
@@ -69,6 +74,7 @@ export async function main(args) {
   for (const option of Object.keys(values)) {
     if (option !== "profile" && !allowed[command].includes(option)) throw new Error(`--${option} does not apply to ${command}`);
   }
+  if (command === "version") { console.log(JSON.stringify(packageVersion())); return 0; }
   const profile = values.profile || process.env.PWRAGENT_PROFILE || "default";
   if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(profile)) throw new Error("Invalid profile name");
   const root = process.env.PWRAGENT_HOME || path.join(homedir(), ".pwragent");
@@ -118,6 +124,12 @@ export async function main(args) {
       await delay(1000);
     }
   }
+  if (command === "status") {
+    const status = await call(directory, "status", {});
+    const installed = installedVersion();
+    console.log(JSON.stringify({ ...status, installed, restartRequired: restartRequired(status.running, installed) }));
+    return 0;
+  }
   console.log(JSON.stringify(await call(directory, command, { id: values.id })));
   return 0;
 }

package/src/daemon.js

@@ -116,7 +116,7 @@ export async function serve({ directory, workspace, home, command, profile }) {
     });
     if (shutdown) { server.close(); return await done; }
     server.on("error", (error) => { void stop(error); });
-    console.log(JSON.stringify({ ready: true, socket: socketPath, pid: process.pid }));
+    console.log(JSON.stringify({ ready: true, socket: socketPath, pid: process.pid, running: runtime.running }));
     return await done;
   } catch (error) {
     await stop(error);

package/src/federation-backend.js

@@ -1,7 +1,6 @@
-import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { FEDERATION_BACKEND_METHOD_CAPABILITIES, FEDERATION_MAX_FRAME_BYTES, fitThreadReplayWithinByteBudget, mergeCausalMessagingContext, pageThreadReplay, shortenDerivedThreadTitle } from "../dist/federation-core.js";
+import { buildThreadIdentityKey, NavigationQueryStore, FEDERATION_BACKEND_METHOD_CAPABILITIES, FEDERATION_MAX_FRAME_BYTES, fitThreadReplayWithinByteBudget, mergeCausalMessagingContext, pageThreadReplay, shortenDerivedThreadTitle } from "../dist/federation-core.js";
 import { ACTIVE, atomicJson, digest } from "./store.js";
 
 // The owner methods this outpost serves. Each one's capability comes from the
@@ -23,6 +22,11 @@ export function ownerMethodCapabilities(methods, contract = FEDERATION_BACKEND_M
 }
 export const METHOD_CAPABILITIES = ownerMethodCapabilities(OWNER_METHODS);
 
+// The placeholder title desktop gives a new thread. Viewers recognize this
+// exact text as "no name yet".
+export const PLACEHOLDER_THREAD_TITLE = "Untitled thread";
+const LEGACY_PLACEHOLDER_THREAD_TITLE = "New outpost thread";
+
 function mode(sandbox) { return sandbox === "workspace-write" ? "auto" : "default"; }
 function sandboxFor(params, fallback = "read-only") {
   if (params.executionMode && !["default", "auto", "full-access"].includes(params.executionMode)) throw new Error("Unsupported execution mode");
@@ -42,16 +46,24 @@ function textInput(input) {
 export class HeadlessBackend {
   constructor(runtime, publish) {
     this.runtime = runtime;
-    this.publish = publish;
-    this.epoch = randomUUID();
+    this.navigation = new NavigationQueryStore();
+    this.publish = (event, eventClass) => {
+      const thread = this.threads.get(event.notification.params.threadId);
+      // Acknowledging an older displayed update does not mark newer work read.
+      if (event.notification.method !== "navigation/thread/seen" || (thread && !this.summary(thread).inbox.inInbox)) {
+        this.navigation.observeAttentionEvent(event);
+      }
+      publish(event, eventClass);
+    };
     // Same headroom as desktop's FEDERATION_RESPONSE_BYTE_BUDGET.
     this.replayByteBudget = FEDERATION_MAX_FRAME_BYTES - 64 * 1024;
-    this.attentionViews = new Map();
     this.file = path.join(path.dirname(runtime.store.directory), "threads.json");
     try {
       const data = JSON.parse(readFileSync(this.file, "utf8"));
       if (data.version !== 1 || !Array.isArray(data.threads)) throw new Error("Invalid headless thread registry");
-      this.threads = new Map(data.threads.map((thread) => [thread.id, thread]));
+      this.threads = new Map(data.threads.map((thread) => [thread.id,
+        thread.titleSource === "fallback" && thread.title === LEGACY_PLACEHOLDER_THREAD_TITLE
+          ? { ...thread, title: PLACEHOLDER_THREAD_TITLE } : thread]));
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
       this.threads = new Map();
@@ -113,7 +125,16 @@ export class HeadlessBackend {
     }
     if (message.method === "headless/jobChanged") {
       this.syncJobs([message.params]);
-      if (message.params.threadId) this.forgetSeenAttentionMember(message.params.threadId);
+      const job = message.params;
+      if (job.threadId && this.latest(job.threadId) === job) {
+        const active = ACTIVE.has(job.status);
+        // An accepted job starts before Codex assigns its turn ID. Let the
+        // shared reducer adopt that ID without allocating another start rank.
+        this.navigation.observeAttentionEvent({ backend: "codex", notification: {
+          method: active ? "turn/started" : "turn/completed",
+          params: { threadId: job.threadId, turnId: job.turnId || (active ? undefined : job.id) },
+        } });
+      }
       this.publish({ backend: "codex", notification: { method: "navigation/invalidated", params: { threadId: message.params.threadId, sourceMethod: "turn/completed" } } }, "navigation");
       return;
     }
@@ -139,7 +160,11 @@ export class HeadlessBackend {
     switch (name) {
       case "listBackends": return this.listBackends();
       case "listThreads": return { backend: "codex", fetchedAt: Date.now(), threads: [...this.threads.values()].filter((thread) => !thread.archived).map((thread) => this.summary(thread)), workspaceRoots: this.runtime.projects.list().map((project) => project.path) };
-      case "getNavigationQueryPage": return this.query(params);
+      case "getNavigationQueryPage": {
+        if (params.inventory === "viewer") throw new Error("Expected owner navigation protocol 2");
+        return this.navigation.readPage({ request: params, scopeKey: envelope.sourceInstanceId || "local",
+          loadIndex: async () => this.navigationIndex() });
+      }
       case "getNavigationLaunchpadConfig": {
         if (params.protocol !== 2) throw new Error("Unsupported navigation protocol");
         if (params.directoryKey !== undefined) this.runtime.projects.resolve(params.directoryKey);
@@ -148,7 +173,7 @@ export class HeadlessBackend {
       }
       case "getNavigationSelectedDetail": return { protocol: 2, ref: params.ref, revision: digest(this.summary(this.owned(params.ref.threadId))), readiness: "ready", identity: "present", thread: this.summary(this.owned(params.ref.threadId)), collections: [] };
       case "getNavigationQueueProjection": return { protocol: 2, ref: params.ref, revision: "no-queue", readiness: "ready", complete: true, entries: [] };
-      case "releaseNavigationAttentionView": this.attentionViews.delete(params.viewId); return {};
+      case "releaseNavigationAttentionView": this.navigation.releaseAttentionView(envelope.sourceInstanceId || "local", params.viewId); return {};
       case "resolveThread": return this.threads.has(params.threadId) ? { thread: this.summary(this.owned(params.threadId)) } : {};
       case "resolveThreadAdmissionState": {
         const thread = this.summary(this.owned(params.threadId));
@@ -210,7 +235,6 @@ export class HeadlessBackend {
         const thread = this.owned(params.threadId);
         const title = params.title || params.name;
         if (typeof title !== "string" || !title.trim() || title.length > 200) throw new Error("Invalid title");
-        thread.updatedAt = Date.now();
         this.setTitle(thread, title.trim(), "explicit");
         return { backend: "codex", threadId: thread.id, title: thread.title };
       }
@@ -219,13 +243,17 @@ export class HeadlessBackend {
         for (const key of ["seenAt", "seenUpdatedAt"]) {
           if (params[key] !== undefined && (!Number.isFinite(params[key]) || params[key] < 0)) throw new Error(`Invalid ${key}`);
         }
-        const seenUpdatedAt = params.seenUpdatedAt ?? this.summary(thread).updatedAt;
+        // An omitted watermark keeps the stored one (see MarkThreadSeenRequest).
+        // A thread never given one is pinned to the seenAt it was judged by,
+        // so recording a new seenAt cannot change its unread state.
+        thread.seenUpdatedAt = params.seenUpdatedAt ?? thread.seenUpdatedAt ?? thread.seenAt ?? 0;
         thread.seenAt = params.seenAt ?? Date.now();
-        thread.seenUpdatedAt = seenUpdatedAt;
         this.persist();
-        this.forgetSeenAttentionMember(thread.id);
-        this.invalidate(thread.id);
-        return { backend: "codex", threadId: thread.id, seenAt: thread.seenAt, seenUpdatedAt };
+        this.publish({ backend: "codex", notification: { method: "navigation/thread/seen",
+          params: { threadId: thread.id, ...(params.seenUpdatedAt !== undefined ? { seenUpdatedAt: params.seenUpdatedAt } : {}) } } }, "transcript");
+        this.invalidate(thread.id, "navigation/thread/seen");
+        return { backend: "codex", threadId: thread.id, seenAt: thread.seenAt,
+          ...(params.seenUpdatedAt !== undefined ? { seenUpdatedAt: params.seenUpdatedAt } : {}) };
       }
       case "setThreadExecutionMode": {
         const thread = this.owned(params.threadId);
@@ -315,11 +343,11 @@ export class HeadlessBackend {
       const result = await this.runtime.codex.request("thread/start", { cwd, dynamicTools: this.runtime.messagingTools.buildDynamicToolSpecs(), approvalPolicy: "never", sandbox, ...(params.model ? { model: params.model } : {}), ephemeral: false });
       if (!result?.thread?.id || typeof result.thread.id !== "string" || result.thread.id.length > 256) throw new Error("Invalid thread/start response");
       this.runtime.loadedThreads.add(result.thread.id);
-      const thread = { id: result.thread.id, messagingFileTools: true, title: "New outpost thread", titleSource: "fallback", createdAt: Date.now(), cwd, sandbox,
+      const thread = { id: result.thread.id, messagingFileTools: true, title: PLACEHOLDER_THREAD_TITLE, titleSource: "fallback", createdAt: Date.now(), cwd, sandbox,
         model: params.model, reasoningEffort: params.reasoningEffort, serviceTier: params.serviceTier };
       this.threads.set(thread.id, thread);
       this.persist();
-      this.invalidate(thread.id);
+      this.invalidate(thread.id, "thread/started");
       return { backend: "codex", threadId: thread.id, executionMode: mode(sandbox) };
     } finally { this.creating = false; }
   }
@@ -388,120 +416,18 @@ export class HeadlessBackend {
         pagination: { supportsPagination: false, hasPreviousPage: false } } };
   }
 
-  forgetSeenAttentionMember(id) {
-    const thread = this.threads.get(id);
-    if (!thread) return;
-    const row = this.summary(thread);
-    if (row.threadStatus !== "active" && !row.inbox.inInbox) {
-      for (const view of this.attentionViews.values()) view.members.delete(id);
-    }
-  }
-
-  attentionOrder(rows, options = { id: "default", promoteOnTurnEnd: true }) {
-    if (typeof options.id !== "string" || !options.id || options.id.length > 256
-      || typeof options.promoteOnTurnEnd !== "boolean") throw new Error("Invalid Attention view");
-    let view = this.attentionViews.get(options.id);
-    if (!view) {
-      if (this.attentionViews.size >= 128) throw new Error("Attention view limit reached; release an unused view");
-      view = { members: new Map(), nextRank: 1 };
-      this.attentionViews.set(options.id, view);
-    }
-    const members = new Map();
-    // Bootstrap oldest turn first. Subsequent ranks follow turn identities and
-    // active/terminal transitions, never mutable thread or job activity stamps.
-    const eligible = rows.filter((row) => row.threadStatus === "active" || row.inbox.inInbox)
-      .sort((a, b) => (Date.parse(this.latest(a.id)?.createdAt) || a.createdAt)
-        - (Date.parse(this.latest(b.id)?.createdAt) || b.createdAt) || a.id.localeCompare(b.id));
-    for (const row of eligible) {
-      const previous = view.members.get(row.id);
-      const job = this.latest(row.id);
-      const turnKey = job?.id;
-      const active = row.threadStatus === "active";
-      const newTurn = turnKey !== previous?.turnKey;
-      const started = active && (!previous?.active || newTurn);
-      const finished = !active && (previous?.active || newTurn);
-      const rank = !previous || started || (finished && options.promoteOnTurnEnd) ? view.nextRank++ : previous.rank;
-      members.set(row.id, { rank, active, turnKey });
-    }
-    view.members = members;
-    return members;
-  }
-
-  query(request) {
-    if (request.protocol !== 2 || !request.query || request.inventory === "viewer") throw new Error("Expected owner navigation protocol 2");
-    let rows = [...this.threads.values()].filter((thread) => !thread.archived).map((thread) => this.summary(thread));
-    const counts = { total: rows.length, active: rows.filter((row) => row.threadStatus === "active").length,
-      unread: rows.filter((row) => row.inbox.inInbox).length, review: rows.filter((row) => row.inbox.inInbox && row.threadStatus !== "active").length, pinned: 0 };
-    const directories = this.runtime.projects.list().map((project) => {
-      const members = rows.filter((row) => row.projectKey === project.path);
-      return { key: project.path, kind: "directory", label: project.label, path: project.path,
-        counts: { total: members.length, active: members.filter((row) => row.threadStatus === "active").length,
-          unread: members.filter((row) => row.inbox.inInbox).length, review: members.filter((row) => row.inbox.inInbox && row.threadStatus !== "active").length, pinned: 0 },
-        pinnedRootCount: 0, unpinnedRootCount: members.length, launchpadPresent: true, launchpadBackend: "codex" };
-    });
-    const query = request.query;
-    const attention = query.kind === "lens" && query.lens === "attention" ? this.attentionOrder(rows, request.attentionView) : undefined;
-    if (!["exact", "children", "group-members", "directory", "lens", "search", "directory-index", "messaging-projects", "messaging-threads", "model-inventory", "star-map", "star-map-geometry"].includes(query.kind)) throw new Error("Unsupported navigation query");
-    if (request.backend && !["codex", "all"].includes(request.backend)) rows = [];
-    if (query.kind === "exact") rows = rows.filter((row) => query.identities?.some((ref) => ref.backend === "codex" && ref.threadId === row.id));
-    else if (["children", "group-members"].includes(query.kind) || query.roots === "pinned") rows = [];
-    else if (query.kind === "directory") rows = rows.filter((row) => row.projectKey === query.directoryKey);
-    else if (query.kind === "lens" && query.lens === "attention") rows = rows.filter((row) => row.threadStatus === "active" || row.inbox.inInbox);
-    if (query.agentOnly || (query.allowedBackends && !query.allowedBackends.includes("codex"))) rows = [];
-    if (query.projectKey) rows = rows.filter((row) => row.projectKey === query.projectKey);
-    if (query.directoryKey) rows = rows.filter((row) => row.projectKey === query.directoryKey);
-    if (query.kind === "star-map") {
-      for (const [key, selection] of Object.entries(query.filters || {})) {
-        if (selection === "neutral") continue;
-        rows = rows.filter((row) => {
-          const matches = key === "attention" && (row.threadStatus === "active" || row.inbox.inInbox);
-          return selection === "include" ? matches : !matches;
-        });
-      }
-    }
-    const filter = query.filter || query.text;
-    if (filter) rows = rows.filter((row) => row.title.toLowerCase().includes(filter.toLowerCase()));
-    const creationOrder = query.kind === "directory" || (query.kind === "lens" && query.lens === "recents");
-    rows.sort((a, b) => (attention ? attention.get(b.id).rank - attention.get(a.id).rank
-      : creationOrder ? b.createdAt - a.createdAt : b.updatedAt - a.updatedAt) || a.id.localeCompare(b.id));
-    const queryKey = digest({ backend: request.backend, query, ...(attention ? { attentionView: request.attentionView } : {}) });
-    const generation = digest(attention ? rows.map((row) => ({ ...row, attentionRank: attention.get(row.id).rank })) : rows);
-    const countsRevision = digest(counts);
-    let offset = 0;
-    if (request.cursor) {
-      const cursor = JSON.parse(Buffer.from(request.cursor, "base64url").toString());
-      if (cursor.queryKey !== queryKey || cursor.generation !== generation || cursor.countsRevision !== countsRevision || cursor.epoch !== this.epoch
-        || !Number.isInteger(cursor.offset) || cursor.offset < 0) throw new Error("Navigation cursor expired; refresh the collection");
-      offset = cursor.offset;
-    } else if (request.anchor?.kind === "thread") {
-      const index = rows.findIndex((row) => row.id === request.anchor.ref.threadId && request.anchor.ref.backend === "codex");
-      if (index >= 0) offset = index;
-    }
-    const limit = Math.min(100, Math.max(1, Number.isInteger(request.pageSize) ? request.pageSize : 50));
-    const page = rows.slice(offset, offset + limit);
-    const complete = offset + page.length >= rows.length;
-    const result = { protocol: 2, queryKey, generation, ownerEpoch: this.epoch, countsRevision, coverage: { state: "complete" }, counts,
-      collectionSize: rows.length, rangeStart: offset, complete,
-      entries: page.map((row, index) => ({ row: { ...row, ref: { backend: "codex", threadId: row.id }, rowRevision: digest(row),
-        ordinaryChildCount: 0, nativeSubAgentGroupPresent: false, queueCount: 0, queueState: "ready" }, orderKey: String(offset + index).padStart(8, "0"),
-        ...(attention ? { attentionRank: attention.get(row.id).rank } : {}), placement: { kind: "root" } })),
-      ...(!complete ? { nextCursor: Buffer.from(JSON.stringify({ queryKey, generation, countsRevision, epoch: this.epoch, offset: offset + page.length })).toString("base64url") } : {}) };
-    if (["directory-index", "messaging-projects", "star-map-geometry"].includes(query.kind)) {
-      result.directories = directories.filter((directory) => (!query.keys || query.keys.includes(directory.key)) && (!query.paths || query.paths.includes(directory.path))
-        && (!query.directoryKey || query.directoryKey === directory.key)
-        && (!query.allowedBackends || query.allowedBackends.includes("codex")) && !query.agentOnly
-        && (!filter || `${directory.label} ${directory.path}`.toLowerCase().includes(filter.toLowerCase())));
-      result.collectionSize = result.directories.length;
-      result.entries = []; result.complete = true; delete result.nextCursor;
-    }
-    if (query.kind === "model-inventory") {
-      const groups = new Map();
-      for (const row of rows) { const key = row.model || ""; groups.set(key, { backend: "codex", model: row.model, threadCount: (groups.get(key)?.threadCount || 0) + 1, fastThreadCount: 0 }); }
-      result.modelGroups = [...groups.values()]; result.collectionSize = groups.size;
-      result.entries = []; result.complete = true; delete result.nextCursor;
+  navigationIndex() {
+    const threads = [...this.threads.values()].filter((thread) => !thread.archived).map((thread) => this.summary(thread));
+    const byProject = new Map();
+    for (const thread of threads) {
+      let keys = byProject.get(thread.projectKey);
+      if (!keys) { keys = []; byProject.set(thread.projectKey, keys); }
+      keys.push(buildThreadIdentityKey(thread.source, thread.id));
     }
-    if (query.kind === "directory") result.selectionDirectory = directories.find((directory) => query.directoryKey === directory.key);
-    if (Buffer.byteLength(JSON.stringify(result)) > 256 * 1024) throw new Error("Navigation page exceeds its byte budget; request fewer rows");
-    return result;
+    return { threads, directories: this.runtime.projects.list().map((project) => ({
+      key: project.path, kind: "directory", label: project.label, path: project.path,
+      threadKeys: byProject.get(project.path) || [], needsAttentionCount: 0,
+      launchpad: { backend: "codex" },
+    })) };
   }
 }

package/src/federation-core.ts

@@ -23,3 +23,6 @@ export { resolveMessagingOutboundFile, validateMessagingFileMetadata } from "@pw
 
 export * from "@pwragent/federation/federation-replacement-receiver";
 export { FEDERATION_BACKEND_METHOD_CAPABILITIES } from "@pwragent/federation/federation-backend-methods";
+
+export { NavigationQueryStore } from "@pwragent/owner-core/navigation-query-store";
+export { buildThreadIdentityKey, NAVIGATION_QUERY_MAX_RESULT_BYTES } from "@pwragent/shared";

package/src/federation.js

@@ -142,12 +142,12 @@ export class HeadlessFederation {
   }
 
   async invite({ port = 47831, label }) {
-    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Federation port must be between 1 and 65535");
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("Federation port must be between 0 and 65535 (0 chooses an available port)");
     this.ensureIdentity(label);
     if (!this.router) this.setupRouter();
-    if (this.state.listenPort !== undefined && this.state.listenPort !== port) throw new Error("Restart with the existing listener port; it cannot change while serving");
+    if (port !== 0 && this.state.listenPort !== undefined && this.state.listenPort !== port) throw new Error("Restart with the existing listener port; it cannot change while serving");
     await this.listen(port);
-    this.state.listenPort = port;
+    this.state.listenPort = this.listenerAddress.port;
     const token = randomBytes(32).toString("base64url");
     const now = Date.now();
     const entry = { id: randomUUID(), status: "pending", generatedAt: now, expiresAt: now + 15 * 60_000,

package/src/runtime.js

@@ -3,12 +3,16 @@ import path from "node:path";
 import { readFileSync, readdirSync } from "node:fs";
 import { AgentToolRouter, buildPwrAgentMessagingToolDefinitions, readPwrAgentMessagingDynamicToolCall, resolveMessagingOutboundFile, validateMessagingFileMetadata, FILE_PUSH_MAX_BYTES } from "../dist/federation-core.js";
 import { Codex } from "./codex.js";
+import { installedVersion } from "./version.js";
 import { ACTIVE, atomicJson, digest, privateDirectory, validId } from "./store.js";
 
 export class Runtime {
   constructor({ store, workspace, home, command, onFailure }) {
     this.store = store;
     this.workspace = workspace;
+    // Snapshot at startup: upgrading the package files does not change the
+    // code this process is running.
+    this.running = installedVersion();
     this.projects = new OutpostProjects(path.dirname(store.directory), workspace);
     this.messagingTools = new AgentToolRouter(buildPwrAgentMessagingToolDefinitions((request) => this.messagingRequest(request), { nativeDynamicPdfImages: true }));
     this.fileAccess = { privateStorageRoots: [home, process.env.PWRAGENT_HOME].filter(Boolean),
@@ -41,7 +45,7 @@ export class Runtime {
   async handle(method, params = {}) {
     if (this.stopping) throw new Error("Daemon is stopping");
     switch (method) {
-      case "status": return { version: 1, ready: true, pid: process.pid, activeJob: this.active || null, workspace: this.workspace };
+      case "status": return { version: 1, ready: true, pid: process.pid, running: this.running, activeJob: this.active || null, workspace: this.workspace };
       case "project-list": return this.projects.list();
       case "project-create": case "project-clone": return this.projects.create(params);
       case "project-add": return this.projects.add(params);

package/src/version.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+
+// The release writes pwragentRelease: { tag, commit } into the published
+// manifest. A checkout has none, so only string fields are reported.
+export function versionInfo(pkg) {
+  const source = pkg.pwragentRelease;
+  const release = {};
+  if (typeof source?.tag === "string") release.tag = source.tag;
+  if (typeof source?.commit === "string") release.commit = source.commit;
+  return { name: pkg.name, version: pkg.version, ...(Object.keys(release).length ? { release } : {}) };
+}
+
+// Read on each call from this package's own manifest, so the CLI reports the
+// files currently installed. The daemon reads it once at startup instead.
+export function packageVersion() {
+  return versionInfo(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")));
+}
+
+// The version fields that status compares, without the package name.
+export function installedVersion() {
+  const { name: _name, ...fields } = packageVersion();
+  return fields;
+}
+
+export function formatVersion({ name, version, release }) {
+  const details = [release?.tag, release?.commit && `commit ${release.commit}`].filter(Boolean);
+  return details.length ? `${name} ${version} (${details.join(", ")})` : `${name} ${version}`;
+}
+
+// A daemon that predates version reporting returns no running version. It is
+// older than this installation, so it needs a restart too.
+export function restartRequired(running, installed) {
+  return !running
+    || running.version !== installed.version
+    || running.release?.commit !== installed.release?.commit;
+}