create-pmos 0.26.0 → 0.28.0

package/workspace/public/pm/state.js

@@ -25,7 +25,7 @@ const STORE_KEY = 'pmos.workspace.pm.v1';
 function initial() {
   return {
     theme: 'dark', sel: null, q: '', mode: 'product', collapsedGroups: {}, settingsOpen: false,
-    product: null, newSessProfile: 'claude-work', intgSynced: {},
+    product: null, intgSynced: {},
     addSrc: 'github', addRepo: 'github.com/acme/atlas-mobile', addPath: '~/code/notes-cli',
     addLog: [], addedProducts: [], extraKnow: {},
     // the folder chooser's two transient bits: the in-app browser's current listing (null = closed)
@@ -55,6 +55,38 @@ function initial() {
      * last bind. None is persisted — a half-finished declaration restored on reload would be a
      * question about a moment that has passed, and `bindResult` is a report about one request. */
     bindSess: null, bindTo: '', bindResult: null,
+    /* ── the session pre-flight (workspace-session-preflight) ──────────────────────────────────
+     * `newSess` is `{slug}` while the form is open and null otherwise. The rest is what the PM has
+     * typed and clicked in it, plus the two server reads it renders over (`branches` from
+     * /api/git/branches, `profiles` from /api/profiles) and the answer to the last attempt.
+     *
+     * NONE of it is in PERSIST below, and that is a decision rather than an omission: the
+     * allow-list is explicit, so these are excluded by construction. A branch choice restored from
+     * localStorage is how a PM starts a session on a branch they picked yesterday for a question
+     * they have already answered — and `newSessBusy` restored true would be a form wedged shut
+     * waiting on a request that ended with the last page.
+     *
+     * `branchInfo` is separate from `newSessBranches`: it is the server's `{t:'branch'}` broadcast,
+     * written by tab-term.js whenever a checkout happens ANYWHERE, and it is what stops an open
+     * picker going stale while the PM checks something out in a terminal.
+     *
+     * ── WHY THE PROFILE SLOT IS NAMED FOR THE FORM AND NOT FOR "A NEW SESSION" ────────────────
+     * It was `newSessProfile`, and `＋ session` read it — which made it a slot two different
+     * controls wrote and read, only one of which ever asked the PM anything. Opening the form wrote
+     * the server's remembered preference into it, every chip wrote the PM's choice into it, and
+     * cancelling cleared neither; the next one-click `＋ session` then filed that choice onto its
+     * session, put it on the tab, and (since a tab's profile now travels to the server) sent it as
+     * a spawn instruction. A descriptor the server cannot resolve is refused, so one click produced
+     * no session and a refusal written inside the terminal it had already opened — the exact shape
+     * the pre-flight exists to remove, on the path the PRD calls primary.
+     *
+     * `preflightProfile` therefore belongs to the form, is reset when it opens AND when it closes,
+     * and is read by nothing else. `＋ session` states no profile at all, which is the honest
+     * answer for a control that never asked. */
+    newSess: null, newSessName: '', newSessAgent: 'shell',
+    newSessBranch: '', newSessBranchNew: '', newSessBranchMode: false,
+    newSessIsolate: null, newSessError: null, newSessBusy: false,
+    newSessBranches: null, preflightProfile: null, profiles: null, branchInfo: null,
     col0: true, col1: true, col2: true, scratchOpen: false, scratchText: '', copied: false,
     flowsMap: null, schedList: null, agentList: null, memory: null,
     savedDocs: {}, scratchCopied: false,
@@ -64,6 +96,13 @@ function initial() {
      * against. `scratchText` remains the text ON SCREEN, so every existing reader (the copy button,
      * ⇥ send to terminal, the fixture render) is unchanged. `scratchKey` is which pad that is. */
     scratchPads: {}, scratchKey: null,
+    /* The server's answer to "is the runtime state settled?" (/api/workspaces#state_health), null
+     * until the data layer answers. `{ok:false}` means the workspace could not move the PM's state
+     * out of the checkout because both directories hold state, so any list drawn from a store the
+     * per-user directory does not hold is SHORT — panel 1 draws it as a red banner rather than
+     * letting an empty skills list read as "you have no skills". Deliberately NOT in PERSIST: it is
+     * a fact about this server's boot, and a stale one restored from localStorage would be a lie. */
+    stateHealth: null,
   };
 }
 

package/workspace/public/pm/tab-term.js

@@ -124,6 +124,152 @@ const SOCK = {
   timer: null,
 };
 
+/* ── what rides on spawnQueue, and why it is two kinds ─────────────────────────────────────────
+ * The queue itself is unchanged in MECHANISM: `created` carries no correlation id, the server
+ * answers `new` in receipt order, so first-in-first-out IS the correlation and two simultaneous
+ * starts cannot be handed each other's shell. What changed is what a slot holds.
+ *
+ *   {kind:'pane', tabId}       — the original behaviour: a pane already exists and is waiting for
+ *                                its session. Still used by bind()'s fallback spawn (see below).
+ *   {kind:'ask', msg, resolve} — NOBODY is waiting on screen. The answer resolves a promise, and
+ *                                the caller decides whether a tab is opened at all.
+ *
+ * The second kind is the whole of workspace-session-preflight's R1. Before it, a refusal arrived
+ * after the tab, the pane and the xterm had all been built, so `{t:'error'}` could only be written
+ * INSIDE a terminal belonging to a session the server had just declined to start.
+ *
+ * ── WHY A SLOT ALSO CARRIES ITS MESSAGE, AND WHETHER IT WAS SENT ──────────────────────────────
+ * An `ask` is queued BEFORE it is on the wire, because on the first use of the pre-flight there is
+ * no wire yet: `connect()` opens a WebSocket and the handshake is asynchronous, so the socket that
+ * the very first press opens is still in readyState 0 when that press would have sent. The first
+ * implementation called `send()` synchronously and reported the false refusal "not connected to the
+ * workspace server — nothing was started" — which made the feature dead on first use in a fresh
+ * window, and alive on the second press only because the failed press had left a socket behind.
+ *
+ * So a slot holds the message it still owes the server, and `flushAsks()` puts it on the wire the
+ * moment there is one — from `requestSpawn` when the socket is already up, and from `ws.onopen`
+ * when it is not. This is the idiom the module already used for panes: bind() answers a cold socket
+ * with "connecting to the workspace server…" and is re-run from `onopen`.
+ *
+ * The FIFO correlation is unchanged in meaning but is now stated exactly: `created`/`error` belong
+ * to the oldest request THAT WAS ACTUALLY SENT (takeSent). A queued-but-unsent slot cannot absorb
+ * the answer to somebody else's message, because the server has never heard of it. What actually
+ * enforces the correlation is that queue order and WIRE order are the same thing — which is why
+ * `ws.onopen` flushes the asks before it re-binds the panes, and why takeSent is a floor rather
+ * than the mechanism. See its own note.
+ */
+const SPAWN_TIMEOUT_MS = 15000;
+
+/** Resolve an `ask` slot exactly once, and stop its timer. */
+function settleAsk(req, out) {
+  if (!req || req.settled) return;
+  req.settled = true;
+  if (req.timer) { clearTimeout(req.timer); req.timer = null; }
+  try { req.resolve(out); } catch { /* a caller that threw is not this module's to repair */ }
+}
+
+/** Fail every outstanding `ask`. A dropped promise is the same swallow this module is removing. */
+function failAllAsks(error) {
+  for (const req of SOCK.spawnQueue) if (req && req.kind === 'ask') settleAsk(req, { ok: false, error });
+}
+
+/**
+ * Put every queued `ask` that is not yet on the wire onto it, in queue order — and stop at the
+ * first one the socket will not take, so the queue's order stays the order the server received.
+ * Called from `requestSpawn` (the socket may already be up) and from `ws.onopen` (it has just come
+ * up). Sending in queue order is what keeps FIFO the correlation `created` relies on.
+ */
+function flushAsks() {
+  for (const req of SOCK.spawnQueue) {
+    if (!req || req.kind !== 'ask' || req.sent || req.settled) continue;
+    if (!send(req.msg)) return;
+    req.sent = true;
+  }
+}
+
+/**
+ * The oldest request the server has actually been sent. `consume` removes it (an answer that ends
+ * the request) or leaves it (a `notice`, which is followed by a `created` for the same request).
+ *
+ * It is a search rather than a `shift` because the head of the queue may now be an `ask` that is
+ * waiting for the socket to open: the server cannot be answering a message it was never sent, and
+ * handing that slot somebody else's `created` would attach a pre-flight to the wrong PTY.
+ *
+ * SAID PLAINLY, BECAUSE THE SUITE CANNOT SHOW IT: no call site reaches that state today. `bind()`
+ * only queues while the socket is open, `flushAsks` runs before the re-bind, and both are removed
+ * again when a send is refused — so replacing this with a plain `shift()` passes every assertion in
+ * pm-term-test.js (checked, not assumed). What keeps the correlation honest in practice is the
+ * ORDER in `ws.onopen`, and that IS asserted — the race test one page down goes red when the panes
+ * are re-bound first. This is a floor under an invariant, not behaviour anybody can observe.
+ */
+function takeSent(consume) {
+  const i = SOCK.spawnQueue.findIndex((r) => r && r.sent);
+  if (i < 0) return null;
+  const req = SOCK.spawnQueue[i];
+  if (consume) SOCK.spawnQueue.splice(i, 1);
+  return req;
+}
+
+/**
+ * Ask the server to START a session, and answer what it said. NOTHING is opened here — no tab, no
+ * pane, no terminal. That is the caller's to do, and only on `{ok:true}`.
+ *
+ * Resolves `{ok:true, id, notice}` on `created`, or `{ok:false, error}` on any of the four ways a
+ * request can end without one:
+ *   · the server refused it (`{t:'error'}` — an unreadable profile, a failed worktree, a failed
+ *     checkout, all of which spawnWithBranch decides BEFORE spawnSession is reached);
+ *   · the socket closed with the request still outstanding;
+ *   · the socket never came up at all;
+ *   · nothing came back within SPAWN_TIMEOUT_MS.
+ * It always settles. A promise that hangs is a form that hangs, which is the same failure in a
+ * different costume.
+ *
+ * A COLD SOCKET IS NOT A REFUSAL. `connect()` returns before the WebSocket handshake completes, so
+ * on the first press in a window with no terminal open there is nothing to send on yet. The message
+ * is therefore QUEUED and flushed from `ws.onopen`; only the timeout and a socket that actually
+ * closed can end it without an answer. Reporting "not connected" synchronously is what made this
+ * control fail every first press in a fresh window.
+ */
+export function requestSpawn(opts) {
+  const o = opts || {};
+  if (FIXTURE) {
+    return Promise.resolve({ ok: false, error: 'fixture mode starts no sessions' });
+  }
+  connect();
+  return new Promise((resolve) => {
+    const req = {
+      kind: 'ask', resolve, notice: null, settled: false, timer: null, sent: false,
+      msg: {
+        t: 'new',
+        name: o.name,
+        agent: o.agent || 'shell',
+        ws: o.ws,
+        /* Sent even when the PM chose nothing, and that is deliberate on two of them. `isolate` has
+         * a server-side default (`server.js` liveSessionCount) whose own comment says the client
+         * should state what the PM actually saw; `profile: null` is a DELIBERATE "no profile",
+         * which the server distinguishes from a client that forgot the field. */
+        branch: o.branch || null,
+        createBranch: !!o.createBranch,
+        isolate: o.isolate === undefined ? null : o.isolate,
+        profile: o.profile === undefined ? null : o.profile,
+      },
+    };
+    SOCK.spawnQueue.push(req);
+    /* Armed BEFORE the flush, and armed whether or not the message goes out now: a request waiting
+     * for a socket that never opens must end in a sentence, not in a form that spins for ever. */
+    req.timer = setTimeout(() => {
+      SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== req);
+      settleAsk(req, {
+        ok: false,
+        error: req.sent
+          ? 'the workspace server did not answer — nothing was started'
+          : 'could not reach the workspace server — nothing was started',
+      });
+    }, SPAWN_TIMEOUT_MS);
+    flushAsks();
+  });
+}
+
 /* The session heartbeat arrives about every 2s. It is deliberately NOT pushed through setState:
  * a state change repaints all four panels, and repainting the window twice a second to redraw
  * nothing would destroy text selection, scroll position and any in-flight edit. Nothing in this
@@ -140,13 +286,24 @@ function connect() {
   SOCK.ws = ws;
   ws.onopen = () => {
     SOCK.open = true; SOCK.tries = 0;
+    /* The asks FIRST, and the order is the point: a pre-flight that pressed `start session` before
+     * this socket existed has been waiting here, and binding the panes first would put a pane's
+     * fallback `new` ahead of it on the wire while the queue still said otherwise. Flushing first
+     * keeps queue order and wire order the same thing, which is what makes FIFO a correlation. */
+    flushAsks();
     for (const rec of panes.values()) if (rec.kind === 'real') bind(rec);
   };
   ws.onclose = () => {
     SOCK.open = false; SOCK.ws = null; SOCK.attached.clear();
     /* An in-flight `new` is abandoned rather than retried: the server may well have started the
      * session before the socket dropped, and the reconnect's `hello` will find it by name. Retrying
-     * blind is how a PM ends up with two shells and one tab. */
+     * blind is how a PM ends up with two shells and one tab.
+     *
+     * An `ask` is not merely abandoned, it is ANSWERED. Dropping the promise would leave the
+     * pre-flight spinning on a question that can no longer be answered — the same swallow this
+     * module is removing, one layer up. The wording is careful: the session may in fact exist, so
+     * it says what PMOS knows (this window did not start one) and not more. */
+    failAllAsks('the connection to the workspace server was lost — this window started nothing');
     SOCK.spawning.clear(); SOCK.spawnQueue = [];
     for (const rec of panes.values()) {
       if (rec.kind !== 'real') continue;
@@ -204,11 +361,21 @@ function handle(m) {
     return;
   }
   if (m.t === 'created') {
-    // `created` carries no correlation id, so the OLDEST outstanding request takes it. The server
+    // `created` carries no correlation id, so the oldest request THAT WAS SENT takes it. The server
     // answers `new` in the order it received them, which makes the queue the correlation — matching
     // by iteration order over the pane map would hand two simultaneous starts each other's shell.
-    const id = SOCK.spawnQueue.shift();
-    if (!id) return;
+    // "That was sent" is the whole guard: a queued ask still waiting for the socket to open has not
+    // been asked for anything, so it cannot be the thing being answered.
+    const req = takeSent(true);
+    if (!req) return;
+    if (req.kind === 'ask') {
+      // Nobody is on screen waiting for this. Hand the caller the id and whatever non-fatal truth
+      // arrived just before it; the caller opens the tab, and the tab carries the id so bind()
+      // ATTACHES rather than starting a second session for the same click.
+      settleAsk(req, { ok: true, id: m.id, notice: req.notice || null });
+      return;
+    }
+    const id = req.tabId;
     SOCK.spawning.delete(id);
     const rec = panes.get(id);
     if (!rec) { send({ t: 'detach', id: m.id }); return; }   // the tab closed while we waited
@@ -219,13 +386,39 @@ function handle(m) {
     return;
   }
   if (m.t === 'error' || m.t === 'notice') {
+    /* An `error` CONSUMES its slot — the request is over. A `notice` only PEEKS, because the server
+     * sends `notice` and then `created` for the same request and the slot has to survive to take
+     * the `created`. That asymmetry predates this change and is preserved exactly. */
+    const req = takeSent(!!m.error);
+    if (!req) return;
+    if (req.kind === 'ask') {
+      // THE POINT OF THE WHOLE INITIATIVE. A refusal resolves the promise and opens nothing: no
+      // tab, no pane, no xterm, no extraSess row. It used to be written as a dimmed line inside a
+      // terminal the click had already built, for a session the server had just declined to start.
+      if (m.error) settleAsk(req, { ok: false, error: m.error });
+      else req.notice = m.notice;         // held, and shown by whoever ends up owning the pane
+      return;
+    }
     const line = m.error ? 'pmos: ' + m.error : 'pmos: ' + m.notice;
-    const id = m.error ? SOCK.spawnQueue.shift() : SOCK.spawnQueue[0];
-    if (m.error && id) SOCK.spawning.delete(id);
-    const rec = id ? panes.get(id) : null;
+    if (m.error) SOCK.spawning.delete(req.tabId);
+    const rec = panes.get(req.tabId);
     if (rec) note(rec, line, true);
     return;
   }
+  if (m.t === 'branch') {
+    /* The picker must not go stale. The server broadcasts this after a worktree is added, after a
+     * checkout and after a worktree is removed — so a branch the PM checked out in a terminal, or
+     * one this very spawn created, changes what the open pre-flight should be offering. The
+     * retired single-file client acted on exactly this (app.js:294); the four-panel port dropped
+     * every one of the three broadcasts on the floor.
+     *
+     * Written to state unconditionally rather than only when a form is open: `branchInfo` is a
+     * cache of the server's last word about a workspace, and a reader that is not open ignores it.
+     * The `ws` is carried so a reader can tell whether the news is about the repository it is
+     * asking about. */
+    setState({ branchInfo: { ...m, at: Date.now() } });
+    return;
+  }
 }
 
 const recFor = (sessionId) => {
@@ -355,10 +548,44 @@ function bind(rec) {
   if (!SOCK.open) { note(rec, 'pmos: connecting to the workspace server…'); return; }
   if (SOCK.spawning.get(rec.tab.id)) return;
   if (wantsSpawn(rec.tab)) {
-    // agent 'shell' deliberately: PMOS cannot know which agent CLI the PM meant from a tab alone,
-    // and falling back from an agent to a shell after the fact would be the dishonest version.
-    SOCK.spawning.set(rec.tab.id, true);
-    SOCK.spawnQueue.push(rec.tab.id);
+    /* THE FALLBACK SPAWN — no longer the PM's path, and no longer pretending to be.
+     *
+     * Since workspace-session-preflight, a session the PM started through a control that ASKS
+     * arrives here already carrying `sessionId`, so `resolveSessionId` returns above and this is
+     * never reached for it. What still reaches it is a session record with `spawn:true` and no id:
+     * a test seed (pm-term-test.js, ui-test.js both write `extraSess` directly), and a tab whose
+     * server-side session vanished between the click and the render.
+     *
+     * It is kept rather than removed, and that is an honest weakness worth stating: the defect is
+     * closed because every PM path goes through a control that asks, NOT by construction. A future
+     * call site that writes `extraSess` directly re-opens it. See the PRD's R5.
+     *
+     * WHAT IT MAY SEND IS EXACTLY WHAT A TAB CARRIES — `agent` and `profile`, and nothing else.
+     * An earlier draft of this line also sent `branch`, `createBranch` and `isolate` off the tab
+     * record, under a comment claiming a seed could name them. Nothing sets any of the three
+     * (`openTerm` in panel-initiatives.js is the only builder of a term tab) and none of them is in
+     * `TAB_FIELDS` (state.js), so all three were `undefined` on every tab that has ever existed:
+     * three nulls dressed as a feature, and a claim in a comment that no code path could satisfy.
+     *
+     * They are also the three that must NOT be here even if a tab did carry one. This path exists
+     * to re-open a view whose session went missing — a reload, a server restart — and a restored
+     * tab that re-ran a checkout each time would move the PM's working tree behind their back,
+     * repeatedly, for a decision they made once. A branch is a question, and the control that asks
+     * it is the pre-flight; its answer reaches the server through `requestSpawn`, never through a
+     * tab record.
+     *
+     * `profile` stays because it is genuinely a tab's own: `openTerm` sets it from the session the
+     * PM clicked and `TAB_FIELDS` persists it, so a vanished session is restarted under the
+     * environment it claimed rather than under a different one. `agent` is honoured when a caller
+     * puts one on the tab and defaults to `shell` otherwise, which is the only honest default for
+     * a tab that cannot say what the PM meant. */
+    const t = rec.tab;
+    SOCK.spawning.set(t.id, true);
+    /* `sent: true` from birth: this slot is only ever pushed when the socket is up (the guard a few
+     * lines above), and it is removed again if `send` refuses it. An `ask` is the kind that can sit
+     * in the queue unsent, waiting for `onopen`. */
+    const req = { kind: 'pane', tabId: t.id, sent: true };
+    SOCK.spawnQueue.push(req);
     note(rec, 'pmos: starting a session…', true);
     /* `initiative` is the ONE field this message was missing (workspace-session-attribution R2).
      * `＋ session` is clicked on an initiative row, `openTerm` puts that row's id on the tab as
@@ -370,12 +597,13 @@ function bind(rec) {
      * A tab with no slug sends nothing extra and the session is unattributed. That is the honest
      * outcome, not a failure: the server never refuses a spawn over a label. */
     const ok = send({
-      t: 'new', name: rec.tab.sess, agent: 'shell', ws: wsForTab(rec.tab),
-      initiative: rec.tab.slug || null,
+      t: 'new', name: t.sess, agent: t.agent || 'shell', ws: wsForTab(t),
+      initiative: t.slug || null,
+      profile: t.profile === undefined ? null : t.profile,
     });
     if (!ok) {
-      SOCK.spawning.delete(rec.tab.id);
-      SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== rec.tab.id);
+      SOCK.spawning.delete(t.id);
+      SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== req);
     }
     return;
   }
@@ -697,6 +925,28 @@ export function killSession(id) {
   return send({ t: 'kill', id });
 }
 
+/**
+ * Write a status line into a tab's terminal, by tab id — for a caller that holds a fact about a
+ * session but not the pane showing it.
+ *
+ * The pre-flight is the caller. `spawnWithBranch` answers an accepted start with a `notice` — a
+ * worktree's path, "not a git repository, so no branch was applied" — and that notice arrives
+ * BEFORE the pane it belongs to exists, because the pane is now built from the acceptance. Without
+ * this the server's deliberate non-fatal truth would be dropped precisely because the request
+ * succeeded, which is the same swallow as the one this initiative removes, in the happy path.
+ *
+ * The pane may not be mounted on the very next frame, so the write is retried a few times and then
+ * given up on quietly — a status line is worth trying for, not worth a timer that never stops.
+ */
+export function noteOnTab(tabId, line, tries) {
+  const rec = panes.get(tabId);
+  if (rec && rec.term) { note(rec, line, true); return true; }
+  const left = tries === undefined ? 20 : tries;
+  if (left <= 0) return false;
+  setTimeout(() => noteOnTab(tabId, line, left - 1), 100);
+  return false;
+}
+
 /**
  * The SERVER's session id this tab is bound to, or null. The scratchpad reads it: a pad belongs to
  * the session, and the session's identity is this id — not the tab id (which survives a session
@@ -729,6 +979,17 @@ export function termProbe() {
   return out;
 }
 
-if (typeof window !== 'undefined') window.pmTerm = { refitVisible, termProbe, panes };
+/**
+ * The message entry point, exposed for the browser suite ONLY.
+ *
+ * `handle` is what `ws.onmessage` calls after `JSON.parse`, so feeding it a frame exercises the
+ * exact path a real broadcast takes — nothing is stubbed and no branch is special-cased for a
+ * test. It exists because the `{t:'branch'}` claim cannot honestly be asserted any other way: the
+ * only way to make the server broadcast one is to check a branch out, and the server under test in
+ * pm-term-test.js is serving the repository the suite is running in.
+ */
+export function __handleForTest(m) { return handle(m); }
+
+if (typeof window !== 'undefined') window.pmTerm = { refitVisible, termProbe, panes, requestSpawn };
 
 export default mountTerm;