@khoavu882/doflow 2.0.0 → 2.0.2

package/src/runtime/verb-view.js

@@ -0,0 +1,268 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The shared view helper for verbs that answer in a brief or a full view (feature 137, IC-002, IC-003, IC-007,
+ * IC-008). A verb declares its own brief spec beside its handler; this module resolves the view a call asked for,
+ * projects a full answer onto a keep-path list, pages an ordered item list by cursor, builds next lines from
+ * validated parsed options, and serializes JSON compact off a terminal and indented on one.
+ *
+ * Like `cli-result.ts`, this module requires nothing from src/runtime/ at load time, so any handler can require
+ * it without a cycle. It requires nothing at all.
+ */
+
+                             
+
+/** One verb's brief view, declared beside its handler. */
+                     
+                        
+                           
+                                   
+                                    
+ 
+
+/** The ordering key of a pageable item: the creating event's time in milliseconds, then its event id. */
+                     
+                        
+                         
+ 
+
+/** A caller mistake in a view option: the handler reports it as a usage error (exit 2). */
+class ViewUsageError extends Error {}
+
+const VIEWS                    = ['brief', 'full'];
+
+function resolveView(raw         , defaultView      )       {
+  if (raw === undefined || raw === null) return defaultView;
+  if (typeof raw === 'string' && VIEWS.includes(raw)) return raw        ;
+  throw new ViewUsageError(`--view must be brief or full (got '${String(raw)}')`);
+}
+
+// ---------------------------------------------------------------------------------------------- keep paths
+
+                    
+               
+                                                            
+ 
+
+const KEEP_PATH = /^\$(?:\.[A-Za-z_][A-Za-z0-9_]*(?:\[\])?)+$/;
+const KEEP_SEGMENT = /\.([A-Za-z_][A-Za-z0-9_]*)(\[\])?/g;
+const keepTrees = new Map                  ();
+
+/** Builds the tree of a keep list; a malformed path, or one name used both as an array and not, throws. */
+function keepTree(keep                   )           {
+  const cacheKey = keep.join('\n');
+  const cached = keepTrees.get(cacheKey);
+  if (cached) return cached;
+  const root           = { all: false, children: new Map() };
+  for (const path of keep) {
+    if (!KEEP_PATH.test(path)) throw new Error(`malformed keep path '${path}'`);
+    let node = root;
+    for (const match of path.matchAll(KEEP_SEGMENT)) {
+      const [, name, brackets] = match;
+      const array = brackets !== undefined;
+      let child = node.children.get(name);
+      if (!child) {
+        child = { array, node: { all: false, children: new Map() } };
+        node.children.set(name, child);
+      } else if (child.array !== array) {
+        throw new Error(`keep path '${path}' uses '${name}' both as an array and as a single value`);
+      }
+      node = child.node;
+    }
+    node.all = true;
+  }
+  keepTrees.set(cacheKey, root);
+  return root;
+}
+
+function projectValue(value     , node          )      {
+  if (node.all) return value;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const out                          = {};
+  for (const key of Object.keys(value)) {
+    const child = node.children.get(key);
+    if (!child || value[key] === undefined) continue;
+    let part;
+    if (child.array) {
+      part = Array.isArray(value[key])
+        ? value[key].map((element     ) => (child.node.all || element === null || typeof element !== 'object' || Array.isArray(element)
+          ? element : (projectValue(element, child.node) ?? {})))
+        : undefined;
+    } else {
+      part = projectValue(value[key], child.node);
+      // An object none of whose kept paths exist is absent, not an empty shell.
+      if (part !== undefined && !child.node.all && Object.keys(part).length === 0) part = undefined;
+    }
+    if (part !== undefined) out[key] = part;
+  }
+  return out;
+}
+
+/**
+ * Projects a full answer onto keep paths: `$` then segments `.name` or `.name[]`; a path keeps the whole value at
+ * its last segment, `[]` maps over an array (order and length kept), an absent path is skipped, and output keys
+ * follow the full answer's key order.
+ */
+function projectBrief(full                         , keep                   )                          {
+  return projectValue(full, keepTree(keep)) ?? {};
+}
+
+// -------------------------------------------------------------------------------------------------- cursor
+
+const CURSOR = /^([0-9]{1,15}):([0-9]{8}T[0-9]{9}Z-[0-9a-hjkmnp-tv-z]{6})$/;
+const DIGITS = /^[0-9]+$/;
+
+function encodeCursor(key           )         {
+  if (!Number.isSafeInteger(key.atMs) || key.atMs < 0 || String(key.atMs).length > 15) {
+    throw new ViewUsageError(`cursor time must be 0 to 15 digits of milliseconds (got ${key.atMs})`);
+  }
+  return `${key.atMs}:${key.event}`;
+}
+
+/** The key a cursor names, or null when the text is not a cursor of this format. */
+function decodeCursor(text         )                   {
+  const match = typeof text === 'string' ? CURSOR.exec(text) : null;
+  return match ? { atMs: Number(match[1]), event: match[2] } : null;
+}
+
+/** True when key `a` orders after key `b`: later time, or the same time and a greater event id. */
+function keyAfter(a           , b           )          {
+  return a.atMs > b.atMs || (a.atMs === b.atMs && a.event > b.event);
+}
+
+/**
+ * Pages an item list already in ascending key order. Items at or before the cursor are dropped, then the first
+ * `limit` are kept. `nextCursor` is the last shown item's key when items remain after it, else null.
+ */
+function pageItems   (items              , opts   
+                                                                                          
+                          
+ )                                                           {
+  let limit = opts.defaultLimit;
+  if (opts.limit !== undefined) {
+    const text = String(opts.limit);
+    if (!DIGITS.test(text) || Number(text) < 1) {
+      throw new ViewUsageError(`--limit must be a whole number of 1 or more (at most ${opts.maxLimit} are returned)`);
+    }
+    limit = Math.min(opts.maxLimit, Number(text));
+  }
+  let rest = items;
+  if (opts.cursor !== undefined) {
+    const after = decodeCursor(opts.cursor);
+    if (after === null) throw new ViewUsageError('--cursor must be the nextCursor of an earlier list');
+    rest = items.filter((item) => keyAfter(opts.key(item), after));
+  }
+  const page = limit === null ? rest.slice() : rest.slice(0, limit);
+  const more = page.length < rest.length;
+  return {
+    items: page,
+    shown: page.length,
+    nextCursor: more && page.length > 0 ? encodeCursor(opts.key(page[page.length - 1])) : null,
+  };
+}
+
+// ----------------------------------------------------------------------------------------------- next lines
+
+const SAFE_VALUE = /^[A-Za-z0-9._:@,/-]{1,200}$/;
+const LABELS = { page: 'Next page', 'page-full': 'Full view of this page', full: 'Full view' }         ;
+const VIEW_FLAGS                    = ['cursor', 'limit', 'view'];
+
+function kebab(name        )         {
+  return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+/**
+ * `doflow-run <verb>[ --action <action>]( --<flag>[ <value>])*`, flags in the order of `carried`. A value renders
+ * only when it is `true` (bare flag) or a short safe token (or finite number); any other value renders as the
+ * placeholder `<flag>`, so free text is never carried. `false`, null and undefined are omitted.
+ */
+function commandLine(verb        , action                    , carried                         )         {
+  const parts = ['doflow-run', verb];
+  if (action !== undefined) parts.push('--action', action);
+  for (const [name, value] of Object.entries(carried)) {
+    if (value === undefined || value === null || value === false) continue;
+    const flag = kebab(name);
+    parts.push(`--${flag}`);
+    if (value === true) continue;
+    const text = typeof value === 'number' && Number.isFinite(value) ? String(value) : value;
+    parts.push(typeof text === 'string' && SAFE_VALUE.test(text) ? text : `<${flag}>`);
+  }
+  return parts.join(' ');
+}
+
+/**
+ * The next line of one kind: `page` (the page after this one), `page-full` (this page in the full view, carrying
+ * the input cursor and `--limit <shown>`) or `full` (the verb's whole, bounded, full answer). The options echoed
+ * are those the spec's `carry` names, in that order, then `--cursor`, `--limit`, `--view` (a `page` line names
+ * `--view full` only when the caller's `view` is `full`). Returns no line when
+ * the kind has nothing to point at (`page` without a nextCursor, `page-full` with nothing shown). In a JSON answer
+ * (`json: true`) every line ends with `--json`, so the command as written prints the same JSON shape; a text
+ * answer's lines carry no `--json`.
+ */
+function viewLines(kind                               , ctx   
+                                                                            
+                                                                          
+ )           {
+  const args                          = {};
+  for (const name of ctx.spec.carry) {
+    if (!VIEW_FLAGS.includes(name)) args[name] = ctx.carried[name];
+  }
+  if (kind === 'page') {
+    if (!ctx.nextCursor) return [];
+    args.cursor = ctx.nextCursor;
+    args.limit = ctx.spec.carry.includes('limit') ? ctx.carried.limit : undefined;
+    // A walk stays in the view it started in: brief is the default, so only the full view is named.
+    if (ctx.view === 'full') args.view = 'full';
+  } else if (kind === 'page-full') {
+    if (!ctx.shown || ctx.shown < 1) return [];
+    args.cursor = ctx.cursor ?? undefined;
+    args.limit = ctx.shown;
+    args.view = 'full';
+  } else {
+    args.view = 'full';
+  }
+  const asJson = ctx.json === true ? ' --json' : '';
+  return [`${LABELS[kind]}: ${commandLine(ctx.spec.verb, ctx.spec.action, args)}${asJson}`];
+}
+
+/**
+ * Adds the envelope to an answer body: `view` first; `shown` and `nextCursor` directly after `count` when the body
+ * has one, else after `view`; `next` last (replacing a `next` the body already carries).
+ */
+function withEnvelope(body                         , env   
+                                                                                   
+ )                          {
+  const paging                          = {};
+  if (env.shown !== undefined) paging.shown = env.shown;
+  if (env.nextCursor !== undefined) paging.nextCursor = env.nextCursor;
+  const out                          = { view: env.view };
+  const hasCount = 'count' in body;
+  if (!hasCount) Object.assign(out, paging);
+  for (const [key, value] of Object.entries(body)) {
+    if (key === 'view' || key === 'shown' || key === 'nextCursor' || key === 'next') continue;
+    out[key] = value;
+    if (key === 'count') Object.assign(out, paging);
+  }
+  const next = env.next ?? (body.next                                 );
+  if (next !== undefined) out.next = next;
+  return out;
+}
+
+// --------------------------------------------------------------------------------------------- serialization
+
+/** Compact JSON off a terminal, two-space indented on one; `isTTY` defaults to `process.stdout.isTTY === true`. */
+function serializeJson(value         , opts                      = {})         {
+  const isTTY = opts.isTTY ?? process.stdout.isTTY === true;
+  return isTTY === true ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+
+function emitJson(value         , opts                      = {})       {
+  console.log(serializeJson(value, opts));
+}
+
+module.exports = {
+  ViewUsageError, resolveView, projectBrief, pageItems, encodeCursor, decodeCursor,
+  commandLine, viewLines, withEnvelope, serializeJson, emitJson,
+};

package/src/runtime/verification/engine.js

@@ -1176,51 +1176,6 @@ class VerificationEngine {
     };
   }
 
-  /**
-   * Declares completion. FR-009: a task is complete only when its required checks pass, or when the
-   * user explicitly accepts what is still failing.
-   *
-   * @param {Object} report
-   * @param {Object} [acceptance]
-   * @param {boolean} [acceptance.userAccepted]
-   * @param {string} [acceptance.acceptedBy] who accepted; an unattributed acceptance is refused
-   * @param {string} [acceptance.note]
-   * @returns {{ complete: boolean, basis: string, reason: string, acceptedFailures?: Array<Object> }}
-   */
-  declareCompletion(report     , acceptance      = {})      {
-    if (!report || typeof report.status !== 'string') {
-      throw new Error('declareCompletion expects a report produced by runContract');
-    }
-    if (report.status === 'PASS') {
-      return { complete: true, basis: 'required-checks-passed', reason: report.reason };
-    }
-    if (acceptance.userAccepted !== true) {
-      return {
-        complete: false,
-        basis: 'not-accepted',
-        reason: `Verification is ${report.status}: ${report.reason} Completion needs the required checks to pass or an explicit user acceptance.`,
-      };
-    }
-    const requiresAccepter = (this.policy.completion || {}).overrideRequiresAccepter !== false;
-    if (requiresAccepter && (typeof acceptance.acceptedBy !== 'string' || acceptance.acceptedBy.trim() === '')) {
-      // "The user explicitly accepts" needs a user. An anonymous flag is indistinguishable from the
-      // caller setting it for itself.
-      return {
-        complete: false,
-        basis: 'acceptance-unattributed',
-        reason: 'Accepting a failing verification requires naming who accepted it.',
-      };
-    }
-    return {
-      complete: true,
-      basis: 'user-accepted-failures',
-      reason: acceptance.note || `Accepted by ${acceptance.acceptedBy} while ${report.status}.`,
-      acceptedFailures: (report.tiers || [])
-        .filter((t     ) => t.required && t.status !== 'PASS' && t.status !== 'NOT_APPLICABLE' && t.status !== 'SUBSUMED' && t.status !== 'SKIPPED')
-        .map((t     ) => ({ tier: t.id, status: t.status, reason: t.reason })),
-    };
-  }
-
   /**
    * A stable fingerprint of what failed. Two identical fingerprints across attempts mean the retry
    * changed nothing observable, which FR-010 forbids as a response.

package/src/runtime/worker/command.js

@@ -285,7 +285,7 @@ function evaluate({ reg, worker, harness, needs, coverage, env, cwd, root, nowMs
     nowMs,
   );
   const requirements = readiness.requirementsFor({ harness, worker }, facts, needs, coverage, edit);
-  return { requirements, version: found.version, ...readiness.eligibility(requirements) };
+  return { requirements, version: found.version, binaryPath: found.path, ...readiness.eligibility(requirements) };
 }
 
 /** IC-011 steps 0 to 12, then the supervisor spawn and the start poll. */
@@ -365,7 +365,9 @@ async function runAction(o     ) {
     edit: editRecord, childOf, request: childOf ? o.request : null,
     ...launchRecord(worker, identity, prompt.bytes.toString('utf8'), edit, binding),
     ...(binding ? { binding: { model: binding.model, flag: binding.flag } } : {}),
-    descriptor: worker,
+    // The binary the probe found, as an absolute path: the supervisor spawns from the execution worktree,
+    // where a relative PATH entry would name another file than the one probed.
+    descriptor: evaluated.binaryPath && worker?.cli ? { ...worker, cli: { ...worker.cli, binary: evaluated.binaryPath } } : worker,
     prompt: { path: prompt.path, sha256: prompt.sha256, bytes: prompt.bytes.length },
     needs: evaluated.requirements.map((item     ) => ({ requirement: item.requirement, at: item.at ?? null })),
   };

package/src/runtime/worker/launch.js

@@ -3,8 +3,7 @@
 // Feature 081 B.3 (IC-003, IC-012; DEC-030, DEC-037, DEC-045): the real launcher.
 //
 // `launchEnv` names the worker in the caller's environment: the caller's variables are inherited
-// unchanged (DEC-045), except for the five identity variables, DOFLOW_WORKER_RUN and the optional
-// project-only DOFLOW_GUARD_DROP_DATABASES launch snapshot (112). The run segment of
+// unchanged (DEC-045), except for the five identity variables and DOFLOW_WORKER_RUN. The run segment of
 // the claim's run key is the worker's run, or, when that segment is the default `local`, the run
 // id without its `w-` prefix (DEC-037), so the worker always resolves to a launched identity and
 // its 078 unit `L.<run>.<lineage>.<token>` is unique to this run. A child run (082 IC-015) is
@@ -24,12 +23,9 @@
 // and the emission text is never returned for storage.
 
 const crypto = require('node:crypto');
-const fs = require('node:fs');
-const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { emitContext, utf8Bytes } = require('../context/arbitrate.js');
 const { grantSummary } = require('../context/summary-store.js');
-const { loadSettings } = require('../settings/resolve.js');
 
                                               
 /** 120 IC-011 / IC-012: the binding shape consumed by the recipe assembler. */
@@ -37,11 +33,9 @@ const { loadSettings } = require('../settings/resolve.js');
 
 /** IC-012: the names a launch may set, in the order the run record lists them. The first five are the
  * identity contract; `DOFLOW_WORKER_RUN` (110) carries the worker run id `w-<12 hex>` and nothing else,
- * so the worker's telemetry can name its own run. The seventh variable (112) is an optional
- * snapshot of project-only database names. Neither is part of the stored identity. */
+ * so the worker's telemetry can name its own run. It is not part of the stored identity. */
 const WORKER_RUN_VAR = 'DOFLOW_WORKER_RUN';
-const DROP_DATABASES_VAR = 'DOFLOW_GUARD_DROP_DATABASES';
-const ENV_SET = Object.freeze(['DOFLOW_RUN_ID', 'DOFLOW_LINEAGE_ID', 'DOFLOW_ATTEMPT', 'DOFLOW_SESSION_ROLE', 'DOFLOW_WORKTREE', WORKER_RUN_VAR, DROP_DATABASES_VAR]);
+const ENV_SET = Object.freeze(['DOFLOW_RUN_ID', 'DOFLOW_LINEAGE_ID', 'DOFLOW_ATTEMPT', 'DOFLOW_SESSION_ROLE', 'DOFLOW_WORKTREE', WORKER_RUN_VAR]);
 const PROMPT_ELEMENT = '{prompt}';
 const LAST_MESSAGE_FILE_ELEMENT = '{lastMessageFile}';
 const MODEL_ELEMENT = '{model}';
@@ -73,31 +67,8 @@ class LaunchUsageError extends Error {
   }
 }
 
-/** 112: read the owning project's layers at launch, never the worker checkout, caller snapshot or
- * the launcher's process environment. Every fault omits the exemption. A fresh env copy bypasses
- * settings memoisation so an earlier launch cannot pin stale authorisation. */
-function dropDatabases(execWorktree        , env     )                {
-  try {
-    if (!path.isAbsolute(execWorktree)) return null;
-    const canonical = fs.realpathSync(execWorktree);
-    if (!fs.statSync(canonical).isDirectory()) return null;
-    const dispatch = /^(.*)\/\.doflow\/state\/dispatch-worktrees\/d-[0-9a-f]{12}$/.exec(canonical);
-    if (!dispatch || dispatch[0] !== canonical) return null;
-    const projectRoot = dispatch[1] || path.parse(canonical).root;
-    const resolved = loadSettings({ projectRoot, env: { ...env } }).get('guard.workerDropDatabases', 'project');
-    // 086's linked-checkout fallback is not authority for this exemption. An invalid project file
-    // also voids the snapshot, even if a different layer could have supplied a usable value.
-    if (resolved.origin.checkout !== 'own' || !['project', 'local'].includes(resolved.origin.layer)
-      || resolved.candidates.some((c     ) => ['project', 'local'].includes(c.layer) && c.status === 'invalid')) return null;
-    const value = resolved.value;
-    if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > 1024
-      || /^[a-z][a-z0-9_]{0,62}( [a-z][a-z0-9_]{0,62})*$/.exec(value)?.[0] !== value || value.split(' ').length > 32) return null;
-    return value;
-  } catch { return null; }
-}
-
-/** The five identity variables, optional worker run id and project-only guard snapshot. Both
- * launch-only values replace (or remove) caller values; the caller's environment is never mutated. */
+/** The five identity variables and the optional worker run id. The run id replaces (or removes) the
+ * caller's value; the caller's environment is never mutated. */
 function withIdentity(env     , identity                , execWorktree        , runId         )      {
   if (runId !== undefined && !RUN_ID.test(runId)) throw new LaunchUsageError('run-id-malformed', `launch: run id must match ${RUN_ID}: ${runId}`);
   const out      = {
@@ -110,12 +81,9 @@ function withIdentity(env     , identity                , execWorktree        ,
   };
   if (runId !== undefined) out[WORKER_RUN_VAR] = runId;
   else delete out[WORKER_RUN_VAR];
-  delete out[DROP_DATABASES_VAR];
   // 120 IC-003: the primary declaration names the person's main session, never a worker.
   delete out.DOFLOW_PRIMARY_HARNESS;
   delete out.DOFLOW_PRIMARY_MODEL;
-  const databases = dropDatabases(execWorktree, env);
-  if (databases !== null) out[DROP_DATABASES_VAR] = databases;
   return out;
 }
 

package/src/runtime/worker/readiness.js

@@ -78,9 +78,13 @@ function workerDescriptors({ descriptors, registry, view }      = {})
   return ids.filter((id) => Object.hasOwn(descriptors, id)).map((id) => ({ harness: id, worker: descriptors[id] }));
 }
 
-/** The first executable `binary` on `env.PATH`, or null. Starts no process. */
-function findOnPath(binary        , env     , platform = process.platform)                {
-  const dirs = String(env?.PATH ?? '').split(path.delimiter).filter(Boolean);
+/**
+ * The first executable `binary` on `env.PATH`, or null. Starts no process. A relative PATH entry is
+ * read against `cwd` (the caller's directory) when one is given, so the path found is absolute and
+ * names the same file whichever directory a later process starts in.
+ */
+function findOnPath(binary        , env     , platform = process.platform, cwd         )                {
+  const dirs = String(env?.PATH ?? '').split(path.delimiter).filter(Boolean).map((dir) => (cwd ? path.resolve(cwd, dir) : dir));
   const suffixes = platform === 'win32'
     ? ['', ...String(env?.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
     : [''];
@@ -116,7 +120,7 @@ function discoverOne({ harness, worker }     , { env, cwd, now, platform }     )
   if (!supported(cli)) {
     return { harness, binary: null, present: false, path: null, version: null, reason: 'cli-unknown', at: iso(now()) };
   }
-  const found = findOnPath(cli.binary, env, platform);
+  const found = findOnPath(cli.binary, env, platform, cwd);
   if (!found) return { harness, binary: cli.binary, present: false, path: null, version: null, reason: 'not-on-path', at: iso(now()) };
   const execFileImpl = (bin        , args          , options     ) => execFileSync(bin, args, { ...options, env, cwd });
   const result = runProbe([found, ...cli.versionArgv], { execFileImpl, timeoutMs: PROBE_TIMEOUT_MS });
@@ -487,8 +491,8 @@ const CAPABILITY_REQUIREMENTS                         = Object.freeze({
 const FACT_RESULT                         = Object.freeze({ yes: 'met', no: 'failed', unknown: 'unknown' });
 
 /**
- * DEC-044: the `blocking-hook` policies, built from the coverage rows because coverage's
- * `POLICY_ORDER` is not exported and `src/lifecycle/coverage.js` does not change (IC-032).
+ * DEC-044: the `blocking-hook` policies, built from the coverage rows because coverage exports no
+ * policy list and `src/lifecycle/coverage.js` does not change (IC-032).
  */
 function policyVocabulary(coverage     )              {
   const policies = new Set        ((coverage?.rows || []).map((row     ) => row.policy));

package/src/runtime/worker/supervisor.js

@@ -321,22 +321,33 @@ function boundedWait(promise              , ms        )               {
   return Promise.race([promise, bound]).finally(() => clearTimeout(timer));
 }
 
-/** Reads only the bounded Codex output-last-message prefix; absent or unreadable files are optional. */
-function readLastMessage(parser     , file        )       {
-  if (typeof parser.lastMessage !== 'function') return;
+/** What masking did to a retained final message, in the run record beside the stdout and stderr pointers. */
+const ALTERED_WARNING = 'masking altered this final message: it is not suitable for byte-exact patch application; apply the worker\'s changes from its isolated worktree, not from this text';
+
+/**
+ * Reads only the bounded Codex output-last-message prefix; absent or unreadable files are optional.
+ * Returns the pointer the run record keeps (`path` relative to `stateRoot`, the masked `bytes`,
+ * whether masking `altered` the text and, when it did, the `warning`), or null when no file was read.
+ */
+function readLastMessage(parser     , file        , stateRoot        )      {
+  if (typeof parser.lastMessage !== 'function') return null;
   let fd                    ;
   try {
     fd = fs.openSync(file, 'r');
     const bytes = Buffer.alloc(65536);
     const length = fs.readSync(fd, bytes, 0, bytes.length, 0);
-    const masked = maskBody(bytes.subarray(0, length).toString('utf8')).text;
+    const raw = bytes.subarray(0, length).toString('utf8');
+    const masked = maskBody(raw).text;
     parser.lastMessage(masked);
     // NFR-004: the retained copy holds only the masked, bounded text, never the raw worker output.
     fs.closeSync(fd);
     fd = undefined;
-    try { fs.writeFileSync(file, masked, 'utf8'); } catch { fs.rmSync(file, { force: true }); }
+    try { fs.writeFileSync(file, masked, 'utf8'); } catch { fs.rmSync(file, { force: true }); return null; }
+    const altered = masked !== raw;
+    return { path: path.relative(stateRoot, file).split(path.sep).join('/'), bytes: Buffer.byteLength(masked), altered, ...(altered ? { warning: ALTERED_WARNING } : {}) };
   } catch {
     // Codex may not have produced this optional file; that does not change the run outcome.
+    return null;
   } finally {
     if (fd !== undefined) {
       try { fs.closeSync(fd); } catch { /* unreadable/closed files are ignored */ }
@@ -509,7 +520,8 @@ async function superviseRun({
       readOnly = { status: 'unverifiable', changes: [], head: { before: before.head, after: null }, refsChanged: null };
     }
   }
-  if (lastMessageFile) readLastMessage(parser, lastMessageFile);
+  const lastMessage = lastMessageFile ? readLastMessage(parser, lastMessageFile, stateRoot) : null;
+  if (lastMessage) (output       ).lastMessage = lastMessage;
   const report = parser.end();
   // 106 IC-002: a failure whose masked summary holds a declared quota signal is marked quota.
   const quota = quotaOf(report, run.descriptor);

package/src/runtime/workflow-orchestrator.js

@@ -196,6 +196,29 @@ function compileProgram(workflow     ) {
   return nodes;
 }
 
+/** The stage a loop program adds to a class that has no review stage of its own (trivial-edit). */
+const LOOP_REVIEW_STAGE = Object.freeze({
+  id: 'review', skill: 'do-code-review', agent: 'reviewer', kind: 'review', readinessTemplate: null, optional: false,
+  purpose: 'Review the delivered change and report an approval status.',
+});
+
+/**
+ * The program the roadmap loop runs for a task class (AU-P1). The loop is unattended, so it takes
+ * no optional stage out of the walk: every stage is required, a class without a review stage gets
+ * one, and a `gate-b` follows the last review so the class's gate-b policy (core/registry/gates.json)
+ * can approve the merge. The feature class already has all of that. workflows.json is not changed:
+ * an attended `/do-implement` run keeps its gate-free program.
+ */
+function loopWorkflow(workflow     ) {
+  if ((workflow.gates || []).some((gate     ) => gate.id === 'gate-b')) return workflow;
+  const stages = (workflow.stages || []).map((stage     ) => ({ ...stage, optional: false }));
+  if (!stages.some((stage     ) => stage.kind === 'review')) stages.push({ ...LOOP_REVIEW_STAGE });
+  const review = stages.filter((stage     ) => stage.kind === 'review').at(-1);
+  const gate = { id: 'gate-b', name: 'Before commit or merge', afterStage: review.id, kind: 'approval', trigger: 'always',
+    prompt: 'Review is complete. Proceed to commit and merge?' };
+  return { ...workflow, stages, gates: [...(workflow.gates || []), gate] };
+}
+
 class WorkflowOrchestrator {
                       
                         
@@ -285,11 +308,15 @@ class WorkflowOrchestrator {
     return run;
   }
 
-  /** Begin a new run. An existing run for the same task id is refused — resume instead. */
-  start({ taskId, taskClass, now }      = {}) {
+  /** Begin a new run. An existing run for the same task id is refused — resume instead.
+   * `loopProgram` is the roadmap loop's option only (loopWorkflow): the run journal records it, and no
+   * verb passes it. */
+  start({ taskId, taskClass, now, loopProgram = false }      = {}) {
     assertSafeId(taskId, 'taskId');
     if (this.readRun(taskId)) throw new Error(`Workflow run '${taskId}' already exists; resume it instead of restarting`);
-    const workflow = this.engine.resolveWorkflow(taskClass); // unknown classes are rejected loudly
+    const resolved = this.engine.resolveWorkflow(taskClass); // unknown classes are rejected loudly
+    const workflow = loopProgram ? loopWorkflow(resolved) : resolved;
+    const looped = workflow !== resolved; // the feature class already is a loop program: its journal is unchanged
     const program = compileProgram(workflow);
     const run = {
       version: 1,
@@ -300,8 +327,9 @@ class WorkflowOrchestrator {
       state: runState('RUNNING'),
       cursor: 0,
       program,
-      history: [{ at: iso(now), action: 'start', detail: `task-class=${taskClass}` }],
+      history: [{ at: iso(now), action: 'start', detail: `task-class=${taskClass}${looped ? ' program=roadmap-loop' : ''}` }],
       startedAt: iso(now),
+      ...(looped ? { programKind: 'roadmap-loop' } : {}),
       // The feature the run belongs to, so another checkout can tell it from a run with the same id.
       ...(this.featureSlug ? { featureSlug: this.featureSlug } : {}),
       ...this.traceFields(),
@@ -456,9 +484,13 @@ class WorkflowOrchestrator {
         },
         harnessName: displayName,
         since,
-        addCommand: (server     ) => {
+        addCommand: (server     , harnessId      = null) => {
           const reach = reachOf();
-          const row = reach?.harnesses.find((item     ) => !['selected', 'configured'].includes(item.servers[server]));
+          const has = (item     ) => ['selected', 'configured'].includes(item.servers[server]);
+          // The brief's own harness is where the server was missing; another harness having it says nothing.
+          const target = harnessId ? reach?.harnesses.find((item     ) => item.id === harnessId) : null;
+          if (target) return has(target) ? null : reach.addCommand(target.id, target.scope, server);
+          const row = reach?.harnesses.find((item     ) => !has(item));
           return row ? reach.addCommand(row.id, row.scope, server) : null;
         },
       });
@@ -1465,4 +1497,4 @@ function handleOrchestrateCommand({
   }
 }
 
-module.exports = { WorkflowOrchestrator, RUN_STATES, GATE_DECISIONS, STAGE_OUTCOMES, handleOrchestrateCommand, recordStagePack };
+module.exports = { WorkflowOrchestrator, loopWorkflow, RUN_STATES, GATE_DECISIONS, STAGE_OUTCOMES, handleOrchestrateCommand, recordStagePack };

package/core/harnesses/claude/hooks/pre-bash-guard.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Claude front door: pre-bash-guard through the shared lifecycle bridge.
-set -uo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
-if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
-  exit 0
-fi
-doflow_bridge claude PreToolUse pre-bash-guard
-exit $?

package/core/harnesses/codex/hooks/pre-bash-guard.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Codex front door: pre-bash-guard through the shared lifecycle bridge.
-set -uo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
-if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
-  exit 0
-fi
-doflow_bridge codex PreToolUse pre-bash-guard
-exit $?

package/core/harnesses/copilot/hooks/doflow-pre-bash-guard.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-# Copilot CLI front door: pre-bash-guard through the shared lifecycle bridge.
-set -uo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-copilot}"
-here="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=doflow-lib.sh
-. "$here/doflow-lib.sh"
-copilot_front_door "$here" PreToolUse pre-bash-guard deny
-exit $?

package/core/harnesses/kiro/hooks/pre-bash-guard.sh

@@ -1,25 +0,0 @@
-#!/usr/bin/env bash
-case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
-# Kiro front door: pre-bash-guard through the shared lifecycle bridge.
-set -euo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-kiro}"
-here="$(dirname "$0")"
-# shellcheck source=lib.sh
-source "$here/lib.sh"
-raw=$(cat)
-payload=$(kiro_bridge_payload <<<"$raw")
-event="PreToolUse"
-if command -v jq >/dev/null 2>&1; then event=$(printf '%s' "$raw" | jq -r '.hook_event_name // "PreToolUse"' 2>/dev/null) || event="PreToolUse"; fi
-bridge="$here/../../.doflow/shared/hooks/bridge/bridge.sh"
-if [ ! -f "$bridge" ]; then
-  printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2
-  exit 2
-fi
-. "$bridge" 2>/dev/null || { printf '%s\n' '[doflow] shared hooks lack the bridge; run: doflow update -t kiro' >&2; exit 2; }
-if doflow_bridge kiro "$event" pre-bash-guard <<<"$payload"; then
-  status=0
-else
-  status=$?
-fi
-if [ "$status" -eq 2 ]; then printf '\n' >&2; fi
-exit "$status"