@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/context/pointer.js

@@ -0,0 +1,142 @@
+'use strict';
+
+// TypeScript migration: run directly by Node native type-stripping.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+function sha256(text        )         {
+  return `sha256:${crypto.createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}
+
+function inside(root        , file        , fsImpl = fs)                {
+  const absolute = path.resolve(file);
+  let realRoot        ;
+  let realFile        ;
+  try {
+    realRoot = fsImpl.realpathSync(path.resolve(root));
+    realFile = fsImpl.realpathSync(absolute);
+  } catch { return null; }
+  const relative = path.relative(realRoot, realFile);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+  const normalized = relative.split(path.sep).join('/');
+  if (normalized.split('/').includes('state')) return null;
+  return normalized;
+}
+
+function lineSlice(lines          , startLine        , endLine        )         {
+  return lines.slice(startLine - 1, endLine).join('\n') + '\n';
+}
+
+function rangesFor(file        , text        , requirement         )                                                                        {
+  const lines = text.split(/\r?\n/);
+  const result                                                                        = [];
+  if (requirement) {
+    let section = '';
+    for (let i = 0; i < lines.length; i++) {
+      const heading = lines[i].match(/^##\s+(.*)$/);
+      if (heading) section = heading[1];
+      if (!/^##\s+[34](?:[.)]|\s|$)/.test(lines[i])) continue;
+      let end = i + 1;
+      while (end < lines.length && !/^##\s+/.test(lines[end])) end++;
+      for (let j = i + 1; j < end; j++) {
+        if (!/^\s*\*\*Detail:?\*\*/i.test(lines[j])) continue;
+        let blockEnd = j + 1;
+        while (blockEnd < end && !/^\s*\*\*[A-Za-z][^*]*:?\*\*/.test(lines[blockEnd])) blockEnd++;
+        result.push({ startLine: j + 1, endLine: blockEnd, heading: section || null });
+        j = blockEnd - 1;
+      }
+      i = end - 1;
+    }
+    return result;
+  }
+  let start = -1;
+  let title                = null;
+  const flush = (end        ) => {
+    if (start >= 0 && end >= start) result.push({ startLine: start + 1, endLine: end, heading: title });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const heading = lines[i].match(/^##\s+(.+)$/);
+    if (heading) {
+      flush(i);
+      start = i;
+      title = heading[1].trim();
+    }
+  }
+  flush(lines.length);
+  return result;
+}
+
+function createPointer({ path: rel, heading, range, slice }     )      {
+  const bytes = Buffer.byteLength(slice, 'utf8');
+  return {
+    id: `ptr:${rel}:${range.startLine}-${range.endLine}`,
+    path: rel,
+    heading,
+    range,
+    digest: sha256(slice),
+    bytes,
+    tokensEst: { value: Math.ceil(bytes / 4), basis: 'estimated:bytes/4' },
+    inlineBytes: Buffer.byteLength(`- ptr:${rel}:${range.startLine}-${range.endLine} ${rel}:${range.startLine}-${range.endLine} ${bytes} B\n`, 'utf8'),
+    load: `read ${rel} lines ${range.startLine}-${range.endLine}`,
+  };
+}
+
+function sourceFiles({ projectRoot, feature, fsImpl = fs }     )                                                    {
+  const root = path.resolve(projectRoot);
+  const featureDir = feature?.featureDir ? path.resolve(feature.featureDir) : null;
+  const candidates                                                    = [];
+  const add = (file                           , requirement = false) => {
+    if (!file) return;
+    const absolute = path.isAbsolute(file) ? file : path.resolve(feature?.repoRoot || root, file);
+    let stat     ;
+    try { stat = fsImpl.statSync(absolute); } catch { return; }
+    if (!inside(root, absolute, fsImpl) || !stat.isFile()) return;
+    if (!candidates.some((item) => item.absolute === absolute)) candidates.push({ absolute, requirement });
+  };
+  if (featureDir) {
+    add(feature.paths?.requirement || path.join(featureDir, 'intention', 'requirement.md'), true);
+    for (const file of [
+      feature.paths?.design,
+      feature.paths?.plan,
+      path.join(featureDir, 'design', 'design.md'),
+      path.join(featureDir, 'design', 'specs.md'),
+      path.join(featureDir, 'design', 'data-model.md'),
+      path.join(featureDir, 'plan', 'plan.md'),
+      path.join(featureDir, 'design.md'),
+      path.join(featureDir, 'plan.md'),
+    ]) add(file);
+  }
+  return candidates;
+}
+
+function collectPointers({ projectRoot, feature, fsImpl = fs }     )        {
+  const root = path.resolve(projectRoot);
+  const pointers        = [];
+  for (const source of sourceFiles({ projectRoot: root, feature, fsImpl })) {
+  const rel = inside(root, source.absolute, fsImpl);
+    if (!rel) continue;
+    let text        ;
+    try { text = fsImpl.readFileSync(source.absolute, 'utf8'); } catch { continue; }
+    const lines = text.split(/\r?\n/);
+    for (const range of rangesFor(rel, text, source.requirement)) {
+      const slice = lineSlice(lines, range.startLine, range.endLine);
+      if (!slice.trim()) continue;
+      pointers.push(createPointer({ path: rel, heading: range.heading, range: { startLine: range.startLine, endLine: range.endLine }, slice }));
+    }
+  }
+  return pointers;
+}
+
+function readPointerSlice({ projectRoot, pointer, fsImpl = fs }     )                                           {
+  const rel = inside(projectRoot, path.resolve(projectRoot, pointer.path), fsImpl);
+  if (!rel || rel !== pointer.path) return null;
+  const file = path.resolve(projectRoot, rel);
+  try {
+    const lines = fsImpl.readFileSync(file, 'utf8').split(/\r?\n/);
+    const slice = lineSlice(lines, pointer.range.startLine, pointer.range.endLine);
+    return { slice, digest: sha256(slice) };
+  } catch { return null; }
+}
+
+module.exports = { collectPointers, createPointer, readPointerSlice, sha256 };

package/src/runtime/context/primary-command.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * `doflow primary` (120 IC-008): the read-only view of which harness and model the main session runs.
+ * `--action resolve` prints `resolvePrimary` (IC-007); `--action observed` prints `observedSessions`
+ * (093 IC-018 a). Neither writes anything: no state, no config home, no upkeep.
+ * Loaded only when the verb, `status` or `doctor` prints the primary, never on an install path.
+ */
+
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadRegistry } = require('../../registry/index.js');
+const { finishRuntime, captureCaught } = require('../cli-result.js');
+const { resolvePrimary, observedSessions } = require('./primary.js');
+
+const ALLOWED_FLAGS = new Set(['--action', '--json']);
+
+function dash(value         )         {
+  return value === null || value === undefined ? '-' : String(value);
+}
+
+/** The text form: one line per field, then each warning. */
+function primaryLines(primary     )           {
+  const { declared, observed } = primary;
+  const declaredText = declared
+    ? `${declared.harness}/${dash(declared.model)} (${declared.origin.harness}${declared.origin.model ? `, model ${declared.origin.model}` : ''})`
+    : '-';
+  const observedText = observed ? `${observed.model} (${observed.event}, ${observed.observedAt}, sessions ${observed.sessions})` : '-';
+  return [
+    `state: ${primary.state}`,
+    `harness: ${dash(primary.harness)}`,
+    `model: ${dash(primary.model)}`,
+    `family: ${primary.family}`,
+    `declared: ${declaredText}`,
+    `observed: ${observedText}`,
+    `probe: ${primary.probe}`,
+    `reason: ${dash(primary.reason)}`,
+    ...primary.warnings.map((warning        ) => `warning: ${warning}`),
+  ];
+}
+
+/** The origin layer of the declared harness; `default` when nothing declared one. */
+function primaryOrigin(primary     )         {
+  return primary.declared?.origin?.harness ?? 'default';
+}
+
+/** `<state> <harness>/<model> (<origin>)`, the line `status` and `doctor` share. */
+function primarySummary(primary     )         {
+  return `${primary.state} ${dash(primary.harness)}/${dash(primary.model)} (${primaryOrigin(primary)})`;
+}
+
+/** The `doctor` object: the probe label is `declared-only` without a probe, else the harness's recorded probe status. */
+function primaryDoctorView({ primary, registry }                                 )      {
+  const entry = (registry.harnesses || []).find((harness     ) => harness?.id === primary.harness);
+  const probe = primary.probe === 'none' ? 'declared-only' : (entry?.primaryProbe?.status ?? 'unverified');
+  return { state: primary.state, harness: primary.harness, model: primary.model, origin: primaryOrigin(primary), probe };
+}
+
+/** The text form of `observed`: the store, one line per checkout, one per session; no path or raw id. */
+function observedLines(body     )           {
+  return [
+    `store: ${body.store}`,
+    ...body.checkouts.map((c     ) => `checkout ${c.worktreeKey} ${c.role}${c.current ? ' current' : ''} ${c.branch === null ? 'detached' : c.branch} ${dash(c.head)} ${dash(c.headCommittedAt)}`),
+    ...body.sessions.map((s     ) => {
+      const unit = s.launched ? ` L.${s.launched.run}.${s.launched.lineage}.${s.launched.attempt}` : '';
+      return `session ${s.sessionKey} ${s.worktreeKey} ${s.kind}${unit} harness ${dash(s.harness)} model ${dash(s.model)} started ${dash(s.startedAt)} last-hook-record ${dash(s.lastHookRecordAt)}`;
+    }),
+    ...(body.truncated ? ['truncated: true'] : []),
+    ...(body.unreadable > 0 ? [`unreadable: ${body.unreadable}`] : []),
+  ];
+}
+
+function handlePrimaryCommand({ action, json = false, flags = [], env = process.env, cwd = process.cwd(), registry, out = (line        ) => console.log(line) }      = {})         {
+  const usage = (message        )         => {
+    out(json ? JSON.stringify({ ok: false, error: 'usage', message }) : `doflow primary: ${message}`);
+    return finishRuntime(2);
+  };
+  if (action !== 'resolve' && action !== 'observed') return usage('action must be resolve');
+  const extra = (flags            ).map((flag) => flag.split('=')[0]).find((flag) => !ALLOWED_FLAGS.has(flag));
+  if (extra !== undefined) return usage(`unsupported flag ${extra}; only --action and --json apply`);
+
+  if (action === 'observed') {
+    try {
+      const observed = observedSessions({ env, cwd });
+      if (!observed.ok) {
+        if (json) out(JSON.stringify({ v: 1, error: observed.error }));
+        else console.error('[ERROR] primary: cannot list checkouts');
+        return finishRuntime(1);
+      }
+      if (json) out(JSON.stringify(observed.body));
+      else for (const line of observedLines(observed.body)) out(line);
+      return finishRuntime(0);
+    } catch (error     ) {
+      captureCaught(error, 'primary', 1);
+      console.error(`[ERROR] primary: ${error?.message || String(error)}`);
+      return finishRuntime(1);
+    }
+  }
+
+  try {
+    const primary = resolvePrimary({ env, projectRoot: cwd, registry });
+    if (json) out(JSON.stringify(primary));
+    else for (const line of primaryLines(primary)) out(line);
+    return finishRuntime(primary.state === 'refused' ? 1 : 0);
+  } catch (error     ) {
+    captureCaught(error, 'primary', 1);
+    console.error(`[ERROR] primary: ${error?.message || String(error)}`);
+    return finishRuntime(1);
+  }
+}
+
+/** The `status` and `doctor` reader: one resolution with the shipped registry; the caller handles a fault. */
+function resolveForReport({ env, projectRoot, repoRoot = REPO_ROOT }                                                      )                                  {
+  const registry = loadRegistry({ repoRoot });
+  return { primary: resolvePrimary({ env, projectRoot, registry }), registry };
+}
+
+module.exports = { handlePrimaryCommand, primaryLines, primarySummary, primaryDoctorView, resolveForReport };

package/src/runtime/context/primary.js

@@ -0,0 +1,344 @@
+'use strict';
+
+// A.3 (IC-005 and IC-007): read-only resolution of the main session's declared and observed model.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { cwdHash, stateDir, ID_PATTERN, ATTEMPT_PATTERN } = require('./identity.js');
+const { loadSettings } = require('../settings/resolve.js');
+const { validateValue } = require('../settings/files.js');
+const { loadRegistry } = require('../../registry/index.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+                                              
+
+                       
+                
+                
+                     
+                   
+ 
+
+                                   
+                      
+                      
+                  
+              
+                           
+ 
+
+function isObject(value         )                               {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function sameModel(left        , right        )          {
+  return left.trim().toLowerCase() === right.trim().toLowerCase();
+}
+
+/** IC-005: the common observation shape, without a reader's lifetime policy. */
+function parseObservation(value     , harness        )                                                                               {
+  if (!isObject(value)) return null;
+  const keys = Object.keys(value).sort();
+  if (keys.join(',') !== 'event,harness,model,observedAt,schema,session') return null;
+  if (value.schema !== 1 || value.harness !== harness) return null;
+  if (typeof value.model !== 'string' || validateValue({ type: 'model-id' }, value.model)) return null;
+  if (typeof value.event !== 'string' || value.event.length === 0) return null;
+  if (typeof value.observedAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(value.observedAt)) return null;
+  if (!Number.isFinite(Date.parse(value.observedAt))) return null;
+  if (typeof value.session !== 'string' || !/^[0-9a-f]{16}$/.test(value.session)) return null;
+  return { model: value.model, event: value.event, observedAt: value.observedAt, session: value.session };
+}
+
+/** IC-005: read valid main-session model observations for one project and harness. A file that
+ * cannot be read or parsed adds one to `counts.unreadable` when `counts` is given. */
+function readObservations({ root, projectRoot, harness, now, maxAgeMs = null, counts }                                                               )        {
+  if (!root) return [];
+  const dir = path.join(root, 'primary', cwdHash(projectRoot), harness);
+  let entries          ;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  const observations        = [];
+
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    try {
+      if (!fs.lstatSync(file).isFile()) continue;
+      const value = parseObservation(JSON.parse(fs.readFileSync(file, 'utf8')), harness);
+      if (!value) { if (counts) counts.unreadable += 1; continue; }
+      const observedAt = Date.parse(value.observedAt);
+      if (observedAt > now) continue;
+      if (maxAgeMs !== null && now - observedAt > maxAgeMs) continue;
+      observations.push({ ...value, time: observedAt });
+    } catch {
+      // Malformed, unreadable, and non-file entries do not count as observations.
+      if (counts) counts.unreadable += 1;
+    }
+  }
+  return observations;
+}
+
+/** The `model-observations` store's age bound in milliseconds, or null when it declares none. */
+function observationMaxAgeMs(storage     )                {
+  const store = (storage.stores || []).find((entry     ) => entry?.id === 'model-observations');
+  const maxAgeDays = store?.bound?.maxAgeDays;
+  return Number.isFinite(maxAgeDays) ? maxAgeDays * 24 * 60 * 60 * 1000 : null;
+}
+
+/** IC-013 / IC-005: read one worker's observation; the storage store owns its lifetime. */
+function readWorkerObservation({ root, identity, harness, fsImpl = fs }     )                                                                               {
+  try {
+    if (typeof root !== 'string' || !isObject(identity)) return null;
+    if (typeof identity.run !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$/.test(identity.run)) return null;
+    if (typeof identity.lineage !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$/.test(identity.lineage)) return null;
+    if (typeof identity.attempt !== 'string' || !/^[1-9][0-9]{0,3}$/.test(identity.attempt)) return null;
+    const file = path.join(root, 'worker-model', `L.${identity.run}.${identity.lineage}.${identity.attempt}.json`);
+    if (!fsImpl.lstatSync(file).isFile()) return null;
+    return parseObservation(JSON.parse(fsImpl.readFileSync(file, 'utf8')), harness);
+  } catch {
+    return null;
+  }
+}
+
+/** IC-007: resolve the primary harness and model using settings and read-only hook observations. */
+function resolvePrimary({
+  env,
+  projectRoot = process.cwd(),
+  registry,
+  models,
+  storage,
+  now = Date.now,
+  observationsRoot,
+}   
+            
+                       
+                 
+               
+                
+                     
+                                   
+  = {})      {
+  const runtimeEnv = env ?? {};
+  const role = (runtimeEnv.DOFLOW_SESSION_ROLE || '').replace(/[A-Z]/g, (c) => c.toLowerCase());
+  const nullDeclared = { harness: null, model: null, origin: { harness: null, model: null } };
+  const result = (state        , fields      = {}) => ({
+    state,
+    harness: null,
+    model: null,
+    family: 'unknown',
+    declared: null,
+    observed: null,
+    probe: 'none',
+    warnings: [],
+    reason: null,
+    ...fields,
+  });
+
+  if (role !== '' && role !== 'main') return result('not-primary', { reason: 'worker-role' });
+
+  const settings = loadSettings({ projectRoot, env: runtimeEnv });
+  const harnessSetting = settings.get('primary.harness');
+  const modelSetting = settings.get('primary.model');
+  const contradictionSetting = settings.get('primary.onContradiction');
+  const harness = harnessSetting.value;
+  const declaredModel = modelSetting.value;
+  const declared = harness === 'unknown' ? null : {
+    harness,
+    model: declaredModel,
+    origin: { harness: harnessSetting.origin.layer, model: declaredModel === null ? null : modelSetting.origin.layer },
+  };
+  const warnings           = [];
+  if (harness === 'unknown') {
+    if (declaredModel !== null) warnings.push('primary-model-without-harness');
+    return result('unknown', { declared: null, warnings });
+  }
+
+  const { REPO_ROOT: repoRoot } = require('../../helper/repo-root.js');
+  const registryValue = registry ?? loadRegistry({ repoRoot });
+  const harnessEntry = (registryValue.harnesses || []).find((entry     ) => entry?.id === harness);
+  const probe = harnessEntry?.primaryProbe?.model === 'payload' ? 'payload' : 'none';
+  if (probe === 'none') return result('declared-only', { harness, model: declaredModel, declared, probe, warnings });
+
+  let loadedModels = models;
+  if (!loadedModels) loadedModels = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core/registry/models.json'), 'utf8'));
+  let loadedStorage = storage;
+  if (!loadedStorage) loadedStorage = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core/registry/storage.json'), 'utf8'));
+  const maxAgeMs = observationMaxAgeMs(loadedStorage);
+  const root = observationsRoot === undefined ? stateDir(runtimeEnv) : observationsRoot;
+  const observations = readObservations({ root, projectRoot, harness, now: now(), maxAgeMs });
+  if (observations.length === 0) {
+    return result('unconfirmed', { harness, model: declaredModel, declared, probe, warnings, reason: 'no-observation' });
+  }
+
+  const groups = new Map               ();
+  for (const observation of observations) {
+    const key = observation.model.trim().toLowerCase();
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key) .push(observation);
+  }
+  if (groups.size > 1) {
+    return result('unconfirmed', { harness, model: declaredModel, declared, probe, warnings, reason: 'ambiguous-sessions' });
+  }
+
+  const group = [...groups.values()][0];
+  group.sort((a, b) => b.time - a.time);
+  const newest = group[0];
+  const observed              = {
+    model: newest.model,
+    event: newest.event,
+    observedAt: newest.observedAt,
+    sessions: group.length,
+  };
+  const observedRecord = { ...observed, session: newest.session };
+  if (declaredModel === null || sameModel(declaredModel, newest.model)) {
+    const provider = (loadedModels.providers || []).find((entry     ) => entry?.id === harness);
+    const families = Array.isArray(provider?.families) ? provider.families.filter((family     ) => family !== 'unknown') : [];
+    const family = families.length === 1 && provider.families.length === 1 ? families[0] : 'unknown';
+    return result('confirmed', { harness, model: newest.model, family, declared, observed: observedRecord, probe, warnings });
+  }
+
+  warnings.push(`primary-contradicted: declared ${declaredModel}, observed ${newest.model}`);
+  const refused = contradictionSetting.value === 'refuse';
+  return result(refused ? 'refused' : 'contradicted', {
+    harness,
+    model: newest.model,
+    declared,
+    observed: observedRecord,
+    probe,
+    warnings,
+    reason: refused ? 'primary-contradicted' : null,
+  });
+}
+
+const SESSION_DIR_LIMIT = 2000;
+const SESSION_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/; // the session-dirs store's match
+const HARNESS_DIR = /^[a-z0-9][a-z0-9-]*$/; // observe-model.sh's harness check
+
+const keyOf = (id        )         => crypto.createHash('sha256').update(id).digest('hex').slice(0, 16);
+const isoOrNull = (value         )                => (typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(value) && Number.isFinite(Date.parse(value)) ? value : null);
+
+/** `L.<run>.<lineage>.<attempt>` (identity.ts), split; null for any other name. */
+function launchedUnit(name        )                                                           {
+  const parts = name.split('.');
+  if (parts.length !== 4 || parts[0] !== 'L') return null;
+  const [, run, lineage, attempt] = parts;
+  return ID_PATTERN.test(run) && ID_PATTERN.test(lineage) && ATTEMPT_PATTERN.test(attempt) ? { run, lineage, attempt } : null;
+}
+
+/** One checkout's HEAD commit time as UTC ISO, from `git log -1 --format=%cI HEAD`; null when git cannot say. */
+function headCommittedAt(top        , exec     , env     )                {
+  try {
+    const res = exec('git', ['-C', top, 'log', '-1', '--format=%cI', 'HEAD'], { encoding: 'utf8', timeout: 10000, env: { ...env, GIT_OPTIONAL_LOCKS: '0' } });
+    if (!res || res.error || res.status !== 0) return null;
+    const at = Date.parse(String(res.stdout || '').trim());
+    return Number.isFinite(at) ? new Date(at).toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * IC-018 a: the project's checkouts and the hook records of the sessions that worked in them.
+ * Checkouts come from `listCheckouts` (sandboxes left out); records are the main-session model
+ * observations at each checkout top and the `sessions/<id>/git-context.json` files whose `cwd` lies
+ * in a checkout (longest prefix; at most SESSION_DIR_LIMIT directories, newest first by mtime). An
+ * observation and a session directory with the same session key are one entry. No path, pid or raw
+ * session id is returned, and nothing is written: no lock, no mkdir, no upkeep.
+ * @returns {{ok: false, error: 'cannot-list-checkouts'} | {ok: true, body: Object}}
+ */
+function observedSessions({
+  env = process.env, cwd = process.cwd(), exec = spawnSync, fsImpl = fs, now = Date.now, storage,
+}                                                                                           = {})      {
+  // Required here, not at the top: `resolve` (and status, doctor) never lists checkouts.
+  const { listCheckouts, checkoutContaining } = require('../checkouts.js');
+  const listed = listCheckouts({ cwd, exec, fsImpl });
+  if (!listed.ok && listed.reason !== 'not-a-git-repository') return { ok: false, error: 'cannot-list-checkouts' };
+  const entries        = listed.ok ? listed.entries : [];
+  const checkouts = entries.filter((e) => !e.sandbox).map((e) => ({
+    worktreeKey: cwdHash(e.path),
+    role: e.path === listed.main ? 'main' : 'linked',
+    current: e.path === listed.current,
+    branch: e.branch,
+    head: e.head === null ? null : e.head.slice(0, 12),
+    headCommittedAt: e.head === null ? null : headCommittedAt(e.path, exec, env),
+  }));
+  const root = stateDir(env);
+  const body      = { v: 1, store: root === null ? 'absent' : 'present', checkouts, sessions: [], truncated: false, unreadable: 0 };
+  if (root === null) return { ok: true, body };
+
+  const counts = { unreadable: 0 };
+  const sessions = new Map             ();
+  const entry = (sessionKey        , worktreeKey        ) => {
+    if (!sessions.has(sessionKey)) {
+      sessions.set(sessionKey, {
+        sessionKey, worktreeKey, kind: 'hook', harness: null, model: null, modelFirstSeenAt: null,
+        startedAt: null, branchAtStart: null, lastHookRecordAt: null, launched: null,
+      });
+    }
+    return sessions.get(sessionKey);
+  };
+
+  const loadedStorage = storage ?? JSON.parse(fsImpl.readFileSync(path.join(REPO_ROOT, 'core/registry/storage.json'), 'utf8'));
+  const maxAgeMs = observationMaxAgeMs(loadedStorage);
+  const nowMs = now();
+  for (const top of entries.filter((e) => !e.sandbox).map((e) => e.path)) {
+    const worktreeKey = cwdHash(top);
+    let harnesses       ;
+    try { harnesses = fsImpl.readdirSync(path.join(root, 'primary', worktreeKey), { withFileTypes: true }); } catch { continue; }
+    for (const dirent of harnesses) {
+      if (!dirent.isDirectory() || !HARNESS_DIR.test(dirent.name)) continue;
+      for (const o of readObservations({ root, projectRoot: top, harness: dirent.name, now: nowMs, maxAgeMs, counts })) {
+        const e = entry(o.session, worktreeKey);
+        if (e.modelFirstSeenAt !== null && Date.parse(e.modelFirstSeenAt) >= o.time) continue; // the newest observation of a key wins
+        Object.assign(e, { harness: dirent.name, model: o.model, modelFirstSeenAt: o.observedAt });
+      }
+    }
+  }
+
+  const sessionsRoot = path.join(root, 'sessions');
+  let dirs                                           = [];
+  try {
+    for (const dirent of fsImpl.readdirSync(sessionsRoot, { withFileTypes: true })) {
+      if (!dirent.isDirectory() || !SESSION_DIR.test(dirent.name)) continue;
+      try { dirs.push({ name: dirent.name, mtimeMs: fsImpl.lstatSync(path.join(sessionsRoot, dirent.name)).mtimeMs }); } catch { /* gone meanwhile */ }
+    }
+  } catch { /* no session directories */ }
+  dirs.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.name < b.name ? -1 : 1));
+  if (dirs.length > SESSION_DIR_LIMIT) { body.truncated = true; dirs = dirs.slice(0, SESSION_DIR_LIMIT); }
+  for (const { name } of dirs) {
+    const dir = path.join(sessionsRoot, name);
+    const file = path.join(dir, 'git-context.json');
+    let context     ;
+    try {
+      if (!fsImpl.lstatSync(file).isFile()) continue;
+    } catch { continue; }
+    try { context = JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { counts.unreadable += 1; continue; }
+    if (!isObject(context)) { counts.unreadable += 1; continue; }
+    const at = checkoutContaining(entries, context.cwd, fsImpl);
+    if (!at || at.sandbox) continue; // another project's session, or a sandbox's: never listed
+    let newest = -Infinity;
+    try {
+      for (const child of fsImpl.readdirSync(dir)) {
+        try { const st = fsImpl.lstatSync(path.join(dir, child)); if (st.isFile()) newest = Math.max(newest, st.mtimeMs); } catch { /* gone */ }
+      }
+    } catch { /* unreadable directory: no last record */ }
+    const unit = launchedUnit(name);
+    const e = entry(keyOf(name), cwdHash(at.path));
+    Object.assign(e, {
+      worktreeKey: cwdHash(at.path),
+      kind: unit ? 'launched' : 'hook',
+      startedAt: isoOrNull(context.captured_at),
+      branchAtStart: typeof context.branch === 'string' && context.branch !== '' ? context.branch : null,
+      lastHookRecordAt: Number.isFinite(newest) ? new Date(newest).toISOString() : null,
+      launched: unit,
+    });
+  }
+
+  const time = (e     ) => Math.max(...[e.lastHookRecordAt, e.startedAt, e.modelFirstSeenAt].map((v) => (v === null ? -Infinity : Date.parse(v))));
+  body.sessions = [...sessions.values()].sort((a, b) => time(b) - time(a) || (a.sessionKey < b.sessionKey ? -1 : 1));
+  body.unreadable = counts.unreadable;
+  return { ok: true, body };
+}
+
+module.exports = { readObservations, readWorkerObservation, resolvePrimary, observedSessions };