@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/fleet/projects.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * `fleet --action projects` (093 IC-019): the projects this machine knows, from two read-only
+ * stores: the user-state `upkeep-roots` index and the `cwd` of each hook project directory
+ * (`<config home>/doflow/session-env/projects/<hash>/meta.json`). A candidate is kept when it is an
+ * existing directory (not a symlink) whose git work-tree top holds `.doflow/` and is not under a
+ * temp folder; candidates that share a git common dir are one project. `root` (the main checkout)
+ * is for the Console server only. Nothing is written: no lock, no mkdir, no upkeep.
+ * @returns {{ok: false, error: 'cannot-list-projects'} | {ok: true, body: Object}}
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { cwdHash, stateDir } = require('../context/identity.js');
+const { listCheckouts } = require('../checkouts.js');
+const { resolveRoots } = require('../storage/roots.js');
+const { loadStorageRegistry } = require('../storage/registry.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const HOOK_DIR_LIMIT = 2000;
+const PROBE_LIMIT = 500; // git probes per call: each is one process, and the Console polls this
+const META_MAX_BYTES = 64 * 1024;
+const LABEL = /^[A-Za-z0-9 ._:/@-]{1,64}$/;
+const FIXED_TEMP_ROOTS = ['/private/tmp', '/private/var/folders'];
+
+                                              
+
+function realOrNull(p        , fsImpl     )                {
+  try { return fsImpl.realpathSync(p); } catch { return null; }
+}
+
+function under(p        , root        )          {
+  return p === root || p.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+}
+
+/** The label rule of IC-004: at most 64 characters of `[A-Za-z0-9 ._:/@-]`, else `(withheld)`. */
+function label(name        )         {
+  return LABEL.test(name) ? name : '(withheld)';
+}
+
+function iso(ms        )                {
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function lstatOrNull(p        , fsImpl     )      {
+  try { return fsImpl.lstatSync(p); } catch { return null; }
+}
+
+function listProjects({
+  env = process.env, cwd = process.cwd(), exec = spawnSync, fsImpl = fs, tempRoots,
+}                                                                              = {})      {
+  const excluded = { missing: 0, temp: 0, notDoflow: 0, unreadable: 0 };
+  const body      = { v: 1, store: 'absent', projects: [], excluded, truncated: false };
+
+  const userState = resolveRoots({ registry: loadStorageRegistry({ repoRoot: REPO_ROOT }), projectRoot: null, global: true, env })['user-state'];
+  const hooks = stateDir(env);
+  if (userState === null && hooks === null) return { ok: true, body };
+  body.store = 'present';
+
+  // Candidates keyed by the path as written; each keeps its sources and the newest last_active seen.
+  const candidates = new Map                                                    ();
+  const add = (dir        , source        , activeMs = -Infinity) => {
+    const c = candidates.get(dir) ?? { sources: new Set        (), activeMs: -Infinity };
+    c.sources.add(source);
+    c.activeMs = Math.max(c.activeMs, activeMs);
+    candidates.set(dir, c);
+  };
+
+  if (userState !== null) {
+    const file = path.join(userState, 'upkeep-roots');
+    const info = lstatOrNull(file, fsImpl);
+    if (info && info.isFile()) {
+      let text = '';
+      try { text = fsImpl.readFileSync(file, 'utf8'); } catch { excluded.unreadable += 1; }
+      for (const line of text.split('\n')) {
+        if (line === '') continue;
+        if (path.isAbsolute(line)) add(line, 'upkeep-roots'); else excluded.unreadable += 1;
+      }
+    }
+  }
+
+  if (hooks !== null) {
+    const base = path.join(hooks, 'projects');
+    let dirs                                           = [];
+    try {
+      for (const dirent of fsImpl.readdirSync(base, { withFileTypes: true })) {
+        if (!dirent.isDirectory()) continue;
+        const st = lstatOrNull(path.join(base, dirent.name), fsImpl);
+        if (st) dirs.push({ name: dirent.name, mtimeMs: st.mtimeMs });
+      }
+    } catch { /* no hook project directories */ }
+    dirs.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.name < b.name ? -1 : 1));
+    if (dirs.length > HOOK_DIR_LIMIT) { body.truncated = true; dirs = dirs.slice(0, HOOK_DIR_LIMIT); }
+    for (const { name } of dirs) {
+      const file = path.join(base, name, 'meta.json');
+      const info = lstatOrNull(file, fsImpl);
+      if (!info) continue; // a directory with no meta.json is not a record
+      let meta     ;
+      try {
+        if (!info.isFile() || info.size > META_MAX_BYTES) throw new Error('unreadable');
+        meta = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+      } catch { excluded.unreadable += 1; continue; }
+      if (meta === null || typeof meta !== 'object' || typeof meta.cwd !== 'string' || !path.isAbsolute(meta.cwd)) { excluded.unreadable += 1; continue; }
+      add(meta.cwd, 'hook-dirs', typeof meta.last_active === 'string' ? Date.parse(meta.last_active) : -Infinity);
+    }
+  }
+
+  const temp = [...(tempRoots ?? [realOrNull(os.tmpdir(), fsImpl) ?? os.tmpdir(), ...FIXED_TEMP_ROOTS])];
+  const isTemp = (p        ) => temp.some((root) => under(p, root));
+
+  /** `git rev-parse` for one directory: its work-tree top and common git dir, or itself when outside git. */
+  const probe = (dir        )                                                  => {
+    let res     ;
+    try {
+      res = exec('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'], { encoding: 'utf8', timeout: 10000 });
+    } catch (error     ) { res = { error }; }
+    if (res && res.error && res.error.code === 'ENOENT') return 'git-missing';
+    const lines = res && !res.error && res.status === 0 ? String(res.stdout || '').split('\n') : [];
+    const top = lines[0] ? realOrNull(lines[0], fsImpl) : null;
+    const common = lines[1] ? realOrNull(lines[1], fsImpl) : null;
+    if (top !== null && common !== null) return { top, common };
+    const self = realOrNull(dir, fsImpl) ?? dir;
+    return { top: self, common: self };
+  };
+
+                                                                                           
+  const groups = new Map               ();
+  let probes = 0;
+  for (const [dir, candidate] of candidates) {
+    const info = lstatOrNull(dir, fsImpl);
+    if (!info || info.isSymbolicLink() || !info.isDirectory()) { excluded.missing += 1; continue; }
+    const real = realOrNull(dir, fsImpl);
+    if (real === null) { excluded.missing += 1; continue; }
+    if (isTemp(real)) { excluded.temp += 1; continue; }
+    if (probes >= PROBE_LIMIT) { body.truncated = true; continue; }
+    probes += 1;
+    const found = probe(dir);
+    if (found === 'git-missing') return { ok: false, error: 'cannot-list-projects' };
+    const doflow = lstatOrNull(path.join(found.top, '.doflow'), fsImpl);
+    if (!doflow || !doflow.isDirectory()) { excluded.notDoflow += 1; continue; }
+    if (isTemp(found.top)) { excluded.temp += 1; continue; }
+    const due = lstatOrNull(path.join(found.top, '.doflow', 'state', 'upkeep-due'), fsImpl);
+    const g = groups.get(found.common) ?? { common: found.common, tops: new Set        (), sources: new Set        (), lastMs: -Infinity };
+    g.tops.add(found.top);
+    for (const s of candidate.sources) g.sources.add(s);
+    g.lastMs = Math.max(g.lastMs, candidate.activeMs, due && due.isFile() ? due.mtimeMs : -Infinity);
+    groups.set(found.common, g);
+  }
+
+  const here = groups.size > 0 ? probe(cwd) : null;
+  if (here === 'git-missing') return { ok: false, error: 'cannot-list-projects' };
+
+  const projects = [...groups.values()].map((g) => {
+    const first = [...g.tops].sort()[0];
+    const listed = listCheckouts({ cwd: first, exec, fsImpl });
+    const real = (p         ) => (typeof p === 'string' ? realOrNull(p, fsImpl) : null);
+    const main = (listed.ok && real(listed.main)) || first;
+    const count = listed.ok ? listed.entries.filter((e     ) => !e.sandbox).length : g.tops.size;
+    return {
+      projectKey: cwdHash(main),
+      root: main,
+      label: label(path.basename(main)),
+      current: here !== null && g.common === here.common,
+      checkouts: Math.max(count, 1),
+      sources: ['upkeep-roots', 'hook-dirs'].filter((s) => g.sources.has(s)),
+      lastRecordAt: iso(g.lastMs),
+    };
+  });
+  const time = (p     ) => (p.lastRecordAt === null ? -Infinity : Date.parse(p.lastRecordAt));
+  projects.sort((a, b) => Number(b.current) - Number(a.current) || time(b) - time(a) || (a.projectKey < b.projectKey ? -1 : 1));
+  body.projects = projects;
+  return { ok: true, body };
+}
+
+module.exports = { listProjects };

package/src/runtime/fleet/tree.js

@@ -0,0 +1,383 @@
+'use strict';
+
+/**
+ * `fleet --action tree` (093 IC-020): one project's agent hierarchy as nodes and edges, built from
+ * records that already exist and written to nowhere. Sources: IC-018 a sessions (hook observations
+ * joined to the session directory), the harnesses' own sub-agent records read through V.4's readers
+ * (`header`, and the metadata mode for the last record time), task attempts by run/lineage, worker runs
+ * (caller, `childOf`, binding, end, a bounded process check) and the dispatch `primary` snapshot.
+ * Every edge names the record it comes from; two nodes merge only on a shared key (a runKey, a run id,
+ * an agent key), never on a harness or a model. A label is the record's own role text, never invented.
+ * A transcript is joined by session id alone (gate-a Q4 A); nothing is written, no path, pid or raw
+ * session id is printed. `internal` (not part of the body) carries what V.6 needs per node: the file to open, and
+ * `records` (DoFlow's own records of the agent: type, time, task, result) and `holds` (the tasks it is working on).
+ * @returns {{ok: false, error: string} | {ok: true, body: Object, internal: Map<string, Object>}}
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { cwdHash, stateDir } = require('../context/identity.js');
+const { observedSessions } = require('../context/primary.js');
+const { listCheckouts } = require('../checkouts.js');
+const { readTaskState } = require('../task-state.js');
+const { readRuns } = require('../worker/run-store.js');
+const processTree = require('../worker/process-tree.js');
+const { loadTranscriptRegistry } = require('../transcripts/registry.js');
+const { readJsonFile, label } = require('../transcripts/cursor.js');
+const { isSafeSlug } = require('../task-scope.js');
+
+const MAX_SESSIONS = 64;
+const MAX_NODES = 256;
+const MAX_CHECKS = 16;
+const SCAN_FILES = 200;
+const LIST_CAP = 2000;
+const SUBAGENT_FILES = 64;
+const NEEDLE_BYTES = 2 * 1024 * 1024;
+const SESSION_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RUN_KEY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+const sha16 = (text        )         => crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+const READERS                            = {
+  'claude-jsonl': () => require('../transcripts/readers/claude-jsonl.js'),
+  'codex-rollout': () => require('../transcripts/readers/codex-rollout.js'),
+  'kiro-jsonl': () => require('../transcripts/readers/kiro-jsonl.js'),
+  'copilot-events': () => require('../transcripts/readers/copilot-events.js'),
+  'pi-jsonl': () => require('../transcripts/readers/pi-jsonl.js'),
+};
+/** How each harness encodes a cwd into its transcript directory name (research section 3). */
+const ENCODE                                          = {
+  claude: (cwd) => cwd.replace(/[^A-Za-z0-9]/g, '-'),
+  pi: (cwd) => cwd.replace(/^[\\/]/, '').replace(/[\\/:]/g, '-'),
+};
+
+function regularFile(file        , fsImpl     )          {
+  try { return fsImpl.lstatSync(file).isFile(); } catch { return false; }
+}
+
+/** Files under `root` matching a glob whose only wildcard is `*` inside one path segment. */
+function expandGlob(root        , pattern        , fsImpl     )           {
+  let found = [root];
+  for (const seg of pattern.split('/')) {
+    const next           = [];
+    if (!seg.includes('*')) for (const dir of found) next.push(path.join(dir, seg));
+    else {
+      const re = new RegExp(`^${seg.split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')}$`);
+      for (const dir of found) {
+        let names           = [];
+        try { names = fsImpl.readdirSync(dir); } catch { /* not a directory */ }
+        for (const name of names.slice(0, LIST_CAP)) if (re.test(name)) next.push(path.join(dir, name));
+      }
+    }
+    found = next.slice(0, LIST_CAP);
+  }
+  return found.filter((file) => regularFile(file, fsImpl)).sort();
+}
+
+/** The registry locations of `entry` for this platform, as `[root, glob]` pairs with the base resolved. */
+function locations(entry     , env     , home        , platform        )                          {
+  const out                          = [];
+  for (const loc of entry.locations) {
+    if (loc.os !== platform || loc.status === 'unknown') continue;
+    let base                = null;
+    if (loc.base === 'home') base = home;
+    else if (loc.base === 'xdg-data') base = env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+    else if (loc.base.startsWith('env:')) base = env[loc.base.slice(4)] || null;
+    if (base) out.push([path.join(base, ...loc.segments), loc.glob]);
+  }
+  return out;
+}
+
+/** Does `file` hold `needle` in its first 2 MiB? Only the yes or no leaves this function. */
+function fileHas(file        , needle        , fsImpl     )          {
+  try {
+    const fd = fsImpl.openSync(file, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(NEEDLE_BYTES, fsImpl.fstatSync(fd).size));
+      fsImpl.readSync(fd, buf, 0, buf.length, 0);
+      return buf.toString('latin1').includes(needle);
+    } finally { fsImpl.closeSync(fd); }
+  } catch { return false; }
+}
+
+function buildTree({
+  env = process.env, cwd = process.cwd(), exec = spawnSync, fsImpl = fs, platform = process.platform, home, alive = processTree.alive, now = Date.now,
+}      = {})      {
+  const observed = observedSessions({ env, cwd, exec, fsImpl, now });
+  if (!observed.ok) return { ok: false, error: observed.error };
+  const listed = listCheckouts({ cwd, exec, fsImpl });
+  const checkouts           = listed.ok ? listed.entries.filter((e     ) => !e.sandbox).map((e     ) => e.path) : [];
+  const projectKey = cwdHash(listed.ok ? listed.main : cwd);
+  const homeDir = home ?? env.HOME ?? os.homedir();
+  const loaded = loadTranscriptRegistry();
+  const registry                      = {};
+  for (const entry of loaded.ok ? loaded.registry.entries : []) registry[entry.harness] = entry;
+
+  const nodes = new Map             ();
+  const edges = new Map             ();
+  const internal = new Map             ();
+  const counts = { unreadable: 0, notChecked: 0 };
+  let checks = 0;
+
+  /** The node for `agentKey`, created once: a second source with the same key adds what the first lacked. */
+  const node = (agentKey        , fields     , intern      )      => {
+    let n = nodes.get(agentKey);
+    if (!n) {
+      if (nodes.size >= MAX_NODES) { counts.notChecked += 1; return null; }
+      n = {
+        agentKey, kind: null, harness: null, model: null, modelBasis: null, label: null, depth: 0, worktreeKey: projectKey,
+        startedAt: null, lastRecordAt: null, liveness: 'not-checked', ended: null, transcript: { reader: null, linked: false, reason: 'no-reader' },
+        ...fields,
+      };
+      nodes.set(agentKey, n);
+      internal.set(agentKey, { kind: fields.kind, records: [], holds: [] });
+    } else {
+      for (const [key, value] of Object.entries(fields)) if (n[key] === null) n[key] = value;
+    }
+    Object.assign(internal.get(agentKey), intern ?? {});
+    return n;
+  };
+  /** One of DoFlow's own records of an agent (`records`) or a task it is working on (`holds`), kept for V.6. */
+  const note = (n     , list                     , item     )       => { if (n) internal.get(n.agentKey)[list].push(item); };
+  const slugOf = (store     , name        )         => (isSafeSlug(store?.slug) ? store.slug : name.replace(/\.json$/, ''));
+  const edge = (from        , to        , basis        )       => {
+    if (from !== to) edges.set(`${from}|${to}|${basis}`, { from, to, basis }); // kept only when both ends are nodes, below
+  };
+  const harnessOf = (id         )                => (typeof id !== 'string' ? null : registry[id] ? id : '(other)');
+  const transcriptOf = (harness               , file               )      => {
+    const entry = harness ? registry[harness] : null;
+    if (!entry) return { reader: null, linked: false, reason: 'no-reader' };
+    if (entry.join === 'none') return { reader: null, linked: false, reason: 'not-linked' };
+    if (entry.reader === null) return { reader: null, linked: false, reason: 'no-reader' };
+    return file ? { reader: entry.reader, linked: true, reason: null } : { reader: entry.reader, linked: false, reason: 'not-found' };
+  };
+  const lastAt = (harness        , file        , companion         )                => {
+    try {
+      const out = READERS[registry[harness].reader]().read({ file, companion, mode: 'metadata', maxBytes: 32768, limit: 64 });
+      return [...out.events].reverse().find((e     ) => e.at)?.at ?? null;
+    } catch { return null; }
+  };
+
+  // ---- main sessions (IC-018 a) and the transcript each one's id names ----------------------------------
+  const sessions        = observed.body.sessions.filter((s     ) => s.kind === 'hook');
+  counts.notChecked += Math.max(0, sessions.length - MAX_SESSIONS);
+  const root = stateDir(env);
+  const rawIds = new Map                ();
+  if (root !== null) {
+    try { for (const name of fsImpl.readdirSync(path.join(root, 'sessions')).slice(0, LIST_CAP)) if (SESSION_DIR.test(name)) rawIds.set(sha16(name), name); } catch { /* none */ }
+  }
+  const scanned = new Map             (); // harness -> [{file, companion, header}] of the bounded scan
+  const scan = (harness        )        => {
+    if (scanned.has(harness)) return scanned.get(harness);
+    const entry = registry[harness];
+    const files           = [];
+    if (entry && entry.reader) {
+      for (const [dir, glob] of locations(entry, env, homeDir, platform)) {
+        if (harness === 'pi') for (const c of checkouts) files.push(...expandGlob(dir, glob.replace('{cwdEncoded}', ENCODE.pi(c)), fsImpl));
+        else files.push(...expandGlob(dir, glob.replace('{sessionId}', '*').replace('{cwdEncoded}', '*'), fsImpl));
+      }
+    }
+    const newest = harness === 'kiro' || harness === 'pi'
+      ? files.map((file) => { try { return { file, t: fsImpl.lstatSync(file).mtimeMs }; } catch { return { file, t: 0 }; } }).sort((a, b) => b.t - a.t).map((x) => x.file)
+      : [...files].sort().reverse();
+    const out        = [];
+    for (const file of [...new Set(newest)].slice(0, SCAN_FILES)) {
+      try { out.push({ file, header: READERS[entry.reader]().header({ file }) }); } catch { counts.unreadable += 1; }
+    }
+    scanned.set(harness, out);
+    return out;
+  };
+  const locate = (harness        , id        )                => {
+    const entry = registry[harness];
+    if (!entry || !entry.reader || entry.join === 'none' || !SESSION_DIR.test(id)) return null;
+    if (harness === 'pi') return scan('pi').find((x) => x.header.sessionId === id)?.file ?? null;
+    for (const [dir, glob] of locations(entry, env, homeDir, platform)) {
+      const hit = expandGlob(dir, glob.replace('{sessionId}', id).replace('{cwdEncoded}', '*'), fsImpl)[0];
+      if (hit) return hit;
+    }
+    return null;
+  };
+
+  const mains        = [];
+  for (const s of sessions.slice(0, MAX_SESSIONS)) {
+    const harness = harnessOf(s.harness);
+    const rawId = rawIds.get(s.sessionKey) ?? null;
+    const file = harness && rawId ? locate(harness, rawId) : null;
+    const agentKey = sha16(`${harness ?? ''}:${rawId ?? s.sessionKey}`);
+    const companion = file && harness === 'kiro' ? file.replace(/\.jsonl$/, '.json') : undefined;
+    const n = node(agentKey, {
+      kind: 'main-session', harness, model: label(s.model), modelBasis: s.model ? 'hook-observation' : null, worktreeKey: s.worktreeKey,
+      startedAt: s.startedAt, lastRecordAt: (file && harness && lastAt(harness, file, companion)) || s.lastHookRecordAt,
+      transcript: transcriptOf(harness, file),
+    }, { harness, sessionId: rawId, file, companion });
+    if (n) {
+      mains.push({ n, harness, rawId, file });
+      if (s.startedAt) note(n, 'records', { type: 'hook-record', at: s.startedAt, task: null, result: null });
+      if (s.lastHookRecordAt && s.lastHookRecordAt !== s.startedAt) note(n, 'records', { type: 'hook-record', at: s.lastHookRecordAt, task: null, result: null });
+    }
+  }
+
+  // ---- harness sub-agent records (IC-020 sources), through the readers' header ---------------------------
+  const child = (parent     , harness        , idPart        , header     , file               , companion         )       => {
+    const agentKey = sha16(`${harness}:${idPart}`);
+    const depth = Number.isInteger(header.depth) ? header.depth : parent.depth + 1;
+    const n = node(agentKey, {
+      kind: 'harness-subagent', harness, model: header.model, modelBasis: header.model ? 'harness-record' : null, label: header.label, depth,
+      worktreeKey: parent.worktreeKey, lastRecordAt: file ? lastAt(harness, file, companion) : null, transcript: transcriptOf(harness, file),
+    }, { harness, sessionId: header.sessionId, agentId: header.agentId, file, companion });
+    if (n) edge(parent.agentKey, agentKey, 'harness-subagent-record');
+  };
+  for (const { n, harness, rawId, file } of mains) {
+    if (!harness || !rawId || !file || !registry[harness]) continue;
+    const reader = READERS[registry[harness].reader]();
+    try {
+      if (harness === 'claude') {
+        const dir = path.join(path.dirname(file), path.basename(file, '.jsonl'), 'subagents');
+        let names           = [];
+        try { names = fsImpl.readdirSync(dir).filter((x        ) => /^agent-.+\.jsonl$/.test(x)).sort().slice(0, SUBAGENT_FILES); } catch { /* none */ }
+        const subs = names.map((name) => {
+          const sub = path.join(dir, name);
+          const meta = readJsonFile(sub.replace(/\.jsonl$/, '.meta.json')) || {};
+          return { sub, header: reader.header({ file: sub }), toolUseId: typeof meta.toolUseId === 'string' ? meta.toolUseId : null };
+        });
+        const made = new Map               ();
+        for (const s of subs.sort((a, b) => (a.header.depth ?? 1) - (b.header.depth ?? 1))) {
+          const depth = s.header.depth ?? 1;
+          // A depth-1 agent was spawned by the main session; deeper ones by the file that holds their tool_use id.
+          const candidates = depth <= 1 ? [{ file, node: n }] : made.get(depth - 1) ?? [];
+          const parent = depth <= 1 ? candidates[0] : candidates.find((c) => s.toolUseId !== null && fileHas(c.file, s.toolUseId, fsImpl));
+          const agentId = s.header.agentId ?? path.basename(s.sub, '.jsonl').replace(/^agent-/, '');
+          const agentKey = sha16(`claude:${rawId}:${agentId}`);
+          const made1 = node(agentKey, {
+            kind: 'harness-subagent', harness, model: s.header.model, modelBasis: s.header.model ? 'harness-record' : null, label: s.header.label, depth,
+            worktreeKey: n.worktreeKey, lastRecordAt: lastAt(harness, s.sub), transcript: transcriptOf(harness, s.sub),
+          }, { harness, sessionId: rawId, agentId, file: s.sub });
+          if (!made1) continue;
+          if (parent) edge(parent.node.agentKey, agentKey, 'harness-subagent-record');
+          made.set(depth, [...(made.get(depth) ?? []), { file: s.sub, node: made1 }]);
+        }
+      } else if (harness === 'copilot') {
+        for (const c of reader.header({ file }).children) child(n, harness, `${rawId}:${c.agentId}`, { ...c, model: null, sessionId: rawId }, null);
+      } else if (harness === 'codex' || harness === 'pi' || harness === 'kiro') {
+        // Children name their parent session id in their own header: follow the chain through the bounded scan.
+        const parents = new Map             ([[rawId, n]]);
+        const headers = scan(harness);
+        for (let grew = true; grew;) {
+          grew = false;
+          for (const h of headers) {
+            const p = h.header.parentSessionId;
+            if (!p || !parents.has(p) || !h.header.sessionId || parents.has(h.header.sessionId)) continue;
+            const companion = harness === 'kiro' ? h.file.replace(/\.jsonl$/, '.json') : undefined;
+            child(parents.get(p), harness, h.header.sessionId, h.header, h.file, companion);
+            const made = nodes.get(sha16(`${harness}:${h.header.sessionId}`));
+            if (made) { parents.set(h.header.sessionId, made); grew = true; }
+          }
+        }
+      }
+    } catch { counts.unreadable += 1; }
+  }
+
+  // ---- DoFlow records: attempts, worker runs, dispatch --------------------------------------------------
+  const readStores = (checkout        , dirName        , read                       )                       => {
+    const dir = path.join(checkout, '.doflow', 'state', dirName);
+    let names           = [];
+    try { names = fsImpl.readdirSync(dir).filter((x        ) => x.endsWith('.json')).sort(); } catch { return []; }
+    const out                       = [];
+    for (const name of names) {
+      try { const data = read(path.join(dir, name)); if (data) out.push([name, data]); } catch { counts.unreadable += 1; }
+    }
+    return out;
+  };
+  const runNode = (runKey        , extra      = {})      => {
+    if (!RUN_KEY.test(runKey)) return null;
+    return node(sha16(`doflow:${runKey}`), { kind: 'doflow-run', worktreeKey: runKey.split('/')[0], ...extra }, { runKey });
+  };
+  const attemptRuns = new Map             (); // `task#token` -> runKey of the attempt
+  for (const checkout of checkouts) {
+    for (const [name, store] of readStores(checkout, 'task-attempts', (file) => readTaskState(fsImpl, file))) {
+      for (const [taskId, entry] of Object.entries(store.tasks ?? {})                        ) {
+        for (const a of Array.isArray(entry?.attempts) ? entry.attempts : []) {
+          if (typeof a.runKey !== 'string') continue;
+          attemptRuns.set(`${taskId}#${a.token}`, a.runKey);
+          const at = [a.endedAt, a.finishedAt, a.startedAt].find((v) => typeof v === 'string') ?? null;
+          const n = runNode(a.runKey, { startedAt: typeof a.startedAt === 'string' ? a.startedAt : null, lastRecordAt: at });
+          if (n) {
+            if (typeof a.owner === 'string' && (n.label === null || (at ?? '') >= (n.lastRecordAt ?? ''))) n.label = label(a.owner);
+            if (at && (n.lastRecordAt === null || at > n.lastRecordAt)) n.lastRecordAt = at;
+            if (typeof a.startedAt === 'string' && (n.startedAt === null || a.startedAt < n.startedAt)) n.startedAt = a.startedAt;
+            const task = label(taskId);
+            if (typeof a.startedAt === 'string') note(n, 'records', { type: 'attempt-claim', at: a.startedAt, task, result: null });
+            const endedAt = [a.finishedAt, a.endedAt].find((v) => typeof v === 'string');
+            if (endedAt) note(n, 'records', { type: 'attempt-end', at: endedAt, task, result: typeof a.result === 'string' ? label(a.result) : null });
+            if (a.state === 'active') note(n, 'holds', { slug: slugOf(store, name), task: taskId });
+          }
+        }
+      }
+    }
+  }
+
+  const runs = new Map             ();
+  for (const checkout of checkouts) {
+    for (const [name, byId] of readStores(checkout, 'worker-runs', (file) => readRuns(file, fsImpl))) {
+      for (const [runId, run] of Object.entries(byId)                        ) if (!runs.has(runId)) runs.set(runId, { run, checkout, slug: slugOf(null, name) });
+    }
+  }
+  const ordered = [...runs.entries()].sort((a, b) => String(b[1].run.startedAt ?? b[1].run.createdAt ?? '').localeCompare(String(a[1].run.startedAt ?? a[1].run.createdAt ?? '')) || (a[0] < b[0] ? -1 : 1));
+  const workerKey = (runId        ) => sha16(`worker:${runId}`);
+  for (const [runId, { run, checkout, slug }] of ordered) {
+    const caller = run.caller && typeof run.caller.runKey === 'string' ? runNode(run.caller.runKey) : null;
+    const harness = harnessOf(run.harness);
+    const isChild = typeof run.childOf === 'string' && run.childOf !== '';
+    let liveness = 'not-checked';
+    if (run.phase !== 'ended') {
+      if (checks < MAX_CHECKS) {
+        checks += 1;
+        const seen = [alive(run.supervisor, { platform }), alive(run.worker, { platform })];
+        liveness = seen.includes(true) ? 'process-seen' : seen.every((v) => v === false) ? 'process-gone' : 'not-checked';
+      } else counts.notChecked += 1;
+    }
+    const n = node(workerKey(runId), {
+      kind: isChild ? 'child-worker-run' : 'worker-run', harness, model: label(run.binding?.model), modelBasis: run.binding?.model ? 'worker-binding' : null,
+      depth: isChild ? 2 : caller ? 1 : 0, worktreeKey: (run.caller?.runKey ?? '').split('/')[0] || cwdHash(checkout),
+      startedAt: run.startedAt ?? run.createdAt ?? null, lastRecordAt: run.end?.at ?? run.startedAt ?? run.createdAt ?? null, liveness,
+      ended: run.end && typeof run.end.at === 'string' ? { at: run.end.at, result: typeof run.end.state === 'string' ? run.end.state : null } : null,
+      transcript: transcriptOf(harness, null),
+    }, { harness, runId });
+    if (!n) continue;
+    const task = label(run.task);
+    const startedAt = run.startedAt ?? run.createdAt;
+    if (typeof startedAt === 'string') note(n, 'records', { type: 'worker-run-start', at: startedAt, task, result: null });
+    if (run.end && typeof run.end.at === 'string') note(n, 'records', { type: 'worker-run-end', at: run.end.at, task, result: typeof run.end.state === 'string' ? label(run.end.state) : null });
+    if (run.phase !== 'ended' && typeof run.task === 'string') note(n, 'holds', { slug, task: run.task });
+    if (isChild) edge(workerKey(run.childOf), n.agentKey, 'worker-childOf');
+    else if (caller) edge(caller.agentKey, n.agentKey, 'worker-caller');
+    else {
+      const viaAttempt = attemptRuns.get(`${run.task}#${run.token}`);
+      const owner = viaAttempt ? runNode(viaAttempt) : null;
+      if (owner) edge(owner.agentKey, n.agentKey, 'attempt-runKey');
+    }
+  }
+  for (const checkout of checkouts) {
+    for (const [, store] of readStores(checkout, 'dispatch', (file) => readTaskState(fsImpl, file))) {
+      for (const d of Object.values(store.dispatches ?? {})         ) {
+        if (typeof d?.parentRunKey !== 'string') continue;
+        const snap = d.primary && typeof d.primary === 'object' ? d.primary : null;
+        const owner = runNode(d.parentRunKey, snap ? { harness: harnessOf(snap.harness), model: label(typeof snap.model === 'string' ? snap.model : null), modelBasis: snap.model ? 'dispatch-snapshot' : null } : {});
+        const launched = [...runs.entries()].find(([, r]) => r.run.task === d.task && r.run.token === d.token && !r.run.childOf);
+        if (owner && launched) edge(owner.agentKey, workerKey(launched[0]), 'dispatch-claim');
+      }
+    }
+  }
+
+  // ---- what leaves: no internal field, kept nodes' edges only ---------------------------------------------
+  const keep = [...nodes.values()];
+  const body = {
+    v: 1, projectKey, nodes: keep, edges: [...edges.values()].filter((e     ) => nodes.has(e.from) && nodes.has(e.to)),
+    limits: { nodes: MAX_NODES, notChecked: counts.notChecked }, unreadable: counts.unreadable,
+  };
+  return { ok: true, body, internal };
+}
+
+module.exports = { buildTree, READERS, MAX_SESSIONS, MAX_NODES, MAX_CHECKS };

package/src/runtime/freshness.js

@@ -21,13 +21,40 @@ function fileHash(root        , locator     )                {
   } catch { return null; }
 }
 
-function measureFreshness(root        , locator     , gitCommit     )      {
-  return { gitCommit, fileHash: fileHash(root, locator), observedAt: new Date().toISOString(), status: 'FRESH' };
+/**
+ * IC-007: the root a relative locator.file is read in: sourceRoot, except for a locator under
+ * `agent-docs/doflow/<slug>/` whose folder is absent in sourceRoot and present in the state root
+ * (the IC-005 `feature_root` case), which resolves in the state root. Any other missing file stays
+ * missing in sourceRoot (=> STALE/missing as today for a non-redirected file).
+ */
+function fileRootFor(sourceRoot        , stateRoot        , locator     )         {
+  const file = locator?.file;
+  if (typeof file !== 'string' || file === '' || path.isAbsolute(file) || path.resolve(sourceRoot) === path.resolve(stateRoot)) return sourceRoot;
+  const normalized = path.normalize(file).replace(/\\/g, '/');
+  const match = normalized.match(/^agent-docs\/doflow\/([^/]+)\/.+/);
+  if (match) {
+    const slug = match[1];
+    const folder = path.join('agent-docs', 'doflow', slug);
+    const isDir = (root        ) => {
+      try { return fs.statSync(path.resolve(root, folder)).isDirectory(); } catch { return false; }
+    };
+    if (!isDir(sourceRoot) && isDir(stateRoot)) {
+      return stateRoot;
+    }
+  }
+  return sourceRoot;
+}
+
+// IC-007: a relative locator.file is hashed in sourceRoot, the checkout the verb runs in; `root`
+// (the record store) is only the default. An absolute locator.file is hashed as is.
+function measureFreshness(root        , locator     , gitCommit     , sourceRoot         = root)      {
+  return { gitCommit, fileHash: fileHash(fileRootFor(sourceRoot, root, locator), locator), observedAt: new Date().toISOString(), status: 'FRESH' };
 }
 
 class FreshnessValidator {
   repoRoot        ;
   treeRoot        ;
+  sourceRoot        ;
   gitRunner                                                 ;
                                                
                                           
@@ -37,11 +64,13 @@ class FreshnessValidator {
    * @param {Object} [options]
    * @param {string} [options.repoRoot]
    * @param {string} [options.treeRoot]
+   * @param {string} [options.sourceRoot] checkout a relative locator.file is hashed in (default repoRoot)
    * @param {Function} [options.gitRunner]
    */
   constructor(options      = {}) {
     this.repoRoot = options.repoRoot || REPO_ROOT;
     this.treeRoot = options.treeRoot || this.repoRoot;
+    this.sourceRoot = options.sourceRoot || this.repoRoot;
     this.gitRunner = options.gitRunner || this.defaultGitRunner.bind(this);
     this.validatingLedger = false;
   }
@@ -158,7 +187,7 @@ class FreshnessValidator {
     }
 
     if (item.freshness?.fileHash) {
-      const currentHash = fileHash(this.repoRoot, item.locator);
+      const currentHash = fileHash(fileRootFor(this.sourceRoot, this.repoRoot, item.locator), item.locator);
       return currentHash === item.freshness.fileHash
         ? { status: 'FRESH' }
         : { status: 'STALE', reason: currentHash ? 'Observed file contents changed' : 'Observed file is missing or unreadable' };
@@ -210,5 +239,6 @@ class FreshnessValidator {
 
 module.exports = {
   measureFreshness,
+  fileRootFor,
   FreshnessValidator,
 };