create-pmos 0.521.0 → 0.523.0

package/workspace/lib/board-publish-parts.js

@@ -0,0 +1,95 @@
+'use strict';
+/* board-publish-parts.js — a publish of several products and programs in one link (batch 27 item 1, ShA; initiative board-share-several).
+ *
+ * A PART is one pick of the Share sheet, in pick order: { kind: 'product', ws, board } · { kind: 'program', id } · { kind: 'initiative', id, ws, board }.
+ * A program can reach several products: it is picked by id, and its products come from its members (GET /api/programs).
+ *
+ *   groupsOf(parts, programs)  -> { groups: [{ ws, board, select: 'kind:id,…' }], tabs: [{ label?, ws, board, program?, kind, id }] } | { error }
+ *                                 one group per product the picks touch (its selection is the union of the picks there), one tab per pick. Pure.
+ *   packOf(parts, { programs, boards, name, make }) -> { ok, pack, kind, label } | { ok: false, status, error }
+ *                                 make(group) -> { ok, pack } is lib/routes-board-publish.js makePack: each product's pack is made and swept as today,
+ *                                 then lib/board-pack.js combinePacks joins them. A product that cannot be read stops the publish with its sentence.
+ *   parseParts(raw)            -> [part] | null   the parts of a request, checked; null when the request is not one of parts */
+const Pack = require('./board-pack.js');
+
+const MAX_PARTS = 12;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
+
+function parseParts(raw) {
+  if (!Array.isArray(raw) || !raw.length) return null;
+  const out = [];
+  for (const p of raw.slice(0, MAX_PARTS + 1)) {
+    if (!p || typeof p !== 'object') return null;
+    const kind = String(p.kind || '');
+    if (kind === 'program') { if (!ID.test(String(p.id || ''))) return null; out.push({ kind, id: String(p.id) }); continue; }
+    if (kind !== 'product' && kind !== 'initiative') return null;
+    const ws = String(p.ws || ''); const board = String(p.board || ws);
+    if (!ID.test(ws) || !ID.test(board)) return null;
+    if (kind === 'initiative' && !ID.test(String(p.id || ''))) return null;
+    out.push(kind === 'product' ? { kind, ws, board } : { kind, id: String(p.id), ws, board });
+  }
+  return out.length > MAX_PARTS ? null : out;
+}
+
+function groupsOf(parts, programs, boards) {
+  const G = new Map(); const tabs = [];
+  const boardOf = (ws) => ((boards || []).find((b) => b && b.ws === ws) || {}).id || ws;
+  const add = (ws, board, sel) => { const g = G.get(ws) || { ws, board, select: [] }; if (!g.select.includes(sel)) g.select.push(sel); G.set(ws, g); return g; };
+  for (const p of parts) {
+    if (p.kind === 'product') { add(p.ws, p.board, 'product:' + p.board); tabs.push({ kind: 'product', ws: p.ws, board: p.board }); continue; }
+    if (p.kind === 'initiative') { add(p.ws, p.board, 'initiative:' + p.id); tabs.push({ kind: 'initiative', id: p.id, ws: p.ws, board: p.board }); continue; }
+    const prog = (programs || []).find((x) => x && x.id === p.id);
+    if (!prog) return { error: 'The program "' + p.id + '" is not in this workspace.' };
+    const wss = [...new Set((prog.members || []).map((m) => m && m.ws).filter(Boolean))];
+    if (!wss.length) return { error: prog.title ? prog.title + ' has no initiatives to share yet.' : 'This program has no initiatives to share yet.' };
+    for (const ws of wss) add(ws, boardOf(ws), 'program:' + p.id);
+    const home = prog.home && wss.includes(prog.home) ? prog.home : wss[0];
+    tabs.push({ kind: 'program', id: p.id, ws: home, board: boardOf(home), program: p.id, label: prog.title || p.id });
+  }
+  return { groups: [...G.values()].map((g) => Object.assign({}, g, { select: g.select.join(',') })), tabs };
+}
+
+/** The label of a product or initiative tab, read from that product's own pack: the board's name, or the initiative's title. */
+function labelFrom(pack, tab) {
+  const key = Object.keys((pack && pack.responses) || {}).find((k) => k.startsWith('/api/board-premium?') && new URLSearchParams(k.split('?')[1]).get('ws') === tab.ws);
+  const model = key && pack.responses[key] && pack.responses[key].model;
+  if (tab.kind === 'initiative') { const r = ((model && model.rows) || []).find((x) => x && x.id === tab.id); return (r && r.title) || tab.id; }
+  return (model && model.board && (model.board.product || model.board.name)) || tab.ws;
+}
+
+async function packOf(parts, o) {
+  const g = groupsOf(parts, o.programs, o.boards);
+  if (g.error) return { ok: false, status: 400, error: g.error };
+  const packs = new Map();
+  for (const grp of g.groups) {
+    const r = await o.make(grp);
+    if (!r.ok) {
+      // a product a program only reaches, with nothing of the program on it now: left out, the program's other products still go
+      if (r.status === 400 && /not on this board/.test(r.error) && !parts.some((p) => p.ws === grp.ws)) continue;
+      return r;
+    }
+    packs.set(grp.ws, r.pack);
+  }
+  if (!packs.size) return { ok: false, status: 400, error: 'Nothing in these picks can be shared yet.' };
+  // one tab per pick; an initiative joins its product's tab when that product is picked too, and initiatives of one product share a tab
+  const tabs = []; const seen = new Map();
+  for (const t of g.tabs) {
+    if (!packs.has(t.ws)) continue;
+    const key = t.ws + '|' + (t.program || '');
+    const label = t.label || labelFrom(packs.get(t.ws), t);
+    if (seen.has(key)) { const was = seen.get(key); if (was.kind === 'initiative' && t.kind === 'product') { was.kind = 'product'; was.label = label; } continue; }
+    const tab = { kind: t.kind, label, ws: t.ws, board: t.board }; if (t.program) tab.program = t.program;
+    seen.set(key, tab); tabs.push(tab);
+  }
+  if (packs.size === 1 && tabs.length === 1 && !tabs[0].program) {   // one pick on one product: the pack as it is today, renamed when the PM did
+    const pack = [...packs.values()][0]; if (String(o.name || '').trim()) pack.scope = Object.assign({}, pack.scope, { label: String(o.name).trim().slice(0, 120) });
+    return { ok: true, pack, kind: (pack.scope && pack.scope.kind) || tabs[0].kind, label: pack.scope.label };
+  }
+  try {
+    const pack = Pack.combinePacks([...packs.values()], tabs, o.name);
+    const kind = tabs.length > 1 ? 'multi' : (tabs[0] && tabs[0].kind) || 'multi';
+    return { ok: true, pack, kind, label: pack.scope.label };
+  } catch (e) { return { ok: false, status: 400, error: String((e && e.message) || e) }; }
+}
+
+module.exports = { MAX_PARTS, parseParts, groupsOf, packOf };

package/workspace/lib/boards-host.js

@@ -51,8 +51,8 @@ function hostOrigin(env = process.env) {
 }
 
 function readState(dir) {
-  try { const s = JSON.parse(fs.readFileSync(fileOf(dir), 'utf8')); return { key: typeof s.key === 'string' ? s.key : null, host: typeof s.host === 'string' ? s.host : '', teams: Array.isArray(s.teams) ? s.teams : [], links: Array.isArray(s.links) ? s.links : [] }; }
-  catch { return { key: null, host: '', teams: [], links: [] }; }
+  try { const s = JSON.parse(fs.readFileSync(fileOf(dir), 'utf8')); return { key: typeof s.key === 'string' ? s.key : null, host: typeof s.host === 'string' ? s.host : '', teams: Array.isArray(s.teams) ? s.teams : [], links: Array.isArray(s.links) ? s.links : [], received: Array.isArray(s.received) ? s.received : [] }; }
+  catch { return { key: null, host: '', teams: [], links: [], received: [] }; }
 }
 /** The address the PM saved on the Publish popover ('' when none). The environment variable PMOS_BOARDS_HOST wins over it (see addressOf). */
 function savedHost(dir) {
@@ -124,7 +124,7 @@ async function publish(dir, o, opts = {}) {
   const now = new Date(opts.now || Date.now()).toISOString();
   const cur = readState(dir);
   cur.key = st.key;
-  cur.links = cur.links.filter((l) => l.id !== b.id).concat([{ id: b.id, url: b.url, team, name: String(o.name || ''), kind: o.kind, selection: o.selection || [], ws: o.ws || '', board: o.board || '', by: String(o.by || ''), made: now, ends: b.ends || null, views: 0 }]);
+  cur.links = cur.links.filter((l) => l.id !== b.id).concat([{ id: b.id, url: b.url, team, name: String(o.name || ''), kind: o.kind, selection: o.selection || [], parts: Array.isArray(o.parts) ? o.parts : undefined, ws: o.ws || '', board: o.board || '', by: String(o.by || ''), made: now, ends: b.ends || null, views: 0 }]);
   writeState(dir, cur);
   return { ok: true, id: b.id, url: b.url, ends: b.ends || null };
 }

package/workspace/lib/boards-received.js

@@ -0,0 +1,105 @@
+'use strict';
+/* boards-received.js — boards other people shared with you, kept in your PMOS (batch 27 item 3, ShX X2 and X3; initiative board-share-several).
+ *
+ * A RECEIVED board is { id, host, url, password, name, by, kind, ends, added }, kept in <runtime state>/board-publish/state.json under `received`
+ * (lib/boards-host.js writeState: mode 0600). The password is a secret on this computer: never returned to the page, never logged (D08), like a
+ * team password. Every function takes the state folder.
+ *
+ * THE CONTRACT with the host (board-host/src/core.js):
+ *   GET  <host>/api/links/<id>/about   X-Link-Password   -> { ok, id, name, kind, by, made, ends }
+ *   POST <host>/api/links/<id>/visit   X-Link-Password   -> { ok, url }   one-time, 5 minutes
+ *   403 is a wrong password, 429 a lockout (the sentence names the minutes), 404 a link that ended or was turned off.
+ *
+ *   parseLink(text)                          -> { host, id, url } | { error }    "<host>/b/<id>" (a copy of the address bar works too)
+ *   add(dir, { link, password }, { fetch })  -> { ok, board } | { ok: false, kind, error }   checked with the host before anything is kept
+ *   forget(dir, id)                          -> { ok }
+ *   readAll(dir, { fetch, now })             -> [{ id, host, url, name, by, kind, ends, state }]   state: open | ended | off | password | locked | unreachable
+ *   visit(dir, id, { fetch })                -> { ok, url } | { ok: false, error }
+ * Ended and turned-off links stay as one quiet row until the PM forgets them: the host deletes both, so the end date kept here tells them apart. */
+const Host = require('./boards-host.js');
+
+const TIMEOUT_MS = 15000;
+const MAX = 50;
+const LINK_ID = /^[A-Za-z0-9_-]{8,64}$/;
+
+function parseLink(text) {
+  const bad = { error: 'This is not a shared board link. It looks like https://boards.pm-os.app/b/…' };
+  let u; try { u = new URL(String(text || '').trim()); } catch { return bad; }
+  if (u.username || u.password) return bad;
+  const host = Host.hostOrigin({ PMOS_BOARDS_HOST: u.origin });
+  const m = /^\/b\/([A-Za-z0-9_-]+)\/?$/.exec(u.pathname);
+  if (!host || !m || !LINK_ID.test(m[1])) return bad;
+  return { host, id: m[1], url: host + '/b/' + m[1] };
+}
+
+async function call(host, method, p, password, fetchFn) {
+  const f = fetchFn || (typeof fetch === 'function' ? fetch : null);
+  if (!f) return { ok: false, kind: 'unreachable', error: 'This computer cannot reach the host (no network client).' };
+  const ctl = typeof AbortController === 'function' ? new AbortController() : null; const timer = ctl ? setTimeout(() => ctl.abort(), TIMEOUT_MS) : null;
+  try {
+    const headers = { Accept: 'application/json' }; if (password) headers['X-Link-Password'] = password;
+    const res = await f(host + p, { method, redirect: 'error', signal: ctl ? ctl.signal : undefined, headers });
+    let j = null; try { j = await res.json(); } catch { /* not JSON */ }
+    if (res.ok && j && j.ok !== false) return { ok: true, body: j };
+    const say = (j && typeof j.error === 'string' && j.error.slice(0, 240)) || '';
+    if (res.status === 403) return { ok: false, kind: 'password', error: 'That password does not work. Ask the person who shared it.' };
+    if (res.status === 429) return { ok: false, kind: 'locked', error: say || 'Too many wrong tries. Try again in a few minutes.' };
+    if (res.status === 404) return { ok: false, kind: 'gone', error: 'This link has ended or was turned off.' };
+    return { ok: false, kind: 'other', error: say || 'The host refused the request (' + res.status + ').' };
+  } catch (e) {
+    return { ok: false, kind: 'unreachable', error: e && e.name === 'AbortError' ? 'The host did not answer in time. Try again.' : 'The host could not be reached. Check the connection.' };
+  } finally { if (timer) clearTimeout(timer); }
+}
+const path = (id, what) => '/api/links/' + encodeURIComponent(id) + '/' + what;
+const listOf = (st) => (Array.isArray(st.received) ? st.received : []);
+const str = (v, n) => String(v == null ? '' : v).slice(0, n);
+const about = (b) => ({ name: str(b.name, 120), by: str(b.by, 60), kind: str(b.kind, 20), ends: str(b.ends, 40) });
+
+async function add(dir, o, opts = {}) {
+  const L = parseLink(o.link); if (L.error) return { ok: false, kind: 'link', error: L.error };
+  const password = o.password == null ? '' : String(o.password);
+  if (password.length > 100) return { ok: false, kind: 'password', error: 'A password is at most 100 characters.' };
+  const st = Host.readState(dir);
+  if (!listOf(st).some((r) => r.id === L.id) && listOf(st).length >= MAX) return { ok: false, kind: 'other', error: 'This computer keeps ' + MAX + ' shared boards. Forget one first.' };
+  const kept = listOf(st).find((r) => r.id === L.id && r.host === L.host);
+  const r = await call(L.host, 'GET', path(L.id, 'about'), password || (kept && kept.password) || '', opts.fetch);
+  if (!r.ok) return { ok: false, kind: r.kind, error: r.kind === 'password' && !password ? 'This board needs its password.' : r.error };
+  const cur = Host.readState(dir);
+  const row = Object.assign({ id: L.id, host: L.host, url: L.url, password: password || (kept && kept.password) || '', added: new Date(opts.now || Date.now()).toISOString() }, about(r.body));
+  cur.received = listOf(cur).filter((x) => x.id !== L.id).concat([row]);
+  Host.writeState(dir, cur);
+  return { ok: true, board: { id: row.id, name: row.name, by: row.by, ends: row.ends } };
+}
+
+function forget(dir, id) {
+  const st = Host.readState(dir); const had = listOf(st).some((r) => r.id === id);
+  st.received = listOf(st).filter((r) => r.id !== id); Host.writeState(dir, st); return { ok: had };
+}
+
+async function readAll(dir, opts = {}) {
+  const now = opts.now || Date.now();
+  const list = listOf(Host.readState(dir));
+  const rows = await Promise.all(list.map(async (x) => {
+    const base = { id: x.id, host: new URL(x.host).host, url: x.url, name: x.name, by: x.by, kind: x.kind, ends: x.ends };
+    const r = await call(x.host, 'GET', path(x.id, 'about'), x.password, opts.fetch);
+    if (r.ok) return Object.assign(base, about(r.body), { state: 'open' });
+    if (r.kind === 'gone') return Object.assign(base, { state: x.ends && Date.parse(x.ends) <= now ? 'ended' : 'off' });
+    return Object.assign(base, { state: r.kind === 'password' || r.kind === 'locked' ? r.kind : 'unreachable', error: r.error });
+  }));
+  // what the host said is kept (the name and end date can change on a republish), so an ended row still says when it ended
+  const cur = Host.readState(dir); let changed = false;
+  for (const row of rows) { const k = listOf(cur).find((x) => x.id === row.id); if (k && row.state === 'open' && (k.name !== row.name || k.ends !== row.ends || k.by !== row.by)) { Object.assign(k, { name: row.name, ends: row.ends, by: row.by }); changed = true; } }
+  if (changed) Host.writeState(dir, cur);
+  return rows;
+}
+
+async function visit(dir, id, opts = {}) {
+  const x = listOf(Host.readState(dir)).find((r) => r.id === id);
+  if (!x) return { ok: false, error: 'This board is not kept on this computer.' };
+  const r = await call(x.host, 'POST', path(x.id, 'visit'), x.password, opts.fetch);
+  if (!r.ok) return { ok: false, kind: r.kind, error: r.error };
+  const url = r.body.url; if (typeof url !== 'string' || !url.startsWith(x.host + '/b/' + x.id)) return { ok: false, error: 'The host sent an address this workspace does not accept.' };
+  return { ok: true, url };
+}
+
+module.exports = { MAX, parseLink, add, forget, readAll, visit };

package/workspace/lib/connector-read.js

@@ -0,0 +1,19 @@
+'use strict';
+/* connector-read.js — which connector tools are read-shaped. Shared by project setup (lib/project-onboard.js) and background runs
+ * (lib/headless.js connectorReads). Kept in its own file so a change to project setup does not reach every suite that uses headless runs. */
+const READ_VERBS = new Set(['search', 'get', 'list', 'read', 'fetch', 'find', 'query', 'lookup', 'view', 'describe', 'retrieve', 'browse', 'resolve']);
+const WRITE_VERBS = new Set(['create', 'update', 'delete', 'add', 'post', 'send', 'write', 'edit', 'move', 'transition', 'comment', 'assign', 'upload',
+  'remove', 'set', 'merge', 'close', 'archive', 'share', 'copy', 'trash', 'label', 'mark', 'apply', 'schedule', 'reply', 'forward', 'draft', 'respond',
+  'invite', 'publish', 'run', 'execute', 'trigger', 'link', 'unlink', 'approve', 'submit', 'save', 'log', 'record', 'register', 'insert', 'append',
+  'clear', 'fork', 'enable', 'disable', 'untrash', 'unmark', 'unlabel', 'cancel', 'install', 'import', 'export', 'generate', 'use', 'push', 'request', 'rename']);
+const words = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w.toLowerCase());
+
+/** A tool may be granted only when its own name (after the server prefix) leads with a read verb and holds no write verb. */
+function readTool(toolName, prefix) {
+  const own = prefix && toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName.replace(/^mcp__[^_]+(?:_[^_]+)*?__/, '');
+  const w = words(own);
+  if (!w.length || w.some((x) => WRITE_VERBS.has(x))) return false;
+  return w.slice(0, 3).some((x) => READ_VERBS.has(x));
+}
+
+module.exports = { readTool, READ_VERBS, WRITE_VERBS };

package/workspace/lib/headless.js

@@ -215,7 +215,7 @@ const TOOLS = Object.freeze({
 // without a prompt. The kinds below read the PM's sources through connectors (Jira, Confluence, Slack, the calendar, mail, Drive), and before
 // dontAsk they relied on the PM's default mode letting a read-only connector tool run. Now the server names those tools: the read-shaped tools
 // of the PM's connected servers (CONNECTOR_READ_SEED, plus what each run's init line reports, server.js), filtered by the same read-verb rule the
-// onboarding search uses (lib/project-onboard.js readTool). A connector WRITE is never named, so it is still denied. The other kinds read no
+// onboarding search uses (lib/connector-read.js readTool). A connector WRITE is never named, so it is still denied. The other kinds read no
 // connector and get none.
 const CONNECTOR_READ_KINDS = Object.freeze(['skill', 'report-setup', 'report-find', 'ms-review', 'propose', 'metric-draft', 'impact', 'metric-read',
   'report-sample-fetch', 'report-structure', 'report-structure-dry', 'report-structure-pull']);
@@ -235,7 +235,7 @@ const CONNECTOR_READ_SEED = Object.freeze([
 const MCP_TOOL_RE = /^mcp__[\w-]+__[\w.-]+$/;   // one exact tool: Claude Code's rule syntax, no server-wide or wildcard rule
 /** The read-shaped connector tools among `names` (a run's init line, or a cached list): exact names only, never a write verb. */
 function connectorReads(names) {
-  const { readTool } = require('./project-onboard.js');
+  const { readTool } = require('./connector-read.js');
   const out = [];
   for (const n of Array.isArray(names) ? names : []) {
     const t = String(n || '');

package/workspace/lib/kit-update.js

@@ -15,8 +15,8 @@
  *
  * 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)
+ *   kit          npx -y --prefer-online create-pmos@<version> --update <repo> (the kernel only; state/ and planning/ untouched)
+ *   app          npx -y --prefer-online create-pmos@<version> workspace --reinstall <repo> (what `pmos upgrade` runs)
  * LOCAL SOURCE. PMOS_UPDATE_SOURCE names a built create-pmos package on this computer: its folder (with package.json, bin/
  * and payload/ or workspace/) or its .tgz from `npm pack`. The check then reads that package's version instead of asking
  * the registry, and the update runs `npx -y --package=<that path> -- create-pmos ...` in place of `npx -y create-pmos@<version> ...`. Nothing
@@ -116,11 +116,12 @@ function source(env = process.env) {
 
 /**
  * The npx arguments that run create-pmos: the registry package at a version, or the local path. A bare path is not
- * enough: npx would try to run it as a command, so a local package goes in with --package.
+ * enough: npx would try to run it as a command, so a local package goes in with --package. --prefer-online makes npm ask
+ * the registry about the pinned version even when it has an older answer cached, which a cache clean used to force.
  */
 const npxArgs = (src, version, rest) => (src && src.kind === 'local'
   ? ['-y', `--package=${src.path}`, '--', PKG_NAME, ...rest]
-  : ['-y', `${PKG_NAME}@${version}`, ...rest]);
+  : ['-y', '--prefer-online', `${PKG_NAME}@${version}`, ...rest]);
 
 /** One changelog entry as the page may show it, or null: a version, a time, and PRs with a number, a summary, from
  *  kit-changelog format 2 a title, and from format 3 a kind (k: new, imp, fix or x), which decides New, Improved or Fixed.
@@ -266,10 +267,6 @@ function whereFrom({ desktop = false, onlineHost = false, tokenKept = false } =
   return { ok: false, error: 'This page signed in with a token that changes when the workspace restarts, so it could not come back. Update the workspace on the computer it runs on, or at its Online address' };
 }
 
-/**
- * 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`.
- */
 /**
  * The environment of the app update. A server started by a login item or a desktop shortcut can have a PATH without
  * the node that runs it, and then neither npx nor the pmos launcher is found. The folder of this node is added at the
@@ -282,26 +279,59 @@ function updateEnv(env = process.env, nodePath = process.execPath) {
   return parts.includes(dir) ? { ...env } : { ...env, [key]: [...parts, dir].join(path.delimiter) };
 }
 
-function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(), source: src = source() } = {}) {
+/**
+ * On Windows the update runs through this hop, so no step of it opens a console window (batch 27 item 7).
+ * A DETACHED child has no console at all, and then every console program it starts (cmd, npm, node, node-gyp) gets a
+ * new, VISIBLE console of its own: npm starts create-pmos without windowsHide, so the server cannot hide those. The hop
+ * is a detached node with no console. It starts the update once with windowsHide, which gives that child a console with
+ * no window, and every program under it shares that hidden console. The hop waits for the update and passes on its exit
+ * code. argv: ['direct', cmd, ...args] runs cmd itself; ['shell', cmd, ...args] runs it through cmd.exe (npx.cmd needs
+ * a shell), each argument quoted, so a repository path with a space stays one argument.
+ */
+function windowsHop(argv, spawnSync) {
+  const [mode, cmd, ...args] = argv;
+  const q = (s) => (/[\s"&|<>^()]/.test(s) ? '"' + String(s).replace(/"/g, '""') + '"' : String(s));
+  const r = mode === 'shell'
+    ? spawnSync([cmd, ...args].map(q).join(' '), { stdio: 'inherit', windowsHide: true, shell: true })
+    : spawnSync(cmd, args, { stdio: 'inherit', windowsHide: true });
+  if (r.error) console.error('The update could not start: ' + r.error.message);
+  return r.status == null ? 1 : r.status;
+}
+const HOP = `process.exit((${windowsHop.toString()})(process.argv.slice(1), require('child_process').spawnSync))`;
+
+/**
+ * The command that starts the app update: { cmd, args }. On macOS and Linux it is npx. On Windows it is this node
+ * running the hop above, and the hop runs npm's own npx-cli.js with this node when it is beside it (the usual Node
+ * install and nvm-windows), else npx.cmd through a shell.
+ */
+function appUpdateCommand(npx, { platform = process.platform, execPath = process.execPath, exists = fs.existsSync } = {}) {
+  if (platform !== 'win32') return { cmd: 'npx', args: npx };
+  const cli = path.win32.join(path.win32.dirname(String(execPath)), 'node_modules', 'npm', 'bin', 'npx-cli.js');
+  const run = exists(cli) ? ['direct', String(execPath), cli] : ['shell', 'npx.cmd'];
+  return { cmd: String(execPath), args: ['-e', HOP, ...run, ...npx] };
+}
+
+/**
+ * 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`.
+ * No npm cache clean: the version is pinned and npx runs with --prefer-online, so npm asks the registry for that
+ * version's details again and downloads the version if it is not in the cache. A clean took the whole cache, so every
+ * update downloaded every dependency again and built node-pty again (batch 27 item 7).
+ */
+function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(), source: src = source(),
+  platform = process.platform, execPath = process.execPath, exists = fs.existsSync } = {}) {
   if (!validVersion(version)) return { ok: false, error: 'Check for updates first' };
   if (src.kind === 'local' && src.error) return { ok: false, error: src.error };
+  const npx = npxArgs(src, version, ['workspace', '--reinstall', '--no-open', String(root)]);
+  const c = appUpdateCommand(npx, { platform, execPath, exists });
   let fd;
   try {
     fs.mkdirSync(path.dirname(logFile), { recursive: true });
     fd = fs.openSync(logFile, 'w');
-    fs.writeSync(fd, `${new Date().toISOString()} clearing npm cache…\n`);
-    fs.writeSync(fd, `${new Date().toISOString()} ${NPM} cache clean --force\n`);
-    fs.writeSync(fd, `${new Date().toISOString()} ${NPX} ${npxArgs(src, version, ['workspace', '--reinstall', '--no-open', String(root)]).join(' ')}\n`);
+    fs.writeSync(fd, `${new Date().toISOString()} ${platform === 'win32' ? 'npx.cmd' : 'npx'} ${npx.join(' ')}\n`);
   } catch (e) { return { ok: false, error: `Could not write the log file: ${e.message}` }; }
   try {
-    // Clear npm cache synchronously before spawning the update, so npx downloads the fresh version
-    cp.execSync(`${NPM} cache clean --force`, { cwd: String(root), env, stdio: ['ignore', fd, fd] });
-  } catch (e) {
-    try { fs.appendFileSync(logFile, `Note: cache clear had an issue, but continuing: ${e.message}\n`); } catch { /* silent */ }
-  }
-  try {
-    const child = spawn(NPX, npxArgs(src, version, ['workspace', '--reinstall', '--no-open', String(root)]),
-      { cwd: String(root), env, detached: true, stdio: ['ignore', fd, fd], windowsHide: true, shell: IS_WIN });
+    const child = spawn(c.cmd, c.args, { cwd: String(root), env, detached: true, stdio: ['ignore', fd, fd], windowsHide: true });
     // A child that could not start writes nothing itself: say why in the log, which the page names when it gives up.
     if (child && typeof child.on === 'function') {
       child.on('error', (e) => { try { fs.appendFileSync(logFile, `The update could not start: ${e.message}\n`); } catch { /* the page times out */ } });
@@ -315,4 +345,4 @@ function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(
   }
 }
 
-module.exports = { PKG_NAME, cmpVer, readChanges, readLastCheck, writeLastCheck, notServedYet, validVersion, source, npxArgs, readKit, fromCheckout, status, compare, latest, updateKit, updateEnv, upgradeApp, whereFrom };
+module.exports = { PKG_NAME, windowsHop, appUpdateCommand, cmpVer, readChanges, readLastCheck, writeLastCheck, notServedYet, validVersion, source, npxArgs, readKit, fromCheckout, status, compare, latest, updateKit, updateEnv, upgradeApp, whereFrom };

package/workspace/lib/project-onboard.js

@@ -24,11 +24,7 @@ const os = require('os');
 const crypto = require('crypto');
 const cp = require('child_process');
 
-const READ_VERBS = new Set(['search', 'get', 'list', 'read', 'fetch', 'find', 'query', 'lookup', 'view', 'describe', 'retrieve', 'browse', 'resolve']);
-const WRITE_VERBS = new Set(['create', 'update', 'delete', 'add', 'post', 'send', 'write', 'edit', 'move', 'transition', 'comment', 'assign', 'upload',
-  'remove', 'set', 'merge', 'close', 'archive', 'share', 'copy', 'trash', 'label', 'mark', 'apply', 'schedule', 'reply', 'forward', 'draft', 'respond',
-  'invite', 'publish', 'run', 'execute', 'trigger', 'link', 'unlink', 'approve', 'submit', 'save', 'log', 'record', 'register', 'insert', 'append',
-  'clear', 'fork', 'enable', 'disable', 'untrash', 'unmark', 'unlabel', 'cancel', 'install', 'import', 'export', 'generate', 'use', 'push', 'request', 'rename']);
+const { readTool } = require('./connector-read.js');
 const HOOKS_OFF = JSON.stringify({ disableAllHooks: true });
 const MAX_FINDINGS = 40;
 const FIELDS = ['purpose', 'team', 'owner', 'timeline', 'goals'];
@@ -37,15 +33,6 @@ const clean = (v, n = 300) => String(v == null ? '' : v).replace(/[\u0000-\u001f
 const httpsOnly = (u) => { try { const x = new URL(String(u)); return x.protocol === 'https:' ? x.href.slice(0, 500) : null; } catch { return null; } };
 /** Claude Code's tool prefix for a server name: `mcp__<name with every other character as _>__`. */
 const prefixOf = (name) => 'mcp__' + String(name).replace(/[^A-Za-z0-9_-]/g, '_') + '__';
-const words = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w.toLowerCase());
-
-/** A tool may be granted only when its own name (after the server prefix) leads with a read verb and holds no write verb. */
-function readTool(toolName, prefix) {
-  const own = prefix && toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName.replace(/^mcp__[^_]+(?:_[^_]+)*?__/, '');
-  const w = words(own);
-  if (!w.length || w.some((x) => WRITE_VERBS.has(x))) return false;
-  return w.slice(0, 3).some((x) => READ_VERBS.has(x));
-}
 
 function parseMcpList(stdout) {
   const out = [];
@@ -282,7 +269,9 @@ function installKit(root, kit) {
   if (fs.existsSync(dest)) throw new Error('A pmos folder is already there. PMOS will not replace it.');
   if (kit.payload) { fs.cpSync(kit.payload, dest, { recursive: true }); }
   else if (kit.buildScript) { cp.execFileSync('bash', [kit.buildScript, root], { stdio: 'ignore', timeout: 300000 }); }
-  else throw new Error('This PMOS install has no kit to add.');
+  // No npm fallback here: only lib/kit-update.js reaches the registry (no-network.test.js). An app installed before the kit shipped with
+  // it gets the kit with its next update.
+  else throw new Error('This PMOS install has no kit to add. Update PMOS in Settings › Updates, then try again.');
   if (!fs.existsSync(path.join(dest, 'AGENTS.md'))) throw new Error('The kit did not install completely.');
   const profile = path.join(root, '.pmos-profile');
   if (!fs.existsSync(profile)) fs.writeFileSync(profile, 'pm-artifacts\n# PMOS repository profile (D68): pm-artifacts | product-code\n');
@@ -290,8 +279,10 @@ function installKit(root, kit) {
   const cur = fs.existsSync(ga) ? fs.readFileSync(ga, 'utf8') : '';
   if (!cur.split('\n').some((l) => l.trim() === '*.jsonl merge=union')) fs.writeFileSync(ga, `${cur}${cur && !cur.endsWith('\n') ? '\n' : ''}*.jsonl merge=union\n`);
 }
+/** Where the kit comes from: the installed app's own payload/ (create-pmos copies it there), the npx bundle's, a PMOS checkout's
+ *  build script. */
 function kitSource(here = __dirname, env = process.env) {
-  const candidates = [env.PMOS_KIT_PAYLOAD, path.join(here, '..', '..', 'payload'), path.join(here, '..', '..', 'npm-pkg', 'payload')].filter(Boolean);
+  const candidates = [env.PMOS_KIT_PAYLOAD, path.join(here, '..', 'payload'), path.join(here, '..', '..', 'payload'), path.join(here, '..', '..', 'npm-pkg', 'payload')].filter(Boolean);
   const payload = candidates.find((p) => fs.existsSync(path.join(p, 'AGENTS.md')));
   if (payload) return { payload };
   const buildScript = path.join(here, '..', '..', 'kit', 'build-kit.sh');

package/workspace/lib/refresh-run.js

@@ -236,7 +236,8 @@ function create(host) {
       }
       start(src, ws, { trigger: d.trigger, slot: d.slot, note: d.note });
     }
-    try { healTick(t, set); } catch (e) { warn('source repair', e); }
+    // PMOS_SOURCE_HEAL=off stops the repairs (a suite about pressed and scheduled runs sets it, so no repair run races them)
+    if (process.env.PMOS_SOURCE_HEAL !== 'off') { try { healTick(t, set); } catch (e) { warn('source repair', e); } }
     if (t - lastPrune > PRUNE_EVERY_MS) {
       lastPrune = t;
       try { const p = R.prune(dir, rules.keep, t); if (p.lines || p.copies) warn('refresh log', { message: `removed ${p.lines} lines and ${p.copies} copies older than ${rules.keep} days` }); } catch (e) { warn('refresh log prune', e); }

package/workspace/lib/routes-board-publish.js

@@ -2,7 +2,8 @@
 /* routes-board-publish.js — publish a board to the central host from the workspace (initiative board-publish, slice 2; D103; PRD P1 to P5).
  *
  *   GET  /api/board-publish                                  -> { ok, host, days, links }       a read: whether a host is set, the choices, the open links (never the key)
- *   POST /api/board-publish          { ws, board, select, team, password, days, shared_by }  -> { ok, id, url, ends }
+ *   POST /api/board-publish          { ws, board, select | parts, name?, team, password, days, shared_by }  -> { ok, id, url, ends, name }
+ *                                    parts (batch 27 item 1): several products and programs in one link, one tab per pick (lib/board-publish-parts.js)
  *   POST /api/board-publish/republish { id }                 -> { ok, ends }     the same selection, as the board is now; same link, same password
  *   POST /api/board-publish/off      { id }                  -> { ok }           the host deletes the copy at once
  *   POST /api/board-publish/password { id }                  -> { ok, password } a new link password from the host, shown once; the old one stops
@@ -11,6 +12,10 @@
  *   POST /api/board-publish/join     { invite } or { host, team, password } -> { ok, team }   verified with the host first; the password stays on this computer
  *   POST /api/board-publish/leave    { team }                -> { ok }          forgets the team here
  *   POST /api/board-publish/open     { team, id }            -> { ok, url }     a one-time address for a team member, opened in a browser tab
+ *   POST /api/board-publish/receive  { link, password? }     -> { ok, board }   a board shared with you, kept here (batch 27 item 3; lib/boards-received.js)
+ *   POST /api/board-publish/forget   { id }                  -> { ok }          forgets it here
+ *   POST /api/board-publish/visit    { id }                  -> { ok, url }     its one-time address, opened in a browser tab
+ *   GET  /api/board-publish/shared also answers withYou: [{ id, host, url, name, by, kind, ends, state }]   (no password, ever)
  *
  * EVERY POST IS A PAGE PRESS (pm-guard requirePagePress): only a press on the page publishes, not a request an agent session makes (PRD P2, D97 S3).
  * THE SECRET SCAN runs on the finished pack before anything leaves (P3): a hit blocks the publish and the answer names the rule, never the text (D08).
@@ -24,6 +29,8 @@ const Host = require('./boards-host.js');
 const shareStore = require('./share-store.js');
 const secretScan = require('./secret-scan.js');
 const Teams = require('./boards-teams.js');
+const Parts = require('./board-publish-parts.js');
+const Received = require('./boards-received.js');
 
 const PUBLIC = path.join(__dirname, '..', 'public');
 let versionMemo = null;
@@ -74,7 +81,7 @@ module.exports = {
   prefixes: ['/api/board-publish'],
   handle: async (req, res, url, ctx) => {
     const p = url.pathname;
-    if (!/^\/api\/board-publish(\/(republish|off|password|host|shared|join|leave|open))?$/.test(p)) return false;
+    if (!/^\/api\/board-publish(\/(republish|off|password|host|shared|join|leave|open|receive|forget|visit))?$/.test(p)) return false;
     const send = (obj, code) => { ctx.json(res, obj, code); return true; };
     const dir = stateDir(ctx);
     if (!dir) return send({ ok: false, error: 'No state folder.' }, 500);
@@ -88,8 +95,8 @@ module.exports = {
     }
     // the Shared view's read (slice 4): your own links and every joined team's list, read now from each host. Nothing is kept from the read.
     if (req.method === 'GET' && p === '/api/board-publish/shared') {
-      const teams = await Teams.readAll(dir);
-      return send({ ok: true, readAt: new Date().toISOString(), yours: Host.links(dir).map((l) => ({ id: l.id, url: l.url, team: l.team, name: l.name, kind: l.kind, by: l.by, made: l.made, ends: l.ends, views: l.views })), teams });
+      const [teams, withYou] = await Promise.all([Teams.readAll(dir), Received.readAll(dir)]);
+      return send({ ok: true, readAt: new Date().toISOString(), withYou, yours: Host.links(dir).map((l) => ({ id: l.id, url: l.url, team: l.team, name: l.name, kind: l.kind, by: l.by, made: l.made, ends: l.ends, views: l.views })), teams });
     }
     if (req.method !== 'POST') return send({ ok: false, error: 'GET or POST only' }, 405);
 
@@ -104,6 +111,16 @@ module.exports = {
       const r = await Teams.join(dir, { invite: body.invite, host: body.host, team: body.team, password: body.password });
       return send(r.ok ? { ok: true, team: r.team } : { ok: false, error: r.error, kind: r.kind }, r.ok ? 200 : (r.kind === 'locked' ? 429 : 400));
     }
+    // a board someone shared with you (batch 27 item 3, ShX): checked with its host first; the password stays on this computer (D08)
+    if (p === '/api/board-publish/receive') {
+      const r = await Received.add(dir, { link: body.link, password: body.password });
+      return send(r.ok ? { ok: true, board: r.board } : { ok: false, error: r.error, kind: r.kind }, r.ok ? 200 : (r.kind === 'locked' ? 429 : r.kind === 'unreachable' ? 502 : 400));
+    }
+    if (p === '/api/board-publish/forget') { const r = Received.forget(dir, String(body.id || '')); return send(r.ok ? { ok: true } : { ok: false, error: 'This board is not kept on this computer.' }, r.ok ? 200 : 404); }
+    if (p === '/api/board-publish/visit') {
+      const r = await Received.visit(dir, String(body.id || ''));
+      return send(r.ok ? { ok: true, url: r.url } : { ok: false, error: r.error, kind: r.kind }, r.ok ? 200 : 502);
+    }
     if (p === '/api/board-publish/leave') { const r = Teams.leave(dir, String(body.team || '')); return send(r.ok ? { ok: true } : { ok: false, error: 'This computer has not joined that team.' }, r.ok ? 200 : 404); }
     if (p === '/api/board-publish/open') {   // the one-time address of a team's board, to open in a browser tab
       const r = await Teams.open(dir, String(body.team || ''), String(body.id || ''));
@@ -124,28 +141,41 @@ module.exports = {
 
     // publish and republish both make a pack, scan it, then send it
     const now = Date.now();
-    let sel; let meta;
+    let sel; let meta; let parts = null;
     if (p === '/api/board-publish/republish') {
       const l = Host.readState(dir).links.find((x) => x.id === String(body.id || ''));
       if (!l) return send({ ok: false, error: 'This link is not one of yours.' }, 404);
       sel = { ws: l.ws, board: l.board, select: (l.selection || []).map((s) => s.kind + ':' + s.id).join(','), by: l.by, ends: l.ends };
-      meta = l;
+      meta = l; parts = Array.isArray(l.parts) && l.parts.length ? Parts.parseParts(l.parts) : null;
     } else {
       const days = Number(body.days);
       if (!Host.DAYS.includes(days)) return send({ ok: false, error: 'Ends in 1, 7 or 30 days.' }, 400);
       sel = { ws: body.ws, board: body.board || body.ws, select: Array.isArray(body.select) ? body.select.map((s) => s.kind + ':' + s.id).join(',') : String(body.select || ''), by: String(body.shared_by || '').slice(0, 60) || sharedBy(), ends: new Date(now + days * 86400000).toISOString() };
+      if (body.parts != null) { parts = Parts.parseParts(body.parts); if (!parts) return send({ ok: false, error: 'Pick up to ' + Parts.MAX_PARTS + ' products, programs or initiatives to publish.' }, 400); }
+    }
+    const base = { at: new Date(now).toISOString(), viewer: viewerVersion(), view: body.view || (meta && meta.view) };
+    let pack; let name; let kind;
+    if (parts) {
+      // several picks (batch 27 item 1, ShA): a pack per product, each made and swept as today, joined into one pack with a tab per pick
+      const c = await require('./board-publish-choices.js').contextOf(req, ctx, sel.ws, sel.board);
+      if (!c) return send({ ok: false, error: 'The board is still being read. Try again in a moment.' }, 202);
+      const r = await Parts.packOf(parts, { programs: c.programs, boards: c.boards, name: meta ? meta.name : String(body.name || '').slice(0, 120), make: (g) => makePack(req, ctx, Object.assign({ by: sel.by, ends: sel.ends }, base, { ws: g.ws, board: g.board, select: g.select })) });
+      if (!r.ok) return send({ ok: false, error: r.error }, r.status || 502);
+      pack = r.pack; name = r.label; kind = r.kind;
+    } else {
+      const pk = await makePack(req, ctx, Object.assign({}, sel, base));
+      if (!pk.ok) return send({ ok: false, error: pk.error }, pk.status || 502);
+      pack = pk.pack; name = pack.scope.label; kind = kindOf(pack);
     }
-    const pk = await makePack(req, ctx, Object.assign({}, sel, { at: new Date(now).toISOString(), viewer: viewerVersion(), view: body.view }));
-    if (!pk.ok) return send({ ok: false, error: pk.error }, pk.status || 502);
-    const hits = secretScan.scan(JSON.stringify(pk.pack));
+    const hits = secretScan.scan(JSON.stringify(pack));
     if (hits.length) return send({ ok: false, error: 'This board holds what looks like a secret (' + hits.join(', ') + '). Remove it, then publish again.', secrets: hits }, 422);
 
     if (p === '/api/board-publish/republish') {
-      const r = await Host.republish(dir, meta.id, pk.pack, { env });
+      const r = await Host.republish(dir, meta.id, pack, { env });
       return send(r.ok ? { ok: true, ends: r.ends } : { ok: false, error: r.error }, r.ok ? 200 : (r.status || 502));
     }
     const selection = Array.isArray(body.select) ? body.select.map((s) => ({ kind: String(s.kind), id: String(s.id) })) : String(body.select || '').split(',').filter(Boolean).map((s) => ({ kind: s.slice(0, s.indexOf(':')), id: s.slice(s.indexOf(':') + 1) }));
-    const r = await Host.publish(dir, { pack: pk.pack, team: body.team, name: pk.pack.scope.label, kind: kindOf(pk.pack), by: sel.by, days: Number(body.days), password: body.password == null ? '' : body.password, selection, ws: sel.ws, board: sel.board }, { env });
-    return send(r.ok ? { ok: true, id: r.id, url: r.url, ends: r.ends } : { ok: false, error: r.error }, r.ok ? 200 : (r.status || 502));
+    const r = await Host.publish(dir, { pack, team: body.team, name, kind, by: sel.by, days: Number(body.days), password: body.password == null ? '' : body.password, selection, parts, ws: sel.ws, board: sel.board }, { env });
+    return send(r.ok ? { ok: true, id: r.id, url: r.url, ends: r.ends, name } : { ok: false, error: r.error }, r.ok ? 200 : (r.status || 502));
   },
 };

package/workspace/lib/routes-onboard.js

@@ -62,6 +62,14 @@ function hasWork(root) {
   return INITIATIVE_DIRS.some((d) => ls(d).some((n) => n.endsWith('.md') && !/^README|template/i.test(n)))
     || RECORD_DIRS.some((d) => ls(d).some((n) => n.endsWith('.jsonl') && filled(d, n)));
 }
+/** The installer's home folder while it is still an empty kit (PMOS in it, no work yet), as folder facts; otherwise null. */
+function installerKit(ctx) {
+  if (!ctx.homeRoot || !(ctx.workspaceList ? ctx.workspaceList() : []).some((w) => w && w.root && path.resolve(w.root) === path.resolve(ctx.homeRoot))) return null;
+  const pm = P.pmosIn(ctx.homeRoot);
+  if (!pm || !pm.kit || hasWork(ctx.homeRoot)) return null;
+  const facts = P.folderFacts(ctx.homeRoot);
+  return facts.ok && facts.exists && !facts.inside_other_git ? facts : null;
+}
 function view(ctx) {
   const { st, bound } = fresh(ctx, read(ctx));
   const ws = st.done && st.done.ws && ctx.getWs(st.done.ws);
@@ -123,6 +131,15 @@ async function handle(req, res, url, ctx) {
         if (r.cancelled || !r.path) return send({ ok: false, cancelled: true });
         if (b.mode === 'new') parent = r.path; else root = r.path;
       }
+      // One folder per product: the one-line installer already made ~/PMOS a Git repository with an empty kit and opened it as the home
+      // product. The first proposal is that folder, so setup fills it (and renames it to the product) instead of nesting a second
+      // repository inside it and leaving an empty "PMOS" product behind (onboarding grill, 2026-11-04). Choosing "Make a new folder"
+      // afterwards still proposes a new one.
+      const reuse = b.mode === 'new' && !parent && !st.folder && installerKit(ctx);
+      if (reuse) {
+        write(ctx, { ...st, folder: { mode: 'existing', root: reuse.root, facts: reuse, chosen: false, reused: true } });
+        return send(view(ctx));
+      }
       if (b.mode === 'new') {
         const pr = P.proposeFolder(parent, st.project.name);
         if (!pr.ok) return send(pr, 400);

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.521.0",
+  "version": "0.523.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.521.0",
+      "version": "0.523.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^1.3.0",