create-pmos 0.7.3 → 0.9.0

package/workspace/lib/session-state.js

@@ -0,0 +1,139 @@
+/* session-state — the presented state of a session, joined from the workspace's TWO sources.
+ * (workspace-waiting-on-you R2/R3/R4/R5/R6.)
+ *
+ * One source of truth for "what word goes beside this session", used on BOTH sides:
+ *   - server.js requires it (sessionList publishes the joined state)
+ *   - the browser loads it as /lib/session-state.js before app.js (window.PMOSSessionState)
+ * so the sidebar and the server can never hold different opinions about one session. That is not
+ * hypothetical tidiness: QUIET_AFTER_MS was once re-typed as a literal in app.js, two copies of one
+ * number free to drift, and the fix was to ship it from one place. A duplicated TABLE fails the
+ * same way with more surface area.
+ *
+ * ── THE TWO SOURCES, AND WHY NEITHER IS ENOUGH ALONE ────────────────────────────────────────
+ *   CADENCE   (harness-parse.deriveState ← lastOutputAt)  answers  "is anything happening?"
+ *   STRUCTURE (transcript-read.turn      ← the JSONL)     answers  "whose turn is it?"
+ *
+ * Cadence alone cannot tell a finished turn from a crash from a slow tool — which is why
+ * workspace-harness-tower's R1 forbade upgrading `quiet` to "waiting on you", and why that rule is
+ * SATISFIED here rather than repealed: the stronger words are built from BOTH, and every cell
+ * without corroboration still says exactly what it said before.
+ *
+ * The two contributions are NOT symmetric, and pretending otherwise would be the first step toward
+ * over-claiming:
+ *   - for `needs`   the transcript is load-bearing and the quiet clock is only a SETTLE-TIMER
+ *                   (the terminal is still painting the final block for a moment after a turn ends)
+ *   - for `blocked` the transcript only says a call is open; the quiet clock does the real
+ *                   discriminating, because a running tool emits bytes and a permission prompt does not
+ *
+ * ── THE PROPERTY THIS FILE EXISTS TO GUARANTEE (R4) ─────────────────────────────────────────
+ * `needs` is reachable ONLY from turn === 'user', and transcript-read sets 'user' only when NO
+ * tool_use is unresolved. A crashed session's dangling call is a permanent phantom (2/25 real
+ * transcripts) and a phantom IS an unresolved call — so a phantom can only ever reach `tool`, and
+ * `needs` is UNCONSTRUCTABLE for it.
+ *
+ * There is deliberately NO `if (!phantom)` anywhere here. A check is a thing a later change can
+ * forget to call; a state that cannot be built needs no discipline to stay honest. This is the same
+ * discipline as the shipped "age without liveness is refused" — and if you are editing this file,
+ * the test that matters is `needs you` over the join's WHOLE domain, not one example of it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSSessionState = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  // The cadence clock's three values (harness-parse.deriveState) — this module's first input.
+  const CADENCE = ['working', 'quiet', 'exited'];
+  // The transcript's answer to whose turn it is — this module's second input. `null` = no answer,
+  // which is the NORMAL case for a shell/codex session and for any claude session whose transcript
+  // cannot be resolved. It is not an error and draws no apology.
+  const TURN = ['user', 'agent', 'tool', null];
+  // What can end up on screen. The first three are pre-existing and unchanged; the last two are
+  // this feature. `failed` is absent by design — it has no observable (harness-tower).
+  const PRESENTED = ['working', 'quiet', 'exited', 'needs', 'blocked'];
+
+  // The word beside the glyph. Deliberately separate from the key: `blocked`'s word names its own
+  // uncertainty, because its evidence cannot distinguish a permission prompt from a hung tool from
+  // a corpse. The surface may not launder that into confidence.
+  const WORD = {
+    working: 'working',
+    quiet: 'quiet',
+    exited: 'exited',
+    needs: 'needs you',
+    blocked: 'maybe blocked',
+  };
+
+  // Filled = corroborated by both sources, hollow = suspected from one. `needs` takes ◆, which has
+  // sat declared-but-dead in the client's GLYPH map since the harness tower; this makes it live.
+  const GLYPH = { working: '●', quiet: '◼', exited: '○', needs: '◆', blocked: '◇' };
+
+  // Which presented states may carry the open call's verb + age. Unchanged for `working` (shipped
+  // behaviour); extended to `blocked`, where the age is the most informative part of a weak claim —
+  // "a call has been open 6m and nothing is moving" is the whole signal.
+  const CARRIES_CALL_AGE = { working: true, blocked: true };
+
+  /**
+   * THE JOIN (R2). Total over CADENCE × TURN: every one of the twelve cells is defined here, and
+   * `presentedStates()` below exists so a test can walk the domain rather than sample it.
+   *
+   * Pure: no clock read, no I/O, no DOM. The caller supplies the already-derived cadence state, so
+   * this function cannot disagree with `deriveState` about the threshold — it never sees one.
+   *
+   *   turn ↓ / cadence →   working    quiet          exited
+   *   'user'               working    NEEDS          exited
+   *   'tool'               working    BLOCKED        exited
+   *   'agent'              working    quiet          exited
+   *   null                 working    quiet          exited
+   *
+   * Three cells change from pre-feature behaviour. The other nine are byte-identical, and that is
+   * asserted rather than assumed.
+   */
+  function presented(cadence, turn) {
+    // `exited` is the server's own lifecycle fact and outranks anything the transcript says: a
+    // transcript is a file that outlives its process, so a dead session's last record would
+    // otherwise keep claiming a turn forever.
+    if (cadence === 'exited') return 'exited';
+    // Bytes are arriving. Whatever the transcript says, something IS happening, so no stronger
+    // claim is available or needed — and this is what stops `needs` firing during the moment the
+    // terminal is still painting the turn it just finished.
+    if (cadence === 'working') return 'working';
+    if (cadence !== 'quiet') return 'working';   // unknown cadence ⇒ the weakest live word, never a claim
+    // Quiet. Only here can the transcript raise the claim above `quiet`.
+    if (turn === 'user') return 'needs';         // turn ended AND nothing moving ⇒ the human is up
+    if (turn === 'tool') return 'blocked';       // a call is open AND nothing moving ⇒ suspect
+    return 'quiet';                              // 'agent' (model call in flight) or null (no source)
+  }
+
+  /** Every (cadence, turn, presented) triple. The domain is small — walk it, don't sample it. */
+  function presentedStates() {
+    const out = [];
+    for (const cadence of CADENCE) {
+      for (const turn of TURN) out.push({ cadence, turn, presented: presented(cadence, turn) });
+    }
+    return out;
+  }
+
+  /** Does this presented state make the strong "this session wants you" claim? */
+  function isNeedsClaim(p) { return p === 'needs'; }
+
+  /**
+   * The full label for a row or tab: the word, plus the quiet clock's age on `quiet`, plus the open
+   * call's verb and age where the state carries it. `fmtDur` is injected (the client and the server
+   * format durations for different audiences) and the ages are computed by the CALLER, because this
+   * module reads no clock.
+   */
+  function label(p, { quietMs = null, call = null, fmtDur = null } = {}) {
+    const w = WORD[p] || p;
+    const d = (ms) => (fmtDur && ms != null ? fmtDur(ms) : null);
+    if (p === 'quiet') { const s = d(quietMs); return s ? `${w} ${s}` : w; }
+    if (CARRIES_CALL_AGE[p] && call && call.verb) {
+      const s = d(call.ageMs);
+      return s ? `${w} · ${call.verb} ${s}` : `${w} · ${call.verb}`;
+    }
+    return w;
+  }
+
+  return { CADENCE, TURN, PRESENTED, WORD, GLYPH, CARRIES_CALL_AGE,
+    presented, presentedStates, isNeedsClaim, label };
+});

package/workspace/lib/transcript-read.js

@@ -168,7 +168,7 @@ function prettyTool(name) {
  */
 function readHarness(file, clean = (x) => x) {
   const out = { model: null, effort: null, turns: 0, tokens: null, tools: null, skills: null,
-    title: null, openCall: null, missing: {} };
+    title: null, openCall: null, turn: null, missing: {} };
   let raw;
   try {
     const st = fs.statSync(file);
@@ -199,6 +199,11 @@ function readHarness(file, clean = (x) => x) {
   // report the raw fact {verb, sinceTs}; we never claim it is live.
   const openUse = new Map();       // tool_use_id → { verb, ts }  (insertion order = chronological)
   const resolved = new Set();      // tool_use_ids that got a tool_result
+  // WHOSE TURN IS IT (workspace-waiting-on-you R1). The last TURN-TAKING record's role — nothing
+  // more. `ai-title` and `attachment` records are CLI bookkeeping and are deliberately not
+  // turn-taking, and neither is a SYNTHETIC assistant record: counting one as "the assistant
+  // finished speaking" is exactly how a false `needs you` would be manufactured.
+  let lastRole = null;             // 'assistant' | 'user' | null
 
   for (const line of raw.split('\n')) {
     if (!line) continue;
@@ -217,6 +222,7 @@ function readHarness(file, clean = (x) => x) {
       for (const c of (Array.isArray(um.content) ? um.content : [])) {
         if (c && c.type === 'tool_result' && c.tool_use_id) resolved.add(c.tool_use_id);
       }
+      lastRole = 'user';           // a prompt was submitted, or a tool result landed
       continue;
     }
     if (r.type === 'attachment') {
@@ -234,6 +240,7 @@ function readHarness(file, clean = (x) => x) {
     if (m.model && m.model !== SYNTHETIC) {
       out.model = clean(m.model);
       out.turns++;                                  // only real model turns count
+      lastRole = 'assistant';                       // ...and only a real turn takes the turn
       if (r.effort) out.effort = clean(String(r.effort));
     }
     const u = m.usage || {};
@@ -260,6 +267,19 @@ function readHarness(file, clean = (x) => x) {
     if (!resolved.has(id)) out.openCall = { verb: info.verb, sinceTs: info.ts };
   }
 
+  // ── Whose turn (R1). Derived here, from what the pass already collected — no second walk. ──
+  // The ORDER of these three branches is the honesty property the whole feature rests on (R4).
+  // `tool` is tested FIRST, so any unresolved call claims the turn. A crashed session's dangling
+  // tool_use is a PERMANENT phantom (2/25 real transcripts), and a phantom is by definition an
+  // unresolved call — so a phantom always lands on `tool`, and `user` (the only turn from which
+  // the strong `needs you` claim can be built) is UNREACHABLE for it. Not a guard that rejects
+  // the phantom: a value it cannot construct. Reordering these branches silently converts a
+  // corpse into "waiting on you", which is the one lie this surface must not tell.
+  if (out.openCall) out.turn = 'tool';              // awaiting a tool — OR the PM's approval of one
+  else if (lastRole === 'assistant') out.turn = 'user';   // the model stopped; the human is up
+  else if (lastRole === 'user') out.turn = 'agent';       // a prompt/result landed; the model is up
+  // else: null — nothing turn-taking was parseable, so no claim is made.
+
   if (!out.model) out.missing.model = 'the transcript names no model yet';
   if (!out.effort) out.missing.effort = 'the transcript records no effort level';
   if (toolTotal) out.tools = { counts: toolCounts, total: toolTotal };
@@ -271,11 +291,13 @@ function readHarness(file, clean = (x) => x) {
   else out.missing.tokens = 'the transcript records no token usage yet';
   if (!out.skills) out.missing.skills = 'the CLI listed no skills for this session';
   if (!out.turns) out.missing.turns = 'no model turns in the transcript yet';
-  // NOTE: `title` and `openCall` deliberately get NO `missing` entry. This map carries reasons the
-  // UI RENDERS in place of a value; both of these instead fall back to a real shipped rendering
-  // (agent · cwd for an untitled session; the plain `working`/`quiet` word when no call is open).
-  // Putting them here would break the map's contract — "empty missing == everything was readable" —
-  // and put a reason on screen where a perfectly good value already goes.
+  // NOTE: `title`, `openCall` and `turn` deliberately get NO `missing` entry. This map carries
+  // reasons the UI RENDERS in place of a value; all three instead fall back to a real shipped
+  // rendering (agent · cwd for an untitled session; the plain `working`/`quiet` word when no call
+  // is open and when the turn is unknown). Putting them here would break the map's contract —
+  // "empty missing == everything was readable" — and put a reason on screen where a perfectly good
+  // value already goes. For `turn` that fallback IS the feature's refusal rule (R5): no second
+  // source, no claim, and the row reads exactly as it did before this existed.
 
   return out;
 }