create-pmos 0.25.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';
@@ -1476,6 +1609,14 @@ function persist(s) {
   // fact: a record persisted before profiles existed restores as "not recorded", and inventing a
   // key for the past would be a lie about it.
   if ('profile' in s) meta.profile = s.profile == null ? null : s.profile;
+  // WHAT THIS SESSION IS FOR, and where that came from. Same `in`-guard as `profile` above and for
+  // the same reason: every session running before this field existed has no attribution, and
+  // writing a key for it would turn "we were never told" into "it belongs to nothing". Both keys
+  // move together — an attribution with no provenance could not be told apart from a reading.
+  if ('initiative' in s) {
+    meta.initiative = s.initiative == null ? null : s.initiative;
+    meta.attributedBy = s.attributedBy || null;
+  }
   try {
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
@@ -1773,6 +1914,16 @@ function sessionList() {
         ? treeShare.roleOf(s.id, treeOfWs.get(s.ws) || null, writerByTree.get(treeOfWs.get(s.ws)))
         : null,
       tree_peers: treeShare.coTenants(rowsAll, treeOfWs, treeOfWs.get(s.ws) || null, s.id).length,
+      // ── what this session is for (workspace-session-attribution R1) ──
+      // THREE STATES, kept apart on the wire because the surface has to tell them apart:
+      //   initiative: 'x', attributed_by: 'spawn'    PMOS was told at spawn — first-hand
+      //   initiative: 'x', attributed_by: 'declared' the PM bound a running session — their word
+      //   initiative: null, attributed_by: null      never recorded — NOT "belongs to nothing"
+      // The branch reading is deliberately NOT folded in here. It is the client's fallback
+      // (lib/working-set.js), computed from `/api/workspaces`, and merging it into this field would
+      // make an inference indistinguishable from a record — the exact confusion this field removes.
+      initiative: 'initiative' in s ? (s.initiative == null ? null : s.initiative) : null,
+      attributed_by: 'initiative' in s ? (s.attributedBy || null) : null,
       profile_id: 'profile' in s ? (s.profile == null ? null : s.profile) : null,
       profile_line: profilesLib.profileLine(
         !('profile' in s) ? undefined
@@ -2133,6 +2284,24 @@ function nextSessionId() {
   return id;
 }
 
+/**
+ * An initiative id, or null — the ONE gate every attribution path goes through.
+ *
+ * `fourPanel.validId` is the repo's existing answer to "is this a record name?" and it is reused
+ * rather than re-typed: it already guards the `/api/initiative` path interpolation and the two
+ * declaration stores, so a second regex here would be a second opinion about what an id is, free to
+ * drift from the one that decides whether a file can be read.
+ *
+ * Returning null rather than throwing is deliberate. An unusable value must leave the session
+ * UNATTRIBUTED — which is a real, honest state with a surface of its own — never half-attributed to
+ * something that failed to parse, and never a spawn refused over a label.
+ */
+function initiativeIdOrNull(v) {
+  if (v == null) return null;
+  const s = String(v).trim();
+  return s && fourPanel.validId(s) ? s : null;
+}
+
 // Resolve a requested profile id BEFORE anything is spawned (profiles R3/R9). The rule the whole
 // feature turns on: a session must never claim a profile whose overlay was not applied. So the
 // three outcomes are kept apart — nothing asked for, asked for and readable, asked for and gone —
@@ -2150,7 +2319,7 @@ function resolveProfileForSpawn(id) {
       : `profile "${id}" is not among the descriptors in ${read.dir} — PMOS will not substitute another` };
 }
 
-function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
+function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative }) {
   const id = nextSessionId();
   const w = getWs(ws);
   const root = w ? w.root : SELF_ROOT;
@@ -2172,6 +2341,24 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
   const base = { id, ws: w ? w.id : wsId(SELF_ROOT), root, name: (name && String(name).trim()) || agent, agent, origin: tag,
     profile: pres.id, profileRefusal: pres.ok ? null : pres.error };
 
+  /* WHAT THIS SESSION IS FOR (workspace-session-attribution R1).
+   *
+   * A PMOS session has never recorded which initiative it is working on — not here, not on the wire,
+   * not on disk — so every initiative-keyed surface had to INFER it from the `initiative/<id>` branch
+   * convention, which holds in one of four ordinary situations. The board that shipped on that
+   * inference could not see the session that wrote it, because that session was on a `claude/*`
+   * branch.
+   *
+   * The key is set ONLY when the caller supplied one, exactly as `profile` is, and for the same
+   * reason: its ABSENCE has to stay a fact. A session started before this field existed, or started
+   * outside PMOS, restores as not-recorded — and "not recorded" must never be confused with
+   * "recorded as none", which is what a `null` default would have produced. `attributedBy` says
+   * where the value came from, because a value the PM declared and a value PMOS was told at spawn
+   * are different claims and the surface has to be able to tell them apart.
+   */
+  const init = initiativeIdOrNull(initiative);
+  if (init) { base.initiative = init; base.attributedBy = 'spawn'; }
+
   // A missing agent CLI is detected BEFORE any spawn (on Linux the exec-in-fork failure is
   // otherwise silent) — the same honest exited pane on both the tmux and the direct path.
   if (!isShell && !commandExists(agent)) {
@@ -2193,6 +2380,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
       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);
@@ -2212,6 +2400,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
     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);
@@ -2247,7 +2436,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
 // A FAILED git operation in a real repo must never spawn a session on the wrong branch (rubric
 // hard floor): we return {ok:false} and spawn nothing. Kept as its own function so the
 // git-then-maybe-spawn contract is unit-testable without a WS client.
-function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative }) {
   const w = getWs(ws);
   if (!w) return { ok: false, error: 'no workspace' };
   // The profile is checked BEFORE any git operation. A composer that picked a profile PMOS cannot
@@ -2289,7 +2478,7 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
       broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
     }
   }
-  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative });
   // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
   // block above. The isolate default already computes that other sessions would be disturbed — and
   // then the whole git block is skipped when no branch was picked, which is the common path and the
@@ -2377,6 +2566,10 @@ function startWork({ initiative, repoKey, ws, agent, name, profile }) {
     createBranch: plan.createBranch,
     isolate: plan.isolate,
     profile,
+    // THE FIX THIS FUNCTION HAS BEEN ONE ARGUMENT AWAY FROM SINCE IT WAS WRITTEN. `initiative`
+    // arrived here, decided the branch and supplied a fallback display name, and was then dropped
+    // — so the one start path DESIGNED to know what it was starting work on never told the session.
+    initiative,
   });
   if (!r.ok) return r;
   return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
@@ -2549,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') {
@@ -3350,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.
@@ -3626,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' } });
@@ -3645,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 ` +
@@ -3659,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.`;
@@ -3729,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); }
@@ -3930,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
@@ -3994,6 +4202,45 @@ async function handleRequest(req, res) {
     // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
     return json(res, { ws: w ? w.id : null, ...out });
   }
+  if (p === '/api/session/initiative' && req.method === 'POST') {
+    /* Bind a RUNNING session to an initiative — the PM's own word about work already in flight
+     * (workspace-session-attribution R3/R8).
+     *
+     * Every session running when this shipped has no attribution, and so does every session started
+     * outside PMOS. Without this they would stay unattributed forever, which would make the whole
+     * field a promise about the future and no help with the work on screen today.
+     *
+     * Three properties this endpoint holds:
+     *   1. It is a DECLARATION. `attributedBy: 'declared'` is written, never 'spawn', so the surface
+     *      can keep the PM's word apart from what PMOS was told first-hand. Same distinction
+     *      `initiative-links.jsonl` already draws with `origin`/`state`.
+     *   2. It is SINGLE-VALUED, and a replacement says what it replaced. `previous` comes back on
+     *      the response rather than being overwritten with no trace (R8) — a re-bind the PM did not
+     *      mean to do is otherwise unrecoverable and unnoticeable.
+     *   3. It touches NOTHING else. No checkout, no branch, no respawn. The session keeps running
+     *      exactly as it was; the only thing that changes is what PMOS says it is for.
+     *
+     * `initiative: null` CLEARS the binding, which is the honest way back from a wrong one — and it
+     * still writes the key, because a session the PM has explicitly unbound is a different state
+     * from one that was never recorded.
+     */
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const s = sessions.get(String(body.id || ''));
+    if (!s) return json(res, { ok: false, error: 'no such session' }, 404);
+    const clearing = body.initiative === null || body.initiative === '';
+    const next = clearing ? null : initiativeIdOrNull(body.initiative);
+    if (!clearing && !next) {
+      return json(res, { ok: false, error: 'that initiative id is not a record name' }, 400);
+    }
+    const previous = 'initiative' in s ? (s.initiative || null) : null;
+    s.initiative = next;
+    s.attributedBy = next ? 'declared' : null;
+    persist(s);
+    pushSessions();
+    return json(res, { ok: true, id: s.id, initiative: next, attributed_by: s.attributedBy, previous });
+  }
   if (p === '/api/initiative/link' && req.method === 'POST') {
     // Recording that an artifact corresponds to an external page. This writes a DECLARATION and
     // makes no request: PMOS holds no credential, so it can state what the PM says the mapping is
@@ -4095,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);
@@ -4522,7 +4773,10 @@ wss.on('connection', (ws) => {
     } else if (m.t === 'resize') {
       const s = sessions.get(m.id); if (s && s.pty) { try { s.pty.resize(m.cols, m.rows); s.cols = m.cols; s.rows = m.rows; } catch {} }
     } else if (m.t === 'new') {
-      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile });
+      // `initiative` is what the client has always held and never sent: `＋ session` is clicked on
+      // an initiative row, the tab carries its `slug`, and the spawn message named three other
+      // fields. An absent or unusable value leaves the session unattributed — never a refused spawn.
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile, initiative: m.initiative });
       // A refused profile is its own sentence, not "branch: …" — the composer's error line names
       // what PMOS could not read, and nothing was started.
       if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'branch: ') + r.error })); return; }

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 };