@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/failure/capture.js

@@ -95,7 +95,9 @@ function doflowFrame(error     )                {
   for (const line of stack.split('\n')) {
     const match = /^\s*at (?:async )?(?:(.+?) \()?(.+?):\d+:\d+\)?$/.exec(line);
     if (!match) continue;
-    const file = match[2].replace(/^file:\/\//, '');
+    const file = process.platform === 'win32' && /^file:\/\/\/[A-Za-z]:/.test(match[2])
+      ? path.normalize(match[2].slice('file:///'.length))
+      : match[2].replace(/^file:\/\//, '');
     if (!file.startsWith(root) || file.includes(`${path.sep}node_modules${path.sep}`)) continue;
     const fn = (match[1] || '').replace(/^new /, '').split('.').pop() .replace(/\s.*$/, '') || '<anonymous>';
     return `${path.relative(REPO_ROOT, file).split(path.sep).join('/')}:${fn}`;

package/src/runtime/failure/cli.js

@@ -12,9 +12,11 @@
  */
 
 const fs = require('node:fs');
+const path = require('node:path');
 const { finishRuntime, usageError } = require('../cli-result.js');
 const { maskLine, printSafe } = require('../mask.js');
-const { failureHome, captureSwitch, sentinelPath } = require('./home.js');
+const { failureHome, captureSwitchDetailed } = require('./home.js');
+const { writeLayer, backupLayerFile } = require('../settings/write.js');
 const { rotateIfDue } = require('./capture.js');
 const store = require('./store.js');
 const { projectRoot } = require('../lifecycle/root.js');
@@ -119,19 +121,33 @@ function settleFailure({ fp, as, reason, cwd, env = process.env, now = new Date(
 
 // ── capture ────────────────────────────────────────────────────────────────────────────────────
 
-function captureState({ set, env = process.env, now = new Date() }      = {})      {
+function captureState({ set, env = process.env }      = {})      {
   if (set !== undefined && set !== 'on' && set !== 'off') throw new FailureUsageError(`--set must be on or off (got '${set}')`);
   const home = failureHome(env);
-  if (home !== null && set === 'off') {
-    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(sentinelPath(home), `${now.toISOString()}\n`, { mode: 0o600 });
-  } else if (home !== null && set === 'on') {
-    fs.rmSync(sentinelPath(home), { force: true });
+  let settingsFile                = null;
+  if (home !== null && set !== undefined) {
+    const file = path.join(path.dirname(home), 'settings.json');
+    settingsFile = file;
+    const written = writeLayer({ file, set: { 'failure.capture': set }, scrubKeys: set === 'on' ? ['failure.capture'] : [] });
+    if (!written.ok && set === 'off' && written.code === 'unparseable') {
+      const backup = backupLayerFile(file);
+      if (!backup.ok) return refusal('capture', 'write-failed', backup.detail);
+      console.error(printSafe(`note: malformed settings preserved at ${backup.file}`));
+      const recovered = writeLayer({ file, set: { 'failure.capture': set }, force: true });
+      if (!recovered.ok) return refusal('capture', 'write-failed', recovered.detail);
+    } else if (!written.ok) {
+      return refusal('capture', 'write-failed', written.detail);
+    }
   }
-  const state = captureSwitch(home, env);
+  const state = captureSwitchDetailed(home, env);
+  if (settingsFile && state.decidedBy === 'core/registry/settings.json') state.decidedBy = settingsFile;
+  for (const note of state.deprecatedNotes) console.error(printSafe(`note: ${note}`));
   // With no failure home nothing is captured, whatever the switch says.
   const result      = { ok: true, action: 'capture', effective: home === null ? 'off' : state.effective, sentinel: state.sentinel, env: state.env };
   if (home === null) result.home = null;
+  else if (set !== undefined) {
+    result.decidedBy = state.decidedBy;
+  }
   return result;
 }
 
@@ -147,7 +163,7 @@ function lines(result     )           {
     return [...out, ...result.next.map((n        ) => `next: ${n}`)];
   }
   if (result.action === 'settle') return [`${result.fp} settled as ${result.as}${result.followup ? `, follow-up ${result.followup.id}` : ''}`];
-  return [`capture ${result.effective}${result.sentinel ? ' (switched off on this machine)' : ''}${result.env ? ` (DOFLOW_FAILURE_CAPTURE=${result.env})` : ''}`];
+  return [`capture ${result.effective}${result.sentinel ? ' (switched off on this machine)' : ''}${result.env ? ` (DOFLOW_FAILURE_CAPTURE=${result.env})` : ''}${result.decidedBy ? ` (decided by ${result.decidedBy})` : ''}`];
 }
 
 /**

package/src/runtime/failure/home.js

@@ -4,32 +4,50 @@
 
 /**
  * Where DoFlow's own failures are kept on this machine, and whether capture is on (IC-011, IC-014).
- * One folder per machine, shared by every project (DEC-007). Node and the bash writers resolve the
- * home the same way, so a failure captured by either lands in the one list: `XDG_CONFIG_HOME` when it
- * is set, non-empty and absolute, else `$HOME/.config` when `HOME` is set and absolute. Node reads the
- * `HOME` variable and not `os.homedir()`, so both sides agree. A relative or missing base means
- * there is no home, and capture is skipped.
+ * One folder per machine, shared by every project (DEC-007), `failures` beside `settings.json` in the
+ * config home (`../config-home.js`, shared with the bash writers so a failure captured by either lands
+ * in the one list). No config home means no failure home, and capture is skipped.
+ *
+ * The switch (IC-005), in order: no home skips; the environment can only turn capture off; the sentinel
+ * `<home>/off` file turns it off; a `failure.capture` value in `<config home>/settings.json` other than
+ * "on" turns it off (the lexical rule, `../settings/lexical.js`). Otherwise it is on.
  */
 
-const fs = require('node:fs');
 const path = require('node:path');
-
-const OFF_VALUES = new Set(['off', '0', 'false', 'no']);
+const { configHome } = require('../config-home.js');
+const { isOffWord } = require('../off-words.js');
 
 /** @param {Object} [env] defaults to process.env
  * @returns {string|null} the failure home, an absolute path, or null when none can be resolved */
 function failureHome(env      = process.env)                {
-  const xdg = env.XDG_CONFIG_HOME;
-  if (typeof xdg === 'string' && xdg !== '') {
-    return path.isAbsolute(xdg) ? path.join(xdg, 'doflow', 'failures') : null;
-  }
-  const home = env.HOME;
-  if (typeof home === 'string' && path.isAbsolute(home)) return path.join(home, '.config', 'doflow', 'failures');
-  return null;
+  const { dir } = configHome(env);
+  return dir === null ? null : path.join(dir, 'failures');
 }
 
 const sentinelPath = (home        )         => path.join(home, 'off');
 const eventsPath = (home        )         => path.join(home, 'events.jsonl');
+/** `settings.json` sits in the config home, one level above the failure home. */
+const settingsPath = (home        )         => path.join(path.dirname(home), 'settings.json');
+
+/** Resolves the machine-wide setting and returns the file and sentinel parts of the old result shape. */
+function resolvedCapture(home        , env     )                                                                                                                                     {
+  const { loadSettings } = require('../settings/resolve.js');
+  const resolverEnv = { ...env, XDG_CONFIG_HOME: path.dirname(path.dirname(home)) };
+  const view = loadSettings({ global: true, env: resolverEnv });
+  const result = view.get('failure.capture', 'global');
+  const sentinel = result.candidates.some((candidate     ) =>
+    candidate.legacy && candidate.source === sentinelPath(home) && candidate.value === 'off');
+  const file = result.candidates.find((candidate     ) =>
+    !candidate.legacy && candidate.layer === 'user' && candidate.source === settingsPath(home));
+  const settings = file?.value === 'on' || file?.value === 'off' ? file.value : null;
+  return {
+    effective: result.value === 'off' ? 'off' : 'on', sentinel, settings,
+    decidedBy: result.origin.source,
+    deprecatedNotes: view.notes.filter((note     ) => note.code === 'deprecated'
+      && note.key === 'failure.capture' && result.origin.legacy && note.source === result.origin.source)
+      .map((note     ) => note.text),
+  };
+}
 
 /** The value of `DOFLOW_FAILURE_CAPTURE` when it is set to anything, else null. */
 function envSetting(env      = process.env)                {
@@ -38,27 +56,36 @@ function envSetting(env      = process.env)                {
 }
 
 /**
- * The capture switch (IC-014). The sentinel file wins over everything and the environment can only
- * turn capture off, never on over a sentinel. One `stat`, no folder created.
+ * The capture switch (IC-014, IC-005). The resolver applies the global sentinel, lexical settings
+ * file value and environment layers; any off value wins. The resolver reads without creating a folder.
  * @param {string|null} home
  * @param {Object} [env]
- * @returns {{effective: 'on'|'off', sentinel: boolean, env: string|null}}
+ * @returns {{effective: 'on'|'off', sentinel: boolean, env: string|null, settings: 'on'|'off'|null}}
+ *   `settings` is the lexical read of settings.json: null when the file holds no `failure.capture`
  */
-function captureSwitch(home               , env      = process.env)                                                                     {
-  let sentinel = false;
-  if (home) {
-    try { sentinel = fs.statSync(sentinelPath(home)).isFile(); } catch { sentinel = false; }
-  }
+function captureSwitchDetailed(home               , env      = process.env)                                                                                                                                                         {
   const setting = envSetting(env);
-  const envOff = setting !== null && OFF_VALUES.has(setting.trim().toLowerCase());
-  return { effective: sentinel || envOff ? 'off' : 'on', sentinel, env: setting };
+  if (!home) {
+    const envOff = isOffWord(setting);
+    return { effective: envOff ? 'off' : 'on', sentinel: false, env: setting, settings: null, decidedBy: null, deprecatedNotes: [] };
+  }
+  try {
+    const resolved = resolvedCapture(home, env);
+    return { ...resolved, env: setting };
+  } catch {
+    return { effective: 'off', sentinel: false, env: setting, settings: null, decidedBy: null, deprecatedNotes: [] };
+  }
 }
 
-/** The hot-path check a writer makes: the environment first, then one `stat` of the sentinel. */
+/** The public switch shape, with the resolver's deciding source added by IC-005 P3. */
+function captureSwitch(home               , env      = process.env)                                                                                                                              {
+  const state = captureSwitchDetailed(home, env);
+  return { effective: state.effective, sentinel: state.sentinel, env: state.env, settings: state.settings, decidedBy: state.decidedBy };
+}
+
+/** The hot-path check a writer makes; the shared resolver owns sentinel and settings-file reads. */
 function captureIsOff(home        , env      = process.env)          {
-  const setting = envSetting(env);
-  if (setting !== null && OFF_VALUES.has(setting.trim().toLowerCase())) return true;
-  try { return fs.statSync(sentinelPath(home)).isFile(); } catch { return false; }
+  try { return resolvedCapture(home, env).effective === 'off'; } catch { return true; }
 }
 
-module.exports = { failureHome, captureSwitch, captureIsOff, sentinelPath, eventsPath, envSetting };
+module.exports = { failureHome, captureSwitch, captureSwitchDetailed, captureIsOff, sentinelPath, eventsPath, envSetting };

package/src/runtime/failure/store.js

@@ -20,6 +20,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { failureHome, captureSwitch, eventsPath } = require('./home.js');
 const { printSafe } = require('../mask.js');
+const { appendRegular } = require('./capture.js');
 
 const ROTATED = /^events-\d{8}T\d{6}Z-\d+\.jsonl$/;
 const SETTLEMENTS = 'settlements.jsonl';
@@ -203,14 +204,18 @@ function loadEntries({ env = process.env } = {})      {
 }
 
 /**
- * Appends one settlement line (IC-013). Only `failure --action settle` calls this.
+ * Appends one settlement line (IC-013). Only `failure --action settle` calls this. The line goes to a
+ * regular file only (`appendRegular`, shared with the capture writer): a FIFO at `settlements.jsonl`
+ * would block the open for ever, and a symlink or device is not a place to write.
  * @param {string} home
  * @param {{fp: string, as: string, reason?: string|null, followup?: string|null, now?: Date}} settlement
+ * @throws when the file cannot be appended to; it is left as it was
  */
 function appendSettlement(home        , { fp, as, reason = null, followup = null, now = new Date() }     )       {
   fs.mkdirSync(home, { recursive: true, mode: 0o700 });
   const line = JSON.stringify({ v: 1, at: now.toISOString(), fp, as, reason, followup });
-  fs.appendFileSync(settlementsPath(home), `${line}\n`, { flag: 'a', mode: 0o600 });
+  const written = appendRegular(settlementsPath(home), `${line}\n`);
+  if (!written) throw new Error(`${settlementsPath(home)} is not a regular file that can be appended to (a FIFO, a link, a device or a file without write access), so the settlement was not recorded. Nothing was written.`);
 }
 
 const DOFLOW_PACKAGE = '@khoavu882/doflow';

package/src/runtime/feature-pointer.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The feature pointer (row 135): `<storeRoot>/.doflow/state/feature/<id>.json` names the feature one
+ * checkout of the repository is working on, so a fresh session reads it instead of inferring the
+ * feature from the branch alone. Only the runtime writes it, when a feature is started or switched
+ * (`lifecycle --action init`, an `orchestrate` start or catch-up that begins a `feature` run) and
+ * clears it when the feature finishes. The branch stays the other witness: `describe` reports a
+ * disagreement instead of trusting either side.
+ *
+ * One file per checkout, named by the first 16 hex of the sha256 of the checkout's realpath git
+ * toplevel, so two worktrees on two features never share a file: there is no read-modify-write
+ * across checkouts to lose an update in, and each write is a temp file renamed into place.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { resolveActiveFeature } = require('./feature-resolve.js');
+
+const SCHEMA = 1;
+const POINTER_DIR = path.join('.doflow', 'state', 'feature');
+const POINTER_NAME = /^[0-9a-f]{16}\.json$/;
+
+                                                                                                                                                                      
+
+const checkoutId = (checkout        )         => crypto.createHash('sha256').update(checkout).digest('hex').slice(0, 16);
+/** The pointer file of the checkout whose realpath git toplevel is `checkout`. */
+const pointerFile = (storeRoot        , checkout        )         => path.join(storeRoot, POINTER_DIR, `${checkoutId(checkout)}.json`);
+
+function git(cwd        , args          )                {
+  try { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; }
+}
+
+/** The checkout `cwd` is in (its realpath git toplevel) and its current branch, or null outside a repository. */
+function checkoutOf(cwd        )                                                {
+  const top = git(cwd, ['rev-parse', '--show-toplevel']);
+  if (!top) return null;
+  let key = top;
+  try { key = fs.realpathSync(top); } catch { /* keep git's spelling */ }
+  return { key, branch: git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']) || null };
+}
+
+/** One pointer file: `{status:'none'}`, `{status:'ok', data}` or `{status:'unreadable', reason}`. */
+function readEntry(file        )                                                                                 {
+  let text        ;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (error     ) {
+    return error.code === 'ENOENT' ? { status: 'none' } : { status: 'unreadable', reason: error.message };
+  }
+  try {
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || data.schema !== SCHEMA || typeof data.slug !== 'string') {
+      return { status: 'unreadable', reason: `${path.basename(file)} is not a schema ${SCHEMA} pointer file` };
+    }
+    return { status: 'ok', data };
+  } catch (error     ) {
+    return { status: 'unreadable', reason: `${path.basename(file)} is not valid JSON: ${error.message}` };
+  }
+}
+
+function writeEntry(file        , entry              )       {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(entry, null, 2)}\n`);
+    fs.renameSync(temp, file);
+  } finally {
+    try { fs.unlinkSync(temp); } catch { /* renamed away, or never written */ }
+  }
+}
+
+function removeEntry(file        )       {
+  try { fs.unlinkSync(file); } catch (error     ) { if (error.code !== 'ENOENT') throw error; }
+}
+
+/** Runs a pointer write; a failure is one stderr note and never reaches the verb's exit status. */
+function bestEffort(what        , fn            )       {
+  try { fn(); } catch (error     ) { console.error(`doflow: note: feature pointer not ${what}: ${error.message}`); }
+}
+
+/** The artifact folder of `slug`, repo-relative: the resolver's answer, else the default folder when it exists. */
+function artifactDirOf(checkout        , storeRoot        , slug        )                {
+  const found = resolveActiveFeature({ projectRoot: checkout, slug });
+  if (!found.error && found.paths && typeof found.paths.feature_dir === 'string') return found.paths.feature_dir;
+  const rel = path.join('agent-docs', 'doflow', slug);
+  for (const root of [checkout, storeRoot]) {
+    try { if (fs.statSync(path.join(root, rel)).isDirectory()) return rel; } catch { /* absent */ }
+  }
+  return null;
+}
+
+/** Sets the calling checkout's entry to `slug` (a later start of another slug overwrites it, and so does an unreadable file). */
+function recordFeature({ storeRoot, cwd, slug, taskId = null }                                                                                 )       {
+  if (!slug) return;
+  bestEffort('written', () => {
+    const here = checkoutOf(cwd);
+    if (!here) return;
+    writeEntry(pointerFile(storeRoot, here.key), {
+      schema: SCHEMA, checkout: here.key, slug, artifactDir: artifactDirOf(here.key, storeRoot, slug), branch: here.branch, taskId, updatedAt: new Date().toISOString(),
+    });
+  });
+}
+
+/** Removes the calling checkout's entry when it names `slug`; an unreadable file is left alone. */
+function clearCheckout({ storeRoot, cwd, slug }                                                         )       {
+  if (!slug) return;
+  bestEffort('cleared', () => {
+    const here = checkoutOf(cwd);
+    if (!here) return;
+    const file = pointerFile(storeRoot, here.key);
+    const read = readEntry(file);
+    if (read.status === 'ok' && read.data .slug === slug) removeEntry(file);
+  });
+}
+
+/** Removes every entry naming `slug`, whichever checkout holds it (the feature is finished). */
+function clearSlug({ storeRoot, slug }                                            )       {
+  if (!slug) return;
+  bestEffort('cleared', () => {
+    const dir = path.join(storeRoot, POINTER_DIR);
+    let names          ;
+    try { names = fs.readdirSync(dir); } catch (error     ) { if (error.code === 'ENOENT') return; throw error; }
+    for (const name of names.filter((n) => POINTER_NAME.test(n))) {
+      const read = readEntry(path.join(dir, name));
+      if (read.status === 'ok' && read.data .slug === slug) removeEntry(path.join(dir, name));
+    }
+  });
+}
+
+/**
+ * What the calling checkout's pointer says against what its branch says.
+ * `state`: none (no entry), agree, mismatch (branch or branch-derived slug differs) or unreadable.
+ * A mismatch names neither side as the answer: `slug` is null and both are reported.
+ */
+function describeActive({ storeRoot, cwd }                                    )      {
+  const here = checkoutOf(cwd);
+  const found = resolveActiveFeature({ projectRoot: here ? here.key : cwd });
+  const derived = !found.error && found.paths && typeof found.paths.feature_slug === 'string' ? found.paths.feature_slug : null;
+  const current = { branch: here ? here.branch : null, slug: derived };
+  const base = { slug: null, artifactDir: null, branch: null, pointer: null, current };
+  if (!here) return { ...base, state: 'none' };
+  const file = pointerFile(storeRoot, here.key);
+  const read = readEntry(file);
+  if (read.status === 'unreadable') return { ...base, state: 'unreadable', reason: read.reason, file: path.relative(storeRoot, file) };
+  if (read.status === 'none') return { ...base, state: 'none' };
+  const entry = read.data ;
+  const mismatch = entry.branch !== current.branch || (derived !== null && derived !== entry.slug);
+  if (mismatch) return { ...base, state: 'mismatch', pointer: entry };
+  return { state: 'agree', slug: entry.slug, artifactDir: entry.artifactDir ?? null, branch: entry.branch ?? null, pointer: entry, current };
+}
+
+/**
+ * The calling checkout's pointer entry when its recorded branch is the checkout's branch, else null
+ * (no repository, no entry, unreadable, or a branch switch since). Unlike `describeActive` it does
+ * not run the feature resolver: a caller on a hot path (the context-pack verb, issue #9) needs the
+ * runtime's own record, not a second derivation from the branch.
+ */
+function activeEntry({ storeRoot, cwd, checkout }                                                                                                   )                      {
+  // `checkout` is the caller's already-resolved checkout (its feature resolution): no git child is spawned for it.
+  let here                                               ;
+  if (checkout?.repoRoot) {
+    let key = checkout.repoRoot;
+    try { key = fs.realpathSync(key); } catch { /* keep the resolver's spelling */ }
+    here = { key, branch: checkout.branch || null };
+  } else here = checkoutOf(cwd);
+  if (!here) return null;
+  const read = readEntry(pointerFile(storeRoot, here.key));
+  return read.status === 'ok' && read.data .branch === here.branch ? read.data  : null;
+}
+
+module.exports = { recordFeature, clearCheckout, clearSlug, describeActive, activeEntry, pointerFile, POINTER_DIR };

package/src/runtime/feature-resolve.js

@@ -27,7 +27,7 @@ const PATHS_HELPER = resolveBashHelper('do-paths.sh');
  * @param {Object} options
  * @param {string} options.projectRoot working directory the resolution is relative to
  * @param {string|null} [options.slug] explicit feature override, passed straight through
- * @returns {{repoRoot:string, featureDir:string, paths:Object}|{error:string, message:string}}
+ * @returns {{repoRoot:string, featureRoot:string, featureDir:string, featureFolder:string, paths:Object}|{error:string, message:string}}
  *   `paths` is the resolver's own parsed JSON (repo-root-relative artifact paths and has_* flags),
  *   so a caller needs no second resolver call.
  */
@@ -73,7 +73,18 @@ function resolveActiveFeature({ projectRoot, slug = null }
   if (!paths.repo_root || !paths.feature_dir) {
     return { error: 'no-active-feature', message: 'the resolver named no active feature directory to scaffold' };
   }
-  return { repoRoot: paths.repo_root, featureDir: path.resolve(paths.repo_root, paths.feature_dir), paths };
+  // `featureDir` is the folder in the checkout asked about (what every caller used before 115 and
+  // still tests for "this checkout has the folder"). `featureRoot` is the checkout that holds the
+  // folder (the main checkout when a linked worktree has none of its own) and `featureFolder` the
+  // folder there: the `decision` verb reads and writes its register through those.
+  const featureRoot = paths.feature_root || paths.repo_root;
+  return {
+    repoRoot: paths.repo_root,
+    featureRoot,
+    featureDir: path.resolve(paths.repo_root, paths.feature_dir),
+    featureFolder: path.resolve(featureRoot, paths.feature_dir),
+    paths,
+  };
 }
 
 module.exports = { resolveActiveFeature, PATHS_HELPER };

package/src/runtime/fleet/command.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * `doflow fleet` (093 V8): the cross-project, read-only Fleet verb. `--action projects` prints
+ * `listProjects` (IC-019); `--action tree`, run with `cwd` = one project, prints that project's agent
+ * hierarchy (IC-020, `buildTree`). It writes nothing: no state, no config home, no upkeep.
+ */
+
+const { finishRuntime, captureCaught } = require('../cli-result.js');
+
+const ALLOWED_FLAGS = new Set(['--action', '--json']);
+
+function dash(value         )         {
+  return value === null || value === undefined ? '-' : String(value);
+}
+
+/** The text form: one line per project, no path (`root` is for the Console server only). */
+function projectLines(body     )           {
+  const { excluded } = body;
+  return [
+    `store: ${body.store}`,
+    ...body.projects.map((p     ) => `project ${p.projectKey} ${p.label}${p.current ? ' current' : ''} checkouts ${p.checkouts} sources ${p.sources.join(',')} last-record ${dash(p.lastRecordAt)}`),
+    `excluded: missing ${excluded.missing} temp ${excluded.temp} not-doflow ${excluded.notDoflow} unreadable ${excluded.unreadable}`,
+    ...(body.truncated ? ['truncated: true'] : []),
+  ];
+}
+
+/** The text form of `tree`: one line per node and per edge; keys, labels and bases only. */
+function treeLines(body     )           {
+  return [
+    `project ${body.projectKey}`,
+    ...body.nodes.map((n     ) => `node ${n.agentKey} ${n.kind} harness ${dash(n.harness)} model ${dash(n.model)} label ${dash(n.label)} depth ${n.depth} liveness ${n.liveness} transcript ${n.transcript.linked ? 'linked' : n.transcript.reason}`),
+    ...body.edges.map((e     ) => `edge ${e.from} -> ${e.to} ${e.basis}`),
+    `limits: nodes ${body.limits.nodes} not-checked ${body.limits.notChecked} unreadable ${body.unreadable}`,
+  ];
+}
+
+function handleFleetCommand({ action, json = false, flags = [], env = process.env, cwd = process.cwd(), exec, tempRoots, alive, out = (line        ) => console.log(line) }      = {})         {
+  const usage = (message        )         => {
+    out(json ? JSON.stringify({ ok: false, error: 'usage', message }) : `doflow fleet: ${message}`);
+    return finishRuntime(2);
+  };
+  if (action !== 'projects' && action !== 'tree') return usage('action must be projects or tree');
+  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`);
+
+  try {
+    if (action === 'tree') {
+      const { buildTree } = require('./tree.js');
+      const built = buildTree({ env, cwd, ...(exec ? { exec } : {}), ...(alive ? { alive } : {}) });
+      if (!built.ok) {
+        if (json) out(JSON.stringify({ v: 1, error: built.error }));
+        else console.error('[ERROR] fleet: cannot list checkouts');
+        return finishRuntime(1);
+      }
+      if (json) out(JSON.stringify(built.body));
+      else for (const line of treeLines(built.body)) out(line);
+      return finishRuntime(0);
+    }
+    const { listProjects } = require('./projects.js');
+    const listed = listProjects({ env, cwd, ...(exec ? { exec } : {}), ...(tempRoots ? { tempRoots } : {}) });
+    if (!listed.ok) {
+      if (json) out(JSON.stringify({ v: 1, error: listed.error }));
+      else console.error('[ERROR] fleet: cannot list projects');
+      return finishRuntime(1);
+    }
+    if (json) out(JSON.stringify(listed.body));
+    else for (const line of projectLines(listed.body)) out(line);
+    return finishRuntime(0);
+  } catch (error     ) {
+    captureCaught(error, 'fleet', 1);
+    console.error(`[ERROR] fleet: ${error?.message || String(error)}`);
+    return finishRuntime(1);
+  }
+}
+
+module.exports = { handleFleetCommand };