create-pmos 0.16.0 → 0.17.0

package/workspace/lib/engine/workflow-state.js

@@ -164,25 +164,88 @@ function git(root, args) {
  * evaluated has not been satisfied, and saying so is the whole point of the honesty rule above.
  */
 function commitRange(root) {
+  return buildRange(root, { spec: null });
+}
+
+/*
+ * The BOARD's range: the whole trunk, not the pull request.
+ *
+ * These are two different questions and they were sharing an answer. The gate asks "inside this
+ * diff, did the spec precede the build?" — only decidable within the PR. The board asks "where does
+ * this initiative stand?", which the PR range cannot answer at all: on a branch level with `main`
+ * the range is EMPTY, so every initiative reported `no implementation commits in this range` and
+ * collapsed to stage `spec`. A delivered initiative rendered identically to one never started.
+ *
+ * Splitting them means a rule can read `done` on the board and still be evaluated inside the gate.
+ * That is intended and is stated in the board's own footer, so it never reads as a discrepancy.
+ */
+function historyRange(root) {
+  const trunk = ['origin/main', 'main', 'origin/master', 'master']
+    .find((c) => git(root, ['rev-parse', '--verify', '--quiet', c]));
+  return buildRange(root, { spec: trunk || 'HEAD', whole: true });
+}
+
+/*
+ * ONE pass over the range, not one git call per question.
+ *
+ * Two `git log` invocations build every index the ladder needs: which paths each commit CHANGED
+ * (for buildCommits) and where each path was ADDED (for firstAppearance). Previously firstAppearance
+ * shelled out once per path per initiative and buildCommits ran `git show` once per commit per
+ * initiative — 330+ processes for the board on an empty range (23 s), and O(commits × initiatives)
+ * on a full one, which is what made full history look impossible rather than merely unimplemented.
+ */
+function buildRange(root, { spec, whole }) {
   if ((git(root, ['rev-parse', '--is-shallow-repository']) || '').trim() === 'true') {
     return { ok: false, reason: 'shallow clone — no history to order commits by (CI needs fetch-depth: 0)' };
   }
-  const candidates = [];
-  if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
-  candidates.push('origin/main', 'main', 'origin/master', 'master');
   let base = null;
-  for (const c of candidates) {
-    if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
-    const mb = git(root, ['merge-base', c, 'HEAD']);
-    if (mb && mb.trim()) { base = mb.trim(); break; }
+  let range = spec;
+  if (!range) {
+    const candidates = [];
+    if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
+    candidates.push('origin/main', 'main', 'origin/master', 'master');
+    for (const c of candidates) {
+      if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
+      const mb = git(root, ['merge-base', c, 'HEAD']);
+      if (mb && mb.trim()) { base = mb.trim(); break; }
+    }
+    range = base ? `${base}..HEAD` : 'HEAD';
   }
-  const spec = base ? `${base}..HEAD` : 'HEAD';
-  const log = git(root, ['log', '--reverse', '--format=%H', spec]);
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct', '--name-only', range]);
   if (log == null) return { ok: false, reason: 'git history unreadable' };
-  const shas = log.split('\n').map((s) => s.trim()).filter(Boolean);
+
+  const shas = [];
+  const changed = [];                 // index -> string[] of paths touched
+  const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  for (const chunk of log.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const lines = chunk.split('\n');
+    const head = (lines.shift() || '').trim();
+    const [sha, ct] = head.split(/\s+/);
+    if (!sha) continue;
+    shas.push(sha);
+    dates.push(Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null);
+    changed.push(lines.map((s) => s.trim()).filter(Boolean));
+  }
   const index = new Map();
   shas.forEach((sha, i) => index.set(sha, i));
-  return { ok: true, base, index, shas, wholeHistory: !base };
+
+  // Where each path was ADDED, as an index into the same range. `--diff-filter=A` in one pass.
+  const added = new Map();
+  const addLog = git(root, ['log', '--reverse', '--format=%x1e%H', '--diff-filter=A', '--name-only', range]);
+  if (addLog != null) {
+    for (const chunk of addLog.split('\x1e')) {
+      if (!chunk.trim()) continue;
+      const lines = chunk.split('\n');
+      const sha = (lines.shift() || '').trim();
+      const at = index.has(sha) ? index.get(sha) : null;
+      if (at == null) continue;
+      for (const f of lines.map((s) => s.trim()).filter(Boolean)) {
+        if (!added.has(f)) added.set(f, at);
+      }
+    }
+  }
+  return { ok: true, base, index, shas, changed, dates, added, wholeHistory: whole ? true : !base };
 }
 
 /*
@@ -200,6 +263,10 @@ function commitRange(root) {
 function firstAppearance(root, range, rel) {
   const onDisk = fs.existsSync(path.join(root, rel));
   if (!range.ok) return onDisk ? undefined : null;
+  // The single-pass index answers first, and over the whole trunk it answers everything that has
+  // ever been committed — so the fallback below only runs for a PR range, where "added before the
+  // range" and "never committed" are genuinely different answers and only git can tell them apart.
+  if (range.added && range.added.has(rel)) return range.added.get(rel);
   const log = git(root, ['log', '--diff-filter=A', '--reverse', '--format=%H', '--', rel]);
   const sha = log ? log.split('\n').map((s) => s.trim()).filter(Boolean)[0] : null;
   if (!sha) return onDisk ? Infinity : null;
@@ -213,9 +280,10 @@ function buildCommits(root, range, lane) {
   if (!range.ok) return { unknown: true };
   let first = null; let count = 0; let sample = null;
   for (let i = 0; i < range.shas.length; i++) {
-    const files = git(root, ['show', '--name-only', '--format=', range.shas[i]]);
-    if (!files) continue;
-    const hit = files.split('\n').map((s) => s.trim()).filter(Boolean).find((f) => isBuildPath(f, lane));
+    // range.changed came from the range's own single pass; the per-commit `git show` this replaced
+    // ran once per commit PER INITIATIVE, which is why the board took 23 s before it read anything.
+    const files = (range.changed && range.changed[i]) || [];
+    const hit = files.find((f) => isBuildPath(f, lane));
     if (!hit) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
@@ -290,10 +358,29 @@ function computeWorkflow(id, opts) {
   const effLane = knownLane ? lane : 'feature';           // unknown lane = strictest, as the bash gate does
   const range = (opts && opts.range) || commitRange(root);
   // See ENFORCED_FROM: git decides, the frontmatter only breaks a tie git cannot see.
+  //
+  // `recIdx === -1` — "the record predates this range" — is the right test for a PR range and a
+  // MEANINGLESS one over the whole trunk, where nothing predates the range and every legacy record
+  // would suddenly be enforced. So the commit DATE decides whenever the range can supply it, and
+  // -1 keeps its meaning for the gate's range. Same question, asked of evidence that survives both.
   const recIdx = firstAppearance(root, range, recRel);
-  const legacy = (recIdx === undefined || recIdx === null)
-    ? String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM   // fallback only — see ENFORCED_FROM
-    : recIdx === -1;
+  const recAt = (range.dates && typeof recIdx === 'number' && recIdx >= 0) ? range.dates[recIdx] : null;
+  /*
+   * `reconstructed_from` — the merge date of work whose record was written afterwards.
+   *
+   * A record backfilled today for a PR that merged in June has TODAY's commit date, so the date
+   * test would enforce today's rules on work that predates them and report a violation nobody
+   * could ever have avoided. The declared merge date decides instead.
+   *
+   * This is not an escape hatch: it must name a date, that date is checkable against the merge it
+   * claims, and declaring one AFTER `ENFORCED_FROM` makes the record non-legacy — so work that
+   * genuinely skipped the loop still reports blocked, which is the point of writing it down.
+   */
+  const recon = String(fm.reconstructed_from || '').trim().slice(0, 10);
+  const legacy = recIdx === -1 ? true
+    : /^\d{4}-\d{2}-\d{2}$/.test(recon) ? recon < ENFORCED_FROM
+      : recAt ? new Date(recAt * 1000).toISOString().slice(0, 10) < ENFORCED_FROM
+        : String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM;   // fallback — see ENFORCED_FROM
   /*
    * `legacy` answers the ENFORCEMENT question — should this PR fail? It is NOT the visibility
    * question. Filtering the board by it was a real bug: on `main`, every record is legacy, so the
@@ -304,7 +391,12 @@ function computeWorkflow(id, opts) {
    * `lastActivity` is the honest fallback for everything else, because "when was this last worked
    * on" is a fact the repo already holds and nobody has to maintain.
    */
-  const inChange = recIdx !== -1 && recIdx !== null && recIdx !== undefined;
+  // `● in this change` must keep meaning "the diff under review touches this". Over the whole trunk
+  // that is true of everything, which makes the marker noise — so the board passes the GATE's range
+  // separately and the marker is answered from that, or dropped when there is no such range.
+  const changeRange = (opts && opts.changeRange) || (range.wholeHistory ? null : range);
+  const chgIdx = changeRange ? firstAppearance(root, changeRange, recRel) : null;
+  const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
   const lastActivity = (() => {
     const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
     const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
@@ -522,10 +614,14 @@ function computeWorkflow(id, opts) {
         steps.push(step('spec', 'spec', 'done', `${specNames} — first-appeared at or before the first build commit`));
       } else {
         const late = rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? rubric : prd;
-        steps.push(step('spec', 'spec', 'blocked',
+        // `legacy` applies here exactly as it does to O4. It always should have — the rule simply
+        // never fired for a legacy record while the board shared the gate's PR range, because an
+        // empty range has no build commit to be out of order with. Reading the trunk exposed it:
+        // 81 records that predate enforcement were suddenly failing a rule written after them.
+        steps.push(step('spec', 'spec', legacy ? 'unknown' : 'blocked',
           `ORDER VIOLATION — implementation (${build.sample}) was committed BEFORE ${late} first appeared`,
           'the rubric is the spec (D13). Land the spec artifacts in an earlier commit than the build, or split this PR so the spec lands first',
-          { blocking: true, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
+          { blocking: !legacy, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
       }
     }
   }
@@ -776,6 +872,10 @@ function renderBoard(rows, opts) {
   out.push('');
   // Never a silent cap — a truncated list that does not say so reads as "that is everything".
   if (hidden) out.push(`  ${c(33, `+ ${hidden} more without a recorded acceptance, not shown`)} ${c(90, `— node ${opts.self} --all`)}`);
+  // The two ranges, said out loud. The board reads the whole trunk so a delivered initiative does
+  // not render as unstarted; the gate reads the PR so "spec before build" stays decidable. A rule
+  // can therefore read done here and still be evaluated on the PR — intended, and not a discrepancy.
+  out.push(`  ${c(90, 'derived from the whole trunk history; the CI gate evaluates order within the PR only')}`);
   out.push(`  ${c(90, `one initiative in detail:  node ${opts.self} <id>`)}`);
   out.push('');
   return out.join('\n');
@@ -871,8 +971,12 @@ function main(argv) {
     return 0;
   }
 
-  const range = commitRange(root);
-  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range }));
+  // R-7: the BOARD reads the trunk, not the pull request. The gate path above keeps commitRange().
+  // The PR range is still computed and passed alongside — it is what `● in this change` means, and
+  // it is the one thing the trunk range genuinely cannot answer.
+  const range = historyRange(root);
+  const changeRange = commitRange(root);
+  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range, changeRange }));
   if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
   if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
   process.stdout.write(renderBoard(rows, { self, all }));
@@ -882,6 +986,9 @@ function main(argv) {
 module.exports = {
   computeWorkflow, renderLadder, renderBoard, listInitiatives, layout, inFlight, BOARD_CAP,
   parseLeadingFrontmatter, specimenRoute, surfaceRoute, priorsCitation, isBuildPath, commitRange,
+  // the board's trunk range, exported so the suite can assert the split: the same record is legacy
+  // under BOTH ranges, and `in this change` is false under the trunk one.
+  historyRange,
   ENFORCED_FROM,
 };
 

package/workspace/lib/server-discovery.js

@@ -0,0 +1,127 @@
+'use strict';
+/* lib/server-discovery.js — WHICH workspace server is running, and on WHICH port.
+ *
+ * The launcher used to answer that question with a constant: port 7433, or whatever
+ * `PMOS_WS_PORT` said in THIS shell. That constant is why a second repo could not be added to a
+ * running workspace. The sequence the PM hit, end to end:
+ *
+ *   1. something already held 7433 (a wedged server, a crashed one whose socket lingered, or an
+ *      unrelated program), so the server exited with EADDRINUSE and printed the advice
+ *      `PMOS_WS_PORT=7500 npm start`;
+ *   2. the PM followed it, and the workspace came up on 7500 — the browser tab is on 7500;
+ *   3. `pmos` in the other repo, in a fresh shell with no `PMOS_WS_PORT`, looked at 7433 only,
+ *      found nothing, and started a SECOND server there. The repo was registered — with the
+ *      server nobody was looking at.
+ *
+ * Nothing in that sequence errors. That is the whole defect: two servers, each honest, and a repo
+ * that "never added" because it landed in the one that isn't on screen.
+ *
+ * So the port is DISCOVERED, never assumed. The candidate list is built from state the running
+ * server itself writes (`state/server-<port>.pid`, written on listen and removed on shutdown —
+ * server.js), which makes a server discoverable however it was started: `pmos`, `npm start`, or a
+ * hand-typed `PMOS_WS_PORT=7500 node server.js`.
+ *
+ * An explicit `PMOS_WS_PORT` is treated as a PIN, not a hint: it narrows the candidates to that one
+ * port and never widens them. The test suite depends on that isolation — a suite that could attach
+ * to the PM's real workspace would drive their live sessions.
+ *
+ * Everything here is pure, or reads the filesystem and nothing else: no sockets, no child
+ * processes. The I/O lives in the caller (bin/pmos.js, doctor.js), so the whole policy is testable
+ * in-process without binding a port.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_PORT = 7433;
+// How far the launcher rolls forward when the default port is taken by something that is not a
+// workspace server. Bounded on purpose: "start somewhere, anywhere" would scatter servers across
+// the ephemeral range and make discovery a scan.
+const FALLBACK_SPAN = 12;
+
+// state/server-<port>.pid — the launcher AND the server agree on this name; it is the only place a
+// port is recorded, so it is the only shape parsed here.
+const PID_RE = /^server-(\d{2,5})\.pid$/;
+
+const pidFileName = (port) => `server-${Number(port)}.pid`;
+
+/**
+ * Every `state/server-<port>.pid` on disk, most recently written first. A record is returned even
+ * when its pid is unreadable — a file whose contents are gone still names a port worth probing,
+ * and treating it as absent is how a running server becomes invisible.
+ */
+function pidRecords(stateDir) {
+  let names = [];
+  try { names = fs.readdirSync(stateDir); } catch { return []; }
+  const out = [];
+  for (const name of names) {
+    const m = PID_RE.exec(name);
+    if (!m) continue;
+    const file = path.join(stateDir, name);
+    let pid = null, mtime = 0;
+    try { pid = Number(String(fs.readFileSync(file, 'utf8')).trim()) || null; } catch {}
+    try { mtime = fs.statSync(file).mtimeMs; } catch {}
+    out.push({ port: Number(m[1]), pid, file, mtime });
+  }
+  out.sort((a, b) => b.mtime - a.mtime);
+  return out;
+}
+
+/**
+ * The ports to probe, in order. With a pinned port that list is exactly one long — see the header:
+ * a pin is an instruction, and widening it would let a test (or a second workspace deliberately
+ * kept apart) attach to a server it was told not to touch.
+ */
+function candidatePorts({ stateDir, pinned = null, defaultPort = DEFAULT_PORT } = {}) {
+  const pin = Number(pinned);
+  if (Number.isInteger(pin) && pin > 0) return [pin];
+  const seen = new Set();
+  const out = [];
+  const push = (p) => { if (Number.isInteger(p) && p > 0 && !seen.has(p)) { seen.add(p); out.push(p); } };
+  push(Number(defaultPort) || DEFAULT_PORT);
+  for (const r of pidRecords(stateDir)) push(r.port);
+  return out;
+}
+
+/** Is this pid still around? EPERM means yes-but-not-ours, which is still alive. */
+function pidAlive(pid, kill) {
+  const k = kill || ((p, sig) => process.kill(p, sig));
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { k(pid, 0); return true; } catch (e) { return !!e && e.code === 'EPERM'; }
+}
+
+/**
+ * Which pid files describe a server that is gone. Deliberately conservative: a file is stale only
+ * when its port does NOT answer AND its pid is NOT alive. A server that is mid-start — listening
+ * socket not yet open, process very much alive — must survive this, or one launcher would delete
+ * another's record and make it undiscoverable a second later.
+ */
+function stalePidFiles(stateDir, { livePorts = [], alive = pidAlive } = {}) {
+  const live = new Set(livePorts.map(Number));
+  return pidRecords(stateDir)
+    .filter((r) => !live.has(r.port) && !alive(r.pid))
+    .map((r) => r.file);
+}
+
+/**
+ * The first port at or after `start` that `isFree` accepts, within the bounded span. `isFree` is
+ * injected (the caller owns the socket), so this stays pure and the span is assertable.
+ */
+function nextFreePort(start, isFree, span = FALLBACK_SPAN) {
+  const from = Number(start) || DEFAULT_PORT;
+  for (let p = from; p < from + span; p++) if (isFree(p)) return p;
+  return null;
+}
+
+/**
+ * Does this JSON body come from a workspace server? `/api/sessions` answers `{sessions:[…]}`, and
+ * requiring the array is what keeps an unrelated program that happens to serve JSON on 7433 from
+ * being adopted as "the workspace" — the launcher would then register the PM's repo into it.
+ */
+function looksLikeWorkspace(body) {
+  return !!body && typeof body === 'object' && Array.isArray(body.sessions);
+}
+
+module.exports = {
+  DEFAULT_PORT, FALLBACK_SPAN, PID_RE,
+  pidFileName, pidRecords, candidatePorts, pidAlive, stalePidFiles, nextFreePort, looksLikeWorkspace,
+};

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.16.0",
+      "version": "0.17.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/pm/data.js

@@ -774,6 +774,34 @@ export async function addRepo({ source, kind }) {
   };
 }
 
+/**
+ * panel-repos.js — `chooseFolder(start)`. The machine's OWN folder dialog, opened by the server.
+ *
+ * A browser cannot hand back an absolute path — its directory picker yields a name and a handle,
+ * never a path — so the add-a-product form could only ever offer a text field, and the PM had to
+ * know and type the path of the repo they were looking at. The server runs on the PM's machine and
+ * binds 127.0.0.1 (D62), so it opens the native chooser and returns the chosen path; this function
+ * only asks. Registration still goes through `addRepo()` → POST /api/workspaces, so nothing here
+ * bypasses a guard: the dialog produces a string, and the PM confirms it like any other.
+ *
+ * `{cancelled:true}` and `{unsupported:true}` are ANSWERS, not failures — a headless Linux box has
+ * no chooser at all, which is what `listFolder()` below stands in for.
+ */
+export async function chooseFolder(start) {
+  if (FIXTURE) return { ok: false, unsupported: true };
+  return postJson('/api/pick-folder', { start: start || '' });
+}
+
+/**
+ * panel-repos.js — `listFolder(dir)`. The in-app folder browser's data source, for when there is
+ * no native chooser (and for anyone who prefers it). The server returns directory NAMES only —
+ * never a file, never a byte of content — and flags which ones are git repositories.
+ */
+export async function listFolder(dir) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode has no filesystem' };
+  return getJson('/api/fs/list', dir ? { path: dir } : null);
+}
+
 /**
  * panel-tabs.js — `startSession(slug, sess)`. Deliberately NOT a spawn.
  *

package/workspace/public/pm/panel-repos.js

@@ -299,6 +299,93 @@ function field(key, value) {
   });
 }
 
+/* ── choosing the folder, instead of typing its path ─────────────────────────────────────────
+ * The form's local branch used to be a bare text field, so "add the repo I am looking at" meant
+ * knowing its absolute path and typing it correctly — and the two endpoints that exist to avoid
+ * exactly that (`/api/pick-folder`, `/api/fs/list`) had no caller anywhere in the front end.
+ *
+ * Two ways in, because one of them is not always there: the machine's native dialog first, and the
+ * in-app browser when there is no native chooser (headless Linux), when one is already open, or
+ * when the PM asks for it. A cancelled dialog changes nothing — it is an answer, not a failure.
+ */
+const browseRowStyle = 'display:grid;grid-template-columns:76px 1fr auto;gap:10px;padding:10px 14px';
+const chooseStyle = 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:32px;'
+  + 'background:transparent;border:1px solid var(--border);color:var(--muted-foreground)';
+
+/** The in-app browser, opened at `dir` (empty = the server's idea of home). */
+function openBrowse(dir) {
+  // Fixture mode reads NOTHING off this machine — the comparator drives this surface, and a run
+  // that opened a dialog or listed the PM's home directory would be doing real work behind a
+  // scripted board. It says so instead of degrading into a vaguer "no endpoint" line.
+  if (FIXTURE) {
+    setState({ addLog: [{ t: 'the folder chooser is off in fixture mode — nothing on this machine is read', c: 'var(--warning)' }] });
+    return;
+  }
+  if (!dataMod || typeof dataMod.listFolder !== 'function') {
+    setState({ addLog: [{ t: 'no local endpoint for browsing folders — type the path instead', c: 'var(--warning)' }] });
+    return;
+  }
+  setState({ addBrowse: { loading: true, path: dir || '', entries: [] } });
+  Promise.resolve(dataMod.listFolder(dir)).then((res) => {
+    if (!res || res.ok === false) {
+      setState({ addBrowse: { path: dir || '', entries: [], error: (res && res.error) || 'that folder could not be listed' } });
+      return;
+    }
+    setState({ addBrowse: res });
+  }).catch((e) => setState({ addBrowse: { path: dir || '', entries: [], error: e && e.message ? e.message : String(e) } }));
+}
+
+/** Ask the server to open the machine's folder dialog; fall back to the in-app browser. */
+function chooseFolder() {
+  if (FIXTURE || !dataMod || typeof dataMod.chooseFolder !== 'function') { openBrowse(state.addPath); return; }
+  setState({ addPicking: true });
+  Promise.resolve(dataMod.chooseFolder(state.addPath)).then((res) => {
+    setState({ addPicking: false });
+    if (res && res.ok && res.root) { setState({ addPath: res.root, addBrowse: null }); return; }
+    if (res && res.cancelled) return;                       // the PM closed the dialog: no change, no noise
+    openBrowse(state.addPath);                              // unsupported, busy, or unreachable → in-app
+  }).catch(() => { setState({ addPicking: false }); openBrowse(state.addPath); });
+}
+
+/** Take the folder currently open in the browser as the answer. */
+function useFolder(p) {
+  if (!p) return;
+  setState({ addPath: p, addBrowse: null });
+}
+
+const browseRow = (label, title, onClick, muted) => el('button', {
+  onClick, title,
+  style: 'display:flex;align-items:center;gap:8px;width:100%;padding:5px 10px;min-height:28px;text-align:left;'
+    + 'font-family:var(--mono);font-size:11px;color:var(--' + (muted ? 'muted-foreground' : 'foreground') + ')',
+  hover: 'background:var(--accent)',
+}, label);
+
+/** The browser body: where we are, one row per sub-directory, and a way to take the current one. */
+function browseBody() {
+  const b = state.addBrowse;
+  const rows = [];
+  rows.push(el('div', { style: 'display:flex;align-items:center;gap:8px;padding:6px 10px;border-bottom:1px solid var(--border)' },
+    el('span', { style: 'flex:1;font-family:var(--mono);font-size:11px;overflow-wrap:anywhere' }, ip(b.path || '…')),
+    el('button', { onClick: () => useFolder(b.path), style: chooseStyle + ';min-height:26px', hover: 'border-color:var(--ring)' },
+      ip('use this folder')),
+  ));
+  if (b.error) rows.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--destructive)' }, ip(b.error)));
+  else if (b.loading) rows.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--muted-foreground)' }, ip('reading…')));
+  else {
+    const list = [];
+    if (b.parent) list.push(browseRow('↑  ..', b.parent, () => openBrowse(b.parent), true));
+    for (const e of b.entries || []) {
+      // The repo marker is the whole point of showing this list rather than a plain file chooser:
+      // it says which of these folders PMOS can actually open as a workspace.
+      list.push(browseRow((e.isRepo ? '⑂  ' : '·  ') + e.name, e.path, () => openBrowse(e.path), !e.isRepo));
+    }
+    if (b.denied) list.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--warning)' }, ip('this folder cannot be read')));
+    else if (!list.length) list.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--muted-foreground)' }, ip('no sub-folders here')));
+    rows.push(el('div', { style: 'max-height:220px;overflow-y:auto' }, list));
+  }
+  return el('div', { style: 'margin:0 14px 10px;border:1px solid var(--border)' }, rows);
+}
+
 function srcButton(id, label) {
   const on = state.addSrc === id;
   return el('button', {
@@ -425,10 +512,16 @@ export function addProductBody() {
       el('button', { onClick: ingestGithub, style: goStyle }, '⇣ connect + ingest'),
     ));
   } else {
-    out.push(el('div', { style: rowStyle },
+    // Field FIRST, chooser beside it: the path is still typeable (and still the thing that gets
+    // registered), the button only fills it in. The row keeps label + input as its first two
+    // children, which is the shape panel 1's suite reads.
+    out.push(el('div', { style: browseRowStyle },
       el('span', { style: labelStyle }, 'folder'),
       field('addPath', state.addPath),
+      el('button', { onClick: chooseFolder, style: chooseStyle, hover: 'border-color:var(--ring)' },
+        ip(state.addPicking ? 'choosing…' : 'choose…')),
     ));
+    if (state.addBrowse) out.push(browseBody());
     out.push(el('div', { style: 'padding:2px 14px 8px;font-size:11.5px;line-height:1.5;color:var(--muted-foreground)' },
       'Starts with an empty board — nothing is imported from a bare folder. File the first initiative to begin.'));
     out.push(el('div', { style: 'padding:2px 14px 12px;border-bottom:1px solid var(--border)' },

package/workspace/public/pm/state.js

@@ -28,6 +28,10 @@ function initial() {
     product: null, newSessProfile: 'claude-work', intgSynced: {},
     addSrc: 'github', addRepo: 'github.com/acme/atlas-mobile', addPath: '~/code/notes-cli',
     addLog: [], addedProducts: [], extraKnow: {},
+    // the folder chooser's two transient bits: the in-app browser's current listing (null = closed)
+    // and whether the machine's native dialog is open. Neither is persisted — a dialog that
+    // "reopens" on reload is a lie about what the OS is showing.
+    addBrowse: null, addPicking: false,
     newType: 'init', newName: '', newSlug: '', newAnchor: null, newFlow: 'adlc-feature',
     userGroups: {}, userKrs: {}, addedInits: {}, userInits: {}, selTask: null, collapsedPhases: {},
     detail: { kind: 'init' },