create-pmos 0.4.0 → 0.6.0

package/workspace/lib/transcript-read.js

@@ -0,0 +1,247 @@
+'use strict';
+/**
+ * transcript-read — the harness, read from the agent CLI's own STRUCTURED record instead of
+ * from rendered terminal bytes.
+ *
+ * WHY THIS EXISTS. The first cut of the harness tower parsed scrollback, and four of six rows
+ * in the drill-in came back empty: the CLI does not PRINT its model, effort, token usage or
+ * skill set into the terminal. It writes them to a JSONL transcript. So the fix was never a
+ * better parser — it was the wrong source. Verified on this machine: 408 assistant records
+ * carrying message.model, record-level effort, message.usage token counts, and tool_use names
+ * with MCP attribution, plus one skill_listing attachment.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────
+ * VENDOR COUPLING — READ BEFORE CHANGING. Owner: the PM (wawan).
+ *
+ * This reads an UNDOCUMENTED internal file layout with no compatibility promise:
+ *   ~/.claude/sessions/<pid>.json          → {pid, sessionId, cwd, version, …}
+ *   ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl
+ * The registry file is version-stamped (seen: 2.1.220). When a CLI upgrade moves or reshapes
+ * either file, every signal here returns its FAILURE STATE — which is correct behaviour, not a
+ * bug to paper over. What to check: (1) does ~/.claude/sessions/<pid>.json still exist and
+ * carry sessionId + cwd? (2) is the transcript still <cwd-with-slashes-as-dashes>/<sessionId>.jsonl?
+ * (3) do assistant records still carry message.model / message.usage / content[].tool_use?
+ *
+ * THE RULE THAT MAKES THIS SAFE: no guessing, ever. In particular we NEVER fall back to
+ * "the newest .jsonl in this project directory" when the pid→session lookup misses. That
+ * fallback would silently render session B's model, tokens and tool counts on session A's row,
+ * and two claude sessions in one repo is the NORMAL case here — every session is confined to
+ * its workspace root. A miss renders "can't identify this session's transcript" and stops.
+ *
+ * THE ONE HOP WE DO TOLERATE (child-walk): the workspace's default pane is a SHELL, and the PM
+ * types `claude` INSIDE it, so the real agent is a DESCENDANT of the pane pid, which itself has
+ * no session record. When — and only when — the pane pid has no record of its own, we descend a
+ * BOUNDED number of process levels for a descendant that resolves, accepting it ONLY if its own
+ * registry cwd sits inside this workspace root. That is the SAME isolation proof the pane path
+ * makes, never a weaker one: identity still flows pid → session record → cwd-in-root. A
+ * descendant whose cwd escapes root is refused, not shown. This is emphatically NOT the
+ * "newest .jsonl" guess above — we still prove the identity of the pid we resolve.
+ *
+ * Read-only. Never writes to the PTY or to any CLI state (D62 — the harness runs untouched);
+ * the child-walk only reads a `ps` snapshot and session-record files.
+ * ─────────────────────────────────────────────────────────────────────────────────────────
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+
+// The child-walk is bounded so a deep shell nest can never stall a broadcast; past this depth the
+// refusal stands (an honest floor, not a silent truncation — the pane pid still had no record).
+const MAX_WALK_DEPTH = 2;
+
+const HOME = () => process.env.PMOS_CLAUDE_HOME || path.join(os.homedir(), '.claude');
+// A transcript can grow large; cap what we read so a long session cannot stall a broadcast.
+const MAX_BYTES = 8 * 1024 * 1024;
+// Synthetic assistant records are the CLI's own bookkeeping, not model turns — never counted,
+// and never a source for the model name (they carry the literal '<synthetic>').
+const SYNTHETIC = '<synthetic>';
+
+/** cwd → the CLI's project-directory slug. '/home/user/pmos' → '-home-user-pmos'. */
+function slugFor(cwd) {
+  return String(cwd || '').replace(/\//g, '-');
+}
+
+/**
+ * Default descendant lister: ONE `ps` snapshot → a ppid→children map → the direct children of
+ * `pid`. Injected in tests so the walk is exercised without real processes. Returns [] on any
+ * failure — a resolver miss must degrade to the refusal, never throw.
+ */
+function defaultChildren(pid) {
+  let out;
+  try {
+    out = cp.execFileSync('ps', ['-Ao', 'pid=,ppid='], { encoding: 'utf8', timeout: 2000 });
+  } catch {
+    return [];
+  }
+  const kids = new Map();
+  for (const line of out.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+    if (!m) continue;
+    const p = Number(m[1]);
+    const pp = Number(m[2]);
+    if (!kids.has(pp)) kids.set(pp, []);
+    kids.get(pp).push(p);
+  }
+  return kids.get(Number(pid)) || [];
+}
+
+/** Breadth-first descendants of `pid`, bounded to `maxDepth` levels. `listChildren(pid)->pids`. */
+function descendants(pid, listChildren, maxDepth = MAX_WALK_DEPTH) {
+  const seen = new Set([Number(pid)]);
+  let frontier = [Number(pid)];
+  const found = [];
+  for (let d = 0; d < maxDepth && frontier.length; d++) {
+    const next = [];
+    for (const p of frontier) {
+      for (const c of listChildren(p) || []) {
+        const cn = Number(c);
+        if (seen.has(cn)) continue;
+        seen.add(cn);
+        next.push(cn);
+        found.push(cn);
+      }
+    }
+    frontier = next;
+  }
+  return found;
+}
+
+/**
+ * Resolve ONE pid to its validated transcript. Returns {sessionId, file, version} on success, or a
+ * typed miss: {noRecord} (no session file for this pid — the shell case), {unreadable}, {outside}
+ * (cwd escapes root — the isolation refusal), or {noTranscript} (record exists, transcript not yet
+ * written). The cwd-in-root proof here is what makes the child-walk safe: it runs on EVERY pid we
+ * consider, pane or descendant, identically.
+ */
+function resolvePid(pid, root, home) {
+  let reg;
+  try {
+    reg = JSON.parse(fs.readFileSync(path.join(home, 'sessions', `${pid}.json`), 'utf8'));
+  } catch {
+    return { noRecord: true };
+  }
+  if (!reg || !reg.sessionId || !reg.cwd) return { unreadable: true };
+  const rel = path.relative(root, reg.cwd);
+  if (root && (rel.startsWith('..') || path.isAbsolute(rel))) return { outside: true };
+  const file = path.join(home, 'projects', slugFor(reg.cwd), `${reg.sessionId}.jsonl`);
+  if (!fs.existsSync(file)) return { noTranscript: true };
+  return { sessionId: reg.sessionId, file, version: reg.version || null };
+}
+
+/**
+ * Map a live process to its transcript. Returns {sessionId, file, version} or {missing}.
+ * `root` is the workspace root the session is confined to: the registry's own cwd must sit
+ * inside it, or we refuse — that is the isolation check, not a formality. When the pane pid has
+ * no record of its own (a SHELL the PM launched claude inside), descend a bounded number of
+ * process levels for a descendant that resolves in-root — see the child-walk note at the head.
+ * `listChildren` is injectable for tests; it defaults to a real `ps` snapshot.
+ */
+function findTranscript(pid, root, home = HOME(), listChildren = defaultChildren) {
+  if (!pid) return { missing: "can't identify this session's transcript — no process id" };
+  const direct = resolvePid(pid, root, home);
+  if (direct.sessionId) return direct;
+  // Only a pane with NO record of its own triggers the walk — that is precisely the shell-wrapped
+  // case. A pane that HAS a record (outside root, unreadable, or transcript-not-yet-written) is a
+  // real, identified session; we return its honest state rather than second-guessing it downward.
+  if (direct.noRecord) {
+    for (const child of descendants(pid, listChildren)) {
+      const r = resolvePid(child, root, home);
+      if (r.sessionId) return r;   // first in-root descendant with a real transcript wins
+    }
+    return { missing: "can't identify this session's transcript — the CLI wrote no session record" };
+  }
+  if (direct.outside) return { missing: "can't identify this session's transcript — it belongs to another workspace" };
+  if (direct.unreadable) return { missing: "can't identify this session's transcript — the session record is unreadable" };
+  return { missing: "can't read the harness — the CLI has written no transcript yet" };
+}
+
+/** Turn 'mcp__github__pull_request_read' into 'github/pull_request_read'. */
+function prettyTool(name) {
+  const m = /^mcp__(.+?)__(.+)$/.exec(String(name || ''));
+  return m ? `${m[1]}/${m[2]}` : String(name || '');
+}
+
+/**
+ * Read the harness out of a transcript. `clean` is server.js's scrub() — every string that can
+ * reach the screen goes through it (D08), because tool names and skill names are free text.
+ */
+function readHarness(file, clean = (x) => x) {
+  const out = { model: null, effort: null, turns: 0, tokens: null, tools: null, skills: null, missing: {} };
+  let raw;
+  try {
+    const st = fs.statSync(file);
+    const fd = fs.openSync(file, 'r');
+    try {
+      const start = Math.max(0, st.size - MAX_BYTES);
+      const len = st.size - start;
+      const buf = Buffer.allocUnsafe(len);
+      fs.readSync(fd, buf, 0, len, start);
+      raw = buf.toString('utf8');
+      if (start > 0) raw = raw.slice(raw.indexOf('\n') + 1);   // drop a partial first line
+    } finally { fs.closeSync(fd); }
+  } catch {
+    out.missing.all = "can't read the harness — the transcript could not be read";
+    return out;
+  }
+
+  const toolCounts = {};
+  let toolTotal = 0;
+  const tok = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+  let sawUsage = false;
+
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    let r;
+    try { r = JSON.parse(line); } catch { continue; }   // a torn line is skipped, never guessed
+    if (r.type === 'attachment') {
+      const a = r.attachment || {};
+      if (a.type === 'skill_listing' && typeof a.skillCount === 'number') {
+        out.skills = {
+          count: a.skillCount,
+          names: Array.isArray(a.names) ? a.names.slice(0, 40).map((n) => clean(String(n))) : [],
+        };
+      }
+      continue;
+    }
+    if (r.type !== 'assistant') continue;
+    const m = r.message || {};
+    if (m.model && m.model !== SYNTHETIC) {
+      out.model = clean(m.model);
+      out.turns++;                                  // only real model turns count
+      if (r.effort) out.effort = clean(String(r.effort));
+    }
+    const u = m.usage || {};
+    if (typeof u.input_tokens === 'number' || typeof u.output_tokens === 'number') {
+      sawUsage = true;
+      tok.input += u.input_tokens || 0;
+      tok.output += u.output_tokens || 0;
+      tok.cacheRead += u.cache_read_input_tokens || 0;
+      tok.cacheCreate += u.cache_creation_input_tokens || 0;
+    }
+    for (const c of (m.content || [])) {
+      if (c && c.type === 'tool_use' && c.name) {
+        const name = clean(prettyTool(c.name));
+        toolCounts[name] = (toolCounts[name] || 0) + 1;
+        toolTotal++;
+      }
+    }
+  }
+
+  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 };
+  else out.missing.tools = 'no tool calls in the transcript yet';
+  // Tokens are reported as ABSOLUTE counts and never as a percentage: the context window size
+  // is not in the record, and autocompaction makes the running total move backward. A percentage
+  // of an unknown denominator is not a quantity — that refusal predates this module and stands.
+  if (sawUsage) out.tokens = tok;
+  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';
+
+  return out;
+}
+
+module.exports = { findTranscript, readHarness, prettyTool, slugFor, resolvePid, descendants,
+  MAX_BYTES, MAX_WALK_DEPTH };

package/workspace/package-lock.json

@@ -0,0 +1,94 @@
+{
+  "name": "pmos-workspace",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pmos-workspace",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "@xterm/addon-fit": "^0.11.0",
+        "@xterm/addon-web-links": "^0.12.0",
+        "@xterm/xterm": "^5.5.0",
+        "node-pty": "^1.0.0",
+        "playwright-core": "^1.61.1",
+        "ws": "^8.18.0"
+      },
+      "bin": {
+        "pmos": "bin/pmos.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@xterm/addon-fit": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.11.0.tgz",
+      "integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==",
+      "license": "MIT"
+    },
+    "node_modules/@xterm/addon-web-links": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-web-links/-/addon-web-links-0.12.0.tgz",
+      "integrity": "sha512-4Smom3RPyVp7ZMYOYDoC/9eGJJJqYhnPLGGqJ6wOBfB8VxPViJNSKdgRYb8NpaM6YSelEKbA2SStD7lGyqaobw==",
+      "license": "MIT"
+    },
+    "node_modules/@xterm/xterm": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
+      "integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
+      "license": "MIT"
+    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT"
+    },
+    "node_modules/node-pty": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+      "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^7.1.0"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.61.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz",
+      "integrity": "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.21.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.1.tgz",
+      "integrity": "sha512-+0NTnW77fFN/DjQi6k/Sq/Yvk4Sgajw7urW8V+asjXnRgDs9gyGkdb7EzgfhA4goXsRIZKE28fzIXBHEzhuiWw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

package/workspace/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pmos-workspace",
+  "version": "0.1.0",
+  "private": true,
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
+  "license": "MIT",
+  "bin": { "pmos": "bin/pmos.js" },
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test.js",
+    "test:ui": "node ui-test.js",
+    "doctor": "node doctor.js"
+  },
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^5.5.0",
+    "node-pty": "^1.0.0",
+    "playwright-core": "^1.61.1",
+    "ws": "^8.18.0"
+  }
+}