create-pmos 0.58.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@e8fcb2a
+kernel-source: pmos@e9f1bd9
 assembled: 2026-10-06
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T13:15:52Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T13:15:52Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T13:15:52Z"}
 status: stable
 ---
 

package/workspace/guide/layout.md

@@ -25,7 +25,7 @@ Each place is drawn when its run is built. Until then the place says which run b
 
 ## Settings
 
-Settings holds settings only, in six sections:
+Settings holds settings only, in seven sections:
 
 - **Repositories**: every registered repository. Press a repository to make it the current one. Press its ⋯ for **Rename** or **Remove from PMOS**. Each asks in a sheet, and a remove asks you to confirm. **Add repository** shows the scan of a folder before you add it.
 - **Profiles**: the Claude profiles a session can start with. They open in the detail.
@@ -33,6 +33,9 @@ Settings holds settings only, in six sections:
 - **Validate consent**: the consent of the current repository. Turn it on or off here. **Open Validate** opens the Validate page as a tab.
 - **Online**: puts this workspace at your own address, such as `pmos.pm-os.app`, through a Cloudflare tunnel. Enter the public address, the tunnel name, your Cloudflare team domain, the Access audience (AUD) tag and your email, then press **Turn on**. The workspace runs the tunnel and remembers the switch when it restarts. On your phone, open the address and sign in with Cloudflare Access (Google or an email code). The workspace does not ask for its token there. Only the computer that runs the workspace can change this section. A phone sees whether it is on. [REMOTE.md](../REMOTE.md) has the one-time Cloudflare steps.
 - **Theme**: Dark or Light.
+- **Updates**: the version of the workspace app and the version of the kit in the current repository. Press **Check for updates** to compare them with the latest published version of PMOS. This is the only time the workspace asks the internet for a version, and it asks only when you press. When a newer version is available, a button shows for each part that is older:
+  - **Update the kit** does what `npx create-pmos@latest --update` does in a terminal. It changes only the kit's own files under `pmos/` (skills, scripts, templates and guides). Your records in `state/`, `planning/` and `okf/product/` do not change. The last lines of the output show under the button. The changed files are under `pmos/`, which Sync treats as records, so Sync (or automatic sync) sends them with your other records. To read them first, look at `git diff pmos/` before you sync.
+  - **Update the workspace** does what `pmos upgrade` does in a terminal. It asks you first. The workspace stops, installs the new version and starts again, and the page reloads when the new version starts. Sessions keep running in tmux. Press it on the computer that runs the workspace. From a phone it is refused, because the phone cannot see the restart through. When the workspace runs from a PMOS checkout, update it with `git pull` instead.
 
 Your work is never in Settings. It is in Today, Initiatives, Board and Reports.
 

package/workspace/lib/kit-update.js

@@ -0,0 +1,161 @@
+'use strict';
+/* kit-update.js — check for a newer create-pmos, and update the kit or the workspace app, from the page (workspace-kit-update).
+ *
+ *   readKit(root)                           → { present:false } | { present:true, version, kernelSource, installed, mode }
+ *   status({ root, appVersion, appDir })    → { app: { version, fromCheckout }, kit }       local only, no network
+ *   latest({ exec })                        → Promise<{ ok, version } | { ok:false, error }>   npm view create-pmos version
+ *   compare(st, latestVersion)              → { appBehind, kitBehind }
+ *   updateKit(root, { version, exec })      → Promise<{ ok, output, kit } | { ok:false, error, output }>
+ *   upgradeApp(root, { version, logFile, spawn }) → { ok, log } | { ok:false, error }
+ *
+ * The page does what the terminal does, and nothing more. Each action runs the command the README tells the PM to type:
+ *   check        npm view create-pmos version
+ *   kit          npx -y create-pmos@<version> --update <repo>            (the kernel only; state/ and planning/ untouched)
+ *   app          npx -y create-pmos@<version> workspace --reinstall <repo> (what `pmos upgrade` runs)
+ * The version is the one the check found, so what is installed is what the PM was shown, not whatever `latest` is a
+ * minute later. The app upgrade stops this server (create-pmos runs `pmos stop`), so it runs DETACHED, writes its output
+ * to a log file, and the page waits for the server to come back.
+ *
+ * NETWORK. These are the workspace's only egress to the npm registry. No HTTP client is opened here: npm and npx open
+ * their own. Every call is reached only from a POST the page sends when the PM presses a button (server.js
+ * /api/kit/check, /api/kit/update, /api/kit/upgrade-app); no timer and no GET reaches them. no-network.test.js holds
+ * that.
+ */
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+const PKG_NAME = 'create-pmos';
+const IS_WIN = process.platform === 'win32';
+const NPM = IS_WIN ? 'npm.cmd' : 'npm';
+const NPX = IS_WIN ? 'npx.cmd' : 'npx';
+const CHECK_TIMEOUT_MS = 30000;
+const UPDATE_TIMEOUT_MS = 5 * 60000;
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const OUTPUT_LINES = 20;
+
+/** -1 when a < b, 0 when equal, 1 when a > b. Dotted numeric; a missing or non-numeric part counts as 0. */
+function cmpVer(a, b) {
+  const pa = String(a || '0').split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0').split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+const validVersion = (v) => typeof v === 'string' && VERSION_RE.test(v);
+
+/**
+ * The repository's vendored kit, from pmos/KIT-VERSION. build-kit.sh writes `kernel-source:` and create-pmos appends an
+ * `installed-via: create-pmos@<v>` block on each vendor and update, so the LAST installed-via is the version in use.
+ */
+function readKit(root) {
+  let text;
+  try { text = fs.readFileSync(path.join(String(root || ''), 'pmos', 'KIT-VERSION'), 'utf8'); }
+  catch { return { present: false }; }
+  const last = (key) => {
+    let v = null;
+    for (const line of text.split(/\r?\n/)) {
+      const i = line.indexOf(':');
+      if (i > 0 && line.slice(0, i).trim() === key) v = line.slice(i + 1).trim();
+    }
+    return v;
+  };
+  const via = last('installed-via');
+  const m = via ? /create-pmos@(\S+)/.exec(via) : null;
+  return {
+    present: true,
+    version: m && validVersion(m[1]) ? m[1] : null,
+    kernelSource: last('kernel-source'),
+    installed: last('installed'),
+    mode: last('install-mode'),
+  };
+}
+
+/** True when the app runs from a PMOS checkout (workspace/ beside a .git): there `git pull` updates it, not npm. */
+function fromCheckout(appDir) {
+  try { return fs.existsSync(path.join(String(appDir), '..', '.git')); } catch { return false; }
+}
+
+function status({ root, appVersion, appDir }) {
+  return { app: { version: appVersion || null, fromCheckout: fromCheckout(appDir) }, kit: readKit(root) };
+}
+
+function compare(st, latestVersion) {
+  if (!validVersion(latestVersion)) return { appBehind: false, kitBehind: false };
+  const app = st && st.app && st.app.version;
+  const kit = st && st.kit && st.kit.present ? st.kit.version : null;
+  return {
+    appBehind: !!app && cmpVer(app, latestVersion) < 0,
+    // A kit with no installed-via line (vendored by hand from a checkout) has no version to compare: offer the update.
+    kitBehind: !!(st && st.kit && st.kit.present) && (!kit || cmpVer(kit, latestVersion) < 0),
+  };
+}
+
+const tail = (s) => String(s || '').trim().split(/\r?\n/).slice(-OUTPUT_LINES).join('\n');
+
+/** execFile as a promise that never rejects. */
+function run(exec, cmd, args, opts) {
+  return new Promise((resolve) => {
+    exec(cmd, args, { encoding: 'utf8', windowsHide: true, shell: IS_WIN, ...opts }, (err, stdout, stderr) => {
+      resolve({ err: err || null, stdout: String(stdout || ''), stderr: String(stderr || '') });
+    });
+  });
+}
+
+function why(r, what) {
+  if (!r.err) return null;
+  if (r.err.code === 'ENOENT') return `${what} could not run: the command was not found on this computer's PATH`;
+  if (r.err.killed) return `${what} took too long and was stopped`;
+  const said = tail(r.stderr).split('\n').filter(Boolean).pop();
+  return `${what} did not finish${said ? ': ' + said : ''}`;
+}
+
+async function latest({ exec = cp.execFile } = {}) {
+  const r = await run(exec, NPM, ['view', PKG_NAME, 'version', '--json'], { timeout: CHECK_TIMEOUT_MS });
+  const bad = why(r, 'The check');
+  if (bad) return { ok: false, error: bad };
+  let v = r.stdout.trim();
+  try { const j = JSON.parse(v); if (typeof j === 'string') v = j; } catch { /* plain text */ }
+  if (!validVersion(v)) return { ok: false, error: 'The check did not return a version number' };
+  return { ok: true, version: v };
+}
+
+async function updateKit(root, { version, exec = cp.execFile } = {}) {
+  if (!validVersion(version)) return { ok: false, error: 'Check for updates first' };
+  if (!readKit(root).present) return { ok: false, error: 'This repository has no PMOS kit folder (pmos/KIT-VERSION)' };
+  const r = await run(exec, NPX, ['-y', `${PKG_NAME}@${version}`, '--update', String(root)], { timeout: UPDATE_TIMEOUT_MS, cwd: String(root) });
+  const output = tail(r.stdout + (r.stderr ? '\n' + r.stderr : ''));
+  const bad = why(r, 'The kit update');
+  if (bad) return { ok: false, error: bad, output };
+  return { ok: true, output, kit: readKit(root) };
+}
+
+/**
+ * Start the app reinstall and return at once. The child is detached from this server, because create-pmos stops this
+ * server before it reinstalls, and it starts the new one after. Its output goes to `logFile`.
+ */
+function upgradeApp(root, { version, logFile, spawn = cp.spawn } = {}) {
+  if (!validVersion(version)) return { ok: false, error: 'Check for updates first' };
+  let fd;
+  try {
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    fd = fs.openSync(logFile, 'w');
+    fs.writeSync(fd, `${new Date().toISOString()} ${NPX} -y ${PKG_NAME}@${version} workspace --reinstall ${root}\n`);
+  } catch (e) { return { ok: false, error: `Could not write the log file: ${e.message}` }; }
+  try {
+    const child = spawn(NPX, ['-y', `${PKG_NAME}@${version}`, 'workspace', '--reinstall', String(root)],
+      { cwd: String(root), detached: true, stdio: ['ignore', fd, fd], windowsHide: true, shell: IS_WIN });
+    if (child && typeof child.on === 'function') child.on('error', () => { /* reported in the log by npx, or the page times out */ });
+    if (child && typeof child.unref === 'function') child.unref();
+    return { ok: true, log: logFile };
+  } catch (e) {
+    return { ok: false, error: `The workspace update could not start: ${e.message}` };
+  } finally {
+    try { fs.closeSync(fd); } catch { /* the child holds its own copy */ }
+  }
+}
+
+module.exports = { PKG_NAME, cmpVer, validVersion, readKit, fromCheckout, status, compare, latest, updateKit, upgradeApp };

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/components.css

@@ -2245,7 +2245,7 @@
   margin: 12px 16px 0;
   color: var(--muted-foreground);
 }
-/* Settings: one column of five sections. */
+/* Settings: one column of seven sections. */
 .fr-set {
   display: flex;
   flex-direction: column;
@@ -2299,6 +2299,22 @@
 .fr-set__add {
   padding: 12px 0;
 }
+.fr-set__error {
+  color: var(--destructive);
+}
+.fr-set__output {
+  margin: 0;
+  max-height: 200px;
+  overflow: auto;
+  padding: 8px;
+  border: 1px solid var(--border);
+  background: var(--muted);
+  color: var(--foreground);
+  font-family: var(--mono);
+  font-size: 11px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
 @media (max-width: 760px) {
   .fr-detail,
   .fr-dock {

package/workspace/public/pm/dest-settings.js

@@ -1,6 +1,6 @@
 /* pm/dest-settings.js — the Settings destination, the frame's ⚙ (pm-os-absorb Run 3, slice 3A; PRD R9).
  *
- * Settings holds settings only, in six sections and in this order:
+ * Settings holds settings only, in seven sections and in this order:
  *   Repositories       every registered repository as a row (open it to make it current; ⋯ for more), and Add repository,
  *                      which draws the existing add-repository flow (view-addrepo.js) in place
  *   Profiles           one row that opens the Claude profiles in the detail
@@ -8,6 +8,10 @@
  *   Validate consent   the current repository's consent switch (GET and POST /api/validate/repo)
  *   Online             the Online switch and its five settings (GET and POST /api/online; workspace-online-mode, D89)
  *   Theme              Dark or Light
+ *   Updates            the workspace app's version and the current repository's kit version; Check for updates asks the
+ *                      npm registry for the latest create-pmos (POST /api/kit/check, the PM's press only), and Update the
+ *                      kit / Update the workspace run what `npx create-pmos@latest --update` and `pmos upgrade` run
+ *                      (workspace-kit-update). The workspace update restarts the server, so the page waits and reloads.
  * The work itself (what needs you, initiatives, items, reports) is never here.
  *
  * The mount contract (registry.js): mountDestination(host, ctx) is called on every render with the same host. The page
@@ -23,10 +27,13 @@ import { repoTuples, activeProduct, renameRepo, removeRepo } from './panel-repos
 import { repoRow } from './fixture.js';
 import { sessionDefaults, setSessionDefaults } from './dock.js';
 import { COPY } from './frame-copy.js';
+import { askConfirm } from './dialogs.js';
 
 const P = COPY.page;
 const roots = new WeakMap();      // host -> { root, sig }
 const consentByWs = new Map();    // ws -> { on: boolean | null, error, at, pending }
+const kitByWs = new Map();        // ws -> { st: GET /api/kit/status body | null, at, pending }
+const upd = { phase: null, latest: null, compare: null, message: '', error: '', output: '' };   // the Updates section
 const online = { data: null, error: null, note: null, at: 0, pending: false };   // GET /api/online, and the last refusal
 let addOpen = false;
 let addMod = null;
@@ -76,7 +83,7 @@ const section = (id, title, kids, action) => el('section', { class: 'fr-set__sec
   el('div', { class: 'fr-set__head' }, el('h2', { class: 'fr-set__title' }, title), action || null),
   kids);
 
-/* ── the six sections ───────────────────────────────────────────────────────────────────────────────────────────── */
+/* ── the seven sections ────────────────────────────────────────────────────────────────────────────────────────── */
 
 function reposSection(scope) {
   const tuples = repoTuples();
@@ -227,6 +234,100 @@ function themeSection() {
   })]);
 }
 
+function readKitStatus(ws, force) {
+  if (!ws || FIXTURE) return;
+  const have = kitByWs.get(ws);
+  if (!force && have && (have.pending || Date.now() - have.at < 30000)) return;
+  const entry = { st: have ? have.st : null, at: Date.now(), pending: true };
+  kitByWs.set(ws, entry);
+  pmGet('/api/kit/status?ws=' + encodeURIComponent(ws)).then((j) => {
+    entry.pending = false; entry.at = Date.now();
+    if (j && j.ok !== false) entry.st = j;
+    setState({});
+  });
+}
+
+const say = (fields) => { Object.assign(upd, fields); setState({}); };
+
+async function checkUpdates(ws) {
+  say({ phase: 'check', message: '', error: '', output: '' });
+  const j = await pmPost('/api/kit/check', { ws });
+  if (j && j.ok !== false) {
+    kitByWs.set(ws, { st: j, at: Date.now() });
+    say({ phase: null, latest: j.latest, compare: { appBehind: !!j.appBehind, kitBehind: !!j.kitBehind } });
+  } else say({ phase: null, error: (j && j.error) || P.updateFailed });
+}
+
+async function updateKit(ws) {
+  say({ phase: 'kit', message: '', error: '', output: '' });
+  const j = await pmPost('/api/kit/update', { ws, version: upd.latest });
+  if (j && j.ok !== false) {
+    kitByWs.set(ws, { st: j, at: Date.now() });
+    say({ phase: null, compare: { ...(upd.compare || {}), kitBehind: false }, message: P.updateKitDone((j.kit && j.kit.version) || upd.latest), output: j.output || '' });
+  } else say({ phase: null, error: (j && j.error) || P.updateFailed, output: (j && j.output) || '' });
+}
+
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Wait for the server to come back after the app update: reload on a new version, or say what happened. */
+async function waitForRestart(from, log) {
+  let sawDown = false;
+  const until = Date.now() + 5 * 60000;
+  while (Date.now() < until) {
+    await pause(2000);
+    const j = await pmGet('/api/sessions');
+    if (!j || j.ok === false || !j.version) { sawDown = true; continue; }
+    if (j.version !== from) { location.reload(); return; }
+    if (sawDown) { say({ phase: null, error: P.updateAppSame(j.version, log) }); return; }
+  }
+  say({ phase: null, error: P.updateAppLost(log) });
+}
+
+async function updateApp(ws, from) {
+  const yes = await askConfirm({ title: P.updateAppTitle, body: P.updateAppBody(from || '?', upd.latest), confirmLabel: P.updateApp });
+  if (!yes) return;
+  say({ phase: 'app', message: P.updateAppBusy, error: '', output: '' });
+  const j = await pmPost('/api/kit/upgrade-app', { ws, version: upd.latest });
+  if (!j || j.ok === false) { say({ phase: null, message: '', error: (j && j.error) || P.updateFailed }); return; }
+  waitForRestart(j.from || from, j.log || '');
+}
+
+function updatesSection(scope) {
+  const repo = scope === 'all' ? null : activeProduct();
+  const ws = wsOfRepo(repo) || wsOfRepo(activeProduct());
+  readKitStatus(ws);
+  const st = (ws && kitByWs.get(ws) && kitByWs.get(ws).st) || null;
+  const app = st && st.app ? st.app : {};
+  const kit = st && st.kit ? st.kit : null;
+  const busy = !!upd.phase;
+  const cmp = upd.compare || {};
+  const kids = [];
+  const appLine = el('div', { class: 'fr-set__line' }, el('span', { 'data-fr': 'app-version' }, P.updatesApp(app.version)),
+    cmp.appBehind && !app.fromCheckout ? button({
+      label: P.updateApp, variant: 'primary', size: 'sm', disabled: busy, attrs: { 'data-fr': 'update-app' },
+      onClick: () => updateApp(ws, app.version),
+    }) : null);
+  kids.push(appLine);
+  if (cmp.appBehind && app.fromCheckout) kids.push(el('p', { class: 'fr-set__note', 'data-fr': 'app-checkout' }, P.updatesCheckout));
+  const kitText = scope === 'all' || !ws ? P.updatesNoRepo : !kit ? '' : kit.present ? P.updatesKit(kit.version) : P.updatesNoKit;
+  kids.push(el('div', { class: 'fr-set__line' }, el('span', { 'data-fr': 'kit-version' }, kitText),
+    cmp.kitBehind && kit && kit.present ? button({
+      label: P.updateKit, variant: 'primary', size: 'sm', disabled: busy, attrs: { 'data-fr': 'update-kit' },
+      onClick: () => updateKit(ws),
+    }) : null));
+  const line = upd.phase === 'check' ? P.updatesChecking : upd.phase === 'kit' ? P.updateKitBusy
+    : upd.message ? upd.message : upd.latest ? (cmp.appBehind || cmp.kitBehind ? P.updatesLatest(upd.latest) : P.updatesCurrent(upd.latest)) : P.updatesNever;
+  kids.push(el('p', { class: 'fr-set__note', role: 'status', 'aria-live': 'polite', 'data-fr': 'update-state' }, line));
+  if (upd.error) kids.push(el('p', { class: 'fr-set__note fr-set__error', role: 'alert', 'data-fr': 'update-error' }, upd.error));
+  if (upd.output) kids.push(el('pre', { class: 'fr-set__output', 'data-fr': 'update-output' }, upd.output));
+  kids.push(el('p', { class: 'fr-set__note' }, P.updatesNote));
+  const check = button({
+    label: P.updatesCheck, variant: 'outline', size: 'sm', icon: 'refresh-cw', disabled: busy || !ws,
+    attrs: { 'data-fr': 'check-updates' }, onClick: () => checkUpdates(ws),
+  });
+  return section('updates', P.updates, kids, check);
+}
+
 /* ── mount ────────────────────────────────────────────────────────────────────────────────────────────────────────── */
 
 function signature(scope) {
@@ -234,7 +335,9 @@ function signature(scope) {
   const addKeys = addOpen ? Object.keys(state).filter((k) => /^add[A-Z]/.test(k)).sort().map((k) => [k, state[k]]) : null;
   let add = '';
   try { add = JSON.stringify(addKeys); } catch { add = String(Date.now()); }
-  return JSON.stringify([repoTuples(), activeProduct(), scope, state.theme, sessionDefaults(), ws, consentByWs.get(ws) || null, addOpen, !!addMod, online.data, online.error, online.note]) + add;
+  const kit = ws ? kitByWs.get(ws) : null;
+  return JSON.stringify([repoTuples(), activeProduct(), scope, state.theme, sessionDefaults(), ws, consentByWs.get(ws) || null, addOpen, !!addMod, online.data, online.error, online.note,
+    kit ? kit.st : null, upd]) + add;
 }
 
 /** True while the PM is typing in the page or a menu of it is open: a rebuild then would take the focus away. */
@@ -262,6 +365,7 @@ export function mountDestination(host, ctx) {
     validateSection(scope),
     onlineSection(),
     themeSection(),
+    updatesSection(scope),
   ]);
 }
 

package/workspace/public/pm/frame-copy.js

@@ -170,6 +170,28 @@ export const COPY = {
     onlineEnv: (host) => `Online at https://${host}/, set by PMOS_PUBLIC_HOST when the workspace started. It signs in with the token. Restart the workspace without PMOS_PUBLIC_HOST to use this switch.`,
     onlineRemote: 'Only the computer that runs the workspace can change this.',
     onlineUnread: 'The Online settings did not load.',
+    updates: 'Updates',
+    updatesCheck: 'Check for updates',
+    updatesChecking: 'Checking for updates…',
+    updatesApp: (v) => 'Workspace app: ' + (v || 'version not known'),
+    updatesKit: (v) => 'Kit in this repository: ' + (v || 'version not recorded'),
+    updatesNoKit: 'This repository has no PMOS kit folder (pmos/), so it has no kit to update.',
+    updatesNoRepo: 'Choose a repository to see its kit.',
+    updatesNever: 'Press Check for updates to compare with the latest published version.',
+    updatesLatest: (v) => 'Latest published version: ' + v + '.',
+    updatesCurrent: (v) => 'Up to date. The latest published version is ' + v + '.',
+    updatesCheckout: 'This workspace runs from a PMOS checkout. Update it with git pull.',
+    updatesNote: 'Updating the kit changes only its own files (skills, scripts, templates and guides). Your records in state/, planning/ and okf/product/ do not change.',
+    updateKit: 'Update the kit',
+    updateKitBusy: 'Updating the kit…',
+    updateKitDone: (v) => 'The kit is now ' + v + '. The changed files are under pmos/, and Sync sends them with your other records.',
+    updateApp: 'Update the workspace',
+    updateAppTitle: 'Update the workspace?',
+    updateAppBody: (from, to) => 'The workspace stops, installs ' + to + ' in place of ' + from + ', and starts again. This takes about a minute. Sessions keep running in tmux.\n\nThis page reloads when the new version starts.',
+    updateAppBusy: 'Updating the workspace. This page reloads when the new version starts.',
+    updateAppSame: (v, log) => 'The workspace started again on ' + v + ', so the update did not finish. The update log is ' + log + '.',
+    updateAppLost: (log) => 'The workspace did not come back on this address. Type pmos in a terminal to open it. The update log is ' + log + '.',
+    updateFailed: 'The update did not finish.',
   },
 };
 

package/workspace/server.js

@@ -112,6 +112,7 @@ const modelLib = require('./lib/models');               // tier routing — one
 const memoryLib = require('./lib/memory');             // curated repository memory — one ledger code path, shared with the agents' CLI (D72)
 const audit = require('./lib/audit');                 // the workflow audit — the sweep the agents' CLI runs, read-only here (D77)
 const syncLib = require('./lib/sync');                 // press-only fetch / integrate / commit records / push (D70)
+const kitUpdate = require('./lib/kit-update.js');       // workspace-kit-update: press-only check and update of the kit and the app
 const gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
 const startPolicy = require('./lib/start-policy');     // ONE stated rule for where a session starts (repo-first R1/R3)
 const treeShare = require('./lib/tree-share');         // who shares a working tree, and who is DECLARED to be driving it
@@ -1868,6 +1869,7 @@ function readLedger(w, basename) {
 // D70 — the lifecycle ledger: the latest line for an initiative wins; `active` reopens. The same rule
 // as scripts/workflow-state.js#readLifecycle (a parity case in workspace/test.js keeps them in step).
 const syncing = new Set();   // repositories with a sync in flight — one at a time
+let kitBusy = null;          // workspace-kit-update: the one kit or app update in flight ('kit' | 'app'), or null
 // D70 as amended 2026-10-06: the same Sync, run without the press at startup and when work sits unpushed and quiet.
 // Every rule it must pass is in lib/auto-sync.js; a scratch server (its own PMOS_STATE_DIR) does not auto-sync.
 const autoSync = require('./lib/auto-sync').createAutoSync({
@@ -6922,6 +6924,50 @@ async function handleRequest(req, res) {
       return json(res, { ws: w.id, name: w.name, ...out });
     } finally { syncing.delete(w.root); }
   }
+  /* ── workspace-kit-update: Settings › Updates. GET reads versions from disk only. Each POST is the PM's press, and is
+   *    the only way the workspace reaches the npm registry (lib/kit-update.js; no-network.test.js holds that). ── */
+  if (p === '/api/kit/status' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    return json(res, { ok: true, ws: w.id, name: w.name, busy: kitBusy, ...kitUpdate.status({ root: w.root, appVersion: APP_VERSION, appDir: __dirname }) });
+  }
+  if ((p === '/api/kit/check' || p === '/api/kit/update' || p === '/api/kit/upgrade-app') && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const g = pmGuard.requirePagePress(req, body);
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
+    // A named workspace only: getWs falls back to the home repository, and an update must never land on a repository
+    // the page did not show.
+    const w = body.ws ? workspaces.get(String(body.ws)) : null;
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
+    const st = () => kitUpdate.status({ root: w.root, appVersion: APP_VERSION, appDir: __dirname });
+    if (p === '/api/kit/check') {
+      const r = await kitUpdate.latest();
+      const now = st();
+      if (!r.ok) return json(res, { ok: false, error: r.error, ws: w.id, ...now }, 502);
+      return json(res, { ok: true, ws: w.id, ...now, latest: r.version, ...kitUpdate.compare(now, r.version) });
+    }
+    if (kitBusy) return json(res, { ok: false, error: kitBusy === 'app' ? 'The workspace is already updating' : 'A kit update is already running' }, 409);
+    if (p === '/api/kit/update') {
+      kitBusy = 'kit';
+      try {
+        const r = await kitUpdate.updateKit(w.root, { version: body.version });
+        boardCache.invalidate(w.root);
+        return json(res, { ws: w.id, ...r, ...st() }, r.ok ? 200 : 502);
+      } finally { kitBusy = null; }
+    }
+    // The app update stops this server and starts a new one. It is refused from a phone: the new server starts on
+    // loopback only, so the phone that asked would lose the page. It is refused from a checkout, which git updates.
+    if (!remoteAccess.isLoopbackAddr(req.socket.remoteAddress) || remoteAccess.isProxied(req.headers, BIND.publicHost)) {
+      return json(res, { ok: false, error: 'Update the workspace from the computer it runs on' }, 403);
+    }
+    if (st().app.fromCheckout) return json(res, { ok: false, error: 'This workspace runs from a PMOS checkout. Update it with git pull' }, 409);
+    const r = kitUpdate.upgradeApp(w.root, { version: body.version, logFile: path.join(STATE, 'app-update.log') });
+    if (!r.ok) return json(res, { ok: false, error: r.error }, 400);
+    kitBusy = 'app';
+    return json(res, { ok: true, ws: w.id, from: APP_VERSION, to: body.version, log: r.log });
+  }
   /* ── next-step actions: prepare is read-only; go starts exactly what was shown; review records the PM's word ── */
   if (p === '/api/next-step/prepare' && req.method === 'POST') {
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }

package/workspace/test-lists/workspace-kit-update.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "workspace-kit-update: Settings › Updates — the check and the kit and app updates (lib/kit-update.js, the /api/kit routes).",
+  "modules": ["kit-update.test.js"],
+  "seconds": { "kit-update.test.js": 6 }
+}