create-pmos 0.26.0 → 0.27.0

package/workspace/server.js

@@ -111,7 +111,96 @@ const HOME_ENABLED = EMBEDDED_SELF || (!!process.env.PMOS_SELF_ROOT && dirExists
 const PUB = path.join(__dirname, 'public');
 const PM_DIR = path.join(PUB, 'pm');   // the four-panel front end — served as a directory, guarded below
 const XROOT = path.join(__dirname, 'node_modules', '@xterm');
-const STATE = path.join(__dirname, 'state');
+// ── WHERE THE PM'S RUNTIME STATE LIVES (see lib/state-root.js for the whole argument). ─────────
+// It is NOT `workspace/state/` any more. That directory is inside the application directory the
+// test suite runs from, which put the PM's live sessions, workspace registry and authored skills
+// within reach of every test, every spawned child and every stray shell command — and three rounds
+// of guarding destructive verbs failed, each to a verb nobody had guarded yet. Unreachable beats
+// guarded. STATE now resolves to a per-user location (PMOS_STATE_DIR wins; else the OS default),
+// and an existing in-repo state/ is MOVED there once, idempotently, on first run.
+const stateRoot = require('./lib/state-root');
+// LEGACY_STATE is what `workspace/state/` used to be, kept for exactly two jobs: it is the source
+// the migration moves FROM, and it is D64's file-mode mirror for an EMBEDDED PMOS-self checkout
+// that has no `pmos/state/` yet (see stateDirFor). The system of record stays in the repository
+// that earned it — only the churny runtime moved out.
+const LEGACY_STATE = path.join(__dirname, 'state');
+// ── REQUIRING THIS FILE IS NOT A QUIET ACT. ───────────────────────────────────────────────────
+// `require('./server.js')` — which two suites do, for the exported helpers — runs everything at
+// module scope: it resolves the state root, registers the home workspace, restores persisted
+// sessions and spawns a first shell. Unconfigured, all of that now lands in the PM's REAL per-user
+// state, and it did exactly that once while this change was being written. So a library consumer
+// must name its own state directory, and finds out by being told rather than by contaminating the
+// PM's registry and discovering it a day later.
+const REQUIRED_AS_LIBRARY = require.main !== module;
+if (REQUIRED_AS_LIBRARY && !stateRoot.overrideDir(process.env)) {
+  throw new Error(
+    'server.js was required as a library with no PMOS_STATE_DIR set. Requiring it runs its module ' +
+    'scope — resolving the runtime state root, registering the home workspace and spawning a shell ' +
+    '— which would write into the PM\'s real runtime state. Point PMOS_STATE_DIR at a scratch ' +
+    'directory before the require (test-run.js#configure does this).');
+}
+// The migration is likewise offered ONLY to a real server start. Relocating the PM's live sessions
+// as a side effect of an import is not a thing an import may do, whatever its state directory.
+const STATE_RESOLVED = stateRoot.resolveStateRoot({
+  env: process.env,
+  legacy: REQUIRED_AS_LIBRARY ? null : LEGACY_STATE,
+});
+const STATE = STATE_RESOLVED.root;
+// ── AN UNSETTLED STATE ROOT MUST NOT DEGRADE INTO "YOU HAVE NOTHING". ─────────────────────────
+// When both directories hold state nothing is moved (only a human can decide which sixteen
+// sessions are the real sixteen) — but the stores the per-user root does NOT hold used to resolve
+// to it anyway, so the PM's eleven skills and forty-five schedules rendered as two empty lists and
+// forty-five scheduled runs silently stopped firing. Per store: fall back to the legacy root ONLY
+// where the per-user root holds no copy at all, so there is exactly one copy and reading/writing it
+// cannot fork anything. See lib/state-root.js#resolveStore for the whole argument, including why a
+// test run can never reach this path.
+//
+// This applies to EVERY outcome that is not a completed move, not only to a conflict. A move the
+// filesystem REFUSES leaves the PM's stores in the legacy directory just as a conflict does, and
+// for one round it resolved them to the per-user root anyway and said nothing at all — the same
+// empty list with the stderr line removed as well. state-root.js#isSettled is the single predicate.
+//
+// RESOLVED PER CALL, NOT ONCE AT BOOT. The previous round pinned these to constants, which meant
+// the process kept whatever it decided at startup: a PM who resolved the conflict — or fixed the
+// permission — went on being served the old directory until they restarted, and a PM who moved a
+// store INTO the per-user root had two live copies with the server writing the stale one. When the
+// root is settled these functions short-circuit before touching the filesystem (the case every test
+// run and every normal boot is in), so the cost is a path.join; only an unsettled root pays for two
+// existsSync calls, which is what the next boot would do anyway.
+function schedStore() {
+  return stateRoot.resolveStore({
+    root: STATE, legacy: LEGACY_STATE, name: 'schedules.json', migration: STATE_RESOLVED.migration });
+}
+function skillsStore() {
+  return stateRoot.resolveStore({
+    root: STATE, legacy: LEGACY_STATE, name: 'skills', migration: STATE_RESOLVED.migration });
+}
+// The ONE fact every surface repeats. `{ok:true}` normally; otherwise a discriminated failure naming
+// BOTH directories — and, for a refused move, the errno and the plain-language cause, because that
+// is the one kind the PM cannot resolve from the directory names alone. Carried on /api/workspaces,
+// /api/skills, /api/schedules and every /api/console payload, and written into the first line of
+// every new terminal pane. stderr alone was not a surface: `pmos` detaches it into a log nobody reads.
+function stateHealthNow() {
+  const sk = skillsStore(), sc = schedStore();
+  return stateRoot.stateHealth({
+    migration: STATE_RESOLVED.migration,
+    fellBack: [sk.fellBack ? 'skills' : null, sc.fellBack ? 'schedules.json' : null].filter(Boolean),
+    // If the state root itself could not be created there is nowhere to read from, every list
+    // renders empty and the migration record says nothing about it — resolveStateRoot used to
+    // swallow that mkdir on the promise that "the caller's first write will report it". The caller
+    // is a store, and what a store does is return []. So the error is carried here instead.
+    rootError: STATE_RESOLVED.rootError || null,
+  });
+}
+if (STATE_RESOLVED.migration.action === 'moved') {
+  console.log(`· moved the workspace's runtime state out of the app directory → ${STATE}`);
+}
+// NOT an `else if`. Chaining it off the 'moved' branch is how 'failed' came to print nothing at all:
+// every non-ok health is reported here on its own terms, whatever the action was.
+{
+  const boot = stateHealthNow();
+  if (!boot.ok) console.error('✗ ' + boot.error);
+}
 const SESS_DIR = path.join(STATE, 'sessions');
 const SCRATCH_DIR = path.join(STATE, 'scratchpad');   // per-workspace staging text (D62; local-only, gitignored)
 const LAYOUT_DIR = path.join(STATE, 'layouts');       // per-workspace arrangements (R7; local-only, gitignored)
@@ -402,6 +491,20 @@ function treePeersDescribed(tree, excludeId) {
 function treeWriter(tree) {
   return treeShare.writerOf(treeClaims, treeOfWsMap(), [...sessions.values()], tree);
 }
+/**
+ * THE UNMIGRATED STATE, SAID WHERE THE PM IS LOOKING.
+ *
+ * A conflict already printed to stderr — and `pmos` detaches stderr into a log nobody reads, so in
+ * practice it printed to nobody while the PM's skills and schedules quietly rendered as two empty
+ * lists. This puts the same sentence in the pane's own scrollback, which is a surface the PM is by
+ * definition looking at and which persists in the session record. Every new session, until the two
+ * directories are resolved, because a notice that shows once is a notice that is missed once.
+ */
+function announceStateHealth(s) {
+  const h = stateHealthNow();
+  if (h.ok) return;
+  appendBuf(s, `\x1b[38;5;203m✗ ${h.error}\x1b[0m\r\n`);
+}
 /**
  * A freshly-live session meets its tree: take the claim if nobody holds one, and write what it
  * found into its own scrollback. The pane line is deliberately part of the session's record rather
@@ -1355,19 +1458,40 @@ function buildSurface(name, root, w) {
 // (D62). v1 tasks are DETERMINISTIC (generated from a surface + the contract = maximally consistent,
 // no agent needed); agent-backed tasks (reasoning work) that spawn a PTY session are the documented
 // extension, not v1. Cadence math is the pure shared module — the tick and the pane's next-run agree.
-const SCHED_FILE = path.join(STATE, 'schedules.json');
+// Resolved per call (schedStore/skillsStore, above): normally `STATE/…`, and under any unsettled
+// state root the legacy copy where the per-user root holds none — read AND written, since it is
+// then the only copy on the machine. stateHealthNow() says so on every surface that lists them.
+// A function rather than a constant so that resolving the conflict, or fixing the permission that
+// refused the move, takes effect on the next read instead of on the next restart.
+function schedFile() { return schedStore().path; }
 const DELIV_DIR = path.join(STATE, 'deliverables');
 // Skills are file-driven (workspace-skill-authoring): built-ins ship committed under workspace/skills/,
 // user-authored ones are scaffolded into state/skills/ by the New Skill flow. There is ONE user-facing
 // concept — a skill — so the picker never exposes the internal `run`/`kind`; how a skill runs (server
 // derives it instantly, or a claude PTY session reasons through it) is decided by the file, not the PM.
 const BUILTIN_SKILLS_DIR = path.join(__dirname, 'skills');
-const USER_SKILLS_DIR = path.join(STATE, 'skills');
+function userSkillsDir() { return skillsStore().path; }
+// The two paths a scheduled agent run must file into, spelled ABSOLUTELY. They used to be written
+// into the scaffold as `workspace/state/…`, which stopped being true the moment runtime state moved
+// out of the application directory (lib/state-root.js) — and a scaffold naming a directory the
+// console never reads is a report that silently never arrives. Derived from the same constants the
+// reader uses, so the two can only agree.
+//
+// `legacy` names where the runtime state USED to live — this application directory's own `state/`.
+// The retarget needs it because the PM's nine idpf-* skills spell the old location ABSOLUTELY
+// (`/Users/…/pmos/workspace/state/deliverables/<run-id>.md`), so there is no leading quote or space
+// to anchor a match on; the only question that can be answered reliably is "is this path's parent
+// the old state root", and only the caller knows where that was. Derived from __dirname, never
+// configured, so it cannot drift from the directory the migration moved out of.
+function filingContract(w) {
+  return { deliverables: DELIV_DIR, needs: needsFileFor(w) || path.join(STATE, 'needs.json'),
+    legacy: LEGACY_STATE };
+}
 // Read the skill files fresh each call so a just-created user skill appears with no restart. User dirs
 // load FIRST and built-ins LAST, so a built-in's load-bearing deterministic fast-path can't be shadowed.
 function loadTasks() {
   return skillStore.loadSkills([
-    { dir: USER_SKILLS_DIR, source: 'user' },
+    { dir: userSkillsDir(), source: 'user' },
     { dir: BUILTIN_SKILLS_DIR, source: 'builtin' },
   ]).map(toTask);
 }
@@ -1382,10 +1506,10 @@ function toTask(s) {
 }
 function taskById(id) { return loadTasks().find((t) => t.id === id || t.skill === id) || null; }
 function readSchedules() {
-  try { const a = JSON.parse(fs.readFileSync(SCHED_FILE, 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
+  try { const a = JSON.parse(fs.readFileSync(schedFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
 }
 function writeSchedules(list) {
-  try { fs.writeFileSync(SCHED_FILE, JSON.stringify(list)); }
+  try { fs.writeFileSync(schedFile(), JSON.stringify(list)); }
   catch (e) { warnWriteFail('schedules.json (scheduled tasks)', e); }
 }
 
@@ -1407,11 +1531,20 @@ function fireSchedule(sched) {
   // AGENT task — fire as a real PTY session running its skill (async; the skill files its own
   // deliverable). The workspace starts it + stamps 'started'; run-now and the tick share this path.
   if (task && task.kind === 'agent') {
+    // THE FILING CONTRACT IS RETARGETED HERE, on the prompt, at the moment it is handed to the
+    // session (lib/skill-store.js#retargetFiling). The PM's eleven existing skills were authored
+    // when runtime state lived at `workspace/state/`, so their bodies still say "write the report
+    // to workspace/state/deliverables/". After the relocation that is a directory the console
+    // never reads: the agent would succeed, report success, and the report would never arrive.
+    // Fixing only the SCAFFOLD fixes only skills that do not exist yet, which is no help to the
+    // eleven that do. `needs.json` is resolved per workspace, so this cannot be a one-off rewrite
+    // of the files either — the right answer for a given fire depends on which repo it fires in.
+    const prompt = task.prompt ? skillStore.retargetFiling(task.prompt, filingContract(w)) : null;
     // The schedule's recorded profile travels with the process it creates (profiles R8.3). Only an
     // AGENT-kind task has a PTY, which is why `profile_applies` is false for the skill-kind rows
     // below rather than the control simply being hidden.
     const s = spawnSession({ name: sched.name, agent: task.agent || 'claude', ws: sched.ws,
-      origin: 'schedule:' + sched.id, initialInput: task.prompt ? task.prompt + '\r' : null,
+      origin: 'schedule:' + sched.id, initialInput: prompt ? prompt + '\r' : null,
       profile: sched.profile == null ? null : sched.profile });
     const list = readSchedules(); const cur = list.find((x) => x.id === sched.id);
     const started = s.state !== 'exited';
@@ -2247,6 +2380,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
       s.buf = `\x1b[38;5;203m✗ ${why}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`;
       persist(s); pushSessions(); pushWorkspaces(); return s;
     }
+    announceStateHealth(s);   // the unmigrated notice comes FIRST — it explains an empty skills list
     announceTree(s);   // before attach, so the advisory is the first line of the pane's record
     attachPty(s);
     feed(s);
@@ -2266,6 +2400,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
     pty: p, tmux: null, note: '', buf: '', cols: 80, rows: 24, clients: new Set(), created: nowISO(),
     lastOutputAt: Date.now() };
   sessions.set(id, s);
+  announceStateHealth(s);
   announceTree(s);   // registered first: a session's co-tenancy question includes itself in the map
   p.onData((d) => {
     appendBuf(s, d);
@@ -2607,7 +2742,11 @@ function stateDirFor(w, { create = false } = {}) {
     const d = path.join(w.root, ...rel);
     if (isDir(d)) return d;
   }
-  if (EMBEDDED_SELF && w.root === SELF_ROOT) return STATE;   // pmos-self: the server's own state/ IS its file-mode mirror (never a tenant home — that writes to its OWN repo below)
+  // pmos-self with no pmos/state/ yet: the checkout's OWN state/ is the file-mode mirror. This is
+  // deliberately LEGACY_STATE and not STATE — D64's system of record belongs to the repository that
+  // earned it, so it must not follow the runtime state out to the per-user directory. (Never a
+  // tenant home — that writes to its OWN repo below.)
+  if (EMBEDDED_SELF && w.root === SELF_ROOT) return LEGACY_STATE;
   // A PMOS-shaped repo with no state dir yet gets the kit's own layout on first write. Never
   // invented for a plain repo — there we fall back and SAY SO rather than write somewhere wrong.
   if (create && wsShape(w.root) === 'pmos') {
@@ -3408,7 +3547,9 @@ async function handleRequest(req, res) {
     return json(res, { ok: true, tree, writer: s.id, previous: prev || null, advisory: true,
       note: 'a declaration, not a guarantee — nothing about either process changed' });
   }
-  if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
+  // `state_health` rides on the payload EVERY client reads at boot, so the unmigrated notice reaches
+  // the PM whichever lens they open first — not only the two lists it is about.
+  if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList(), state_health: stateHealthNow() });
   if (p === '/api/workspaces' && req.method === 'POST') {
     // How `pmos` in another repo becomes another workspace (R1). Local-only, like every
     // route here — the server binds 127.0.0.1 and this only records a path.
@@ -3684,16 +3825,21 @@ async function handleRequest(req, res) {
   if (p === '/api/skills' && req.method === 'GET') {
     const skills = loadTasks().map((t) => ({ id: t.id, label: t.label, skill: t.skill,
       description: t.description || '', output: t.output || [], source: t.source || 'builtin' }));
-    return json(res, { skills });
+    // NEVER a bare list. Under an unmigrated conflict this list is either short by every skill the
+    // PM authored or is being read from the old directory, and in both cases the payload has to say
+    // so — a calm list is a claim that the state is settled (see stateHealthNow).
+    return json(res, { skills, state_health: stateHealthNow() });
   }
   // POST scaffolds a well-formed .skill file from name + "what it should do" + the output shape.
   // A GUI replaces editing server code; user skills default to running as a claude PTY session.
   if (p === '/api/skills' && req.method === 'POST') {
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
-    const built = skillStore.scaffoldSkill(body);
+    // `filing` is built HERE, never taken from the request body: it names filesystem paths, and a
+    // caller-supplied one would be a write instruction dressed up as a preference.
+    const built = skillStore.scaffoldSkill({ ...body, filing: filingContract(getWs(body.ws)) });
     if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
     if (loadTasks().some((t) => t.id === built.slug)) return json(res, { ok: false, error: `a skill named "${built.slug}" already exists` }, 409);
-    try { fs.mkdirSync(USER_SKILLS_DIR, { recursive: true }); fs.writeFileSync(path.join(USER_SKILLS_DIR, built.slug + '.skill'), built.content); }
+    try { const d = userSkillsDir(); fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, built.slug + '.skill'), built.content); }
     catch (e) { return json(res, { ok: false, error: 'could not write the skill file' }, 500); }
     return json(res, { ok: true, skill: { id: built.slug, label: built.label, skill: built.slug,
       description: built.description, output: built.output, source: 'user' } });
@@ -3703,13 +3849,15 @@ async function handleRequest(req, res) {
   // Always leaves a valid file even where claude is absent; the session is honest about not starting.
   if (p === '/api/skills/draft' && req.method === 'POST') {
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
-    const built = skillStore.scaffoldSkill(body);
+    const w0 = getWs(body.ws);
+    const filing = filingContract(w0);
+    const built = skillStore.scaffoldSkill({ ...body, filing });
     if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
     if (loadTasks().some((t) => t.id === built.slug)) return json(res, { ok: false, error: `a skill named "${built.slug}" already exists` }, 409);
-    try { fs.mkdirSync(USER_SKILLS_DIR, { recursive: true }); fs.writeFileSync(path.join(USER_SKILLS_DIR, built.slug + '.skill'), built.content); }
+    try { const d = userSkillsDir(); fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, built.slug + '.skill'), built.content); }
     catch { return json(res, { ok: false, error: 'could not write the skill file' }, 500); }
-    const w = getWs(body.ws);
-    const rel = path.relative(w ? w.root : SELF_ROOT, path.join(USER_SKILLS_DIR, built.slug + '.skill'));
+    const w = w0;
+    const rel = path.relative(w ? w.root : SELF_ROOT, path.join(userSkillsDir(), built.slug + '.skill'));
     const prompt = `Refine the PMOS workspace skill file at ${rel}. It was scaffolded from this ask: ` +
       `"${built.description || built.label}". First read skills/core/SKILL-FORMAT.md (the skill spec) and ` +
       `follow build-skills/skill-creator.skill (the authoring procedure). Keep the runtime frontmatter shape ` +
@@ -3717,7 +3865,7 @@ async function handleRequest(req, res) {
       `ALWAYS produce). Sharpen the BODY into a procedure-first, repeatable procedure grounded in THIS repository's ` +
       `own files and tools only (no network): a Goal line, then numbered steps each ending on a checkable "Done when:" ` +
       `condition. Keep the FILING CONTRACT the scaffold wrote — the run must write its deliverable to ` +
-      `workspace/state/deliverables/<run-id>.md and append the structured object to workspace/state/needs.json ` +
+      `${filing.deliverables}/<run-id>.md and append the structured object to ${filing.needs} ` +
       `(a valid JSON array), never a prose note. Then run the SKILL-FORMAT conformance checklist (items 6-9: ` +
       `predictability, per-step completion criteria, pruning, leading words) over the body — put no self-check block ` +
       `in the file itself. Then stop.`;
@@ -3787,7 +3935,9 @@ async function handleRequest(req, res) {
         profile: s.profile == null ? null : s.profile,
         profile_applies: !!(t && t.kind === 'agent') };
     });
-    return json(res, { schedules: list, now: nowISO() });
+    // Same rule as /api/skills: an empty (or fallen-back) schedule list under a conflict must never
+    // read as "you have no scheduled tasks". A schedule that never loads never fires.
+    return json(res, { schedules: list, now: nowISO(), state_health: stateHealthNow() });
   }
   if (p === '/api/schedules' && req.method === 'POST') {
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
@@ -3988,7 +4138,7 @@ async function handleRequest(req, res) {
     // Stripped by spreading rather than deleting — some surfaces return frozen objects.
     const code = (out && Number.isFinite(out.http_status)) ? out.http_status : 200;
     if (out && out.http_status != null) { out = { ...out }; delete out.http_status; }
-    return json(res, { name, ...out }, code);
+    return json(res, { name, ...out, state_health: stateHealthNow() }, code);
   }
   // ── ONE initiative, assembled (the four-panel surface). ────────────────────────────────────
   // Panel 3 needs the record, its artifacts, its ladder, its external references, its anchor and
@@ -4192,12 +4342,16 @@ async function handleRequest(req, res) {
     // response so the client can be honest about where the decision landed.
     let sink = acceptancesFileFor(w, { create: true });
     const fallback = !sink;
-    if (fallback) sink = path.join(STATE, 'acceptances.jsonl');
+    // LEGACY_STATE, not STATE: an acceptance is a D64 record, and the last-resort sink for a repo
+    // whose state directory could not be resolved stays with the install rather than following the
+    // runtime state out to the per-user directory, where nobody would think to look for a record.
+    if (fallback) sink = path.join(LEGACY_STATE, 'acceptances.jsonl');
     // FAIL LOUD (D64 Track A2): under D64 the file-mode acceptances log is the SYSTEM OF RECORD.
     // A swallowed append + {ok:true} would light the gate green over a record that never landed —
     // exactly the false-green class D64 exists to delete. On write failure return HTTP 500 and
     // {ok:false}, and do NOT report success. The error text carries no header/secret content (D08).
     try {
+      if (fallback) fs.mkdirSync(LEGACY_STATE, { recursive: true });   // the install's state/ may not exist yet
       fs.appendFileSync(sink, JSON.stringify(rec) + '\n');
     } catch (e) {
       warnWriteFail('acceptances.jsonl (Acceptance Gate — system of record)', e);

package/workspace/test-run.js

@@ -0,0 +1,84 @@
+'use strict';
+/* test-run.js — THE ISOLATION A SUITE GETS BY CALLING ONE FUNCTION.
+ *
+ * Every suite in this workspace boots real servers, opens real PTYs and writes real state. The
+ * PM's live runtime state used to live at `workspace/state/`, INSIDE the directory the suites run
+ * from, so it was reachable BY CONSTRUCTION — by any verb, by any subprocess, by any stray shell
+ * command in the tree. `test.js#resetState()` removed sessions/, scratchpad/, workspaces.json,
+ * schedules.json, deliverables/ and skills/ from it five times a run, and the suite was safe in CI
+ * only because a fresh checkout has nothing there.
+ *
+ * The state has moved out (lib/state-root.js). What remains is to make sure a suite never resolves
+ * to the NEW per-user location either — an installed copy's state IS the PM's own, so "the app's
+ * own directory" was never the isolation boundary anybody thought it was. `configure()` points
+ * PMOS_STATE_DIR at a fresh scratch directory before `server.js` is ever required and before any
+ * child is spawned, so a run writes only into a directory it made.
+ *
+ * It also hands out a PRIVATE TMUX SOCKET (never the PM's own, `pmos`) and an EPHEMERAL PORT
+ * claimed from the kernel rather than a bet on 7599/7601-7606. The port is about collisions, not
+ * about state, and it is worth being exact about what it buys: it makes a collision RARE. It does
+ * not DETECT one — a suite that does collide still drives whatever answers, and proving whose
+ * server is on a port is a different defect with its own repair. Nothing here claims otherwise.
+ *
+ * It lives at the workspace root rather than under lib/ on purpose: lib/ is the SHIPPED server
+ * process, and no-network.test.js holds every file there to a standard this scaffolding does not
+ * need to meet. It belongs beside the suites.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const HOST = '127.0.0.1';
+
+let state = null;   // set by configure(); this module is a no-op until then
+
+/** Bind :0, read the port back, release it. Synchronous because callers need PORT as a const. */
+function claimEphemeralPort() {
+  const src = "const s=require('net').createServer();s.listen(0,'127.0.0.1',()=>{process.stdout.write(String(s.address().port));s.close()});";
+  const out = execFileSync(process.execPath, ['-e', src], { encoding: 'utf8' });
+  const n = Number(String(out).trim());
+  if (!Number.isInteger(n) || n <= 0) throw new Error('could not claim an ephemeral port');
+  return n;
+}
+
+/**
+ * Arm a suite. MUST be called before `require('./server')` and before any child is spawned —
+ * server.js resolves its state root at require time, and a child inherits the environment as it
+ * stood when it was spawned.
+ *
+ * Returns, and also exposes on the module: PORT, HOST, BASE, STATE_DIR.
+ */
+function configure({ name = 'run', port = null } = {}) {
+  if (state) return state;
+  const stateDir = process.env.PMOS_STATE_DIR
+    ? path.resolve(process.env.PMOS_STATE_DIR)
+    : fs.mkdtempSync(path.join(os.tmpdir(), `pmos-state-${name}-`));
+  fs.mkdirSync(stateDir, { recursive: true });
+  // In the environment BEFORE server.js is required here and before any child inherits it. Every
+  // boot site in every suite goes through process.env, so this is a chokepoint by construction
+  // rather than a convention each call site has to remember — and a convention that must be
+  // remembered at hundreds of call sites is a convention that will be forgotten at one of them,
+  // which is exactly how this class of defect got in.
+  process.env.PMOS_STATE_DIR = stateDir;
+  // A private tmux socket, never the PM's own ('pmos'), so a suite cannot reach their sessions.
+  process.env.PMOS_TMUX_SOCK = process.env.PMOS_TMUX_SOCK || `pmos-${name}-${process.pid}`;
+
+  const chosen = Number(port) > 0 ? Number(port) : claimEphemeralPort();
+
+  state = {
+    PORT: chosen, HOST, BASE: `http://${HOST}:${chosen}`, STATE_DIR: stateDir,
+    /** Environment for a spawned server/launcher: this run's state dir and tmux socket. */
+    env(extra = {}) {
+      return { ...process.env, PMOS_STATE_DIR: stateDir, ...extra };
+    },
+    /** A port nobody else holds, for a suite that needs a second server. */
+    port: claimEphemeralPort,
+    /** Remove the scratch state directory. Safe by construction: this run made it. */
+    cleanup() { try { fs.rmSync(stateDir, { recursive: true, force: true }); } catch {} },
+  };
+  Object.assign(module.exports, state);
+  return state;
+}
+
+module.exports = { configure, claimEphemeralPort, HOST };