create-pmos 0.5.0 → 0.6.0

package/workspace/lib/schedule-logic.js

@@ -0,0 +1,132 @@
+'use strict';
+/* schedule-logic.js — the pure cadence math for scheduled tasks.
+ *
+ * Harvested from pm-os `do-worker/src/schedule-logic.mjs`: no I/O, no globals, importable by the
+ * server tick AND (conceptually) the GUI's "next run" preview — so what the PM is shown is exactly
+ * what will fire. Window-based due-ness, NO catch-up (a missed slot is skipped, per the PRD): a
+ * schedule is due iff a scheduled slot falls in the interval (lastRun, now].
+ *
+ * A schedule: { cadence:'daily'|'weekly'|'bi-weekly'|'monthly', day:'Mon'..'Sun' (weekly/bi-weekly),
+ *   dayOfMonth:1..28 (monthly), time:'HH:MM', enabled, lastRun:ISO|null }. Times are host-local (v1).
+ */
+
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];   // JS getDay() index
+const CADENCES = ['daily', 'weekly', 'bi-weekly', 'monthly'];
+
+function parseTime(t) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(t || '09:00'));
+  if (!m) return { h: 9, m: 0 };
+  return { h: Math.min(23, +m[1]), m: Math.min(59, +m[2]) };
+}
+function atTime(d, time) {
+  const { h, m } = parseTime(time);
+  const x = new Date(d);
+  x.setHours(h, m, 0, 0);
+  return x;
+}
+function dayIndex(day) { const i = DAYS.indexOf(String(day)); return i < 0 ? 1 : i; }   // default Mon
+
+// The most recent scheduled slot at or before `now` (Date), or null if none exists yet.
+function lastSlot(schedule, now) {
+  const cad = schedule.cadence;
+  if (cad === 'daily') {
+    const today = atTime(now, schedule.time);
+    return today <= now ? today : addDays(today, -1);
+  }
+  if (cad === 'weekly' || cad === 'bi-weekly') {
+    // walk back from today to the most recent matching weekday at time
+    const want = dayIndex(schedule.day);
+    let d = atTime(now, schedule.time);
+    for (let i = 0; i < 8; i++) {
+      if (d.getDay() === want && d <= now) return d;
+      d = addDays(d, -1);
+    }
+    return null;
+  }
+  if (cad === 'monthly') {
+    const dom = Math.min(28, Math.max(1, +schedule.dayOfMonth || 1));
+    let d = atTime(now, schedule.time); d.setDate(dom);
+    if (d > now) { d = new Date(d); d.setMonth(d.getMonth() - 1); d.setDate(dom); }
+    return d;
+  }
+  return null;
+}
+// The next scheduled slot strictly after `now`.
+function nextSlot(schedule, now) {
+  const cad = schedule.cadence;
+  if (cad === 'daily') {
+    const today = atTime(now, schedule.time);
+    return today > now ? today : addDays(today, 1);
+  }
+  if (cad === 'weekly' || cad === 'bi-weekly') {
+    const want = dayIndex(schedule.day);
+    let d = atTime(now, schedule.time);
+    for (let i = 0; i < 8; i++) {
+      if (d.getDay() === want && d > now) return d;
+      d = addDays(d, 1);
+    }
+    return null;
+  }
+  if (cad === 'monthly') {
+    const dom = Math.min(28, Math.max(1, +schedule.dayOfMonth || 1));
+    let d = atTime(now, schedule.time); d.setDate(dom);
+    if (d <= now) { d = new Date(d); d.setMonth(d.getMonth() + 1); d.setDate(dom); }
+    return d;
+  }
+  return null;
+}
+function addDays(d, n) { const x = new Date(d); x.setDate(x.getDate() + n); return x; }
+
+// Is the schedule due to fire at `now`? Enabled + a slot in (lastRun, now]. For bi-weekly, also
+// require ≥ 13 days since lastRun (weekly slots, fired every other week).
+function isDue(schedule, now = new Date()) {
+  if (!schedule || !schedule.enabled) return false;
+  const slot = lastSlot(schedule, now);
+  if (!slot) return false;
+  const last = schedule.lastRun ? new Date(schedule.lastRun) : null;
+  if (last && last >= slot) return false;
+  if (schedule.cadence === 'bi-weekly' && last) {
+    if ((now - last) / 86400000 < 13) return false;
+  }
+  return true;
+}
+// The next fire time as an ISO string (or null).
+function nextRun(schedule, now = new Date()) {
+  const s = nextSlot(schedule, now);
+  return s ? s.toISOString() : null;
+}
+// A short human phrase for the pane, e.g. "every Fri at 09:00".
+function humanCadence(schedule) {
+  const t = schedule.time || '09:00';
+  switch (schedule.cadence) {
+    case 'daily': return `every day at ${t}`;
+    case 'weekly': return `every ${schedule.day || 'Mon'} at ${t}`;
+    case 'bi-weekly': return `every other ${schedule.day || 'Mon'} at ${t}`;
+    case 'monthly': return `monthly on day ${schedule.dayOfMonth || 1} at ${t}`;
+    default: return schedule.cadence || '';
+  }
+}
+// Validate/normalize a schedule submitted by the client. Returns { ok, schedule } or { ok:false, error }.
+function normalizeSchedule(input) {
+  const s = input || {};
+  if (!s.name || !String(s.name).trim()) return { ok: false, error: 'name is required' };
+  if (!CADENCES.includes(s.cadence)) return { ok: false, error: 'invalid cadence' };
+  if (!s.skill || !String(s.skill).trim()) return { ok: false, error: 'a skill-backed task is required' };
+  return {
+    ok: true,
+    schedule: {
+      name: String(s.name).trim().slice(0, 80),
+      cadence: s.cadence,
+      day: s.day || 'Mon',
+      dayOfMonth: Math.min(28, Math.max(1, +s.dayOfMonth || 1)),
+      time: parseTimeStr(s.time),
+      tz: s.tz || 'local',
+      task: s.task || s.skill,
+      skill: String(s.skill).trim(),
+      enabled: s.enabled !== false,
+    },
+  };
+}
+function parseTimeStr(t) { const { h, m } = parseTime(t); return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`; }
+
+module.exports = { CADENCES, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };

package/workspace/lib/skill-store.js

@@ -0,0 +1,143 @@
+'use strict';
+/* skill-store.js — file-driven skills. ONE user-facing concept.
+ *
+ * A "skill" is a named, repeatable task with a consistent-output contract. HOW it runs — the server
+ * derives it instantly, or a `claude` PTY session reasons through it — is an INTERNAL field (`run:`)
+ * the picker never exposes. That collapses the old deterministic-vs-agent "kind" leak the PM (rightly)
+ * found confusing (workspace-skill-authoring): from the user's view there is just a skill.
+ *
+ * A skill file (`*.skill`) is frontmatter + a body procedure:
+ *   - frontmatter: name, description, and an `output` list = the section keys it ALWAYS produces
+ *     (the consistency contract, mirroring the surface-contract shape check).
+ *   - body: the procedure. For an agent skill this is the prompt fed to the session; for a built-in
+ *     deterministic skill the body is documentation (the server derives the output from `surface`).
+ *
+ * Built-in skills ship committed under workspace/skills/; user-authored skills are scaffolded by the
+ * New Skill flow into a writable dir (state/skills/, gitignored like other state). Pure of the network
+ * (D54) — fs only, no deps, unit-testable directly.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// A skill name is a short slug — it is both the id and the filename stem, so it must be path-safe.
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+const MAX_OUTPUT = 20;
+
+function slugify(s) {
+  return String(s || '').toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+}
+function titleCase(s) {
+  return String(s || '').replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function stripQuotes(v) { return String(v).replace(/^["']|["']$/g, ''); }
+
+// A permissive mini-parser: an optional leading `---` frontmatter block (scalar `key: value` and
+// one-level `- ` lists), then the body. No YAML dependency — the format is deliberately tiny and
+// self-explanatory (the ACI design principle, D19). Unknown keys are tolerated.
+function parseSkill(text) {
+  const src = String(text || '');
+  const fm = {}; const lists = {};
+  let body = src.trim();
+  const lines = src.split('\n');
+  if (lines[0] && lines[0].trim() === '---') {
+    let curList = null; let closed = false; let bodyStart = 1;
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.trim() === '---') { bodyStart = i + 1; closed = true; break; }
+      const item = line.match(/^\s*-\s+(.*)$/);
+      if (item && curList) { lists[curList].push(item[1].trim()); continue; }
+      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+      if (kv) {
+        const key = kv[1]; const val = kv[2].trim();
+        if (val === '') { curList = key; lists[key] = lists[key] || []; }
+        else { fm[key] = stripQuotes(val); curList = null; }
+      }
+    }
+    if (closed) body = lines.slice(bodyStart).join('\n').trim();
+  }
+  const name = fm.name || '';
+  // `run` is the ONLY internal signal: deterministic (server fast-path) vs agent (a PTY session).
+  const run = /^det/i.test(fm.run || '') ? 'deterministic' : 'agent';
+  return {
+    name,
+    label: fm.label || titleCase(name),
+    description: fm.description || '',
+    run,
+    surface: fm.surface || null,
+    agent: fm.agent || 'claude',
+    output: (lists.output || []).filter(Boolean).slice(0, MAX_OUTPUT),
+    body,
+  };
+}
+
+function loadDir(dir, source) {
+  const out = [];
+  let ents = [];
+  try { ents = fs.readdirSync(dir); } catch { return out; }
+  for (const f of ents.sort()) {
+    if (!f.endsWith('.skill')) continue;
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    const s = parseSkill(text);
+    const id = s.name || f.replace(/\.skill$/, '');
+    if (!NAME_RE.test(id)) continue;   // an unparseable/hostile filename never becomes a skill
+    out.push({ ...s, name: id, id, skill: id, source, file: path.join(dir, f) });
+  }
+  return out;
+}
+
+// Merge a list of {dir, source} — LATER dirs override earlier by id. Callers pass user dirs first and
+// built-ins last, so a built-in's load-bearing fast-path can never be shadowed by a user file.
+function loadSkills(dirs) {
+  const byId = new Map();
+  for (const { dir, source } of dirs) for (const s of loadDir(dir, source)) byId.set(s.id, s);
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// Scaffold a well-formed user skill file from the New Skill flow's fields. Returns { ok, slug, content }
+// or { ok:false, error }. User skills default to run:agent — a user-authored skill reasons through a
+// claude session (the existing agent path); the deterministic fast-path is reserved for the built-ins.
+function scaffoldSkill({ name, description, output, body } = {}) {
+  const slug = slugify(name);
+  if (!NAME_RE.test(slug)) return { ok: false, error: 'name must be a short slug (letters, digits, hyphens)' };
+  const label = titleCase(name) || slug;
+  const desc = String(description || '').replace(/[\r\n]+/g, ' ').trim().slice(0, 240);
+  let out = Array.isArray(output) ? output : String(output || '').split(/[\n,]/);
+  out = out.map((x) => String(x).replace(/\s+/g, ' ').trim()).filter(Boolean).slice(0, MAX_OUTPUT);
+  if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
+  const proc = String(body || '').trim() || defaultBody(label, desc, out);
+  const content = [
+    '---',
+    `name: ${slug}`,
+    `label: ${JSON.stringify(label)}`,
+    `description: ${JSON.stringify(desc)}`,
+    'run: agent',
+    'agent: claude',
+    'output:',
+    ...out.map((o) => `  - ${o}`),
+    '---',
+    '',
+    proc,
+    '',
+  ].join('\n');
+  return { ok: true, slug, label, description: desc, output: out, content };
+}
+
+function defaultBody(label, desc, out) {
+  return [
+    `You are running the "${label}" skill in this PMOS workspace (local, file mode).`,
+    '',
+    `Goal: ${desc || '(describe what this skill should do)'}`,
+    '',
+    'Produce a deliverable with EXACTLY these sections — the consistency contract, the same shape',
+    'every run:',
+    ...out.map((o) => `  - ${o}`),
+    '',
+    'Ground everything in this repository\'s own local files and tools only (no network). When you are',
+    'done, write the deliverable and file a short note to needs-you so the PM sees the result.',
+  ].join('\n');
+}
+
+module.exports = { NAME_RE, slugify, titleCase, parseSkill, loadDir, loadSkills, scaffoldSkill };

package/workspace/lib/surface-contract.js

@@ -0,0 +1,79 @@
+'use strict';
+/* surface-contract.js — the deliverable contract for on-demand workspace surfaces.
+ *
+ * Harvested from pm-os `do-worker/src/deliverable-contract.mjs` (the pm-os intake, Cluster J / J1):
+ * each surface TYPE declares the shape it must carry, and a deterministic check validates a surface
+ * BEFORE it renders — so "reliable when the PM needs it" is ENFORCED, not hoped. Pure: no I/O, no
+ * DOM, no deps, importable by the server and unit-tested directly.
+ *
+ * A required item FIELD may be null — that means "not tracked in state yet" (RICE/effort/…), and the
+ * renderer shows "— not tracked" for it. The contract only insists the KEY exists, so the surface can
+ * never silently drop a field; it can only honestly say it doesn't have the value. The `min` on the
+ * primary collection is the "can't-produce" floor: a surface with nothing to show fails the contract
+ * and the client renders the explicit can't-produce state instead of a blank or partial view.
+ */
+
+const CONTRACTS = Object.freeze({
+  initiatives: {
+    label: 'Initiative list',
+    top: ['initiatives', 'pulse', 'needs'],
+    item: { key: 'initiatives', min: 1, fields: ['id', 'status', 'phase'] },
+  },
+  roadmap: {
+    label: 'Roadmap',
+    top: ['groups'],
+    item: { key: 'groups', min: 1, fields: ['label', 'items'] },
+  },
+  okr: {
+    label: 'OKR + levers',
+    top: ['objectives'],
+    item: { key: 'objectives', min: 1, fields: ['id', 'krs'] },
+  },
+  report: {
+    label: 'Report',
+    top: ['cadence', 'sections'],
+    item: { key: 'sections', min: 3, fields: ['heading'] },
+  },
+});
+
+function checkSurface(type, data) {
+  const c = CONTRACTS[type];
+  if (!c) {
+    return { pass: false, missing: ['contract'],
+      checks: [{ name: 'known-type', pass: false, reason: `no contract for surface "${type}"` }] };
+  }
+  data = data || {};
+  const checks = [];
+  const missing = [];
+
+  // 1) required top-level keys are present
+  for (const k of c.top) {
+    const present = data[k] !== undefined && data[k] !== null;
+    checks.push({ name: `has:${k}`, pass: present, reason: present ? 'present' : 'absent' });
+    if (!present) missing.push(k);
+  }
+
+  // 2) the primary collection carries at least `min` items (the can't-produce floor)
+  const it = c.item;
+  const arr = Array.isArray(data[it.key]) ? data[it.key] : [];
+  const enough = arr.length >= it.min;
+  checks.push({ name: `min:${it.key}`, pass: enough, reason: `${arr.length} / ${it.min} required` });
+  if (!enough) missing.push(it.key);
+
+  // 3) every item carries its required field KEYS (a null value = "not tracked", still valid)
+  let fieldOk = true;
+  let offendingField = null;
+  for (const item of arr) {
+    for (const f of it.fields) {
+      if (!item || !Object.prototype.hasOwnProperty.call(item, f)) { fieldOk = false; offendingField = f; break; }
+    }
+    if (!fieldOk) break;
+  }
+  checks.push({ name: 'item-fields', pass: fieldOk,
+    reason: fieldOk ? `every item carries ${it.fields.join(', ')}` : `an item is missing "${offendingField}"` });
+  if (!fieldOk) missing.push('item-fields');
+
+  return { pass: checks.every((x) => x.pass), missing, checks };
+}
+
+module.exports = { CONTRACTS, checkSurface };

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