@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/context/delivery-store.js

@@ -3,9 +3,8 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
 const fs = require('node:fs');
-const path = require('node:path');
 const { boundedAcquire, updateTaskState } = require('../task-state.js');
-const { taskStoreDir } = require('../task-scope.js');
+const { taskRecord } = require('../task-scope.js');
 
 const MAX_DELIVERIES = 5;
 const ACTUAL_UNMEASURED = 'no harness reports token usage to an external CLI; profile tokenTelemetry unverified';
@@ -64,8 +63,7 @@ function createDeliveryEntry({ pack, form, harness = null, sources = {}, expansi
 }
 
 function readDeliveryEntry({ projectRoot, taskId, slug = null, packDigest, fsImpl = fs }     )             {
-  const dir = taskStoreDir({ projectRoot, store: 'delivery', taskId, slug });
-  const file = path.join(dir, `${taskId}.json`);
+  const file = taskRecord({ projectRoot, store: 'delivery', taskId, slug, fsImpl }).read;
   try {
     const disk = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
     return (Array.isArray(disk.deliveries) ? disk.deliveries : []).find((entry     ) => entry.packDigest === packDigest) || null;
@@ -80,11 +78,11 @@ function recordDelivery({ projectRoot, taskId, slug = null, entry, fsImpl = fs,
   if (typeof taskId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || taskId.includes('..')) {
     throw new Error(`Invalid task id '${taskId}'`);
   }
-  const dir = taskStoreDir({ projectRoot, store: 'delivery', taskId, slug });
-  const file = path.join(dir, `${taskId}.json`);
+  const { file, seed } = taskRecord({ projectRoot, store: 'delivery', taskId, slug, fsImpl });
   const written = updateTaskState({
     fsImpl,
     file,
+    prepare: seed,
     acquire: (impl     , target        ) => acquire(impl, target, { retries: 3, waitMs: 5 }),
     build(disk     ) {
       const deliveries = Array.isArray(disk?.deliveries) ? disk.deliveries : [];

package/src/runtime/context/emission-rules.js

@@ -0,0 +1,118 @@
+'use strict';
+
+// Rule compiler for the hook emission table (078 IC-003, DEC-005). Run directly by Node native
+// type-stripping:
+//
+//   node src/runtime/context/emission-rules.js --write   rewrite the committed table
+//   node src/runtime/context/emission-rules.js --check   exit 0 equal, 1 differs, 2 usage
+//
+// The table is compiled from EMISSION_RULES, never written by hand: each rule's finite domain is
+// enumerated through INPUT_DOMAINS and ruleAction(), so every arm the hook reads is the action
+// arbitrate() gives that vector. Every combination is written as its own literal arm; a pattern
+// holds no glob, so the hook's lookup matches exactly what IC-002 lists and nothing else.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { EMISSION_RULES, INPUT_DOMAINS, ruleAction } = require('./arbitrate.js');
+
+const TABLE_REL = 'core/harnesses/shared/hooks/policies/emission-rules.sh';
+const RULES_VERSION = 1;
+const MAX_BYTES_DEFAULT = 16384;
+const SUMMARY_CAP = 4000;
+const SUMMARY_READ = 65536;
+
+/** Every value combination of the named inputs, in vector order. */
+function combinations(inputs                   )             {
+  let out             = [[]];
+  for (const name of inputs) {
+    const domain                    = INPUT_DOMAINS[name];
+    out = out.flatMap((prefix) => domain.map((value) => [...prefix, value]));
+  }
+  return out;
+}
+
+/** JSON with object keys sorted at every depth, so the digest does not depend on key order. */
+function canonicalJson(value         )         {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.keys(value          ).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson((value                           )[key])}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function rulesDigest(rules                    )         {
+  return crypto.createHash('sha256').update(canonicalJson(rules), 'utf8').digest('hex');
+}
+
+function compare(a        , b        )         {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+                                                                                        
+
+/** Every non-skip combination of every rule, sorted by event, segment, vector. */
+function compileArms(rules                 = EMISSION_RULES)                {
+  const arms                = [];
+  for (const r of rules) {
+    for (const values of combinations(r.inputs)) {
+      const action = ruleAction(r, values);
+      if (action !== 'skip') arms.push({ event: r.event, segment: r.segment, vector: values.join(':'), action });
+    }
+  }
+  return arms.sort((a, b) => compare(a.event, b.event) || compare(a.segment, b.segment) || compare(a.vector, b.vector));
+}
+
+/** A value safe inside a single-quoted bash pattern, with no glob character. */
+function literal(text        )         {
+  if (!/^[A-Za-z0-9._:|-]+$/.test(text)) throw new TypeError(`emission-rules: ${JSON.stringify(text)} is not a plain token`);
+  return text;
+}
+
+/** IC-003: the full text of `emission-rules.sh`. */
+function compileEmissionTable(rules                 = EMISSION_RULES)         {
+  const lines = [
+    '# Generated by node src/runtime/context/emission-rules.js --write. Do not edit.',
+    `# rules-digest: sha256:${rulesDigest(rules)}`,
+    `DF_RULES_VERSION=${RULES_VERSION}`,
+    `DF_RULES_MAX_BYTES_DEFAULT=${MAX_BYTES_DEFAULT}`,
+    `DF_RULES_SUMMARY_CAP=${SUMMARY_CAP}`,
+    `DF_RULES_SUMMARY_READ=${SUMMARY_READ}`,
+    'doflow_emission_rule() {',
+    "  # $1 = event.segment, $2 = vector: input values joined with ':' in IC-002 order",
+    '  case "$1|$2" in',
+  ];
+  for (const arm of compileArms(rules)) {
+    lines.push(`    '${literal(`${arm.event}.${arm.segment}|${arm.vector}`)}') DF_ACTION=${literal(arm.action)} ;;`);
+  }
+  lines.push('    *) DF_ACTION=skip ;;', '  esac', '}');
+  return `${lines.join('\n')}\n`;
+}
+
+const USAGE = 'usage: node src/runtime/context/emission-rules.js --write|--check\n';
+
+/** The CLI: 0 written or equal, 1 the committed table differs from the rules, 2 usage. */
+function main(argv          )         {
+  if (argv.length !== 1 || (argv[0] !== '--write' && argv[0] !== '--check')) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const target = path.join(REPO_ROOT, TABLE_REL);
+  const expected = compileEmissionTable();
+  if (argv[0] === '--write') {
+    fs.writeFileSync(target, expected);
+    return 0;
+  }
+  let actual               ;
+  try { actual = fs.readFileSync(target, 'utf8'); } catch { actual = null; }
+  if (actual === expected) return 0;
+  process.stderr.write(`emission-rules: ${TABLE_REL} is ${actual === null ? 'missing' : 'stale'}; run node src/runtime/context/emission-rules.js --write\n`);
+  return 1;
+}
+
+module.exports = { TABLE_REL, canonicalJson, compileArms, compileEmissionTable, rulesDigest };
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));

package/src/runtime/context/identity.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// Session identity reader (078 IC-007). Run directly by Node native type-stripping.
+//
+// The TypeScript twin of `policies/identity.sh`: both read the launcher-set environment the same
+// way, and test/fixtures/identity/cases.json is the corpus both must agree on (G38.6). Identity
+// comes only from DOFLOW_RUN_ID, DOFLOW_ATTEMPT, DOFLOW_LINEAGE_ID, DOFLOW_SESSION_ROLE and
+// DOFLOW_WORKTREE plus the payload's session_id and cwd; it is never inferred from git or from the
+// harness's own idea of a main session.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { configHome } = require('../config-home.js');
+
+/** DEC-024: a launched unit id `L.<run>.<lineage>.<attempt>` stays inside the 128-character session-dirs match. */
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$/;
+const ATTEMPT_PATTERN = /^[1-9][0-9]{0,3}$/;
+const DEFAULT_RUN = 'local';
+const UNKNOWN_ROLE_LINE = '[doflow] unknown DOFLOW_SESSION_ROLE; treating session as worker\n';
+
+                                              
+                              
+                                                        
+                                                                             
+
+                           
+              
+                  
+                  
+             
+                   
+                           
+                 
+                  
+                            
+ 
+
+                          
+              
+                    
+                 
+                                
+ 
+
+let roleWarned = false;
+
+/** `<config home>/doflow/session-env`, the root `policies/lib.sh` names STATE_DIR; null with no config home (IC-010), and the callers then skip session state. */
+function stateDir(env      = process.env)                {
+  const { dir } = configHome(env);
+  return dir === null ? null : path.join(dir, 'session-env');
+}
+
+/** `(cd "$p" && pwd -P)`: the physical path of an existing directory, or null. */
+function physicalDir(p        )                {
+  try {
+    if (!fs.statSync(p).isDirectory()) return null;
+    return fs.realpathSync.native(p);
+  } catch {
+    return null;
+  }
+}
+
+/** `canonicalize_path` from policies/lib.sh: resolve the parent chain of an existing path, never its leaf. */
+function canonicalizePath(p        )         {
+  try {
+    fs.statSync(p); // `[[ -e ]]` follows symlinks, so a dangling link is "missing"
+    const dir = fs.realpathSync.native(path.dirname(p));
+    const base = path.basename(p);
+    return dir === '/' ? `/${base}` : `${dir}/${base}`;
+  } catch {
+    return p;
+  }
+}
+
+/** `cwd_hash` from policies/lib.sh: first 16 hex chars of sha256 over the canonical path plus `echo`'s newline. */
+function cwdHash(p        )         {
+  let canonical = physicalDir(p) ?? canonicalizePath(p);
+  // bash hashes `pwd -P`, which Git Bash prints as /c/Users/x; hash the same spelling for a native C:\\Users\\x.
+  if (process.platform === 'win32') {
+    const drive = /^([A-Za-z]):[\\/]?(.*)$/.exec(canonical);
+    if (drive) canonical = `/${drive[1].toLowerCase()}${drive[2] ? `/${drive[2].replace(/\\/g, '/')}` : ''}`;
+  }
+  return crypto.createHash('sha256').update(`${canonical}\n`).digest('hex').slice(0, 16);
+}
+
+/** `tr '[:upper:]' '[:lower:]'` on the role, ASCII only, then today's mapping: unset is main, unknown is worker. */
+function readRole(raw                    )                                   {
+  const role = (raw || '').replace(/[A-Z]/g, (c) => c.toLowerCase());
+  if (role === '' || role === 'main') return { role: 'main', unknown: false };
+  if (role === 'worker') return { role: 'worker', unknown: false };
+  return { role: 'worker', unknown: true };
+}
+
+/** DOFLOW_WORKTREE canonicalised when it names an absolute existing directory; else the payload cwd as given (cwdHash canonicalises for the store key). */
+function readWorktree(raw                    , cwd        )         {
+  if (raw && raw.startsWith('/')) {
+    const dir = physicalDir(raw);
+    if (dir !== null) return dir;
+  }
+  return cwd;
+}
+
+/**
+ * Create `sessions/<unitId>/bound` exclusively, holding the session id. True when this session owns
+ * the unit (just bound, or bound earlier by the same session); false when another session bound it,
+ * and false when it cannot be decided (the store is unwritable, `bound` is a symlink, which is never
+ * followed, or `bound` is still empty after one retry). Never throws: the caller treats false as an
+ * inherited session (L1-04).
+ */
+function bindUnit(env     , unitId        , sessionId        )          {
+  const root = stateDir(env);
+  if (root === null) return false;
+  const dir = path.join(root, 'sessions', unitId);
+  const file = path.join(dir, 'bound');
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const fd = fs.openSync(file, 'wx');
+    try {
+      fs.writeSync(fd, `${sessionId}\n`);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch (error     ) {
+    if (error?.code !== 'EEXIST') return false;
+  }
+  // `IFS= read -r bound` of a regular file, not a symlink: its first line. An empty first line may
+  // be a concurrent binder between its create and its write, so it is read once more.
+  for (let tries = 0; tries < 2; tries++) {
+    let bound        ;
+    try {
+      if (!fs.lstatSync(file).isFile()) return false;
+      bound = fs.readFileSync(file, 'utf8').split('\n')[0];
+    } catch {
+      return false;
+    }
+    if (bound !== '') return bound === sessionId;
+  }
+  return false;
+}
+
+/** IC-007: the session identity from the environment and the payload's session id and cwd. */
+function resolveIdentity(env     , options                )                  {
+  const { cwd, sessionId, bind = false } = options;
+  const diagnostics = new Set            ();
+
+  const { role, unknown } = readRole(env.DOFLOW_SESSION_ROLE);
+  if (unknown) {
+    diagnostics.add('role-unknown');
+    if (!roleWarned) {
+      roleWarned = true;
+      (options.warn ?? ((line        ) => process.stderr.write(line)))(UNKNOWN_ROLE_LINE);
+    }
+  }
+
+  const rawRun = env.DOFLOW_RUN_ID || '';
+  const runValid = rawRun !== '' && rawRun !== DEFAULT_RUN && ID_PATTERN.test(rawRun);
+  if (rawRun !== '' && !runValid) diagnostics.add('identity-invalid');
+  const run = runValid ? rawRun : DEFAULT_RUN;
+
+  const rawAttempt = env.DOFLOW_ATTEMPT || '';
+  const attempt = ATTEMPT_PATTERN.test(rawAttempt) ? rawAttempt : '';
+
+  const rawLineage = env.DOFLOW_LINEAGE_ID || '';
+  const lineageValid = rawLineage !== '' && ID_PATTERN.test(rawLineage);
+  if (rawLineage !== '' && !lineageValid) diagnostics.add('identity-invalid');
+  let lineage        ;
+  if (rawRun !== '' && !runValid) lineage = 'solo';
+  else if (rawLineage === '') lineage = role === 'main' ? 'main' : 'solo';
+  else lineage = lineageValid ? rawLineage : 'solo';
+
+  let lineageKind              = 'solo';
+  if (runValid && lineageValid && attempt !== '') lineageKind = 'launched';
+  else if (run === DEFAULT_RUN && lineage === 'main') lineageKind = 'default-main';
+
+  let unitId = lineageKind === 'launched' ? `L.${run}.${lineage}.${attempt}` : sessionId;
+  if (lineageKind === 'launched' && bind) {
+    // An empty session id cannot bind: solo with an empty unit and no capture, as identity.sh.
+    // Any other failure to bind is an inherited session (DEC-044).
+    const mine = sessionId !== '' && bindUnit(env, unitId, sessionId);
+    if (!mine) {
+      if (sessionId !== '') diagnostics.add('identity-inherited');
+      lineageKind = 'solo';
+      lineage = 'solo';
+      unitId = sessionId;
+    }
+  }
+
+  return {
+    run,
+    attempt,
+    lineage,
+    role,
+    worktree: readWorktree(env.DOFLOW_WORKTREE, cwd),
+    lineageKind,
+    unitId,
+    session: sessionId,
+    diagnostics: [...diagnostics].sort(),
+  };
+}
+
+/**
+ * The run ledger's identity fields (082 IC-034, DEC-042). Each value is tested on its own and
+ * omitted, never written, when absent or invalid: `run` by `resolveIdentity`'s `runValid` rule
+ * (non-empty, not `local`, `ID_PATTERN`), `lineage` by `ID_PATTERN`, `attempt` by `ATTEMPT_PATTERN`.
+ */
+function identityFields(env     )                                                       {
+  const out                                                       = {};
+  const run = env.DOFLOW_RUN_ID || '';
+  if (run !== '' && run !== DEFAULT_RUN && ID_PATTERN.test(run)) out.run = run;
+  const lineage = env.DOFLOW_LINEAGE_ID || '';
+  if (ID_PATTERN.test(lineage)) out.lineage = lineage;
+  const attempt = env.DOFLOW_ATTEMPT || '';
+  if (ATTEMPT_PATTERN.test(attempt)) out.attempt = attempt;
+  return out;
+}
+
+module.exports = {
+  ATTEMPT_PATTERN,
+  ID_PATTERN,
+  UNKNOWN_ROLE_LINE,
+  cwdHash,
+  identityFields,
+  resolveIdentity,
+  stateDir,
+};

package/src/runtime/context/pointer.js

@@ -4,6 +4,22 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { loadTaxonomy, isPlainText, isUserContextPath } = require('../intake/taxonomy.js');
+
+/** The user's own files (feature 136's intake): a feature folder's `additional-context/`. Markdown there up to
+ * `pointerMaxBytes` of core/registry/intake.json becomes pointers; nothing else does. */
+const USER_CONTEXT_DIR = 'additional-context';
+
+/** The registry's byte cap, or null when the taxonomy cannot be read (intake is then off: no user pointers). */
+function userPointerMaxBytes(file         )                {
+  const loaded = loadTaxonomy({ file, contributions: false });
+  return loaded.ok ? loaded.taxonomy.pointerMaxBytes : null;
+}
+
+/** `'user-provided'` for a project-relative path inside `agent-docs/doflow/<slug>/additional-context/`, else null. */
+function originOf(rel        )                         {
+  return isUserContextPath(rel) ? 'user-provided' : null;
+}
 
 function sha256(text        )         {
   return `sha256:${crypto.createHash('sha256').update(text, 'utf8').digest('hex')}`;
@@ -67,7 +83,7 @@ function rangesFor(file        , text        , requirement         )
   return result;
 }
 
-function createPointer({ path: rel, heading, range, slice }     )      {
+function createPointer({ path: rel, heading, range, slice, user = false }     )      {
   const bytes = Buffer.byteLength(slice, 'utf8');
   return {
     id: `ptr:${rel}:${range.startLine}-${range.endLine}`,
@@ -79,20 +95,42 @@ function createPointer({ path: rel, heading, range, slice }     )      {
     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}`,
+    origin: user ? 'user-provided' : originOf(rel),
   };
 }
 
-function sourceFiles({ projectRoot, feature, fsImpl = fs }     )                                                    {
+/** Visible, regular `.md` files under a context folder, `.intake/` and every dotfile or symlink left out,
+ * in byte order of path. A folder that is absent, or itself a symlink, gives none. */
+function userContextFiles(dir        , fsImpl = fs)           {
+  const found           = [];
+  const walk = (current        ) => {
+    let entries       ;
+    try { entries = fsImpl.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.isSymbolicLink()) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) found.push(full);
+    }
+  };
+  try { if (fsImpl.lstatSync(dir).isSymbolicLink()) return []; } catch { return []; }
+  walk(dir);
+  return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+function sourceFiles({ projectRoot, feature, fsImpl = fs, intakeFile }     )                                                                   {
   const root = path.resolve(projectRoot);
   const featureDir = feature?.featureDir ? path.resolve(feature.featureDir) : null;
-  const candidates                                                    = [];
-  const add = (file                           , requirement = false) => {
+  const candidates                                                                   = [];
+  const add = (file                           , requirement = false, maxBytes = Infinity, user = 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 (!inside(root, absolute, fsImpl) || !stat.isFile() || stat.size > maxBytes) return;
+    const known = candidates.find((item) => item.absolute === absolute);
+    if (known) known.user ||= user;
+    else candidates.push({ absolute, requirement, user });
   };
   if (featureDir) {
     add(feature.paths?.requirement || path.join(featureDir, 'intention', 'requirement.md'), true);
@@ -106,23 +144,40 @@ function sourceFiles({ projectRoot, feature, fsImpl = fs }     )
       path.join(featureDir, 'design.md'),
       path.join(featureDir, 'plan.md'),
     ]) add(file);
+    const maxBytes = userPointerMaxBytes(intakeFile);
+    if (maxBytes !== null) {
+      for (const file of userContextFiles(path.join(featureDir, USER_CONTEXT_DIR), fsImpl)) add(file, false, maxBytes, true);
+    }
   }
   return candidates;
 }
 
-function collectPointers({ projectRoot, feature, fsImpl = fs }     )        {
+/** `intakeFile` overrides the intake registry path (tests); the default is core/registry/intake.json. */
+function collectPointers({ projectRoot, feature, fsImpl = fs, intakeFile }     )        {
   const root = path.resolve(projectRoot);
   const pointers        = [];
-  for (const source of sourceFiles({ projectRoot: root, feature, fsImpl })) {
+  for (const source of sourceFiles({ projectRoot: root, feature, fsImpl, intakeFile })) {
   const rel = inside(root, source.absolute, fsImpl);
     if (!rel) continue;
+    const user = source.user || Boolean(originOf(rel));
     let text        ;
-    try { text = fsImpl.readFileSync(source.absolute, 'utf8'); } catch { continue; }
+    try {
+      const data = fsImpl.readFileSync(source.absolute);
+      // A user's file may be anything saved as .md; only plain UTF-8 text becomes a pointer. `source.user` is where
+      // the file was found, so a realpath outside the `agent-docs/doflow/<slug>/` shape (a linked agent-docs) is held to it too.
+      if (user && !isPlainText(data)) continue;
+      text = data.toString('utf8');
+    } catch { continue; }
     const lines = text.split(/\r?\n/);
-    for (const range of rangesFor(rel, text, source.requirement)) {
+    const ranges = rangesFor(rel, text, source.requirement);
+    // A user's markdown often opens with a title or runs without `##` headings; the sections alone would drop that text.
+    if (user && (!ranges.length || ranges[0].startLine > 1)) {
+      ranges.unshift({ startLine: 1, endLine: ranges.length ? ranges[0].startLine - 1 : lines.length, heading: null });
+    }
+    for (const range of ranges) {
       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 }));
+      pointers.push(createPointer({ path: rel, heading: range.heading, range: { startLine: range.startLine, endLine: range.endLine }, slice, user }));
     }
   }
   return pointers;
@@ -139,4 +194,4 @@ function readPointerSlice({ projectRoot, pointer, fsImpl = fs }     )
   } catch { return null; }
 }
 
-module.exports = { collectPointers, createPointer, readPointerSlice, sha256 };
+module.exports = { collectPointers, createPointer, originOf, 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 };