@guenbankhai/tools 0.0.0-stage → 0.1.0

package/agentmoni/lib/graph.js

@@ -0,0 +1,106 @@
+// Fixed cards, compact staggered sibling rows, and private branches from each parent's trunk.
+// Shared by the page and node tests; coordinates are first computed as [cross, main].
+(function (root) {
+  const SIZE = { w: 340, h: 244 }, MARGIN = 24;
+  const FOLD = { w: 140, h: 26 };
+  const TRUNK = 36, LANE = 14, LABEL_W = 110, LABEL_V = 80, LABEL_H = 18, LABEL_GAP = 6;
+  const rowsOf = count => count > 12 ? 3 : count > 6 ? 2 : 1;
+
+  function layoutGraph(roots, { vertical = false, collapsed = new Set() } = {}) {
+    const { w, h } = SIZE, along = vertical ? h : w, across = vertical ? w : h;
+    const LEVEL = TRUNK + (vertical ? LABEL_V : LABEL_W) + 2 * LABEL_GAP, GAP = 72;
+    const kids = n => collapsed.has(n.id) ? [] : n.children ?? [];
+    const extent = new Map(), slots = new Map(), nodes = [], edges = [];
+    const measure = n => {
+      const list = kids(n), rows = rowsOf(list.length);
+      list.forEach(measure);
+      const centers = [];
+      list.forEach((k, i) => {
+        let at = extent.get(k) / 2;
+        for (let j = 0; j < i; j++) {
+          const separate = rows === 1 || kids(k).length || kids(list[j]).length;
+          at = Math.max(at, centers[j] + (separate ? (extent.get(list[j]) + extent.get(k)) / 2 + (rows === 1 ? 22 : GAP) : (i - j) * (across + GAP) / rows));
+        }
+        centers.push(at);
+      });
+      const width = Math.max(across, ...list.map((k, i) => centers[i] + extent.get(k) / 2));
+      slots.set(n, centers);
+      extent.set(n, width);
+    };
+    const place = (n, main, start, center = start + extent.get(n) / 2, next = main + along + LEVEL, parent = null) => {
+      const box = { id: n.id, x: vertical ? center - w / 2 : main, y: vertical ? main : center - h / 2, w, h };
+      nodes.push(box);
+      if (parent) edges.push([parent, box]);
+      const list = kids(n), rows = rowsOf(list.length);
+      list.forEach((k, i) => {
+        const cross = start + slots.get(n)[i];
+        place(k, next + (i % rows) * (along + LEVEL), cross - extent.get(k) / 2, cross, next + rows * (along + LEVEL), box);
+      });
+    };
+    let offset = MARGIN;
+    for (const r of roots) { measure(r); place(r, MARGIN, offset); offset += extent.get(r) + 44; }
+    const mainOf = n => vertical ? n.y : n.x, crossOf = n => vertical ? n.x : n.y;
+    const xy = p => vertical ? p : [p[1], p[0]];
+    // Assign routes through each band together; keep wide-gap lanes near their targets.
+    const routes = edges.map(([a, b]) => {
+      const s = [crossOf(a) + across / 2, mainOf(a) + along], t = [crossOf(b) + across / 2, mainOf(b)];
+      const bands = edges.filter(([p, c]) => p === a && mainOf(c) < t[1]).map(([, c]) => mainOf(c));
+      return { a, b, s, t, bands, lanes: new Map() };
+    });
+    for (const m of new Set(nodes.map(mainOf))) {
+      const blocks = nodes.filter(n => mainOf(n) === m).map(n => [crossOf(n), crossOf(n) + across]).sort((a, b) => a[0] - b[0]);
+      const gaps = [[blocks[0][0] - GAP, blocks[0][0]], ...blocks.slice(1).map((b, i) => [blocks[i][1], b[0]]), [blocks.at(-1)[1], blocks.at(-1)[1] + GAP]];
+      const groups = new Map();
+      for (const r of routes.filter(r => r.bands.includes(m))) {
+        const distance = ([lo, hi]) => Math.abs(Math.max(lo + 12, Math.min(hi - 12, r.t[0])) - r.t[0]);
+        const gap = gaps.filter(([lo, hi]) => hi - lo >= 36).sort((a, b) => distance(a) - distance(b))[0];
+        if (!groups.has(gap)) groups.set(gap, []);
+        groups.get(gap).push(r);
+      }
+      for (const [[lo, hi], group] of groups) {
+        group.sort((a, b) => a.t[0] - b.t[0]);
+        group.forEach((r, i) => {
+          const fraction = (i + 1) / (group.length + 1);
+          const lane = hi - lo > 2 * GAP ? Math.max(lo + GAP * fraction, Math.min(hi - GAP * (1 - fraction), r.t[0])) : lo + (hi - lo) * fraction;
+          r.lanes.set(m, lane);
+        });
+      }
+    }
+    const wires = routes.map(({ a, b, s, t, lanes }) => {
+      const p = [s, [s[0], s[1] + TRUNK]];
+      // Thread later-row edges through the gaps of each preceding row. Turns stay in the level gaps.
+      const bands = [...lanes.keys()].sort((x, y) => x - y);
+      for (const m of bands) {
+        const lane = lanes.get(m), bend = m - LEVEL + LANE;
+        p.push([p.at(-1)[0], bend], [lane, bend], [lane, m + along + LANE]);
+      }
+      const final = t[1] - LEVEL + TRUNK;
+      p.push([p.at(-1)[0], final], [t[0], final], t);
+      // Remove zero-length steps and redundant collinear points, retaining an axis-aligned route for inspection.
+      const points = [];
+      for (const q of p) {
+        if (points.length && q.every((v, i) => v === points.at(-1)[i])) continue;
+        while (points.length > 1 && [0, 1].some(i => points.at(-2)[i] === points.at(-1)[i] && points.at(-1)[i] === q[i])) points.pop();
+        points.push(q);
+      }
+      const q = points.map(xy), end = q.at(-1);
+      const label = vertical ? [end[0] + LABEL_GAP, end[1] - LABEL_GAP - LABEL_V / 2] : [end[0] - LABEL_GAP - LABEL_W / 2, end[1] - LABEL_GAP];
+      // Round bends with short cubic curves; the 12px card clearance also covers the moving dot.
+      let path = 'M' + q[0].join(' ');
+      for (let i = 1; i < q.length - 1; i++) {
+        const prev = q[i - 1], cur = q[i], next = q[i + 1];
+        const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+        const r = Math.min(8, dist(prev, cur) / 2, dist(cur, next) / 2);
+        const near = other => cur.map((v, j) => v + (other[j] - v) * r / dist(cur, other));
+        path += ' L' + near(prev).join(' ') + ' C' + cur.join(' ') + ' ' + cur.join(' ') + ' ' + near(next).join(' ');
+      }
+      path += ' L' + end.join(' ');
+      return { from: a.id, to: b.id, segments: q.slice(1).map((v, i) => [...q[i], ...v]), path, label, labelAlign: vertical ? 'start' : 'center' };
+    });
+    const extra = n => collapsed.has(n.id) ? (vertical ? FOLD.h / 2 : FOLD.w - FOLD.h / 2) : 0;
+    return { nodes, wires, width: Math.max(300, ...nodes.map(n => n.x + n.w + MARGIN + (vertical ? 0 : extra(n)))), height: Math.max(120, ...nodes.map(n => n.y + n.h + MARGIN + (vertical ? extra(n) : 0))) };
+  }
+
+  if (typeof module === 'object' && module.exports) module.exports = { layoutGraph, FOLD, LABEL_W, LABEL_V, LABEL_H };
+  else root.AgentGraph = { layoutGraph, FOLD, LABEL_W, LABEL_V, LABEL_H };
+})(typeof globalThis === 'object' ? globalThis : this);

package/agentmoni/lib/history.js

@@ -0,0 +1,50 @@
+// Shared history calculations for the browser and tests.
+(function (root) {
+  function subtree(node, depth = 0, seen = new Set()) {
+    if (!node || seen.has(node.key)) return [];
+    seen.add(node.key);
+    return [{ ...node, depth }, ...(node.children ?? []).flatMap(c => subtree(c, depth + 1, seen))];
+  }
+  // Copies of the live roots with their finished descendants (from `history`, by parent key) attached under the real parent. Finished sessions whose tree has no live root are left out.
+  function withFinished(roots, history) {
+    const live = n => ({ ...n, children: n.children.map(live) });
+    const out = roots.map(live), byKey = new Map();
+    const index = n => { byKey.set(n.key, n); n.children.forEach(index); };
+    out.forEach(index);
+    const ghosts = history.filter(s => !byKey.has(s.key)).map(s => ({ ...s, state: 'ended', lastActivityAt: s.endedAt, context: { tokens: null, limit: null }, done: 0, children: [] }));
+    ghosts.forEach(g => byKey.set(g.key, g));
+    const touched = new Set();
+    for (const g of ghosts) { const p = byKey.get(g.parent); if (p) { p.children.push(g); touched.add(p); } }
+    touched.forEach(p => p.children.sort((a, b) => a.startedAt - b.startedAt));
+    return out;
+  }
+  function union(intervals) {
+    const valid = intervals.filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b) && b >= a).sort((a, b) => a[0] - b[0]);
+    let active = 0, end = -Infinity;
+    for (const [a, b] of valid) { active += Math.max(0, b - Math.max(a, end)); end = Math.max(end, b); }
+    return { active, span: valid.length ? end - valid[0][0] : 0 };
+  }
+  function totals(rows, now = Date.now()) {
+    const kinds = {}, providers = {};
+    for (const s of rows) {
+      kinds[s.kind] = (kinds[s.kind] ?? 0) + 1;
+      const p = providers[s.provider] ??= { tokens: {}, share: {}, kinds: {} };
+      p.kinds[s.kind] = (p.kinds[s.kind] ?? 0) + 1;
+      for (const k of ['input', 'cacheRead', 'cacheWrite', 'output']) {
+        const v = s.tokens?.[k];
+        p.tokens[k] ??= null;
+        if (Number.isFinite(v)) p.tokens[k] = (p.tokens[k] ?? 0) + v;
+      }
+      for (const w of Object.keys(s.share ?? {})) {
+        const v = s.share?.[w]?.total;
+        if (!(w in p.share)) p.share[w] = 0;
+        p.share[w] = p.share[w] == null || !Number.isFinite(v) ? null : p.share[w] + v;
+      }
+    }
+    for (const [provider, p] of Object.entries(providers)) Object.assign(p, union(rows.filter(s => s.provider === provider).map(s => [s.startedAt, s.endedAt ?? (s.state === 'ended' ? s.lastActivityAt : now)])));
+    return { kinds, providers, ...union(rows.map(s => [s.startedAt, s.endedAt ?? (s.state === 'ended' ? s.lastActivityAt : now)])) };
+  }
+  const api = { subtree, withFinished, union, totals };
+  if (typeof module !== 'undefined') module.exports = api;
+  else root.AgentHistory = api;
+})(globalThis);

package/agentmoni/lib/json-fields.js

@@ -0,0 +1,58 @@
+// Read only selected non-secret string fields. Other values are skipped without decoding them.
+const fs = require('node:fs');
+function readFields(file, fields, presence = []) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    let i = 0;
+    const out = {};
+    const ws = () => { while (/\s/.test(text[i] ?? '') && i < text.length) i++; };
+    const expect = c => { ws(); if (text[i++] !== c) throw new Error('bad JSON'); };
+    function string(decode) {
+      const start = i;
+      expect('"');
+      while (i < text.length) {
+        const c = text[i++];
+        if (c === '"') return decode ? JSON.parse(text.slice(start, i)) : undefined;
+        if (c < ' ') throw new Error('bad string');
+        if (c === '\\') {
+          const e = text[i++];
+          if (e === 'u') { if (!/^[\da-f]{4}$/i.test(text.slice(i, i + 4))) throw new Error('bad escape'); i += 4; }
+          else if (!'"\\/bfnrt'.includes(e ?? ' ') || e === undefined) throw new Error('bad escape');
+        }
+      }
+      throw new Error('unfinished string');
+    }
+    function value(keys, depth = 0) {
+      if (depth > 100) throw new Error('too deep');
+      ws();
+      const prefix = keys.join('.');
+      for (const field of fields) if (field === prefix || field.startsWith(prefix + '.')) delete out[field];
+      const selected = fields.includes(keys.join('.'));
+      if (text[i] === '"') {
+        const exists = presence.includes(keys.join('.'));
+        const v = string(selected && !exists);
+        if (selected) out[keys.join('.')] = exists ? true : v;
+      }
+      else if (text[i] === '{' || text[i] === '[') {
+        const object = text[i++] === '{', end = object ? '}' : ']';
+        ws(); if (text[i] === end) { i++; return; }
+        do {
+          ws();
+          const key = object ? string(true) : '';
+          if (object) expect(':');
+          value([...keys, key], depth + 1);
+          ws(); if (text[i] === end) { i++; return; }
+          expect(',');
+        } while (i < text.length);
+        throw new Error('unfinished object');
+      } else {
+        const m = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(i));
+        if (!m) throw new Error('bad value');
+        i += m[0].length;
+      }
+    }
+    value([]); ws();
+    return i === text.length ? out : {};
+  } catch { return {}; }
+}
+module.exports = { readFields };

package/agentmoni/lib/jsonl.js

@@ -0,0 +1,43 @@
+// Reads agent logs (external data): unreadable files and malformed lines are skipped and counted, never fatal.
+const fs = require('node:fs');
+const path = require('node:path');
+
+// All .jsonl files under dir (not following symlinks) modified at or after sinceMs.
+function files(dir, sinceMs = 0) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  return entries.flatMap(e => {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) return files(full, sinceMs);
+    if (!e.isFile() || !e.name.endsWith('.jsonl')) return [];
+    try { return fs.statSync(full).mtimeMs >= sinceMs ? [full] : []; } catch { return []; }
+  });
+}
+
+// Calls visit(record) for each line where want(line) is true (a cheap string test that skips huge lines
+// before JSON.parse). Returns the number of malformed lines; an unreadable file counts as one.
+function scan(file, want, visit) {
+  let text, bad = 0;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return 1; }
+  for (const line of text.split('\n')) {
+    if (!line.trim() || !want(line)) continue;
+    let record;
+    try { record = JSON.parse(line); } catch { bad++; continue; }
+    if (record && typeof record === 'object') visit(record, line);
+  }
+  return bad;
+}
+
+// Parsed result per file, reused while the file's mtime and size are unchanged; callers must not mutate it.
+const cache = new Map();
+function cached(file, parse, store = cache) {
+  let st;
+  try { st = fs.statSync(file); } catch { return parse(file); }
+  const hit = store.get(file);
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit.value;
+  const value = parse(file);
+  store.set(file, { mtimeMs: st.mtimeMs, size: st.size, value });
+  return value;
+}
+
+module.exports = { files, scan, cached };

package/agentmoni/lib/launch.js

@@ -0,0 +1,118 @@
+// Finds registered agent launch commands in shell command position.
+function segments(line) {
+  const out = [];
+  let cur = '', quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '\\' && quote !== "'") { cur += ch + (line[i + 1] ?? ''); i++; continue; }   // an escaped character never opens, closes or splits (not inside '...')
+    if (quote) { if (ch === quote) quote = null; }
+    else if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '\n') { out.push(cur); return out; }
+    else if (ch === ';' || ch === '|' || ch === '&') {
+      if (ch !== ';' && line[i + 1] === ch) i++;
+      out.push(cur); cur = ''; continue;
+    }
+    cur += ch;
+  }
+  return [...out, cur];
+}
+
+// The launch segment of a command line: { kind, seg } or null.
+function launchSegment(command, max = 600, registry = require('./agents/index.js')) {
+  if (typeof command !== 'string') return null;
+  for (const seg of segments(command.slice(0, max))) {
+    const c = seg.trim().replace(/^(?:(?:\w+=\S+|time)\s+)+/, '');   // env assignments and `time` before the command
+    if (/\s(?:--help|-h)(?:\s|$)/.test(c)) continue;
+    for (const [kind, re] of registry.flatMap(a => a.launchPatterns)) if (re.test(c)) return { kind, seg: c };
+  }
+  return null;
+}
+const launchKind = (command, registry) => launchSegment(command, 600, registry)?.kind ?? null;
+
+// Letters and digits only: the shell drops quotes and backslashes, so a prompt in a launch command and in the thread differ in punctuation.
+const squash = t => String(t ?? '').toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+// text: only the quoted arguments of the launch segment itself (the prompt is one of them). A prompt passed by file or unquoted
+// stays out, so a thread cannot match words from another command on the same line; then the choice stays ambiguous.
+const launchOf = (at, kind, cmd, registry, full = false) => {
+  const line = cmd.split('\n')[0], seg = launchSegment(cmd, 65536, registry)?.seg ?? '';
+  const quoted = [...seg.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g)].map(m => m[1] ?? m[2]).join(' ');
+  return { at, kind, cmd: line.slice(0, 200), text: full ? squash(quoted) : [...seg.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g)].map(m => squash(m[1] ?? m[2]).slice(0, 40)).join(' ') };
+};
+
+// Full prompt text is indexed once per transcript version, separately from parsed sessions.
+const promptCache = new Map();
+function fullLaunchTexts(file, registry) {
+  const texts = new Map();
+  require('./jsonl.js').scan(file, line => registry.some(a => a.launchLine?.(line)), r => {
+    const calls = registry.flatMap(a => a.launchCalls?.(r) ?? []);
+    for (const [id, commands] of calls) {
+      if (typeof id !== 'string') continue;
+      const text = commands.filter(cmd => typeof cmd === 'string').map(cmd => launchOf(0, null, cmd, registry, true).text).filter(Boolean);
+      if (text.length) texts.set(id, [...(texts.get(id) ?? []), ...text]);
+    }
+  });
+  return texts;
+}
+
+// Revisit long commands only when their retained head cannot decide a prompt match.
+function matchesPrompt(launch, prompt, file, registry = require('./agents/index.js')) {
+  if (launch.text?.includes(prompt)) return true;
+  if (!launch.toolUseId || !file) return false;
+  if (!promptCache.has(registry)) promptCache.set(registry, new Map());
+  const texts = require('./jsonl.js').cached(file, f => fullLaunchTexts(f, registry), promptCache.get(registry));
+  return texts.get(launch.toolUseId)?.some(text => text.includes(prompt)) ?? false;
+}
+
+// Only literal paths are usable shell evidence.
+const literal = v => typeof v === 'string' && v && !/[$\x60*?{}()<>|&;\n]/.test(v) ? v : null;
+function launchCwd(cmd, cwd, flags = []) {
+  if (typeof cmd !== 'string') return cwd;
+  const parts = segments(cmd.slice(0, 65536));
+  const cds = parts.filter(s => /^\s*cd(?:\s|$)/.test(s));
+  if (cds.length && (cds.length !== 1 || cds[0] !== parts[0])) return null;
+  const cd = /^\s*cd\s+(?:"([^"\n]+)"|'([^'\n]+)'|([^\s;&]+))\s*(?:&&|;)/.exec(cmd);
+  if (cds.length && !cd) return null;
+  const resolve = v => {
+    v = literal(v);
+    if (!v || /^(?:~|-)|^\/(?:mnt\/)?[a-z]\/?$|^[a-z]:[^\\/]/i.test(v) || /^[a-z]:$/i.test(v)) return null;
+    // shortcut: resolve all paths as Windows paths, including Git Bash and WSL drive paths.
+    v = v.replace(/^\/(?:mnt\/)?([a-z])\//i, (_, drive) => drive.toUpperCase() + ':\\');
+    const path = require('node:path');
+    return path.win32.isAbsolute(v) ? path.win32.normalize(v) : cwd ? path.win32.resolve(cwd, v) : null;
+  };
+  if (cd) {
+    cwd = resolve(cd[1] ?? cd[2] ?? cd[3]);
+    if (!cwd) return null;
+  }
+  const seg = launchSegment(cmd, 65536)?.seg ?? '';
+  const args = [];
+  const tokens = /\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([^\s"']+))/gy;
+  let m;
+  while ((m = tokens.exec(seg))) args.push({ value: m[1] ?? m[2] ?? m[3], bare: m[3] != null });
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].bare || !flags.includes(args[i].value) || args[i + 1] == null) continue;
+    cwd = resolve(args[++i].value);   // a non-literal value gives no cwd, like a non-literal cd
+    if (!cwd) return null;
+  }
+  return cwd;
+}
+function resultJob(content) {
+  const text = typeof content === 'string' ? content : Array.isArray(content) ? content.filter(c => typeof c?.text === 'string').map(c => c.text).join('\n') : '';
+  const ids = [...new Set(text.match(/\btask-[a-z0-9]+-[a-z0-9]+\b/g) ?? [])];
+  return ids.length === 1 ? ids[0] : null;
+}
+// Only structured CLI records carry session evidence; prose is not proof.
+function resultSessions(content) {
+  const texts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(c => typeof c?.text === 'string').map(c => c.text) : [];
+  const ids = new Set();
+  for (const text of texts) {
+    for (const part of [text, ...text.split('\n')]) {
+      try {
+        const r = JSON.parse(part);
+        if (typeof r?.session_id === 'string' && /^[a-zA-Z0-9_-]+$/.test(r.session_id)) ids.add(r.session_id);
+      } catch { /* not a JSON record */ }
+    }
+  }
+  return [...ids];
+}
+module.exports = { launchKind, squash, launchOf, launchCwd, resultJob, resultSessions, matchesPrompt };

package/agentmoni/lib/limits.js

@@ -0,0 +1,11 @@
+// Context limits from agent-local sources, refreshed once per minute.
+const agents = require('./agents/index.js');
+function createLimits(options = {}) {
+  const registry = options.registry ?? agents;
+  let table, at = 0;
+  return (provider, model, now = Date.now()) => {
+    if (!table || now - at > 60000) { table = Object.fromEntries(registry.map(a => [a.id, a.loadLimits?.(options)])); at = now; }
+    return table[provider]?.get(String(model ?? '').replace(/\[1m\]$/, '')) ?? null;
+  };
+}
+module.exports = { createLimits };

package/agentmoni/lib/links.js

@@ -0,0 +1,139 @@
+// Parent-child links: proven evidence first, then conservative command inference.
+const agents = require('./agents/index.js');
+const { squash, matchesPrompt } = require('./launch.js');
+const key = s => `${s.provider}:${s.id}`;
+const norm = cwd => typeof cwd === 'string' ? cwd.replace(/^\/([a-z])\//i, '$1:/').replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase() : null;
+
+const WINDOW_MS = 90 * 1000;   // B starts within this after the launch command
+const PROMPT_KEY = 40, PROMPT_MIN = 12;   // letters of B's first prompt compared with the launch command; shorter proves nothing
+const SKEW_MS = 2000;         // clocks of two logs may disagree slightly
+
+// Which launch command could have created B (null: B is not something a command starts).
+// The session owning the nearest ancestor process of B's process (the process table must hold the whole chain).
+// A parent must have started no later than its child, or the pid was reused by an unrelated process.
+function parentByProcess(b, procs, owners) {
+  const byPid = new Map(procs.map(p => [p.pid, p]));
+  let p = byPid.get(b.pid);
+  for (let i = 0; p && i < 32; i++) {
+    const child = p;
+    p = byPid.get(p.ppid);
+    if (p && !(p.startMs <= child.startMs)) return null;
+    const owner = p && owners.get(p.pid);
+    if (owner && owner !== key(b)) return { owner, pid: p.pid };
+  }
+  return null;
+}
+
+// sessions come from resolveStates (they carry state and pid). -> { sessions, warnings }; input objects are not changed.
+function link(sessions, { procs = [], pluginJobs = [], registry = agents } = {}) {
+  const adapter = s => registry.find(a => a.id === s.provider);
+  const out = sessions.map(s => ({ ...s, parent: null, link: null }));
+  const byKey = new Map(out.map(s => [key(s), s]));
+  const owners = new Map(out.filter(s => s.pid != null && s.state !== 'ended').map(s => [s.pid, key(s)]));
+  const ambiguous = [];   // { sessions, parents, text }: links the data cannot decide
+  const attach = (s, parent, evidence) => {
+    const seen = new Set([key(s)]);
+    for (let p = parent; p; p = byKey.get(p)?.parent) {
+      if (seen.has(p)) {
+        ambiguous.push({ sessions: [key(s)], parents: [parent], text: `${key(s)} -> ${parent} would create a cycle: not linked` });
+        return;
+      }
+      seen.add(p);
+    }
+    s.parent = parent;
+    s.link = evidence;
+  };
+
+  const claimed = new Map();
+  for (const a of out) for (const l of a.launches ?? []) {
+    const keys = registry.flatMap(adapter => adapter.launchClaims?.(l) ?? []);
+    for (const k of keys) {
+      claimed.set(k, [...(claimed.get(k) ?? []), { a, l, count: keys.length }]);
+    }
+  }
+  const blocked = new Set();
+  for (const s of out) {
+    const claims = claimed.get(key(s));
+    if (!claims) continue;
+    const { a, l, count } = claims.reduce((first, c) => c.l.at < first.l.at ? c : first), parent = key(a);
+    const processParent = s.pid != null ? parentByProcess(s, procs, owners)?.owner : null;
+    if ((processParent && processParent !== parent) || new Set(claims.map(c => key(c.a))).size !== 1 || count !== 1 || parent === key(s) || (s.parentId && parent !== s.provider + ':' + s.parentId)) {
+      blocked.add(key(s));
+      ambiguous.push({ sessions: [key(s)], parents: [...new Set(claims.map(c => key(c.a)))], text: key(s) + ' has conflicting launch proofs: not linked' });
+    } else attach(s, parent, { kind: 'proven', label: l.kind, evidence: { sessionId: s.id, toolUseId: l.toolUseId } });
+  }
+  for (const s of out) {
+    if (blocked.has(key(s)) || s.link || !s.parentId) continue;
+    attach(s, `${s.provider}:${s.parentId}`, { kind: 'proven', label: adapter(s).parentLabel, evidence: { file: s.source.file, at: s.startedAt, ...(s.agentType ? { agentType: s.agentType } : {}) } });
+  }
+
+  const picks = [];
+  for (const b of out) {
+    if (blocked.has(key(b))) continue;
+    const exact = adapter(b).launchProofs?.(b, pluginJobs, out) ?? [];
+    const want = exact[0]?.label ?? adapter(b).launchKindOf(b);
+    if (!want || b.link) continue;
+    const policy = adapter(b).launchPolicy(want, b);
+    const parentProviders = policy.parentOrigin == null ? null : registry.filter(a => a.originators?.includes(policy.parentOrigin)).map(a => a.id);
+    const proofs = [...exact, ...(adapter(b).provenLinks?.(b, pluginJobs, out) ?? [])].flatMap(p => {
+      if (p.parent) return [p];
+      // Link records may name a session without its agent. Prefer sessions we actually read;
+      // for a missing parent, resolve the origin label through the declarations.
+      const known = out.filter(s => s.id === p.parentId && key(s) !== key(b));
+      const providers = known.length ? known.map(s => s.provider) : registry.filter(a => a.originators?.includes(p.parentOrigin)).map(a => a.id);
+      return providers.map(provider => ({ ...p, parent: `${provider}:${p.parentId}` }));
+    });
+    const parents = [...new Set(proofs.map(p => p.parent))];
+    if (parents.length > 1) {
+      ambiguous.push({ sessions: [key(b)], parents, text: `${key(b)} has conflicting parents: not linked` });
+      continue;
+    }
+    if (parents.length === 1) {
+      attach(b, parents[0], { kind: 'proven', label: want, evidence: proofs[0].evidence });
+      continue;
+    }
+    // A command-started process can be traced up to the session that ran it. Shared hosts cannot supply a process link.
+    const hit = policy.process && b.pid != null ? parentByProcess(b, procs, owners) : null;
+    if (hit) {
+      attach(b, hit.owner, { kind: 'proven', label: want, evidence: { pid: b.pid, parentPid: hit.pid, file: b.source.file, at: b.startedAt } });
+      continue;
+    }
+    const cands = [];
+    for (const a of out) {
+      if (a === b || (parentProviders && !parentProviders.includes(a.provider))) continue;
+      for (const l of a.launches ?? []) {
+        if (norm(l.cwd === undefined ? a.cwd : l.cwd) == null || norm(l.cwd === undefined ? a.cwd : l.cwd) !== norm(b.cwd)) continue;
+        const d = b.startedAt - l.at;
+        if (!l.sessionIds?.length && l.kind === want && d >= -SKEW_MS && d <= WINDOW_MS) cands.push({ a, l, d });
+      }
+    }
+    // The prompt B started with is inside the command that started it: when some launches carry it, only those count.
+    const p = squash(b.prompt).slice(0, PROMPT_KEY);
+    const named = p.length >= PROMPT_MIN ? cands.filter(c => matchesPrompt(c.l, p, c.a.source?.file, registry)) : [];
+    const fits = new Map();   // parent key -> its launch closest before B
+    for (const { a, l, d } of named.length ? named : cands) {
+      if (!fits.has(key(a)) || d < fits.get(key(a)).d) fits.set(key(a), { d, l, file: a.source.file, byPrompt: named.length > 0 });
+    }
+    if (fits.size > 1) ambiguous.push({ sessions: [key(b)], parents: [...fits.keys()], text: `${key(b)} could belong to ${[...fits.keys()].join(' or ')}: not linked` });
+    if (fits.size === 1) picks.push({ b, want, parent: [...fits.keys()][0], ...[...fits.values()][0] });
+  }
+  // One launch that fits several sessions cannot say which it started: link none of them.
+  const uses = new Map();
+  for (const p of picks) uses.set(`${p.parent}@${p.want}@${p.l.at}`, [...(uses.get(`${p.parent}@${p.want}@${p.l.at}`) ?? []), p.b]);
+  // All proven edges are attached before these inferences, so weaker evidence cannot displace them.
+  for (const p of picks) {
+    const users = uses.get(`${p.parent}@${p.want}@${p.l.at}`);
+    if (users.length > 1) { if (users[0] === p.b) ambiguous.push({ sessions: users.map(key), parents: [p.parent], text: `one launch by ${p.parent} fits ${users.map(key).join(' and ')}: not linked` }); continue; }
+    attach(p.b, p.parent, { kind: 'inferred', label: p.want, evidence: { command: p.l.cmd, at: p.l.at, file: p.file, ...(p.byPrompt ? { match: 'prompt' } : {}) } });
+  }
+
+  for (const s of out) {
+    if (s.link && s.kind === 'standalone') s.kind = 'sub';
+    else if (!s.link && s.kind === 'sub' && !s.parentId) s.kind = 'standalone';   // a plugin thread whose parent is unknown
+    // A child still alive under an ended parent keeps working with nobody waiting for it.
+    s.orphan = s.state !== 'ended' && byKey.get(s.parent)?.state === 'ended';
+  }
+  return { sessions: out, warnings: ambiguous.map(a => a.text), ambiguous };
+}
+
+module.exports = { link };

package/agentmoni/lib/list.js

@@ -0,0 +1,71 @@
+// Debug listing of the sessions found on this machine, with links and quota shares:
+// agentmoni --list [--project <path>] [--days N] [--live] [--json]
+const path = require('node:path');
+const { createMonitor } = require('./monitor.js');
+const { providersOf } = require('./present.js');
+const agents = require('./agents/index.js');
+const windowsOf = p => (agents.find(a => a.id === p)?.windows ?? []).map(w => w.id);
+const { totals } = require('./history.js');
+const { tok: k, pct, dur } = require('./format.js');
+
+const norm = p => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
+const inside = (cwd, root) => typeof cwd === 'string' && (norm(cwd) === root || norm(cwd).startsWith(root + path.sep));
+const split = sh => sh ? `${pct(sh.total)} [I ${pct(sh.input)} CR ${pct(sh.cacheRead)} CW ${pct(sh.cacheWrite)} O ${pct(sh.output)}]` : '—';
+
+function accountLine(name, a, outside, now) {
+  const w = x => {
+    const r = a.windows[x];
+    return r ? `${x} ${pct(r.percent)}%${r.resetsAt ? ` reset ${dur(r.resetsAt - now)}` : ''} ${r.at ? ` (read ${dur(now - r.at)} ago)` : ''}${r.stale ? ' stale' : ''}` : `${x} —`;
+  };
+  return `${name.padEnd(6)} ${windowsOf(name).map(w).join('   ')}   outside monitor: ${windowsOf(name).map(x => `${x} +${pct(outside[x])}%`).join(' ')}${a.error ? `   warning: ${a.error}` : ''}`;
+}
+
+async function main(argv) {
+  const arg = name => { const i = argv.indexOf(name); return i < 0 ? null : argv[i + 1]; };
+  const days = Number(arg('--days') ?? 7), now = Date.now();
+  const project = arg('--project'), root = project ? norm(project) : null;
+  const monitor = createMonitor({ days: Math.max(days, 8) });
+  monitor.start(now);
+  const r = await monitor.refresh({ now, waitQuota: true });
+  monitor.stop();
+  const named = new Map([...(r.history ?? []), ...r.sessions].map(s => [`${s.provider}:${s.id}`, s]));
+  const inScope = s => {
+    const seen = new Set();
+    for (let a = s; a && !seen.has(a); a = named.get(a.parent)) {
+      if (inside(a.cwd, root)) return true;
+      seen.add(a);
+    }
+    return false;
+  };
+  const sessions = r.sessions
+    .filter(s => s.lastActivityAt >= now - days * 86400e3 && (root == null || inScope(s)) && (!argv.includes('--live') || s.state !== 'ended'))
+    .sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  if (argv.includes('--json')) return console.log(JSON.stringify({ accounts: r.accounts, outside: r.outside, sessions, warnings: r.warnings, ambiguous: r.ambiguous }, null, 2));
+  for (const p of providersOf(r)) console.log(accountLine(p, r.accounts[p], r.outside[p], now));
+  for (const s of sessions) {
+    const t = s.tokens;
+    console.log([s.provider, s.kind, (s.turn === 'aborted' ? '⊘ interrupted' : s.state) + (s.orphan ? ' orphan' : '') + (s.resume ? ` resume ${s.resume}` : ''), s.model ?? '—', s.effort ?? '',
+      new Date(s.lastActivityAt).toISOString().slice(0, 16), `I ${k(t.input)} CR ${k(t.cacheRead)} CW ${k(t.cacheWrite)} O ${k(t.output)} ctx ${k(s.context)}`,
+      s.name ?? '', s.link ? `<- ${s.parent} (${s.link.kind}, ${s.link.label})` : ''].join(' | '));
+    console.log('    ' + windowsOf(s.provider).map(w => `${w}\u2248${split(s.share[w])}`).join('   '));
+    if (r.sessions.some(c => c.parent === `${s.provider}:${s.id}`)) {
+      const own = s.shareTree[s.provider];
+      console.log('    with children: ' + windowsOf(s.provider).map(w => `${w}\u2248${pct(own[w]?.total)}`).join('   '));
+    }
+  }
+  for (const line of totalsLines(sessions, now)) console.log(line);
+  for (const w of [...r.warnings, ...r.ambiguous.map(a => a.text)]) console.error('warning:', w);
+}
+
+if (require.main === module) main(process.argv.slice(2));
+function totalsLines(rows, now) {
+  if (!rows.length) return [];
+  const t = totals(rows, now);
+  const lines = Object.entries(t.providers).map(([name, p]) => {
+    const v = p.tokens;
+    const kinds = ['main', 'sub', 'standalone'].filter(kind => p.kinds[kind] > 0).map(kind => `${kind} ${p.kinds[kind]}`).join(', ');
+    return `total ${name} | ${kinds} | active ${dur(p.active)} | I ${k(v.input)} CR ${k(v.cacheRead)} CW ${k(v.cacheWrite)} O ${k(v.output)} | ${Object.keys(p.share).map(w => `${w}\u2248${pct(p.share[w])}`).join(' ')}`;
+  });
+  return [...lines, `total all | sessions ${rows.length} | active ${dur(t.active)} | span ${dur(t.span)}`];
+}
+module.exports = { main, totalsLines };