create-pmos 0.52.0 → 0.53.1

package/workspace/lib/item-cli.js

@@ -0,0 +1,195 @@
+'use strict';
+/* item-cli.js — `pmos item …`: an initiative's breakdown items from a terminal (pm-os-absorb Run 1, PRD R24).
+ *
+ *   pmos item add <initiative> "<title>" --stage <id|label> [--due YYYY-MM-DD] [--start YYYY-MM-DD]
+ *                 [--owner you|agent|person:<name>|tracker:<ref>] [--after <id>[,<id>]] [--milestone] [--note "<text>"] [--json]
+ *   pmos item set <item> [--title ..] [--stage ..] [--due ..|none] [--start ..|none] [--owner ..] [--after ids|none]
+ *                 [--milestone|--no-milestone] [--note ..|none] [--blocked "<reason>"|none] [--json]
+ *   pmos item move <item> <todo|doing|review|done> [--evidence <commit|pr|file|session|note>:<ref>] [--json]
+ *   pmos item withdraw <item> [--json]
+ *   pmos item list <initiative> [--json]
+ *   common: [--root <dir>]
+ *
+ * The SAME writer and the SAME fold the workspace page uses (lib/plan-items.js) — no server is needed, and
+ * the terminal and the page cannot disagree about an item. Who wrote a line is decided by the call path,
+ * never by an argument: `pm:wawan` at an interactive terminal, the bound session from PMOS_SESSION, and
+ * `agent:unknown` otherwise. There is no `keep` verb: Keep is the PM's press on the workspace page.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { item: ['add', 'set', 'move', 'withdraw', 'list'] };
+const USAGE = [
+  'usage: pmos item add|set|move|withdraw|list — an initiative\'s breakdown items',
+  '  pmos item add <initiative> "<title>" --stage <stage> [--due YYYY-MM-DD] [--start YYYY-MM-DD]',
+  '                [--owner you|agent|person:<name>|tracker:<ref>] [--after <item>[,<item>]] [--milestone] [--note "<text>"]',
+  '  pmos item set <item> [--title "<title>"] [--stage <stage>] [--due <date>|none] [--start <date>|none] [--owner <owner>]',
+  '                [--after <items>|none] [--milestone|--no-milestone] [--note "<text>"|none] [--blocked "<reason>"|none]',
+  '  pmos item move <item> todo|doing|review|done [--evidence commit|pr|file|session|note:<ref>]',
+  '  pmos item withdraw <item>',
+  '  pmos item list <initiative>',
+  '  every command: [--json] [--root <dir>]',
+  'An item id is <initiative>.<10 characters>. A stage is an id or a label of the initiative\'s stages.',
+  'Who wrote each line comes from where the command runs: you at a terminal, the agent session otherwise.',
+  'Keep is pressed on the workspace page (Breakdown or Today). This command does not write it.',
+];
+const BOOL = new Set(['json', 'milestone', 'no-milestone', 'help']);
+const VALUE = new Set(['title', 'stage', 'due', 'start', 'owner', 'after', 'note', 'blocked', 'evidence', 'root']);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done', withdrawn: 'Withdrawn' };
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+const shortDate = (d) => { if (!d) return null; const t = new Date(d + 'T00:00:00Z'); return `${t.getUTCDate()} ${MONTHS[t.getUTCMonth()]}`; };
+const csv = (v) => String(v).split(',').map((s) => s.trim()).filter(Boolean);
+
+/** One line about an item, for a person. */
+function describe(it, stageLabel) {
+  const bits = [`${it.id} "${it.title}"`, stageLabel || it.stage, STATE_LABEL[it.state] || it.state];
+  if (it.milestone) bits.push('milestone');
+  if (it.due) bits.push(`due ${shortDate(it.due)}`);
+  if (it.blocked) bits.push(`blocked: ${it.blocked.reason}`);
+  if (it.proposed) bits.push('proposed');
+  return bits.join(' · ');
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now } = {}) {
+  const args = argv[0] === 'item' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags } = parse(args.slice(1));
+  const json = !!flags.json;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) {
+    for (const l of USAGE) say(l);
+    return verb ? 0 : 1;          // asked for help → 0; no command at all → 1, as `pmos kg` does
+  }
+  if (verb === 'keep') { say('Keep is written only from the workspace page (Breakdown or Today).'); return 2; }
+  if (!COMMANDS.item.includes(verb)) { say(`unknown item command "${verb}" — one of ${COMMANDS.item.join(', ')}`); return 2; }
+  if ('by' in flags || 'via' in flags) { say(`attribution is set from the call path; --${'by' in flags ? 'by' : 'via'} is not accepted`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const cliOpts = {};
+  if (isTTY !== undefined) cliOpts.isTTY = isTTY;
+  if (env !== undefined) cliOpts.env = env;
+  if (now !== undefined) cliOpts.now = now;
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const stageLabelOf = (initiative, id) => { try { const s = planTree.stagesFor(root, initiative).find((x) => x.id === id); return s ? s.label : id; } catch { return id; } };
+  const fresh = (id) => planItems.readFold(root, { now }).items[id] || null;
+
+  if (verb === 'list') {
+    const initiative = pos[0];
+    if (!initiative) { say('usage: pmos item list <initiative> [--json]'); return 2; }
+    if (!planItems.INIT_RE.test(initiative) || !planTree.recordPath(root, initiative)) return fail(`no initiative ${initiative} in this repository`);
+    const r = planItems.readFold(root, { now });
+    const stages = planTree.stagesFor(root, initiative);
+    const idx = (id) => { const i = stages.findIndex((s) => s.id === id); return i === -1 ? stages.length : i; };
+    const items = r.order.map((id) => r.items[id]).filter((it) => it.initiative === initiative)
+      .sort((a, b) => (idx(a.stage) - idx(b.stage)) || (a.order - b.order) || String(a.createdAt).localeCompare(String(b.createdAt)) || a.id.localeCompare(b.id));
+    const progress = planItems.progressOf(r, initiative);
+    if (json) {
+      const { profile } = planTree.profileAndLane(root, initiative);
+      say(JSON.stringify({ ok: true, initiative, profile, progress, items }));
+      return 0;
+    }
+    say(`${initiative} · ${progress.label}`);
+    for (const s of [...stages, { id: null, label: 'Other' }]) {
+      const mine = items.filter((it) => (s.id === null ? idx(it.stage) === stages.length : it.stage === s.id));
+      if (!mine.length) continue;
+      const real = mine.filter((it) => !it.proposed);
+      say(`  ${s.label}${real.length ? ` · ${real.filter((it) => it.state === 'done').length} of ${real.length}` : ''}`);
+      for (const it of mine) say(`    ${describe(it, s.id ? s.label : it.stage)} · ${it.owner}`);
+    }
+    return 0;
+  }
+
+  let events; let id = null; let before = null;
+  if (verb === 'add') {
+    const [initiative, title] = pos;
+    if (!initiative || title === undefined) { say('usage: pmos item add <initiative> "<title>" --stage <stage> [options]'); return 2; }
+    if (!planItems.INIT_RE.test(initiative) || !planTree.recordPath(root, initiative)) return fail(`no initiative ${initiative} in this repository`);
+    if (!flags.stage) {
+      const stages = planTree.stagesFor(root, initiative);
+      say(`--stage is required — the stages of ${initiative} are: ${stages.map((s) => `${s.id} (${s.label})`).join(', ')}`);
+      return 2;
+    }
+    const ev = { ev: 'planned', initiative, title, stage: flags.stage };
+    if (flags.due) ev.due = flags.due;
+    if (flags.start) ev.start = flags.start;
+    if (flags.owner) ev.owner = flags.owner;
+    if (flags.after) ev.after = csv(flags.after);
+    if (flags.milestone) ev.milestone = true;
+    if (flags.note) ev.note = flags.note;
+    for (const k of ['title', 'blocked', 'evidence', 'no-milestone']) if (k in flags) return fail(`--${k} is not an option of add`, 2);
+    events = [ev];
+  } else {
+    id = pos[0];
+    if (!id) { say(`usage: pmos item ${verb} <item> …`); return 2; }
+    before = (() => { try { return fresh(id); } catch { return null; } })();
+    if (verb === 'set') {
+      const fields = {};
+      if (flags.title) fields.title = flags.title;
+      if (flags.stage) fields.stage = flags.stage;
+      for (const k of ['due', 'start', 'note']) if (flags[k]) fields[k] = flags[k] === 'none' ? null : flags[k];
+      if (flags.owner) fields.owner = flags.owner;
+      if (flags.after) fields.after = flags.after === 'none' ? [] : csv(flags.after);
+      if (flags.milestone) fields.milestone = true;
+      if (flags['no-milestone']) fields.milestone = false;
+      if (flags.milestone && flags['no-milestone']) return fail('--milestone and --no-milestone contradict each other', 2);
+      if (flags.evidence) return fail('--evidence belongs to move', 2);
+      events = [];
+      if (Object.keys(fields).length) events.push({ ev: 'set', item: id, fields });
+      if (flags.blocked) events.push(flags.blocked === 'none' ? { ev: 'flagged', item: id, blocked: false } : { ev: 'flagged', item: id, blocked: true, reason: flags.blocked });
+      if (!events.length) { say('nothing to set — name at least one option (pmos item help)'); return 2; }
+    } else if (verb === 'move') {
+      const to = String(pos[1] || '').toLowerCase();
+      if (!planItems.STATES.includes(to)) { say(`usage: pmos item move <item> ${planItems.STATES.join('|')} [--evidence <kind>:<ref>]`); return 2; }
+      for (const k of Object.keys(flags)) if (!['json', 'root', 'evidence'].includes(k)) return fail(`--${k} is not an option of move`, 2);
+      const ev = { ev: 'moved', item: id, to };
+      if (flags.evidence) ev.evidence = flags.evidence;
+      events = [ev];
+    } else if (verb === 'withdraw') {
+      for (const k of Object.keys(flags)) if (!['json', 'root'].includes(k)) return fail(`--${k} is not an option of withdraw`, 2);
+      events = [{ ev: 'withdrawn', item: id }];
+    }
+  }
+
+  let r;
+  try { r = planItems.appendFromCli(root, events, cliOpts); }
+  catch (e) { return fail('could not record — ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!r.ok) return fail(r.error);
+  const itemId = id || (r.written[0] && r.written[0].item);
+  const after = (() => { try { return fresh(itemId); } catch { return null; } })();
+  const item = after || (before ? { ...before, state: 'withdrawn' } : null);
+  const actor = planItems.actorFromCli({ ...(isTTY !== undefined ? { isTTY } : {}), ...(env !== undefined ? { env } : {}) });
+  if (json) { say(JSON.stringify({ ok: true, item })); return 0; }
+  const by = planTree.byLabel(actor.by);
+  const label = item ? stageLabelOf(item.initiative, item.stage) : '';
+  if (verb === 'add') say(`added ${item.id} "${item.title}" · ${label}${item.due ? ` · due ${shortDate(item.due)}` : ''} · by ${by}`);
+  else if (verb === 'withdraw') say(`withdrew ${itemId}${before ? ` "${before.title}"` : ''} · by ${by}`);
+  else if (verb === 'move') {
+    say(`moved ${item.id} "${item.title}" to ${STATE_LABEL[item.state]}${item.evidence ? ` with evidence ${item.evidence.kind}:${item.evidence.ref}` : ''} · by ${by}`);
+    if (item.noEvidence) say('  no evidence — an agent Done with no evidence goes to the PM. Add --evidence <kind>:<ref>.');
+  } else say(`updated ${describe(item, label)} · by ${by}`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/item-spans.js

@@ -0,0 +1,137 @@
+'use strict';
+// item-spans.js — the dated bars of a breakdown: one span per item from its start and due, and the initiative's span
+// over them (pm-os-absorb, PRD R20, R8 predecessor flag).
+//
+//   spansOf(items, { stages })  → [{ id, stage, start, due, milestone, proposed, overlapsPredecessor, overlap }]
+//   initiativeSpan(spans, { proposed })  → { start, due } | null
+//   stageSpans(spans, { proposed })      → [{ stage, start, due }]   one per stage, in the order of the spans
+//   axisOf(spans, { today })    → { start, end, months: [{ month, start, end }] }   whole months, at least MIN_MONTHS
+//   dayNum(date) · addDays(date, n) · daysBetween(a, b)   calendar-day arithmetic on YYYY-MM-DD, never shifted by a zone
+//
+// `items` is the `items` of a plan-items fold or layout (lib/plan-items.js, lib/plan-tree.js): an object keyed by item
+// id, or a list. Dates are YYYY-MM-DD strings. One engine for Breakdown › Timeline and Initiatives › Timeline (Run 4)
+// and the report's Timeline strip (Run 5). Classic script (a UMD setting window.PMOSItemSpans), served from /lib/, so the
+// bars on the screen and the numbers in a report cannot disagree.
+//
+// The rules (Run 4, slice 4B):
+//   - A withdrawn item has no span. An item with neither date has no span. An item with one date spans that one day.
+//   - Spans come in stage order (`stages`: stage ids or { id } objects, as the layout lists them), then by the item's
+//     `order`, then by start. A stage the list does not name sorts last.
+//   - `milestone` is the item's own flag. A milestone's ◆ sits on its due date.
+//   - `proposed` is the item's own flag: an agent's proposal that the PM has not kept (lib/plan-items.js). It has a span,
+//     but initiativeSpan and stageSpans leave it out unless `{ proposed: true }` is passed, so a batch of proposals
+//     that nobody kept never stretches a stage or an initiative bar. axisOf includes it, so its bar has room.
+//   - `overlapsPredecessor` (R8, at risk): the item starts on or before the day a predecessor ends. A predecessor is an
+//     id in the item's `after` list that is among `items`, live and not Done; it ends on its due date (or its start when
+//     it has no due). An item that is Done is never flagged. `overlap` names the predecessor that ends last, as
+//     { id, due }, so the screen can give the reason; it is null when nothing overlaps.
+//   - A predecessor in another initiative counts only when the caller passes its item too. No date is ever moved here:
+//     the flag shows a clash, and the PM decides (no cascade, PRD R20).
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSItemSpans = api;
+}(typeof self !== 'undefined' ? self : this, function () {
+  const DATE = /^\d{4}-\d{2}-\d{2}$/;
+  const DAY = 86400000;
+  const MIN_MONTHS = 3;
+  const date = (v) => (typeof v === 'string' && DATE.test(v) ? v : null);
+
+  /** Days since 1970-01-01 for a YYYY-MM-DD date (NaN for anything else). */
+  function dayNum(d) {
+    if (!date(d)) return NaN;
+    return Math.round(Date.UTC(Number(d.slice(0, 4)), Number(d.slice(5, 7)) - 1, Number(d.slice(8, 10))) / DAY);
+  }
+  const fromNum = (n) => new Date(n * DAY).toISOString().slice(0, 10);
+  /** The date `n` calendar days after `d` (before it when `n` is negative); null for a bad date. */
+  function addDays(d, n) { const x = dayNum(d); return Number.isNaN(x) ? null : fromNum(x + Math.round(Number(n) || 0)); }
+  /** Whole days from `a` to `b` (b − a). */
+  function daysBetween(a, b) { return dayNum(b) - dayNum(a); }
+
+  const listOf = (items) => (Array.isArray(items) ? items : items && typeof items === 'object' ? Object.values(items) : []);
+
+  function stageRank(stages) {
+    const rank = new Map();
+    (Array.isArray(stages) ? stages : []).forEach((s, i) => {
+      const id = typeof s === 'string' ? s : s && typeof s.id === 'string' ? s.id : null;
+      if (id && !rank.has(id)) rank.set(id, i);
+    });
+    return (id) => (rank.has(id) ? rank.get(id) : rank.size);
+  }
+
+  function spansOf(items, opts) {
+    const rank = stageRank(opts && opts.stages);
+    const live = listOf(items).filter((it) => it && typeof it.id === 'string' && it.state !== 'withdrawn');
+    const byId = new Map(live.map((it) => [it.id, it]));
+    const out = [];
+    for (const it of live) {
+      const start = date(it.start);
+      const due = date(it.due);
+      if (!start && !due) continue;
+      const s = start || due;
+      let overlap = null;
+      if (it.state !== 'done') {
+        for (const pid of Array.isArray(it.after) ? it.after : []) {
+          const p = byId.get(pid);
+          if (!p || p.state === 'done') continue;
+          const end = date(p.due) || date(p.start);
+          if (end && s <= end && (!overlap || end > overlap.due)) overlap = { id: pid, due: end };
+        }
+      }
+      out.push({
+        id: it.id, stage: it.stage || null, start: s, due: due || start, milestone: !!it.milestone, proposed: !!it.proposed,
+        overlapsPredecessor: !!overlap, overlap,
+        _rank: rank(it.stage), _order: Number.isFinite(it.order) ? it.order : Infinity,
+      });
+    }
+    out.sort((a, b) => a._rank - b._rank || a._order - b._order || (a.start < b.start ? -1 : a.start > b.start ? 1 : 0) || (a.id < b.id ? -1 : 1));
+    for (const s of out) { delete s._rank; delete s._order; }
+    return out;
+  }
+
+  const counted = (spans, opts) => listOf(spans).filter((s) => s && date(s.start) && date(s.due) && (!s.proposed || !!(opts && opts.proposed)));
+
+  function initiativeSpan(spans, opts) {
+    const list = counted(spans, opts);
+    if (!list.length) return null;
+    let start = list[0].start;
+    let due = list[0].due;
+    for (const s of list) { if (s.start < start) start = s.start; if (s.due > due) due = s.due; }
+    return { start, due };
+  }
+
+  function stageSpans(spans, opts) {
+    const by = new Map();
+    for (const s of counted(spans, opts)) {
+      const k = s.stage || null;
+      const g = by.get(k);
+      if (!g) by.set(k, { stage: k, start: s.start, due: s.due });
+      else { if (s.start < g.start) g.start = s.start; if (s.due > g.due) g.due = s.due; }
+    }
+    return [...by.values()];
+  }
+
+  /** The time axis for `spans`: whole months from the earliest start to the latest due, with `today` inside it. */
+  function axisOf(spans, opts) {
+    const today = date(opts && opts.today);
+    const whole = initiativeSpan(spans, { proposed: true });
+    let lo = whole ? whole.start : today;
+    let hi = whole ? whole.due : today;
+    if (today) { if (today < lo) lo = today; if (today > hi) hi = today; }
+    if (!lo) return null;
+    const months = [];
+    let y = Number(lo.slice(0, 4));
+    let m = Number(lo.slice(5, 7));
+    const pad = (n) => String(n).padStart(2, '0');
+    for (;;) {
+      const first = `${y}-${pad(m)}-01`;
+      const next = m === 12 ? `${y + 1}-01-01` : `${y}-${pad(m + 1)}-01`;
+      months.push({ month: `${y}-${pad(m)}`, start: first, end: addDays(next, -1) });
+      if (next > hi && months.length >= MIN_MONTHS) break;
+      if (m === 12) { y++; m = 1; } else m++;
+    }
+    return { start: months[0].start, end: months[months.length - 1].end, months };
+  }
+
+  return { spansOf, initiativeSpan, stageSpans, axisOf, dayNum, addDays, daysBetween, MIN_MONTHS };
+}));

package/workspace/lib/launcher-cli.js

@@ -0,0 +1,207 @@
+'use strict';
+/* launcher-cli.js — `pmos launcher on|off|status`: start the workspace without a terminal (initiative workspace-launcher).
+ *
+ *   pmos launcher on [<path>] [--no-login]   write a PMOS app (and, unless --no-login, a login item) for one repository
+ *   pmos launcher off                        remove what `on` wrote, and nothing else
+ *   pmos launcher status                     say what is installed and whether it still points at a real node and repo
+ *
+ * The app and the login item are two more callers of `pmos up <repo>`; nothing here starts a server itself. The app
+ * opens the browser. The login item passes --no-open, so a login starts the server and opens nothing.
+ *
+ *   macOS  ~/Applications/PMOS.app                         Spotlight, Launchpad, drag it to the Dock
+ *          ~/Library/LaunchAgents/com.pmos.workspace.plist  runs at login (RunAtLoad), once
+ *   Linux  $XDG_DATA_HOME/applications/pmos.desktop        the app menu
+ *          $XDG_CONFIG_HOME/autostart/pmos-workspace.desktop
+ *
+ * A file started by the desktop has no shell profile, so the PATH of the terminal that ran `on` is written into the
+ * script; that is how `claude`, `git` and `tmux` resolve. It never starts remote (tailnet) mode and writes no token.
+ * `off` deletes a file only when it carries MARK, so a file of the same name that the PM wrote is left alone.
+ * Native Windows is refused: the workspace needs WSL there for a real PTY (doctor.js says the same).
+ *
+ * plan() is pure: every input is injected, so each platform's files are assertable from any machine.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const stateRoot = require('./state-root');
+
+const COMMANDS = { launcher: ['on', 'off', 'status'] };
+const MARK = 'pmos-launcher: written by `pmos launcher on`';
+const LABEL = 'com.pmos.workspace';
+const USAGE = [
+  'usage: pmos launcher on|off|status — start the workspace without a terminal',
+  '  pmos launcher on [<path>] [--no-login]   a PMOS app for this repository, and a login item that starts the server',
+  '  pmos launcher off                        remove the app and the login item',
+  '  pmos launcher status                     what is installed, and for which repository',
+];
+
+// POSIX shell single quotes: nothing inside is special except the quote itself.
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+// XML text and attribute values in a plist.
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+// A .desktop Exec argument: double-quoted, with the four characters the spec reserves escaped.
+const deq = (s) => `"${String(s).replace(/[\\"`$]/g, (c) => '\\' + c)}"`;
+
+function script({ node, bin, repo, pathEnv, log }) {
+  return [
+    '#!/bin/sh',
+    `# ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it.`,
+    '# It runs `pmos up` on one repository with the PATH the terminal had at setup. Arguments pass through (--no-open).',
+    `PATH=${shq(pathEnv)}; export PATH`,
+    `exec ${shq(node)} ${shq(bin)} up ${shq(repo)} "$@" >>${shq(log)} 2>&1`,
+    '',
+  ].join('\n');
+}
+
+function plist(dict) {
+  const v = (x) => Array.isArray(x) ? `<array>${x.map((s) => `<string>${xml(s)}</string>`).join('')}</array>`
+    : typeof x === 'boolean' ? (x ? '<true/>' : '<false/>') : `<string>${xml(x)}</string>`;
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    `<!-- ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it. -->`,
+    '<plist version="1.0">',
+    '<dict>',
+    ...Object.entries(dict).map(([k, x]) => `  <key>${xml(k)}</key>${v(x)}`),
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function desktop(entries) {
+  return [`# ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it.`, '[Desktop Entry]',
+    ...Object.entries(entries).map(([k, x]) => `${k}=${x}`), ''].join('\n');
+}
+
+/**
+ * The files `on` writes, for one platform. Pure.
+ *   → { files: [{ role: 'app'|'login', path, content, mode }], app, login }   or   { refused: '<reason>' }
+ * `login: false` leaves the login item out.
+ */
+function plan({ platform, home, env = {}, node, bin, repo, login = true }) {
+  if (platform === 'win32') return { refused: 'native Windows needs WSL for a real PTY. Run `pmos launcher on` inside WSL.' };
+  if (platform !== 'darwin' && platform !== 'linux') return { refused: `no launcher is made for ${platform}. Start the workspace with \`pmos\`.` };
+  const log = path.join(stateRoot.defaultRoot({ env, platform, home }), 'launcher.log');
+  const body = script({ node, bin, repo, pathEnv: env.PATH || '/usr/bin:/bin', log });
+  const files = [];
+  if (platform === 'darwin') {
+    const appDir = path.join(home, 'Applications', 'PMOS.app');
+    const exe = path.join(appDir, 'Contents', 'MacOS', 'pmos-launch');
+    files.push({ role: 'app', path: exe, content: body, mode: 0o755 });
+    files.push({ role: 'app', path: path.join(appDir, 'Contents', 'Info.plist'), mode: 0o644, content: plist({
+      CFBundleName: 'PMOS', CFBundleDisplayName: 'PMOS', CFBundleIdentifier: 'com.pmos.launcher',
+      CFBundleExecutable: 'pmos-launch', CFBundlePackageType: 'APPL', CFBundleVersion: '1',
+      // No Dock icon: the script hands off to the browser and exits within seconds.
+      LSUIElement: true,
+    }) });
+    const agent = path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+    if (login) files.push({ role: 'login', path: agent, mode: 0o644, content: plist({
+      Label: LABEL, ProgramArguments: ['/bin/sh', exe, '--no-open'], RunAtLoad: true,
+      // `pmos up` detaches the server and exits; launchd must not reap the group it leaves behind.
+      AbandonProcessGroup: true,
+    }) });
+    return { files, app: appDir, login: login ? agent : null, removable: [appDir, agent] };
+  }
+  const data = env.XDG_DATA_HOME && path.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : path.join(home, '.local', 'share');
+  const conf = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  const exe = path.join(data, 'pmos', 'pmos-launch.sh');
+  const app = path.join(data, 'applications', 'pmos.desktop');
+  const auto = path.join(conf, 'autostart', 'pmos-workspace.desktop');
+  files.push({ role: 'app', path: exe, content: body, mode: 0o755 });
+  files.push({ role: 'app', path: app, mode: 0o644, content: desktop({
+    Type: 'Application', Name: 'PMOS', Comment: 'Open the PMOS workspace', Exec: `/bin/sh ${deq(exe)}`,
+    Terminal: 'false', Categories: 'Development;' }) });
+  if (login) files.push({ role: 'login', path: auto, mode: 0o644, content: desktop({
+    Type: 'Application', Name: 'PMOS workspace', Comment: 'Start the PMOS workspace server at login',
+    Exec: `/bin/sh ${deq(exe)} --no-open`, Terminal: 'false', NoDisplay: 'true', 'X-GNOME-Autostart-enabled': 'true' }) });
+  return { files, app, login: login ? auto : null, removable: [exe, app, auto] };
+}
+
+const marked = (f) => { try { return fs.readFileSync(f, 'utf8').includes(MARK); } catch { return false; } };
+// The file under a removable path that carries the mark: the bundle's script for a .app, else the path itself.
+const markFile = (p) => p.endsWith('.app') ? path.join(p, 'Contents', 'MacOS', 'pmos-launch') : p;
+
+function repoRootOf(dir) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout).trim() : dir;
+}
+
+// What the installed script points at: the repository and whether node and pmos.js still exist.
+function readTarget(exe) {
+  let src = '';
+  try { src = fs.readFileSync(exe, 'utf8'); } catch { return null; }
+  const m = src.match(/^exec '((?:[^']|'\\'')*)' '((?:[^']|'\\'')*)' up '((?:[^']|'\\'')*)'/m);
+  if (!m) return null;
+  const un = (s) => s.replace(/'\\''/g, "'");
+  return { node: un(m[1]), bin: un(m[2]), repo: un(m[3]) };
+}
+
+function run(argv, { say = console.log, platform = process.platform, home = os.homedir(), env = process.env,
+  node = process.execPath, bin = path.join(__dirname, '..', 'bin', 'pmos.js'), cwd = process.cwd() } = {}) {
+  const pos = argv.slice(1).filter((a) => !a.startsWith('--'));
+  const flags = new Set(argv.slice(1).filter((a) => a.startsWith('--')).map((a) => a.slice(2)));
+  const unknown = [...flags].filter((f) => f !== 'no-login' && f !== 'help');
+  if (unknown.length) { say(`✗ unknown option --${unknown[0]}`); for (const l of USAGE) say(l); return 2; }
+  const sub = pos[0];
+  if (!sub || flags.has('help') || sub === 'help') { for (const l of USAGE) say(l); return sub ? 0 : 2; }
+  if (!COMMANDS.launcher.includes(sub)) { say(`✗ pmos launcher ${sub} is not a command`); for (const l of USAGE) say(l); return 2; }
+
+  if (sub === 'on') {
+    const dir = pos[1] ? path.resolve(cwd, pos[1]) : cwd;
+    if (!fs.existsSync(dir)) { say(`✗ ${dir} does not exist`); return 1; }
+    const repo = repoRootOf(dir);
+    const p = plan({ platform, home, env, node, bin, repo, login: !flags.has('no-login') });
+    if (p.refused) { say(`✗ ${p.refused}`); return 1; }
+    // Never write over a file of the same name that the launcher did not write.
+    const foreign = p.files.filter((f) => fs.existsSync(f.path) && !marked(f.path));
+    if (foreign.length) { say(`✗ not written: ${foreign.map((f) => f.path).join(', ')} exists and was not written by pmos launcher`); return 1; }
+    for (const f of p.files) {
+      fs.mkdirSync(path.dirname(f.path), { recursive: true });
+      fs.writeFileSync(f.path, f.content, { mode: f.mode });
+      fs.chmodSync(f.path, f.mode);
+    }
+    say(`✓ PMOS app for ${repo}`);
+    say(`  ${p.app}`);
+    say(platform === 'darwin' ? '  Open it from Spotlight or Launchpad, or drag it to the Dock.' : '  Open it from the app menu.');
+    if (p.login) {
+      say('✓ login item: the workspace server starts when you log in, without a browser window');
+      say(`  ${p.login}`);
+    } else say('  no login item (--no-login): the server starts when you open the app');
+    say('  The app opens the browser on the running workspace and starts the server when none runs.');
+    say('  If you move or upgrade node, run `pmos launcher on` again.');
+    return 0;
+  }
+
+  const p = plan({ platform, home, env, node, bin, repo: cwd });
+  if (p.refused) { say(`✗ ${p.refused}`); return 1; }
+
+  if (sub === 'off') {
+    let removed = 0;
+    for (const r of p.removable) {
+      if (!fs.existsSync(r)) continue;
+      if (!marked(markFile(r))) { say(`· left ${r}: it was not written by pmos launcher`); continue; }
+      fs.rmSync(r, { recursive: true, force: true });
+      say(`✓ removed ${r}`);
+      removed++;
+    }
+    if (!removed) say('○ nothing to remove: no launcher is installed');
+    return 0;
+  }
+
+  // status
+  const exe = p.files.find((f) => f.role === 'app' && f.mode === 0o755).path;
+  const t = marked(exe) ? readTarget(exe) : null;
+  const loginPath = p.removable.find((r) => r.endsWith('.plist') || r.endsWith('pmos-workspace.desktop'));
+  const login = fs.existsSync(loginPath) && marked(loginPath);
+  if (!t) { say('○ no PMOS app is installed (pmos launcher on)'); if (login) say(`· a login item is installed without the app: ${loginPath}`); return 1; }
+  say(`✓ PMOS app — ${p.app}`);
+  say(`  repository: ${t.repo}${fs.existsSync(t.repo) ? '' : '  ✗ not found'}`);
+  say(`  node: ${t.node}${fs.existsSync(t.node) ? '' : '  ✗ not found — run `pmos launcher on` again'}`);
+  say(`  pmos: ${t.bin}${fs.existsSync(t.bin) ? '' : '  ✗ not found — run `pmos launcher on` again'}`);
+  say(login ? `✓ login item — ${loginPath}` : '○ no login item: the server starts when you open the app');
+  return [t.repo, t.node, t.bin].every((x) => fs.existsSync(x)) ? 0 : 1;
+}
+
+module.exports = { run, plan, readTarget, COMMANDS, USAGE, MARK };

package/workspace/lib/measure-cli.js

@@ -0,0 +1,100 @@
+'use strict';
+/* measure-cli.js — `pmos measure …`: record a measured value of a KR or a health budget, with its source (pm-os-absorb
+ * Run 2, PRD R17, R23, R24).
+ *
+ *   pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]
+ *   pmos measure list [<anchor>]
+ *   every command: [--json] [--root <dir>]
+ *
+ * The SAME writer the workspace page uses (lib/measurements.js). A measurement is evidence, not a PM act, so an agent
+ * may write one: the line is attributed by lib/actor.js fromCli (the PM at a terminal, the bound agent session from
+ * PMOS_SESSION, `agent:unknown` otherwise). The source is required: the workspace never computes a KR value, so a
+ * group shows a value only from a line that says where it was read. `--as-of` is today (UTC) when it is not given.
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const actorLib = require('./actor.js');
+const measurements = require('./measurements.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { measure: ['add', 'list'] };
+const USAGE = [
+  'usage: pmos measure add|list — measured values of KRs and health budgets',
+  '  pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]',
+  '  pmos measure list [<anchor>]',
+  '  every command: [--json] [--root <dir>]',
+  'The anchor is the parent_kr an initiative names: a KR such as "KR 2.1", or health:<id>. Quote an anchor with a space.',
+  'The source is the file the value was read from and the commit it was read at, for example planning/okrs/q4.md@1a2b3c4.',
+];
+const BOOL = new Set(['json', 'help']);
+const VALUE = new Set(['source', 'target', 'unit', 'as-of', 'root']);
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+const num = (s) => (typeof s === 'string' && s.trim() !== '' && Number.isFinite(Number(s)) ? Number(s) : NaN);
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now } = {}) {
+  const args = argv[0] === 'measure' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags } = parse(args.slice(1));
+  const json = !!flags.json;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) {
+    for (const l of USAGE) say(l);
+    return verb ? 0 : 1;
+  }
+  if (!COMMANDS.measure.includes(verb)) { say(`unknown measure command "${verb}" — one of ${COMMANDS.measure.join(', ')}`); return 2; }
+  if ('by' in flags || 'via' in flags) { say(`attribution is set from the call path; --${'by' in flags ? 'by' : 'via'} is not accepted`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+
+  if (verb === 'list') {
+    const m = measurements.readMeasurements(root);
+    const anchors = pos[0] ? [pos[0]] : Object.keys(m.byAnchor).sort();
+    if (json) { say(JSON.stringify({ ok: true, byAnchor: Object.fromEntries(anchors.map((a) => [a, (m.byAnchor[a] || []).map((x) => ({ ...x, by: actorLib.pageName(x.by) }))])), flags: m.flags })); return 0; }
+    if (!anchors.length) say('No measurements yet.');
+    for (const a of anchors) {
+      for (const x of m.byAnchor[a] || []) say(`${a} · ${x.value}${x.unit || ''}${x.target === null ? '' : ` → ${x.target}${x.unit || ''}`} on ${x.as_of} · ${x.source} · ${actorLib.pageName(x.by)}`);
+    }
+    for (const f of m.flags) say(`! ${f.why}`);
+    return 0;
+  }
+
+  const [anchor, valueText] = pos;
+  if (!anchor || valueText === undefined) { say(USAGE[1].trim()); return 2; }
+  const value = num(valueText);
+  if (!Number.isFinite(value)) return fail('the value must be a number', 2);
+  const ev = { ev: 'measured', anchor, value };
+  if (flags.target !== undefined) {
+    const t = num(flags.target);
+    if (!Number.isFinite(t)) return fail('--target must be a number', 2);
+    ev.target = t;
+  }
+  if (flags.unit !== undefined) ev.unit = flags.unit;
+  ev.as_of = flags['as-of'] || new Date(now == null ? Date.now() : now).toISOString().slice(0, 10);
+  if (flags.source !== undefined) ev.source = flags.source;
+  const actor = actorLib.fromCli({ isTTY: isTTY === undefined ? !!(process.stdin.isTTY && process.stdout.isTTY) : isTTY, env: env === undefined ? process.env : env });
+  const r = measurements.appendFromCli(root, [ev], { actor, now });
+  if (!r.ok) return fail(r.error);
+  if (json) say(JSON.stringify({ ok: true, written: r.written, eid: r.lines[0].eid }));
+  else say(`✓ ${anchor}: ${value}${ev.unit || ''} on ${ev.as_of} recorded (source ${ev.source})`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };