create-pmos 0.134.0 → 0.135.0

package/workspace/lib/vendor/workspace/lib/state-root.js

@@ -1,587 +0,0 @@
-'use strict';
-/* lib/state-root.js — WHERE THE PM'S RUNTIME STATE LIVES.
- *
- * ── The defect this deletes ────────────────────────────────────────────────────────────────────
- *
- * The workspace used to keep the PM's live runtime state at `workspace/state/`, INSIDE the
- * application directory — the same directory the test suite runs from. Sixteen live tmux sessions,
- * the workspace registry, eleven authored skills and a 15KB schedules.json sat one `rm -rf` away
- * from every suite, every spawned child, and every stray shell command in the tree.
- *
- * Three rounds of guarding destructive verbs failed. Round 3 patched rmSync/rmdirSync/unlinkSync/
- * renameSync; a verifier then destroyed a planted replica nine other ways — writeFileSync,
- * truncateSync, openSync(…,'w'), copyFileSync, cpSync, createWriteStream, execSync('rm -rf'),
- * `find -delete`, and renameSync's unchecked DESTINATION — with the isolation suite green each
- * time. The enumeration of destructive verbs is unbounded, and a shell subprocess defeats any
- * in-process fs patch by construction.
- *
- * So the fix is not another guard. The PM's state MOVES OUT of the application directory. A
- * checkout's `workspace/state/` then holds nothing of the PM's; a test may delete all of it and
- * lose nothing. Unreachable beats guarded: there is no verb that reaches a file that is not there.
- *
- * ── What this is, and what it is NOT ───────────────────────────────────────────────────────────
- *
- * THIS IS LOCAL-ONLY, GITIGNORED RUNTIME STATE: sessions/, workspaces.json, layouts/, scratchpad/,
- * schedules.json, deliverables/, the PM's authored skills/, prefs.json, the per-port pid/log files
- * and tmux.conf. Machine-written, churny, per-machine, never committed.
- *
- * THIS IS NOT D64'S FILE-MODE SYSTEM OF RECORD. `pmos/state/*.jsonl` + `planning/` are canonical
- * records that live IN the repository that earned them, and `server.js#stateDirFor()` resolves
- * those per-workspace, from the workspace's own root. Nothing here touches that path — see the
- * SELF_FILE_MODE_STATE constant in server.js, which deliberately still points inside the checkout.
- *
- * ── Where it goes ──────────────────────────────────────────────────────────────────────────────
- *
- *   PMOS_STATE_DIR             an explicit override; wins over everything. Every test run sets it.
- *   darwin                     ~/Library/Application Support/pmos
- *   elsewhere                  $XDG_STATE_HOME/pmos, else ~/.local/state/pmos
- *
- * ── The migration ──────────────────────────────────────────────────────────────────────────────
- *
- * On first run the existing in-repo state is MOVED, not copied and not merged. Losing the PM's
- * sixteen sessions would be a worse outcome than the bug this fixes, so the rules are strict:
- *
- *   - it runs ONLY for the platform default location. An explicit PMOS_STATE_DIR — which is what
- *     a test sets — never migrates anything, because that would be a test moving the PM's live
- *     state into a scratch directory: the very accident this file exists to make impossible.
- *   - two populated directories are NEVER merged. If the destination already holds state, the
- *     legacy directory is left exactly as it is and the caller is told, so a human decides.
- *   - it is idempotent. After a move the legacy directory is recreated holding only a note, which
- *     does not count as populated, so a second run is a no-op. Proven by a test that runs it twice.
- */
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const APP = 'pmos';
-const NOTE_NAME = 'MOVED.txt';
-
-/* ── THE ONLY TWO OUTCOMES THAT MEAN "SETTLED" ─────────────────────────────────────────────────
- *
- * This set is an ALLOW-list, and that direction is the whole point. `stateHealth` used to open
- * `if (m.action !== 'conflict') return { ok: true }` — a DENY-list of one, which quietly declared
- * every other outcome healthy. `migrateLegacy` already had a second failure outcome ('failed', the
- * filesystem refusing the move), so a run whose move was refused reported `{ok:true}` on every
- * surface, fell back nowhere, and showed the PM zero skills and zero schedules with nothing said —
- * the same silent no-show as the conflict, with even the stderr line removed.
- *
- * So the question is inverted: an outcome is healthy only if it is NAMED here. A third failure mode
- * added tomorrow is non-ok by default and says something, rather than being silently healthy until
- * somebody notices the empty list. Adding an outcome to this set is the deliberate act; forgetting
- * to is the safe one. */
-const SETTLED_ACTIONS = new Set([
-  'none',    // nothing to move: no legacy path, an explicit PMOS_STATE_DIR, or a legacy dir holding no state
-  'moved',   // the contents are now at the per-user root and a note was left behind
-]);
-
-/* ── AND THE SAME DEFECT ONE FUNCTION UP: AN ERROR CONVERTED INTO A TRUSTED VALUE ──────────────
- *
- * Inverting the check at `stateHealth` classifies the OUTCOME correctly. It cannot help when the
- * outcome itself was manufactured out of a swallowed error, which is what the first version of
- * `isPopulated` did:
- *
- *     let names = [];
- *     try { names = fs.readdirSync(dir); } catch { return false; }   // ← the swallow
- *
- * A directory that could not be READ — a permission, an I/O error, a dangling network mount, a file
- * sitting where the directory should be — came back as `false`, indistinguishable from a directory
- * that is genuinely empty. `migrateLegacy` then reached a SETTLED outcome ('none'), `stateHealth`
- * said `{ok:true}`, and every measured symptom of the original bug returned verbatim: zero skills,
- * zero schedules, forty-five schedules that stop firing, and nothing anywhere saying why. An
- * allow-list downstream is powerless against it, because by then the error is a legitimate answer.
- *
- * So the rule this file now holds: AN UNREADABLE DIRECTORY IS NOT AN EMPTY ONE. Reading a directory
- * has THREE answers, not two, and "could not tell" travels all the way to the PM with its errno and
- * its path — the same treatment 'failed' gets. There is no boolean in this module any more that a
- * caller could mistake for an answer; `readState` is the only reader and it is total. */
-
-/** Why a directory could not be LISTED — a different act from refusing a move, so a different table:
- * "cannot write the destination" is the wrong sentence for a directory nobody can open. */
-const WHY_UNREADABLE = {
-  EACCES: 'permission denied — this user cannot list that directory (check its mode and its parents)',
-  EPERM: 'the operation was not permitted — check ownership, a locked/immutable flag, or macOS privacy protection on that directory',
-  ENOTDIR: 'a component of the path is a FILE where a directory was expected',
-  ELOOP: 'a symlink loop in the path',
-  ENAMETOOLONG: 'the path is too long for this filesystem',
-  EIO: 'a low-level I/O error — the volume may be failing or a mount may have gone away',
-  ESTALE: 'a STALE file handle — the network mount this directory is on has been replaced or unmounted',
-  ENODEV: 'no such device — the volume this directory is on is not attached',
-  ENXIO: 'no such device or address — the volume this directory is on is not responding',
-  ETIMEDOUT: 'the filesystem TIMED OUT — a network mount is unreachable',
-  EHOSTDOWN: 'the host serving this network mount is down',
-  EHOSTUNREACH: 'the host serving this network mount is unreachable',
-  ECONNABORTED: 'the connection to this network mount was aborted',
-  EMFILE: 'this process has too many open files',
-  ENFILE: 'the system has too many open files',
-  EBUSY: 'the directory is busy — another process has it locked',
-};
-/** A sentence for an errno, never an empty string. Same contract as `whyRefused`. */
-function whyUnreadable(code) {
-  if (code && Object.prototype.hasOwnProperty.call(WHY_UNREADABLE, code)) return WHY_UNREADABLE[code];
-  return code
-    ? `the filesystem returned ${code} when this directory was listed, which this build has no plain-language translation for`
-    : 'the filesystem refused to list this directory without an error code';
-}
-
-/* Why the filesystem refused a move, in words the PM can act on. Unlike a conflict — which the PM
- * can resolve just by being told the two directories — a refusal cannot be resolved without knowing
- * the CAUSE: a permission is fixed differently from a full disk, which is fixed differently from a
- * read-only volume. An errno alone ("EACCES") is a code the PM has to go look up, so the code is
- * kept AND translated. An unrecognised code still gets a sentence rather than silence. */
-const WHY_REFUSED = {
-  EACCES: 'permission denied — this user cannot write the destination or one of its parent directories',
-  EPERM: 'the operation was not permitted — check ownership, a locked/immutable flag, or macOS privacy protection on the destination',
-  EROFS: 'the destination is on a READ-ONLY filesystem',
-  ENOSPC: 'the disk is FULL — no space left on the destination volume',
-  EDQUOT: 'this user\'s disk QUOTA on the destination volume is exhausted',
-  EXDEV: 'the two directories are on DIFFERENT filesystems and the cross-device copy also failed',
-  ENOENT: 'a path was not there — the destination directory could not be created, or a source entry vanished mid-move',
-  ENOTDIR: 'a component of one of the paths is a FILE where a directory was expected',
-  EISDIR: 'a directory was found where a file was expected',
-  ENOTEMPTY: 'a destination entry already exists and is not empty',
-  EEXIST: 'a destination entry already exists',
-  EBUSY: 'a file is IN USE by another process and could not be moved',
-  ELOOP: 'a symlink loop in one of the paths',
-  ENAMETOOLONG: 'a path is too long for this filesystem',
-  EMFILE: 'this process has too many open files',
-  ENFILE: 'the system has too many open files',
-  EIO: 'a low-level I/O error on the disk — the volume may be failing or disconnected',
-};
-/** A sentence for an errno, never an empty string: an unknown code still has to say something. */
-function whyRefused(code) {
-  if (code && Object.prototype.hasOwnProperty.call(WHY_REFUSED, code)) return WHY_REFUSED[code];
-  return code
-    ? `the filesystem returned ${code}, which this build has no plain-language translation for`
-    : 'the filesystem refused the move without an error code';
-}
-
-/**
- * Did the migration leave the state root SETTLED? `true` only for an outcome named in
- * SETTLED_ACTIONS. A null/absent migration record means no migration was attempted (a caller that
- * passed none), which is settled; a record that HAS an action this build does not recognise is not.
- */
-function isSettled(migration) {
-  if (migration == null) return true;
-  const a = migration.action;
-  return typeof a === 'string' && SETTLED_ACTIONS.has(a);
-}
-
-// Entries that do not make a directory "populated": the checked-in .gitignore that documents the
-// layout, the note this migration leaves behind, and Finder's litter. Anything else is the PM's.
-const NOT_STATE = new Set(['.gitignore', NOTE_NAME, '.DS_Store']);
-// …and the same set is what the migration LEAVES BEHIND. `.gitignore` is a TRACKED file in this
-// repository — it documents the directory's layout — so moving it out deletes a tracked file from
-// the checkout and shows up as a spurious deletion in `git status`. It is not state; it does not
-// travel. (Found the hard way: the first migration in this worktree carried it off.)
-const NEVER_MOVE = NOT_STATE;
-
-/** An explicit override, resolved to an absolute path — or null when unset/blank. */
-function overrideDir(env = process.env) {
-  const v = env && env.PMOS_STATE_DIR;
-  const s = v == null ? '' : String(v).trim();
-  return s ? path.resolve(s) : null;
-}
-
-/**
- * The per-user runtime state directory for this machine. Pure: every input is injected, so the
- * platform branches are assertable without pretending to be another OS.
- */
-function defaultRoot({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
-  const forced = overrideDir(env);
-  if (forced) return forced;
-  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', APP);
-  const xdg = env && env.XDG_STATE_HOME;
-  if (xdg && path.isAbsolute(String(xdg))) return path.join(String(xdg), APP);
-  return path.join(home, '.local', 'state', APP);
-}
-
-/**
- * THE ONLY DIRECTORY READ IN THIS MODULE, and it is total: it answers with a fact about what it
- * managed to find out, never with a boolean that hides which of two very different things happened.
- *
- *   { known: true,  populated: true,  names: [...] }   it holds something of the PM's
- *   { known: true,  populated: false, names: [...] }   it is there and holds no state…
- *   { known: true,  populated: false, absent: true }   …or it is not there at all, which is the same
- *                                                      fact for our purposes and the ordinary case
- *   { known: false, code, syscall, at, message }       WE COULD NOT TELL — and nobody downstream may
- *                                                      pretend that is the same as "empty"
- *
- * ENOENT is the one error that IS an answer: a directory that does not exist holds nothing, and that
- * is every first run on every machine. Everything else — EACCES, EIO, ENOTDIR, ESTALE, a timed-out
- * network mount — is a question this process cannot answer, and it is carried, not swallowed.
- *
- * There is deliberately NO `isPopulated(dir) -> boolean` any more. It existed, it swallowed, and the
- * swallow put back every symptom of the bug this whole module was written to end. If you are about
- * to re-add one for convenience, that is the regression.
- */
-function readState(dir) {
-  if (!dir) return { known: true, populated: false, absent: true, names: [] };
-  let names;
-  try { names = fs.readdirSync(dir); }
-  catch (e) {
-    if (e && e.code === 'ENOENT') return { known: true, populated: false, absent: true, names: [] };
-    return {
-      known: false, populated: null, names: null,
-      code: (e && e.code) || null,
-      syscall: (e && e.syscall) || 'readdir',
-      at: (e && e.path) || dir,
-      message: (e && e.message) || String(e),
-    };
-  }
-  return { known: true, populated: names.some((n) => !NOT_STATE.has(n)), names };
-}
-
-/**
- * Does a path exist? THREE answers, for the same reason `readState` has three: `fs.existsSync`
- * returns `false` both for "not there" and for "this process could not find out", and a caller that
- * treats the second as the first is the swallow again, wearing a different function's name.
- *   'yes' | 'no' | 'unknown'
- */
-function presence(p) {
-  if (!p) return 'no';
-  try { fs.statSync(p); return 'yes'; }
-  catch (e) { return e && e.code === 'ENOENT' ? 'no' : 'unknown'; }
-}
-
-function noteText(target, at) {
-  return [
-    'This directory is no longer where the PMOS workspace keeps runtime state.',
-    '',
-    `Everything that was here was MOVED on ${at} to:`,
-    `  ${target}`,
-    '',
-    'It moved because this directory sits 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. Set PMOS_STATE_DIR to override the location.',
-    '',
-  ].join('\n');
-}
-
-/**
- * Move an in-repo `workspace/state/` to the per-user location, once.
- *
- * Returns `{ action, from, to, reason }` and never throws for an expected condition:
- *   'none'        nothing to move (legacy absent or holding no state)
- *   'conflict'    BOTH directories hold state — nothing touched, a human decides
- *   'moved'       the legacy directory's contents are now at `to`
- *   'failed'      the move was attempted and the filesystem refused; nothing was deleted
- *   'unreadable'  one of the two directories could not be LISTED, so whether it holds state is
- *                 unknown. Nothing was attempted. This is the outcome that used to be reported as
- *                 'none' — a settled, healthy, entirely fictitious "there was nothing to move".
- */
-function migrateLegacy({ legacy, target, now = new Date() } = {}) {
-  const from = legacy ? path.resolve(legacy) : null;
-  const to = target ? path.resolve(target) : null;
-  if (!from || !to || from === to) return { action: 'none', from, to, reason: 'same-or-missing-path' };
-  const unreadable = (r, which) => ({
-    action: 'unreadable', from, to,
-    reason: r.code || 'unreadable',
-    which,                                    // 'legacy' | 'target' — which of the two we are blind to
-    code: r.code || null,
-    syscall: r.syscall || 'readdir',
-    at: r.at || null,
-    message: r.message || null,
-  });
-  const src = readState(from);
-  if (!src.known) return unreadable(src, 'legacy');
-  if (!src.populated) return { action: 'none', from, to, reason: 'legacy-holds-no-state' };
-  const dst = readState(to);
-  if (!dst.known) return unreadable(dst, 'target');
-  if (dst.populated) return { action: 'conflict', from, to, reason: 'both-populated' };
-
-  try {
-    fs.mkdirSync(path.dirname(to), { recursive: true });
-    // Entry-by-entry, so an EMPTY destination that already exists (a bare mkdir, a .gitignore) is
-    // filled rather than refused, and so a cross-device legacy directory still moves.
-    fs.mkdirSync(to, { recursive: true });
-    // `src.names` — the listing `readState` already took, and the only one it will ever have taken
-    // successfully, so a re-read that failed here could not be mistaken for an empty directory.
-    for (const name of src.names) {
-      if (NEVER_MOVE.has(name)) continue;
-      const src = path.join(from, name);
-      const dst = path.join(to, name);
-      if (fs.existsSync(dst)) continue;              // the .gitignore case; never overwrite
-      try { fs.renameSync(src, dst); }
-      catch (e) {
-        if (e && e.code === 'EXDEV') { fs.cpSync(src, dst, { recursive: true }); fs.rmSync(src, { recursive: true, force: true }); }
-        else throw e;
-      }
-    }
-    // Leave the legacy directory in place holding only the note: a checkout keeps its (now scratch)
-    // state/ directory, and the note explains the move to whoever looks there next. The note is in
-    // NOT_STATE, so this exact directory reads as unpopulated on the next run — the idempotence.
-    //
-    // AUDITED SWALLOW, KEPT — but it no longer converts an error into a value anyone trusts. The
-    // note is advisory: after the loop the legacy directory holds only NOT_STATE entries, so it
-    // reads as unpopulated on the next run whether or not the note landed, and 'moved' is the
-    // honest outcome either way. What was wrong was throwing the reason away, so the fact is
-    // CARRIED on the result instead of vanishing — a human who looks at a bare `state/` with no
-    // explanation in it can now find out why there is none.
-    let noteWritten = true, noteError = null;
-    try { fs.writeFileSync(path.join(from, NOTE_NAME), noteText(to, now.toISOString())); }
-    catch (e) { noteWritten = false; noteError = (e && e.code) || (e && e.message) || String(e); }
-    return { action: 'moved', from, to, reason: 'legacy-relocated', noteWritten, noteError };
-  } catch (e) {
-    // CARRY THE CAUSE, not just the fact. A refusal the PM cannot diagnose is a refusal they cannot
-    // fix, and this is the one non-ok outcome where being told the two directories is not enough.
-    return {
-      action: 'failed', from, to,
-      reason: (e && e.code) || 'move-failed',
-      code: (e && e.code) || null,
-      syscall: (e && e.syscall) || null,
-      at: (e && e.path) || null,               // the exact path the filesystem refused, when it named one
-      message: (e && e.message) || String(e),
-    };
-  }
-}
-
-/**
- * THE call site: resolve the runtime state root, migrating an in-repo legacy directory the first
- * time, and create it. `legacy` is `workspace/state/` — passed in rather than derived here so this
- * module never has an opinion about where the application happens to be installed.
- *
- * The migration is skipped whenever the location was chosen explicitly (PMOS_STATE_DIR), because a
- * chosen location is a scratch location and moving the PM's state into it is the accident, not the
- * fix.
- */
-function resolveStateRoot({ env = process.env, platform = process.platform, home = os.homedir(), legacy = null } = {}) {
-  const root = defaultRoot({ env, platform, home });
-  const chosen = !!overrideDir(env);
-  const migration = (!chosen && legacy)
-    ? migrateLegacy({ legacy, target: root })
-    : { action: 'none', from: legacy, to: root, reason: chosen ? 'explicit-state-dir' : 'no-legacy-path' };
-  /* THE THIRD SWALLOW IN THIS FILE, and the one with the best-sounding excuse. It used to read
-   *
-   *     try { fs.mkdirSync(root, { recursive: true }); } catch { }   // the caller's first write
-   *                                                                  // will report it
-   *
-   * — a promise about a caller. The callers are the stores, and what a store does when its
-   * directory is not there is return an empty list: no skills, no schedules, no registry, and a
-   * migration record still saying 'none' so `stateHealth` says {ok:true}. That is the identical
-   * silent no-show, entered through the one door that has nothing to do with the migration at all.
-   * The error is kept and reported. */
-  let rootError = null;
-  try { fs.mkdirSync(root, { recursive: true }); }
-  catch (e) {
-    rootError = {
-      code: (e && e.code) || null,
-      syscall: (e && e.syscall) || 'mkdir',
-      at: (e && e.path) || root,
-      message: (e && e.message) || String(e),
-    };
-  }
-  return { root, migration, chosen, rootError };
-}
-
-/* ── WHAT AN UNSETTLED STATE ROOT MUST NOT MEAN: "YOU HAVE NOTHING" ────────────────────────────
- *
- * This section was written for the CONFLICT outcome and then, for one round, applied only to it —
- * which is how the identical defect survived in the 'failed' outcome with even the stderr line
- * removed. Read every "conflict" below as "any outcome not in SETTLED_ACTIONS": both functions now
- * key off `isSettled`, so a refused move degrades exactly like a conflict, and so does whatever
- * outcome gets added next.
- *
- * `migrateLegacy` refuses to merge two populated directories, and that refusal is right — only a
- * human can decide which sixteen sessions are the real sixteen. What was wrong was what happened
- * NEXT. Every store resolved unconditionally against the per-user root with no fallback, so on a
- * machine where the per-user root existed and held (say) sessions/ and workspaces.json but NO
- * skills/ and NO schedules.json — which is exactly the state an earlier agent round left on the
- * PM's machine — the PM opened the workspace and saw ZERO skills and ZERO schedules. Their eleven
- * skills and forty-five schedules were on disk the whole time, one directory away.
- *
- * And a schedule that never loads never fires. That is the same silent no-show this whole
- * initiative exists to end, arriving through a different door: no error on any surface, a green
- * empty list, and forty-five scheduled runs that simply stop happening. The server did print a
- * conflict to stderr — but `pmos` detaches into a log nobody reads, so in practice it printed to
- * nobody.
- *
- * The two functions below are the answer, and the shape of the answer is a product decision:
- *
- *   1. resolveStore — a READ-AND-WRITE fallback, per store, ONLY where the per-user root has no
- *      copy at all. If the per-user root has its own `skills/`, there are two copies, the fallback
- *      does not happen and a human decides: a fallback that let the PM edit one copy while the
- *      other was authoritative would be a worse trap than the empty list. Where the per-user root
- *      has NOTHING, there is exactly one copy of that store on the machine, and reading and writing
- *      the single copy you found cannot fork anything. So the PM's skills load, their schedules
- *      load AND FIRE, and a fire can still stamp lastRun on the same file it read.
- *
- *      Under a 'failed' move the same argument holds with one extra wrinkle: the move may have got
- *      part-way. The rule handles it unchanged — a store that DID land in the per-user root is read
- *      from there, a store that did not is read from where it stayed, and neither is duplicated.
- *
- *   2. stateHealth — the fallback is never SILENT. It is a discriminated {ok:false} carried on
- *      every surface that lists these stores (see server.js: /api/skills, /api/schedules,
- *      /api/workspaces, /api/console) and written into the first line of every new terminal pane.
- *      It names BOTH directories and says which stores are being read from the old one, so the PM
- *      is told what to resolve rather than shown a calm list that happens to be right today.
- *
- * A TEST RUN NEVER REACHES ANY OF THIS. A test names PMOS_STATE_DIR, which makes the location
- * `chosen`, which means migrateLegacy is never called and `action` is never 'conflict'. So no
- * suite can fall back into the PM's `workspace/state/` — the hermeticity this file bought stands
- * exactly as it did.
- */
-
-/**
- * Where ONE named store lives, given a migration result.
- * Returns `{ path, fellBack }` — `fellBack` true only when this store is being read from the
- * legacy root because the per-user root holds no copy of it.
- */
-function resolveStore({ root, legacy, name, migration } = {}) {
-  const at = root && name ? path.join(root, name) : null;
-  /* THE FOURTH SWALLOW. This used to be two `try { fs.existsSync(x) } catch { }` pairs, and
-   * `existsSync` is itself a swallow with an API: it answers `false` for a path this process could
-   * not stat, so "I could not look" arrived as "it is not there". Read one way that silently
-   * DUPLICATES a store (the per-user copy is unreadable, so we fall back and the PM edits the copy
-   * nobody reads); read the other it silently HIDES one. `presence()` gives the third answer, and
-   * the rule for it is the conservative one in both directions: do not fall back on a guess. The
-   * root is already unsettled whenever this code runs, so the PM is already being told something is
-   * wrong — this only refuses to make it worse behind their back. */
-  // ANY unsettled outcome falls back, not just 'conflict'. When the filesystem REFUSES the move the
-  // PM's stores are still sitting in the legacy directory exactly as they were, and resolving them
-  // to a per-user root that does not hold them is the identical empty-list failure — it just has no
-  // stderr line to go with it. A partially-completed 'failed' move is handled by the same rule as
-  // everything else below: a copy in the per-user root wins, so an entry that DID move is read from
-  // where it landed and an entry that did not is read from where it stayed.
-  if (!at || !legacy || isSettled(migration)) return { path: at, fellBack: false, unreadable: false };
-  // A copy in the per-user root wins and no fallback happens: two copies is the ambiguous case, and
-  // silently preferring either one is how a PM ends up editing the copy nobody reads. An UNKNOWN
-  // per-user copy is treated as present for exactly that reason — a guess that forks the PM's state
-  // is the worse of the two mistakes.
-  const here = presence(at);
-  if (here === 'yes') return { path: at, fellBack: false, unreadable: false };
-  if (here === 'unknown') return { path: at, fellBack: false, unreadable: true };
-  const old = path.join(legacy, name);
-  const there = presence(old);
-  if (there === 'no') return { path: at, fellBack: false, unreadable: false };
-  if (there === 'unknown') return { path: at, fellBack: false, unreadable: true };
-  return { path: old, fellBack: true, unreadable: false };
-}
-
-/**
- * The one fact every surface repeats. `{ok:true}` ONLY for an outcome named in SETTLED_ACTIONS;
- * every other outcome is a discriminated failure naming BOTH directories and the stores still being
- * read from the old one. `fellBack` is a list of store names (e.g. ['skills', 'schedules.json']).
- *
- * The `kind` is the discriminant a surface may branch on:
- *   'unmigrated'   two populated directories — a human picks which is real
- *   'failed'       the filesystem refused the move; `code`/`why`/`at` say WHY, because unlike a
- *                  conflict this one cannot be resolved from the two directory names alone
- *   'unreadable'   one of the two directories could not be LISTED, so whether it holds state is
- *                  unknown. The kind that used to be reported as a healthy 'none'.
- *   'unusable-root' the state root could not be created at all — nowhere to read, nowhere to write
- *   'unknown'     an outcome this build does not recognise. It exists so that a future third
- *                 failure mode is LOUD by default. `{ok:true}` is never the fallthrough.
- *
- * Every kind carries the same keys, so a consumer that only reads `ok`/`error` — which is what
- * panel 1, the pane banner and all four API payloads do — needs no change when a kind is added.
- */
-function stateHealth({ migration, fellBack = [], rootError = null } = {}) {
-  // FIRST, because it outranks everything else: if the state root itself could not be created there
-  // is nowhere to read from and nowhere to write to, and every store will render an empty list
-  // whatever the migration says. This used to be a swallowed mkdir in resolveStateRoot.
-  if (rootError) {
-    const code = rootError.code || null;
-    const why = whyRefused(code);
-    return {
-      ok: false, kind: 'unusable-root',
-      reason: code || 'state-root-not-created',
-      legacy: (migration && migration.from) || null,
-      target: (migration && migration.to) || rootError.at || null,
-      reading_from_legacy: (fellBack || []).filter(Boolean),
-      code, why, at: rootError.at || null, detail: rootError.message || null,
-      error: 'the workspace runtime state directory COULD NOT BE CREATED, so nothing can be read or '
-        + `written and every list will render empty: ${why}`
-        + (code ? ` (${code}${rootError.syscall ? ' on ' + rootError.syscall : ''})` : '')
-        + (rootError.at ? ` at ${rootError.at}` : '') + '. '
-        + 'Fix the cause above, or set PMOS_STATE_DIR to a directory this user can create and write.',
-    };
-  }
-  if (migration == null) return { ok: true };       // no migration was attempted; there is nothing to report
-  const m = migration;
-  if (isSettled(m)) return { ok: true };
-
-  const action = typeof m.action === 'string' && m.action ? m.action : '(no action)';
-  const from = m.from || '(unknown)';
-  const to = m.to || '(unknown)';
-  const names = (fellBack || []).filter(Boolean);
-  // The same sentence in every kind: what is still working, and therefore what is NOT.
-  const stillRunning = names.length
-    ? `Until then ${names.join(' and ')} are being read from the OLD directory, so nothing `
-      + 'silently stops running. '
-    : 'Anything the per-user directory does not hold is unavailable until this is resolved. ';
-  const where = `In the checkout: ${from}. Per-user: ${to}. `;
-  const base = {
-    ok: false,
-    reason: m.reason || action,
-    legacy: m.from || null,
-    target: m.to || null,
-    reading_from_legacy: names.slice(),
-  };
-
-  if (m.action === 'conflict') {
-    return Object.assign(base, {
-      kind: 'unmigrated',
-      error: 'the workspace state is UNMIGRATED — two populated state directories, so nothing was '
-        + 'moved or merged and a human has to decide which is real. '
-        + stillRunning + where
-        + 'Keep one, remove the other, or set PMOS_STATE_DIR to the one you want.',
-    });
-  }
-
-  if (m.action === 'failed') {
-    const code = m.code || (m.reason && m.reason !== 'move-failed' ? m.reason : null);
-    const why = whyRefused(code);
-    return Object.assign(base, {
-      kind: 'failed',
-      code: code || null,
-      why,
-      at: m.at || null,
-      detail: m.message || null,
-      error: 'the workspace state COULD NOT BE MOVED out of the checkout — the filesystem refused '
-        + `the move: ${why}`
-        + (code ? ` (${code}${m.syscall ? ' on ' + m.syscall : ''})` : '')
-        + (m.at ? ` at ${m.at}` : '') + '. Nothing was deleted. '
-        + stillRunning + where
-        + 'Fix the cause above and restart the workspace, or set PMOS_STATE_DIR to a directory this '
-        + 'user can write.',
-    });
-  }
-
-  if (m.action === 'unreadable') {
-    const code = m.code || null;
-    const why = whyUnreadable(code);
-    const which = m.which === 'target' ? 'the PER-USER state directory' : 'the state directory in the checkout';
-    return Object.assign(base, {
-      kind: 'unreadable',
-      which: m.which || null,
-      code: code || null,
-      why,
-      at: m.at || null,
-      detail: m.message || null,
-      // The sentence has to say the thing the old code got WRONG, not just report an errno: this is
-      // NOT "you have nothing". Nobody knows yet whether there is anything, and that is the point.
-      error: `${which} COULD NOT BE READ, so whether it holds the workspace's state is UNKNOWN — `
-        + 'this is NOT the same as it being empty, and nothing was moved, merged or deleted: '
-        + why
-        + (code ? ` (${code}${m.syscall ? ' on ' + m.syscall : ''})` : '')
-        + (m.at ? ` at ${m.at}` : '') + '. '
-        + stillRunning + where
-        + 'Make that directory readable by this user and restart the workspace, or set '
-        + 'PMOS_STATE_DIR to a directory this user can read.',
-    });
-  }
-
-  // The default is to SAY SOMETHING. A migration outcome nobody has thought of yet reaches here.
-  return Object.assign(base, {
-    kind: 'unknown',
-    error: 'the workspace state root is NOT SETTLED — the migration reported '
-      + `\`${action}\`, an outcome this build does not recognise, so it is treated as unresolved. `
-      + stillRunning + where
-      + 'Report this, or set PMOS_STATE_DIR to the directory you want used.',
-  });
-}
-
-module.exports = { APP, NOTE_NAME, NOT_STATE, SETTLED_ACTIONS,
-  WHY_REFUSED, whyRefused, WHY_UNREADABLE, whyUnreadable, isSettled,
-  overrideDir, defaultRoot, readState, presence, migrateLegacy, resolveStateRoot, resolveStore,
-  stateHealth };