create-pmos 0.26.0 → 0.28.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
@@ -679,6 +782,153 @@ function looseDocs(root) {
   }
   return out;
 }
+/* ── SEARCH: the corpus `search everything…` is finally allowed to be ─────────────────────────
+ *
+ * The box shipped searching three DERIVED lists — initiative slugs, paths declared on an initiative
+ * record, and session names — so a file the board was never told about could not be found by typing
+ * its exact name. Worse, a miss rendered "nothing matches — a successful read of nothing", this
+ * repo's phrase for *we looked and there was nothing*, after a search that never opened the folder.
+ *
+ * Four rules hold this honest, and each one is asserted in the suite:
+ *
+ *  1. THE WALK IS THE FOLDER LENS'S WALK. Same `SKIP_DIRS`, same dotted-name exclusion, so search
+ *     and the lens can never disagree about what exists in this folder. A third answer to "what is
+ *     in here" would be worse than the missing feature.
+ *  2. NOTHING NEW IS REACHABLE. Every emitted path is `path.relative(root, …)` from a walk that
+ *     STARTS at the root and only descends through `e.isDirectory()`. `readdirSync(…,
+ *     {withFileTypes:true})` reports a symlink as `isSymbolicLink()` — neither a file nor a
+ *     directory — so a link pointing out of the workspace is never followed and never emitted.
+ *     There is no user-supplied path parameter here at all: the query is a needle, not a location.
+ *  3. IT IS BOUNDED, AND THE BOUND IS IN THE PAYLOAD. A capped list rendered as a complete one is
+ *     the same lie the box already told, with a longer walk behind it — so every cap reports
+ *     itself, and it must be FALSE when nothing was cut. The suite asserts both directions,
+ *     because a flag that is always true is not a flag.
+ *
+ *     TWO caps, TWO flags, deliberately not one. `truncated` means *files you searched for were
+ *     never looked at* (the walk budget, the depth, or the result limit). `content_truncated`
+ *     means *every file was named, but not every body was read* — which is the ordinary state of
+ *     any repository carrying a lock file, and collapsing it into `truncated` would light the
+ *     serious flag permanently and thereby retire it.
+ *  4. `kind` IS preview-kind's ANSWER, NOT A SECOND OPINION. The same classifier the read endpoints
+ *     and the tree flag already use decides whether the reader can show a hit, so search can say
+ *     "found, but not openable" instead of handing the PM a tab that prints a failure.
+ */
+const SEARCH_MAX_FILES = 20000;          // walk budget — a giant repo (or a Drive mount) never hangs the box
+const SEARCH_MAX_DEPTH = 12;             // deeper than the lens's 6: search renders no tree, so depth is cheap
+const SEARCH_CONTENT_FILES = 4000;       // how many readable files get their BODIES scanned
+const SEARCH_CONTENT_BYTES = 256 * 1024; // per file; a bigger one is path-matched only, never read whole
+const SEARCH_LIMIT_DEFAULT = 40;
+const SEARCH_LIMIT_MAX = 200;
+const SEARCH_INDEX_TTL_MS = 4000;        // one word of typing costs one walk, not one per keystroke
+const SEARCH_SNIPPET = 160;
+const SEARCH_OPENABLE = new Set(['markdown', 'text', 'html']);   // what /api/doc will serve
+const searchIndexCache = new Map();      // root -> { at, files, truncated, scanned }
+
+/** Every file under `root`, flat and repo-relative, cached for SEARCH_INDEX_TTL_MS. */
+function searchIndex(root) {
+  const now = Date.now();
+  const hit = searchIndexCache.get(root);
+  if (hit && now - hit.at < SEARCH_INDEX_TTL_MS) return hit;
+  const files = [];
+  let truncated = false;
+  (function walk(dir, rel, depth) {
+    if (truncated) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) {
+        // Depth is a bound like any other: reaching it means files below were NOT looked at.
+        if (depth < SEARCH_MAX_DEPTH) walk(full, r, depth + 1);
+        else truncated = true;
+      } else if (e.isFile()) {
+        if (files.length >= SEARCH_MAX_FILES) { truncated = true; return; }
+        files.push({ path: r, name: e.name, dir: rel, kind: preview.previewKind(e.name) });
+      }
+    }
+  })(root, '', 0);
+  const entry = { at: now, files, truncated, scanned: files.length };
+  searchIndexCache.set(root, entry);
+  return entry;
+}
+
+/** One matched line, trimmed and centred on the needle, so a minified file cannot flood the row. */
+function searchSnippet(line, at) {
+  const s = String(line || '').replace(/\t/g, '  ');
+  if (s.length <= SEARCH_SNIPPET) return s.trim();
+  const start = Math.max(0, at - Math.floor(SEARCH_SNIPPET / 3));
+  return (start > 0 ? '…' : '') + s.slice(start, start + SEARCH_SNIPPET).trim()
+    + (start + SEARCH_SNIPPET < s.length ? '…' : '');
+}
+
+/**
+ * Search one workspace. Path matches first (they are what the PM typed a name for), then content
+ * matches over the readable text files that did not already match by path.
+ * `{ ok, q, hits, truncated, content_truncated, scanned, content_scanned, limit }` — never throws,
+ * never 404s: an empty `hits` with `truncated:false` IS the honest "looked, found nothing".
+ */
+function searchWorkspace(root, query, limit) {
+  const q = String(query == null ? '' : query).trim();
+  const cap = Math.max(1, Math.min(SEARCH_LIMIT_MAX, parseInt(limit, 10) || SEARCH_LIMIT_DEFAULT));
+  if (!q) {
+    return { ok: true, q: '', hits: [], truncated: false, content_truncated: false,
+      scanned: 0, content_scanned: 0, limit: cap };
+  }
+  const needle = q.toLowerCase();
+  const idx = searchIndex(root);
+  const hits = [];
+  const seen = new Set();
+  let overflow = false;                       // more matched than `cap` — a REAL cut, not a coincidence
+
+  for (const f of idx.files) {
+    if (!f.path.toLowerCase().includes(needle)) continue;
+    seen.add(f.path);
+    if (hits.length >= cap) { overflow = true; break; }
+    hits.push({ ...f, match: 'path', line: null, snippet: null, openable: SEARCH_OPENABLE.has(f.kind) });
+  }
+
+  let read = 0;
+  let contentCut = false;
+  if (!overflow) {
+    for (const f of idx.files) {
+      if (seen.has(f.path) || !SEARCH_OPENABLE.has(f.kind)) continue;
+      if (read >= SEARCH_CONTENT_FILES) { contentCut = true; break; }
+      const full = path.join(root, f.path);
+      let st;
+      try { st = fs.statSync(full); } catch { continue; }
+      if (!st.isFile()) continue;
+      if (st.size > SEARCH_CONTENT_BYTES) { contentCut = true; continue; }
+      read += 1;
+      let text;
+      try { text = fs.readFileSync(full, 'utf8'); } catch { continue; }
+      if (text.indexOf(String.fromCharCode(0)) !== -1) continue;    // binary masquerading as text — never scanned
+      const at = text.toLowerCase().indexOf(needle);
+      if (at === -1) continue;
+      if (hits.length >= cap) { overflow = true; break; }
+      const before = text.slice(0, at);
+      const lineNo = before.split('\n').length;
+      const lineStart = before.lastIndexOf('\n') + 1;
+      const lineEnd = text.indexOf('\n', at);
+      hits.push({
+        ...f, match: 'content', line: lineNo,
+        snippet: searchSnippet(text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd), at - lineStart),
+        openable: true,
+      });
+    }
+  }
+
+  return {
+    ok: true, q, hits, limit: cap,
+    // "files you searched for were never looked at" — the serious one.
+    truncated: idx.truncated || overflow,
+    // "every file was named; not every body was read" — the ordinary one.
+    content_truncated: contentCut,
+    scanned: idx.scanned, content_scanned: read,
+  };
+}
+
 // Serve a TEXTUAL document — markdown (incl. .skill), plain-text/config source, or HTML source —
 // per-workspace-guarded. Images are NOT served here (they stream through /api/asset); anything
 // non-textual returns null so the reader shows it inert. A NUL byte ⇒ binary masquerading as text
@@ -1033,10 +1283,32 @@ function deriveState(ev) {
 // state dir is why this surface reported 0 accepted against 23 real acceptance rows — the same
 // "one field, several readers, none agreeing" defect the anchor resolver was built to end.
 function acceptanceFilesFor(w) {
+  return ledgerFilesFor(w, 'acceptances.jsonl');
+}
+// The general form of the comment above, because the defect it describes was never specific to
+// acceptances. `deriveNeeds` read evals.jsonl, acceptances.jsonl AND outcome_checks.jsonl from the
+// state dir alone, so the supervision surface under-reported everything pmos-self records in
+// planning/runs/ — the same "one field, several readers, none agreeing" shape, three ledgers wide.
+// One helper with three call sites, so the fourth ledger added later cannot reintroduce it.
+function ledgerFilesFor(w, basename) {
   const out = [];
   const d = stateDirFor(w);
-  if (d) out.push(path.join(d, 'acceptances.jsonl'));
-  if (w && w.root) out.push(path.join(w.root, 'planning', 'runs', 'acceptances.jsonl'));
+  if (d) out.push(path.join(d, basename));
+  if (w && w.root) out.push(path.join(w.root, 'planning', 'runs', basename));
+  return out;
+}
+// readJsonl over BOTH ledger locations, deduped by nothing: callers fold, and a row present in both
+// is the same row recorded twice, which every existing fold already tolerates.
+function readLedger(w, basename) {
+  const out = [];
+  for (const f of ledgerFilesFor(w, basename)) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch { /* a torn line is reported by the checkers, not here */ }
+    }
+  }
   return out;
 }
 function readAcceptances(w) {
@@ -1355,19 +1627,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 +1675,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 +1700,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 +2549,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 +2569,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 +2911,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') {
@@ -2655,18 +2963,20 @@ function deriveNeeds(w) {
   if (!dir) return [];
   const needs = [];
   const settled = new Set();
-  for (const a of readJsonl(dir, 'acceptances.jsonl')) if (a.run_id) settled.add(a.run_id);
-  for (const e of readJsonl(dir, 'evals.jsonl')) {
+  for (const a of readLedger(w, 'acceptances.jsonl')) if (a.run_id) settled.add(a.run_id);
+  for (const e of readLedger(w, 'evals.jsonl')) {
     if (!e.run_id || settled.has(e.run_id)) continue;
     const verdict = e.verdict ? String(e.verdict) : 'no verdict';
     needs.push({
       run_id: e.run_id, initiative_id: e.initiative_id || null, kind: 'accept', derived: true,
       question: `Acceptance Gate open — evaluator says ${verdict}${e.score != null ? ` (${e.score})` : ''}`,
-      doc: e.rubric_path || null,
+      // `rubric` is the deprecated alias every one of the 26 legacy rows uses; scripts/record-eval.js
+      // requires `rubric_path` going forward. Read both, write only the new one.
+      doc: e.rubric_path || e.rubric || null,
     });
   }
   const disposed = new Set();
-  for (const c of readJsonl(dir, 'outcome_checks.jsonl')) if (c.initiative_id) disposed.add(c.initiative_id);
+  for (const c of readLedger(w, 'outcome_checks.jsonl')) if (c.initiative_id) disposed.add(c.initiative_id);
   const today = nowISO().slice(0, 10);
   let files = [];
   try { files = fs.readdirSync(path.join(dir, 'initiatives')).filter((f) => f.endsWith('.md')).sort(); } catch {}
@@ -3408,7 +3718,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 +3996,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 +4020,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 +4036,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 +4106,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 +4309,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
@@ -4159,6 +4480,25 @@ async function handleRequest(req, res) {
     });
     return json(res, built, built.ok ? 200 : 400);
   }
+  // ── TWO CORPORA, TWO ENDPOINTS, ONE BOX ────────────────────────────────────────────────────
+  // `/api/search` is EPISODIC — what a past session printed. `/api/search/files` is the FOLDER —
+  // what is on disk under this workspace's root. They are deliberately not merged: the hit shapes
+  // share no field (`{session, line, after}` vs `{path, kind, match, openable}`), the scrollback
+  // search scrubs secrets out of text an agent typed, and the file search reports a walk bound.
+  // Collapsing them into one payload would mean one of the two lying about what it looked at.
+  if (p === '/api/search/files') {
+    // `search everything…`, finally over everything: every file under THIS workspace's root, by
+    // path and by content. There is no path parameter — the query is a needle, not a location — so
+    // this adds no reachable path; `openable` reports whether /api/doc (or /api/asset) could show a
+    // hit. `truncated` + `scanned` are the contract that keeps a bounded answer from reading as a
+    // complete one, which is the defect this endpoint exists to end rather than to relocate.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) {
+      return json(res, { ok: false, error: 'no workspace to search', q: url.searchParams.get('q') || '',
+        hits: [], truncated: false, scanned: 0, content_scanned: 0, limit: SEARCH_LIMIT_DEFAULT });
+    }
+    return json(res, { ws: w.id, ...searchWorkspace(w.root, url.searchParams.get('q'), url.searchParams.get('limit')) });
+  }
   if (p === '/api/search') {
     // Episodic recall over this workspace's own past sessions. Localhost only, like everything
     // else here — an agent running in a pane can curl it to check what an earlier run tried.
@@ -4192,12 +4532,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);