@sabaiway/agent-workflow-kit 14.1.0 → 14.3.0

package/tools/checkpoint-restore.mjs

@@ -1,8 +1,11 @@
-// spec:checkpoint — docs/ai/specs/kit/checkpoint/restore.md
+// restoreCheckpoint, restoreTaskThread — spec:checkpoint, spec:task-thread; docs/ai/specs/kit/checkpoint/restore.md
 import { unlinkSync, rmdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { resolveTreeObject, snapshotScope } from './dispatch-baseline.mjs';
+import { resolveTreeObject, snapshotScope, computeBasePayload } from './dispatch-baseline.mjs';
 import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { isThreadTerminalRecord } from './dispatch-record.mjs';
+import { readsTask, readsInsideEpoch, epochClaims } from './task-thread.mjs';
+import { hasPathOverlap } from './claim-relation.mjs';
 import { CHECKPOINT_REF_PREFIX, withRepository, readGit, readGitBytes, readCheckpointRefs,
   withTemporaryIndex, readScopeStat, writeSnapshot, findOpenCheckpointThread } from './checkpoint-core.mjs';
 
@@ -20,8 +23,14 @@ const SEQUENCE_REF_PATTERN = /^[^/]+\/(?:0|[1-9][0-9]*)$/;
 const ALLOWED_MODES = ['100644', '100755', '120000'];
 const LEDGER_ABSENT = 'absent';
 const LEDGER_OK = 'ok';
+const HEAD_ERROR = 'error';
+const DISPATCH_KIND = 'dispatch';
+const FOLD_KIND = 'fold';
+const CHECKPOINT_KIND = 'checkpoint';
+const FOLDED = 'folded';
 const NONEMPTY_CODES = ['ENOTEMPTY', 'EEXIST'];
-const NAMES = { scope: 'target-scope', ledger: 'ledger', open: 'open-thread', conflict: 'type-conflict' };
+const NAMES = { scope: 'target-scope', ledger: 'ledger', open: 'open-thread', conflict: 'type-conflict',
+  task: 'task-target', folded: 'task-folded' };
 const ENCODING_ERROR = 'target tree paths are not lossless UTF-8';
 const ENTRY_ERROR = 'unreadable target tree entry';
 const UNREFERENCED_ERROR = 'no checkpoint sequence carries target';
@@ -31,10 +40,11 @@ const GIT_ARGS = {
   entries: ['ls-tree', '-r', '-z'],
   read: ['read-tree'],
   checkout: ['checkout-index', '-a', '-f'],
+  checkoutPaths: ['checkout-index', '-f', '--'],
 };
 
 const refuse = (reason) => ({ ok: false, code: REFUSE, reason });
-const readTargetEntries = (context, target) => {
+const readTargetEntries = (context, target, files = null) => {
   const bytes = readGitBytes(context, [...GIT_ARGS.entries, target]);
   const text = bytes.toString(UTF8);
   if (!Buffer.from(text, UTF8).equals(bytes)) throw new Error(`${NAMES.scope}: ${ENCODING_ERROR}`);
@@ -42,11 +52,12 @@ const readTargetEntries = (context, target) => {
     const parsed = ENTRY_PATTERN.exec(entry);
     if (parsed === null) throw new Error(`${NAMES.scope}: ${ENTRY_ERROR}`);
     const [, mode, path] = parsed;
+    if (files !== null && !files.includes(path)) return null;
     if (!ALLOWED_MODES.includes(mode) || path.split(SLASH).some((segment) => FORBIDDEN_SEGMENTS.includes(segment))) {
       throw new Error(`${NAMES.scope}: ${path}`);
     }
     return path;
-  });
+  }).filter((path) => path !== null);
 };
 const readHeldSet = (context, target) => {
   const refs = readCheckpointRefs(context).filter(({ ref }) => SEQUENCE_REF_PATTERN.test(ref.slice(CHECKPOINT_REF_PREFIX.length)));
@@ -124,3 +135,49 @@ export const restoreCheckpoint = (cwd, oid, io = {}) => withRepository(cwd, io,
   return snapshot.oid === target ? { ok: true, target, proof: snapshot.oid }
     : refuse(`${MISMATCH}: ${target} ${snapshot.oid}`);
 });
+
+export const restoreTaskThread = (cwd, oid, nonce, io = {}) => withRepository(cwd, io, (context) => {
+  const tree = resolveTreeObject(context.top, oid, context.io);
+  if (!tree.ok) return refuse(tree.reason);
+  const target = readGit(context, [...GIT_ARGS.resolve, oid]);
+  const ledger = readDelegationLedger(context.cwd, context.env);
+  if (ledger.state !== LEDGER_OK) return refuse(`${NAMES.ledger}: ${ledger.reason ?? ledger.state}`);
+  if (ledger.head.state === HEAD_ERROR) return refuse(`${NAMES.ledger}: ${ledger.head.reason}`);
+  const { records, head } = ledger;
+  const index = records.findIndex((record) => record.kind === DISPATCH_KIND && record.nonce === nonce);
+  if (index === LAST) return refuse(`${NAMES.task}: ${nonce}`);
+  const dispatch = records[index];
+  const task = readsTask(dispatch);
+  if (task === null) return refuse(`${NAMES.task}: ${nonce}`);
+  const later = records.slice(index + NEXT).filter((record) => record.nonce === nonce);
+  if (!later.some(isThreadTerminalRecord)) return refuse(`${NAMES.open}: ${nonce}`);
+  if (later.some((record) => record.kind === FOLD_KIND)) return refuse(`${NAMES.folded}: ${nonce}`);
+  if (dispatch.baseline.treeOid !== target) return refuse(`${NAMES.task}: ${nonce}: ${target}`);
+  const scope = snapshotScope(context.top, { baseTreeOid: target }, context.io);
+  if (!scope.ok) return refuse(scope.reason);
+  const paths = scope.paths.filter((path) => task.files.includes(path));
+  const domain = new Set(paths);
+  for (const claim of epochClaims(records, head, isThreadTerminalRecord)) {
+    if (claim.nonce === nonce || !claim.files.some((file) => paths.some((path) => hasPathOverlap(file, path)))) continue;
+    return refuse(`${claim.state === FOLDED ? NAMES.folded : NAMES.open}: ${claim.nonce}`);
+  }
+  const untasked = records.filter((record) => record.kind !== DISPATCH_KIND || readsTask(record) === null);
+  const folded = untasked.find((record, position) => record.kind === DISPATCH_KIND && readsInsideEpoch(record, head)
+    && untasked.slice(position + NEXT).some((successor) => successor.nonce === record.nonce && successor.kind === FOLD_KIND));
+  if (folded !== undefined) return refuse(`${NAMES.folded}: ${folded.nonce}`);
+  const held = readHeldSet(context, target);
+  const open = findOpenCheckpointThread(untasked, held);
+  if (open !== undefined) return refuse(`${NAMES.open}: ${open.nonce}`);
+  const entries = readTargetEntries(context, target, task.files);
+  const outside = entries.find((path) => !domain.has(path));
+  if (outside !== undefined) return refuse(`${NAMES.scope}: ${outside}`);
+  const types = checkTypes(context, entries);
+  if (!types.ok) return types;
+  withTemporaryIndex(context.env, (env) => {
+    readGit(context, [...GIT_ARGS.read, target], env);
+    if (entries.length > START) readGit(context, [...GIT_ARGS.checkoutPaths, ...entries], env);
+  });
+  removeExtras(context, paths, new Set(entries));
+  const proof = computeBasePayload(context.top, { kind: CHECKPOINT_KIND, treeOid: target }, context.io, task.files);
+  return proof !== null && proof.length === START ? { ok: true, target, nonce } : refuse(MISMATCH);
+});

package/tools/checkpoint.mjs

@@ -7,7 +7,7 @@ import { PLANS_REL, isScratchPlanName } from './plan-files.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { CHECKPOINT_REF_PREFIX, refuse, withRepository, readGit, readCheckpointRefs, writeSnapshot,
   findOpenCheckpointThread } from './checkpoint-core.mjs';
-import { restoreCheckpoint } from './checkpoint-restore.mjs';
+import { restoreCheckpoint, restoreTaskThread } from './checkpoint-restore.mjs';
 
 export { CHECKPOINT_REF_PREFIX } from './checkpoint-core.mjs';
 const ACCEPT = 0;
@@ -30,11 +30,15 @@ const LEDGER_OK = 'ok';
 const CLEAN = 'CLEAN';
 const DIRTY = 'DIRTY';
 const PROOF = 'proof';
+const TASK_KIND = 'task';
+const TASK_PROOF = 'clean';
 const PLAN_FLAG = '--plan';
+const NONCE_FLAG = '--nonce';
 const PLAN_ARG_COUNT = 3;
 const OID_ARG_COUNT = 2;
+const TASK_ARG_COUNT = 4;
 const ARGV_OFFSET = 2;
-const USAGE_TEXT = 'usage: checkpoint mint|newest|prune --plan <plan> | verify|restore <oid>';
+const USAGE_TEXT = 'usage: checkpoint mint|newest|prune --plan <plan> | verify <oid> | restore <oid> [--nonce <n>]';
 const PLAN_ERROR = 'expected a readable regular plan directly under docs/plans';
 const SEQUENCE_ERROR = 'expected contiguous numbered refs on trees';
 const GIT_ARGS = {
@@ -122,17 +126,22 @@ const PLAN_OPERATIONS = { [VERBS.mint]: mintCheckpoint, [VERBS.newest]: newestCh
 const formatRef = ({ stem, n, oid }) => `${CHECKPOINT_KIND} ${stem}/${n} ${oid}${NEWLINE}`;
 const formatRefusal = ({ code, reason }) => ({ code, stdout: EMPTY, stderr: `${reason}${NEWLINE}` });
 export const main = (argv = process.argv.slice(ARGV_OFFSET), deps = {}) => {
-  const [verb, operand, planPath] = argv;
+  const [verb, operand, planPath, nonce] = argv;
   const planVerb = Object.hasOwn(PLAN_OPERATIONS, verb);
   const oidVerb = verb === VERBS.verify || verb === VERBS.restore;
+  const taskRestore = verb === VERBS.restore && argv.length === TASK_ARG_COUNT && operand
+    && planPath === NONCE_FLAG && typeof nonce === STRING && nonce !== EMPTY;
   if (!(planVerb && argv.length === PLAN_ARG_COUNT && operand === PLAN_FLAG && planPath)
-    && !(oidVerb && argv.length === OID_ARG_COUNT && operand)) return formatRefusal(refuse(USAGE_TEXT, USAGE));
+    && !(oidVerb && argv.length === OID_ARG_COUNT && operand) && !taskRestore) return formatRefusal(refuse(USAGE_TEXT, USAGE));
   const cwd = deps.cwd ?? process.cwd();
   const operation = verb === VERBS.restore ? restoreCheckpoint : verifyCheckpoint;
-  const result = planVerb ? PLAN_OPERATIONS[verb](cwd, planPath, deps) : operation(cwd, operand, deps);
+  const result = taskRestore ? restoreTaskThread(cwd, operand, nonce, deps)
+    : planVerb ? PLAN_OPERATIONS[verb](cwd, planPath, deps) : operation(cwd, operand, deps);
   if (!result.ok) return formatRefusal(result);
-  if (verb === VERBS.restore) return { code: ACCEPT,
-    stdout: `${CHECKPOINT_KIND} ${VERBS.restore} ${result.target} ${PROOF} ${result.proof}${NEWLINE}`, stderr: EMPTY };
+  if (verb === VERBS.restore) {
+    const proof = taskRestore ? `${TASK_KIND} ${nonce} ${PROOF} ${TASK_PROOF}` : `${PROOF} ${result.proof}`;
+    return { code: ACCEPT, stdout: `${CHECKPOINT_KIND} ${VERBS.restore} ${result.target} ${proof}${NEWLINE}`, stderr: EMPTY };
+  }
   if (verb === VERBS.verify) return { code: result.clean ? ACCEPT : REFUSE,
     stdout: `${result.clean ? CLEAN : DIRTY} ${result.target} ${result.oid}${NEWLINE}`, stderr: EMPTY };
   return { code: ACCEPT, stdout: verb === VERBS.prune ? EMPTY : formatRef(result), stderr: EMPTY };

package/tools/dispatch-baseline.mjs

@@ -1,4 +1,4 @@
-// dispatch-baseline.mjs — snapshotScope, computeBasePayload, computeBaseFingerprint,
+// dispatch-baseline.mjs — snapshotScope, computeBasePayload, computeBaseFingerprint, taskFilesScopeRefusal,
 // isCleanAgainstBase, runBaseDiff and resolveTreeObject; spec:dispatch-baseline.
 // Writes only its own temporary indexes and the blob objects stored by forced adds.
 // Head measurements delegate unchanged to core-evidence without a temporary index.
@@ -20,6 +20,8 @@ const PAYLOAD_DIFF_ARGS = ['--no-ext-diff', '--no-textconv', '--ignore-submodule
 const SCOPE_EXCLUSIONS = ['/docs/plans/', '/.claude/settings.json', '/.claude/settings.local.json', '/.mcp.json'];
 const MISSING_PATH_CODES = ['ENOENT', 'ENOTDIR'];
 const ABSENT_HEAD_STATUS = 1;
+const CHECK_IGNORE_CLEAR_STATUS = 1;
+const EXCLUDE_SOURCES = ['.gitignore', '.gitattributes'];
 const splitPaths = (bytes) => {
   const text = bytes.toString('utf8');
   if (!Buffer.from(text).equals(bytes)) throw new Error('git path names are not lossless UTF-8');
@@ -62,12 +64,12 @@ const readStat = (path, lstat) => {
     throw error;
   }
 };
-const readTreePaths = (run, top, treeOid, env) => splitPaths(readGit(run, ['ls-tree', '-r', '--name-only', '-z', treeOid], top, env));
-const readHeadPaths = (run, top, env) => {
+const readTreePaths = (run, top, treeOid, env, directories = false) => splitPaths(readGit(run, ['ls-tree', '-r', ...(directories ? ['-d', '-t'] : []), '--name-only', '-z', treeOid], top, env));
+const readHeadPaths = (run, top, env, directories = false) => {
   const head = run(['rev-parse', '--verify', '--quiet', 'HEAD'], top, undefined, env);
   if (head && !head.error && !head.signal && head.status === ABSENT_HEAD_STATUS) return [];
   if (!head || head.error || head.signal || head.status !== 0) throw new Error('cannot resolve HEAD');
-  return readTreePaths(run, top, 'HEAD', env);
+  return readTreePaths(run, top, 'HEAD', env, directories);
 };
 const excludePatterns = (top, paths) => [
   ...SCOPE_EXCLUSIONS,
@@ -99,8 +101,7 @@ const collectScope = (top, baseTreeOid, run, lstat, env) => withTemporaryIndex(e
 
 export const snapshotScope = (cwd, { baseTreeOid = null } = {}, io = {}) => {
   try {
-    const env = io.env ?? process.env;
-    const run = makeRunner(io);
+    const env = io.env ?? process.env, run = makeRunner(io);
     const top = locateTop(cwd, run, env);
     return { ok: true, paths: collectScope(top, baseTreeOid, run, io.lstat ?? lstatSync, env) };
   } catch (error) {
@@ -110,8 +111,7 @@ export const snapshotScope = (cwd, { baseTreeOid = null } = {}, io = {}) => {
 
 export const resolveTreeObject = (cwd, oid, io = {}) => {
   try {
-    const env = io.env ?? process.env;
-    const run = makeRunner(io);
+    const env = io.env ?? process.env, run = makeRunner(io);
     const top = locateTop(cwd, run, env);
     const type = readGit(run, ['cat-file', '-t', oid], top, env).toString('utf8').trim();
     return type === 'tree' ? { ok: true } : { ok: false, reason: `${oid} names a ${type}, not a tree` };
@@ -120,19 +120,47 @@ export const resolveTreeObject = (cwd, oid, io = {}) => {
   }
 };
 
-export const runBaseDiff = (cwd, base, args, io = {}) => {
+export const taskFilesScopeRefusal = (cwd, base, paths, io = {}) => {
+  if (paths.length === 0) return null;
+  const current = { path: paths[0] };
+  try {
+    const env = io.env ?? process.env, run = makeRunner(io), lstat = io.lstat ?? lstatSync;
+    const top = locateTop(cwd, run, env);
+    return withTemporaryIndex(env, (indexEnv) => {
+      readGit(run, ['read-tree', '--empty'], top, indexEnv);
+      const treePaths = readHeadPaths(run, top, indexEnv).concat(base.kind === 'checkpoint' ? readTreePaths(run, top, base.treeOid, indexEnv) : []);
+      const directories = readHeadPaths(run, top, indexEnv, true).concat(base.kind === 'checkpoint' ? readTreePaths(run, top, base.treeOid, indexEnv, true) : []);
+      const matchesPattern = (path, pattern) => { const probe = patternToProbe(pattern); return isDirPattern(pattern) ? path === probe.slice(0, -1) || path.startsWith(probe) : path === probe; };
+      const exclusions = excludePatterns(top, paths);
+      for (const path of paths) {
+        current.path = path;
+        if (EXCLUDE_SOURCES.includes(basename(path))) return `${path}: exclude-source`;
+        if (path.split('/').includes('node_modules') || exclusions.some((pattern) => matchesPattern(path, pattern))) return `${path}: excluded`;
+        if (readStat(join(top, path), lstat)?.isDirectory() || directories.includes(path)) return `${path}: directory`;
+        const prefixes = path.split('/').slice(0, -1).map((segment, index, parts) => parts.slice(0, index + 1).join('/'));
+        if (prefixes.some((prefix) => { const stat = readStat(join(top, prefix), lstat); return (stat !== null && !stat.isDirectory()) || treePaths.includes(prefix); })) return `${path}: beneath-non-directory`;
+        if (treePaths.includes(path) || KIT_OWN_PATHS.some((pattern) => matchesPattern(path, pattern))) continue;
+        const { GIT_LITERAL_PATHSPECS: _literalPathspecs, ...ignoreEnv } = indexEnv; const ignored = run(['check-ignore', '--no-index', '-q', '--', path], top, undefined, ignoreEnv);
+        if (!ignored || ignored.error || ignored.signal || ![0, CHECK_IGNORE_CLEAR_STATUS].includes(ignored.status)) throw new Error(`git check-ignore failed: ${ignored?.error?.message ?? String(ignored?.stderr ?? '').trim()}`);
+        if (ignored.status === 0) return `${path}: ignored`;
+      }
+      return null;
+    });
+  } catch (error) { return `${current.path}: ${error.message}`; }
+};
+
+export const runBaseDiff = (cwd, base, args, io = {}, paths = null) => {
   if (base.kind !== 'checkpoint') return null;
   try {
-    const env = io.env ?? process.env;
-    const run = makeRunner(io);
+    const env = io.env ?? process.env, run = makeRunner(io);
     const top = locateTop(cwd, run, env);
     if (!resolveTreeObject(top, base.treeOid, io).ok) return null;
     const scope = snapshotScope(top, { baseTreeOid: base.treeOid }, io);
     if (!scope.ok) return null;
     const basePaths = readTreePaths(run, top, base.treeOid, env);
-    const present = [];
-    const removed = [];
-    for (const path of scope.paths) {
+    const scopedPaths = paths === null ? scope.paths : scope.paths.filter((path) => paths.includes(path));
+    const present = [], removed = [];
+    for (const path of scopedPaths) {
       const stat = readStat(join(top, path), io.lstat ?? lstatSync);
       const baseHoldsPath = basePaths.includes(path);
       const neverCommittable = stat !== null && isNeverCommittableStat(stat);
@@ -141,7 +169,7 @@ export const runBaseDiff = (cwd, base, args, io = {}) => {
       if (materialized) present.push(path);
       if (!materialized && !neverCommittable && (stat === null || baseHoldsPath)) removed.push(path);
     }
-    const excludedBasePaths = basePaths.filter((path) => !scope.paths.includes(path));
+    const excludedBasePaths = basePaths.filter((path) => !scopedPaths.includes(path));
     const conflict = present.find((path) => excludedBasePaths.some((excluded) =>
       path.startsWith(`${excluded}/`) || excluded.startsWith(`${path}/`)));
     if (conflict !== undefined) throw new Error(`live path ${conflict} conflicts with an excluded base path`);
@@ -156,17 +184,17 @@ export const runBaseDiff = (cwd, base, args, io = {}) => {
   }
 };
 
-export const computeBasePayload = (cwd, base, io = {}) => base.kind === 'head'
+export const computeBasePayload = (cwd, base, io = {}, paths = null) => base.kind === 'head'
   ? computeFingerprintPayload(cwd, io)
-  : runBaseDiff(cwd, base, PAYLOAD_DIFF_ARGS, io);
+  : runBaseDiff(cwd, base, PAYLOAD_DIFF_ARGS, io, paths);
 
-export const computeBaseFingerprint = (cwd, base, io) => {
-  const payload = computeBasePayload(cwd, base, io);
+export const computeBaseFingerprint = (cwd, base, io, paths = null) => {
+  const payload = computeBasePayload(cwd, base, io, paths);
   return payload === null ? null : createHash(HASH_ALGORITHM).update(payload).digest('hex');
 };
 
-export const isCleanAgainstBase = (cwd, base, io) => {
+export const isCleanAgainstBase = (cwd, base, io, paths = null) => {
   if (base.kind === 'head') return isTreeClean(cwd, io);
-  const payload = computeBasePayload(cwd, base, io);
+  const payload = computeBasePayload(cwd, base, io, paths);
   return payload === null ? null : payload.length === 0;
 };

package/tools/dispatch-store.mjs

@@ -33,8 +33,8 @@ export const resolveDelegationLockPath = (storePath) => `${storePath}${DELEGATIO
 
 export const UNCOMMITTED_STATE_FINGERPRINT = 'the uncommitted-state fingerprint';
 
-export const uncommittedStateFingerprint = (cwd = process.cwd(), fsx, base = HEAD_BASELINE) => {
-  const fingerprint = base.kind === 'head' ? computeTreeFingerprint(cwd, fsx) : computeBaseFingerprint(cwd, base, fsx);
+export const uncommittedStateFingerprint = (cwd = process.cwd(), fsx, base = HEAD_BASELINE, paths = null) => {
+  const fingerprint = base.kind === 'head' ? computeTreeFingerprint(cwd, fsx) : computeBaseFingerprint(cwd, base, fsx, paths);
   if (fingerprint == null) {
     throw stop(`cannot compute ${UNCOMMITTED_STATE_FINGERPRINT} — not inside a git work tree (or a git probe failed); a record never carries a null tree digest (fail closed)`);
   }

package/tools/dispatch.mjs

@@ -53,8 +53,8 @@
 //     `gate-output` component is emitted in v1. The metric counts the returned change set only.
 //   • a receipt is FORGEABLE, exactly like every record in this family. What the absorb door defends
 //     against is a buggy or interrupted producer, not a hostile one.
-//   • D10 stands as a bar, not a mechanism: at most ONE in-tree exec dispatch runs at a time, and
-//     nothing here refuses a second one, task threads included; files-overlap and mixed-open additionally refuse conflicting task threads at append time.
+//   • D10 stands as a bar, not a mechanism, for untasked threads: at most ONE untasked in-tree exec dispatch
+//     runs at a time, and nothing here refuses a second one; for task threads it is a mechanism: files-overlap and mixed-open refuse conflicting opens at append time, and return and fold refuse out-of-files.
 //   • `await` observes ARRIVAL and nothing else: an expiry never authorizes the next writer, and the
 //     verb releases no slot it never held. Whether the run may be ABSORBED stays `return`'s question. A parallel-write story is not this plan's.
 //
@@ -74,7 +74,7 @@ import {
   DELEGATION_SCHEMA_VERSION, STEP_CLASSES, OBSERVATION_PROVENANCE, RETURN_OUTCOMES,
   SESSION_ID_NULLABLE_OUTCOMES, checkDispatchContractForm, checkDispatchMintConsistency,
   contractDigest, canonicalDelegationDigest, computeNumerator, evaluateMetricEligibility,
-  HEAD_BASELINE, readsBaseline, isTreeOid,
+  HEAD_BASELINE, readsBaseline, isTreeOid, isThreadTerminalRecord,
 } from './dispatch-record.mjs';
 import {
   appendDelegationRecord, readDelegationStore, resolveDelegationStorePath, delegationThreadState,
@@ -89,7 +89,7 @@ import {
   enumerateReturnedObjects, computeReturnedDiff, assembleIntegrationBundle,
 } from './exec-producer.mjs';
 import { gitBuf } from './core-evidence.mjs';
-import { isCleanAgainstBase, resolveTreeObject } from './dispatch-baseline.mjs';
+import { isCleanAgainstBase, resolveTreeObject, taskFilesScopeRefusal, runBaseDiff } from './dispatch-baseline.mjs';
 import { readDelegationLedger } from './dispatch-store-read.mjs';
 import { judgeLedger, threadVerdict, HELD_RECEIPT_BACKEND } from './held-session.mjs';
 import { degradeRecordSet, selectHeldSessionDegrades } from './review-state.mjs';
@@ -100,13 +100,13 @@ import {
 } from './observation-builder.mjs';
 import { handoffReturn, HANDOFF_SLUG_RE } from './worktree-handoff-return.mjs';
 import { parseBrief } from './task-brief.mjs';
-import { byteOrder, validateTask } from './task-thread.mjs';
+import { byteOrder, validateTask, readsTask, claimedPaths } from './task-thread.mjs';
 
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
 
 // The ONE contract sentence, doc-parity-bound into references/modes/dispatch.md: the FORM-only limit
 // and the aggregator's refusals are what a reader must not be able to mis-learn from the mode doc.
-export const DISPATCH_CONTRACT = 'the contract check is FORM-only — fields present, grammars respected, never boundedness, design-decidedness or acceptance adequacy — and `aggregate` REFUSES instead of computing acceptance for a wave with no pre-registration record, over an OPEN thread in scope, over a PRE-DISPATCH degrade that opens no thread, or across several waves with no `--wave`; the writer verbs add NO second legality door — the store\'s preflight is the only one, and its refusals travel verbatim — while `open` copies every mint-time field from the contract header and refuses a deadline below the wrapper cap plus the kill grace, `return` absorbs only a TERMINAL exec receipt whose backend, nonce and independently computed contractDigest match the dispatch it answers, and `fold` binds the CURRENT tree to the folded return\'s postTreeDigest, so a tree that moved between the two never folds, and `await` is satisfied ONLY by the TERMINAL exec receipt of its own dispatch\'s {backend, nonce} — never by a review receipt, a ledger line or a finding manifest — while an expiry names a supervision question and releases NO writer slot; `open` records the thread\'s BASE (`head` by default, `checkpoint` under `--checkpoint <oid>`), `return` and `fold` measure against the base the dispatch recorded, never a flag, and the `fold` VERB itself refuses a checkpoint `code` thread the held-session judge names SUBSTITUTED in that thread\'s own verdict — a precondition like its hidden-path and content-blind guards, the store\'s preflight staying the only door on the record';
+export const DISPATCH_CONTRACT = 'the contract check is FORM-only — fields present, grammars respected, never boundedness, design-decidedness or acceptance adequacy — and `aggregate` REFUSES instead of computing acceptance for a wave with no pre-registration record, over an OPEN thread in scope, over a PRE-DISPATCH degrade that opens no thread, or across several waves with no `--wave`; the writer verbs add NO second legality door — the store\'s preflight is the only one, and its refusals travel verbatim — while `open` copies every mint-time field from the contract header and refuses a deadline below the wrapper cap plus the kill grace, `return` absorbs only a TERMINAL exec receipt whose backend, nonce and independently computed contractDigest match the dispatch it answers, and `fold` binds the CURRENT tree to the folded return\'s postTreeDigest, so a tree that moved between the two never folds, and `await` is satisfied ONLY by the TERMINAL exec receipt of its own dispatch\'s {backend, nonce} — never by a review receipt, a ledger line or a finding manifest — while an expiry names a supervision question and releases NO writer slot; `open` records the thread\'s BASE (`head` by default, `checkpoint` under `--checkpoint <oid>`), `return` and `fold` measure against the base the dispatch recorded, never a flag, and the `fold` VERB itself refuses a checkpoint `code` thread the held-session judge names SUBSTITUTED in that thread\'s own verdict — a precondition like its hidden-path and content-blind guards, the store\'s preflight staying the only door on the record; `open --task` records the task, a task thread is measured over its Files and `open`, `return` and `fold` refuse `files-overlap`, `mixed-open` and `out-of-files`';
 
 // ── the flag surface (the CLI tests pin it against the D3 key sets) ────────────────────────────────
 // flag → the record field it decides. The fields NOT on a flag are DERIVED and listed beside them,
@@ -557,8 +557,10 @@ const runOpen = ({ baseCwd, env, argv, now }) => {
     task = { brief, files: [...new Set(parsed.files.map(({ path }) => path))].sort(byteOrder) };
     const checked = validateTask(task, base.kind);
     if (!checked.ok) return refusal('open', checked.reason);
+    const scope = taskFilesScopeRefusal(cwd, base, task.files);
+    if (scope !== null) return refusal('open', `task-files-scope: ${scope}; nothing was written`);
   }
-  const baselineClean = isCleanAgainstBase(cwd, base);
+  const baselineClean = isCleanAgainstBase(cwd, base, undefined, task?.files ?? null);
   if (baselineClean === null) {
     return refusal('open', 'the working state could not be probed, so the baseline is undecidable — a dispatch never records a guessed baseline, and outside a git work tree there is no tree to fingerprint either (fail closed); nothing was written');
   }
@@ -577,7 +579,7 @@ const runOpen = ({ baseCwd, env, argv, now }) => {
   // delegate's account at return time. `open` is where that lie is cheapest to catch.
   const honest = hiddenFromPlainDiff(top);
   if (!honest.ok) return refusal('open', `${honest.reason}; nothing was written`);
-  const preTreeDigest = uncommittedStateFingerprint(cwd, undefined, base);
+  const preTreeDigest = uncommittedStateFingerprint(cwd, undefined, base, task?.files ?? null);
   const record = {
     schema: DELEGATION_SCHEMA_VERSION,
     kind: 'dispatch',
@@ -668,7 +670,7 @@ export const pollExecArrival = ({ dir, backend, nonce, io = {} }) => {
   return { state: 'satisfied', reason: `the TERMINAL exec receipt landed (${path}) — outcome ${receipt.outcome} · exit ${receipt.exitStatus} · session ${receipt.sessionId ?? 'none'}` };
 };
 
-const NO_SLOT_RELEASED = 'NO writer slot was released: a wait that ended without an answer never authorizes the next dispatch (D10 — one in-tree exec dispatch at a time)';
+const NO_SLOT_RELEASED = 'NO writer slot was released: a wait that ended without an answer never authorizes the next dispatch';
 
 // The bound arithmetic is BigInt, and it HAS to be. The frozen record vocabulary admits any positive
 // SAFE INTEGER `deadlineS` (dispatch-record.mjs), so `deadlineS * 1000` leaves the exactly
@@ -1056,6 +1058,18 @@ export const treeDriftRefusal = (openingDigest, closingDigest) => (openingDigest
   ? null
   : `the tree moved WHILE the return was being computed (${openingDigest.slice(0, 12)}… → ${closingDigest.slice(0, 12)}…) — the enumeration and the diff would then describe two different change sets, and the record would bind a postTreeDigest neither of them saw; nothing was written, so leave the tree alone and return again`);
 
+const getOutOfFilesRefusal = (cwd, base, env) => {
+  const changed = runBaseDiff(cwd, base, ['--name-only', '--no-renames', '-z'], {}, null);
+  if (changed === null) return 'out-of-files: the snapshot domain is undecidable (fail closed); nothing was written';
+  const ledger = readDelegationLedger(cwd, env);
+  if (ledger.state !== 'ok') return `out-of-files: ${ledger.reason ?? `delegation ledger is ${ledger.state}`} (fail closed); nothing was written`;
+  const { records, head } = ledger;
+  if (head.state === 'error') return `out-of-files: ${head.reason} (fail closed); nothing was written`;
+  const claimed = new Set(claimedPaths(records, base.treeOid, head, isThreadTerminalRecord));
+  const unclaimed = changed.toString('utf8').split('\0').filter((path) => path !== '' && !claimed.has(path)).sort(byteOrder);
+  return unclaimed.length === 0 ? null : `out-of-files: ${unclaimed.join(', ')}; nothing was written`;
+};
+
 const runReturn = ({ baseCwd, env, argv, now }) => {
   const { values, operands, cwd } = scan(argv, { ...RETURN_FLAG_FIELDS, ...RETURN_INPUT_FLAGS }, baseCwd, { booleans: RETURN_BOOLEAN_FLAGS });
   refuseOperands('return', operands);
@@ -1156,20 +1170,23 @@ const runReturn = ({ baseCwd, env, argv, now }) => {
   // A tree that moved between them would hand the numerator one change set and the denominator
   // another, and the record would bind a postTreeDigest neither of them describes.
   const base = readsBaseline(dispatch);
-  const openingDigest = uncommittedStateFingerprint(cwd, undefined, base);
-  const enumerated = enumerateReturnedObjects(cwd, { base });
+  const paths = readsTask(dispatch)?.files ?? null;
+  const openingDigest = uncommittedStateFingerprint(cwd, undefined, base, paths);
+  const enumerated = enumerateReturnedObjects(cwd, { base, paths });
   if (!enumerated.ok) return refusal('return', enumerated.reason);
   const opaque = contentBlindRefusal(enumerated.entries);
   if (opaque !== null) return refusal('return', `${opaque}; nothing was written`);
   const lostTarget = symlinkTargetRefusal(top, enumerated.entries);
   if (lostTarget !== null) return refusal('return', `${lostTarget}; nothing was written`);
-  const produced = computeReturnedDiff(cwd, { base });
+  const produced = computeReturnedDiff(cwd, { base, paths });
   if (!produced.ok) return refusal('return', produced.reason);
   // The payload IS the diff and its digest IS the uncommitted-state fingerprint — one computation,
   // so diffDigest and postTreeDigest are equal by construction rather than by coincidence.
   const postTreeDigest = sha256(produced.diff);
   const drift = treeDriftRefusal(openingDigest, postTreeDigest);
   if (drift !== null) return refusal('return', drift);
+  const outOfFiles = paths === null ? null : getOutOfFilesRefusal(cwd, base, env);
+  if (outOfFiles !== null) return refusal('return', outOfFiles);
   // The fail-closed arm of a producer contradiction (one objectId claimed at two sizes). The
   // enumeration is this kit's own and emits one entry per object, so nothing here can reach it —
   // the vocabulary stays the authority on what a component is, and its refusal is surfaced whole.
@@ -1290,7 +1307,8 @@ const runFold = ({ baseCwd, env, argv, now }) => {
   // return and the fold without moving the digest this fold is about to bind. The enumeration runs
   // here for that one question — the fold computes no metric of its own.
   const base = readsBaseline(state.dispatch);
-  const enumerated = enumerateReturnedObjects(cwd, { base });
+  const paths = readsTask(state.dispatch)?.files ?? null;
+  const enumerated = enumerateReturnedObjects(cwd, { base, paths });
   if (!enumerated.ok) return refusal('fold', enumerated.reason);
   const opaque = contentBlindRefusal(enumerated.entries);
   if (opaque !== null) return refusal('fold', `${opaque}; nothing was written`);
@@ -1327,7 +1345,9 @@ const runFold = ({ baseCwd, env, argv, now }) => {
   // fold is honest there — identical payload bytes, identical content — so the rule is "the fold
   // precedes staging", never "staging refuses the fold by construction". A checkpoint measurement
   // never reads the real index, so staging moves nothing there; the fold still precedes `git add`.
-  const treeDigestAtFold = uncommittedStateFingerprint(cwd, undefined, base);
+  const treeDigestAtFold = uncommittedStateFingerprint(cwd, undefined, base, paths);
+  const outOfFiles = paths === null ? null : getOutOfFilesRefusal(cwd, base, env);
+  if (outOfFiles !== null) return refusal('fold', outOfFiles);
   const record = {
     schema: DELEGATION_SCHEMA_VERSION,
     kind: 'fold',
@@ -1672,7 +1692,7 @@ refusal from the store verbatim.
 --checkpoint <oid> records a resolvable TREE object of exactly 40 or 64 lowercase hex characters
 (a commit, blob, tag or unknown id refuses by name); the base rides the record and return/fold read
 it there, while a checkpoint CLEAN line names the base.
---task records the brief's path and its byte-ordered Files, requires --checkpoint (task-base), refuses a brief the parser refuses by the parser's name, and the store refuses files-overlap and mixed-open at append time.
+--task records the brief's path and its byte-ordered Files, requires --checkpoint (task-base), refuses a brief the parser refuses by the parser's name, refuses task-files-scope for a Files path the snapshot domain can never hold, and the store refuses files-overlap and mixed-open at append time; a task thread is measured over its Files.
 
 THE LEDGER a tree-binding verb uses is the CANONICAL one, exactly: <git common dir>/
 agent-workflow-delegation.jsonl. A store inside the work tree is measured as part of the change set
@@ -1800,8 +1820,8 @@ diff: a mode change moves it and no untracked marker line exists. Under a head b
 arrives as a deletion plus a creation, over-counting a plain rename; under a checkpoint base git's own
 rename detection applies inside the one base-relative layer and a detected rename is counted once.
 A receipt is forgeable exactly like every record here;
-and D10 stands as a BAR, not a mechanism — at most one in-tree exec dispatch at a time, and nothing
-refuses a second, task threads included; files-overlap and mixed-open additionally refuse conflicting task threads at append time.
+and D10 stands as a BAR, not a mechanism, for untasked threads — at most one untasked in-tree exec dispatch at a time,
+and nothing refuses a second; for task threads it is a mechanism: files-overlap and mixed-open refuse conflicting opens at append time, and return and fold refuse out-of-files.
 
 Never commits, never runs a subscription CLI, spawns nothing but git READS — with TWO stated exceptions: handoff-return,
 which attests MAIN's index with git write-tree: that may write a tree OBJECT into the odb and moves

package/tools/exec-producer.mjs

@@ -14,7 +14,7 @@
 // the DENOMINATOR) while HEAD→worktree shows nothing at all, so the object would vanish from the
 // NUMERATOR and the two halves of one ratio would describe different change sets. The diff bytes are
 // computeFingerprintPayload's own bytes, imported rather than rebuilt. Under a checkpoint base the
-// walk is one layer against the base tree, through the leaf's temporary index.
+// walk is one layer against the base tree, through the leaf's temporary index; io.paths absent or null = the whole domain.
 //
 // ONE OBJECT, ONE ENTRY. Under a head base an object touched in both layers is a single entry, and its pre-image is
 // always the HEAD blob — never the index blob: the numerator answers what the delegate could have
@@ -359,11 +359,11 @@ const entryForUntracked = (top, rel, lstat) => {
 };
 
 const enumerateCheckpointObjects = (top, base, io) => {
-  const raw = runBaseDiff(top, base, BASE_RAW_ARGS, io);
+  const raw = runBaseDiff(top, base, BASE_RAW_ARGS, io, io.paths ?? null);
   if (raw === null) return refuse('git could not read the base-relative change set (fail closed)');
   const parsed = parseRawRecords(raw, 'the base-relative change set');
   if (!parsed.ok) return parsed;
-  const numstat = runBaseDiff(top, base, BASE_NUMSTAT_ARGS, io);
+  const numstat = runBaseDiff(top, base, BASE_NUMSTAT_ARGS, io, io.paths ?? null);
   if (numstat === null) return refuse('git could not read the numstat binary markers (fail closed)');
   const binary = parseNumstatMarkers(numstat, 'the base-relative binary markers');
   if (!binary.ok) return binary;
@@ -482,7 +482,7 @@ export const computeReturnedDiff = (cwd = process.cwd(), io = {}) => {
   // caller that framed a bundle around a thrown read would have no bytes and no reason either.
   try {
     const base = io.base ?? HEAD_BASELINE;
-    const payload = base.kind === 'checkpoint' ? computeBasePayload(cwd, base, io) : computeFingerprintPayload(cwd);
+    const payload = base.kind === 'checkpoint' ? computeBasePayload(cwd, base, io, io.paths ?? null) : computeFingerprintPayload(cwd);
     return payload == null
       ? refuse('the canonical payload could not be computed (fail closed)')
       : { ok: true, diff: payload };

package/tools/inject-methodology.mjs

@@ -90,6 +90,8 @@ export const KNOWN_PRIOR_METHODOLOGY_SLOT = [
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
   // engine 4.6.0 — the three-activity pointer, before feedback-triage joined the named activities.
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution, routine) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
+  // engine 5.7.0 — the four-activity pointer, before epic and task joined the named activities.
+  '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution, routine, feedback-triage) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
 ];
 export const KNOWN_PRIOR_ORCH_SLOT = [
   // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).
@@ -113,9 +115,9 @@ export const METHODOLOGY_DESCRIPTOR = {
   markerName: 'methodology',
   anchorLabel: 'methodology anchor (the "Read it before any code change." Session-Protocols line)',
   knownPriorCanonicals: KNOWN_PRIOR_METHODOLOGY_SLOT,
-  upgradeSignature: 'Communication',
+  upgradeSignature: 'feedback-triage, epic, task',
   upgradeAdvice:
-    'the workflow-methodology pointer predates the communication-contract clause (deliver the artifact inline, lead with the result) — refresh it to the current canon, or add the clause by hand; the contract still applies.',
+    'the workflow-methodology pointer predates the current canon — six named activities (plan-authoring, plan-execution, routine, feedback-triage, epic, task) with the communication-contract clause (deliver the artifact inline, lead with the result) — refresh it to the current canon, or add what it lacks by hand; the contract still applies.',
 };
 export const ORCHESTRATION_DESCRIPTOR = {
   startMarker: ORCH_START_MARKER,
@@ -443,8 +445,8 @@ export const runCli = async (argv, deps = {}) => {
       'present-filled': 'workflow-methodology pointer already present',
     }[methResult.status];
     // Read-only upgrade advisories for a CUSTOMIZED methodology pointer that reconcile preserved verbatim
-    // (a refreshed/filled/inserted slot already carries the current canon, so it gets none): the AD-019
-    // procedures route AND the §1.9 communication-contract clause. No mutation — reported notes only.
+    // (a refreshed/filled/inserted slot already carries the current canon, so it gets none): the AD-019 procedures route
+    // AND the current-canon hint, keyed on the six-activity token (it names the §1.9 clause too). No mutation — notes only.
     const notes = [];
     if (methResult.status === 'present-filled') {
       const p = methodologyProceduresHint(afterMeth); if (p) notes.push(p);

package/tools/orchestration-readme.mjs

@@ -60,12 +60,20 @@ const FOUR_README = FOLD_README.replace(
   "Four activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review), 'routine' (slots carrier, parallel) and 'feedback-triage' (slot review).",
 );
 
-export const CANON_README = FOUR_README.replace(
+const FOUR_SEED_README = FOUR_README.replace(
   "The default below is 'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required.",
   "Every slot seeded below is 'solo' — no execution backend required. A slot the seed leaves silent takes the computed default stated further down: 'feedback-triage.review' is reviewed as soon as a review backend is ready (solo until then); 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' stay 'solo', and 'routine.parallel' stays 'on'.",
 );
 
-export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README, FOLD_README, FOUR_README]);
+export const CANON_README = FOUR_SEED_README
+  .replace("Four activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review), 'routine' (slots carrier, parallel) and 'feedback-triage' (slot review).",
+    "Six activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review), 'routine' (slots carrier, parallel), 'feedback-triage' (slot review), 'epic' (slots author, review) and 'task' (slots author, execute).")
+  .replace("the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' accept solo | subagent.",
+    "the carrier slots 'plan-authoring.author', 'plan-authoring.fold', 'routine.carrier' and 'epic.author' accept solo | subagent, and the task slots 'task.author' and 'task.execute' take the execute values.")
+  .replace("'feedback-triage.review' is reviewed as soon as a review backend is ready (solo until then); 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' stay 'solo',",
+    "'feedback-triage.review' is reviewed as soon as a review backend is ready (solo until then), and so is 'epic.review'; 'plan-authoring.author', 'plan-authoring.fold', 'routine.carrier', 'epic.author', 'task.author' and 'task.execute' stay 'solo',");
+
+export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README, FOLD_README, FOUR_README, FOUR_SEED_README]);
 
 export const refreshReadme = (config) => {
   if (config == null || typeof config !== 'object' || Array.isArray(config)) return { config, changed: false };

package/tools/procedures.mjs

@@ -276,6 +276,7 @@ export const REVIEW_ROUNDS_TOOL = join(dirname(fileURLToPath(import.meta.url)),
 export const REPO_SEARCH_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'repo-search.mjs');
 export const FEEDBACK_RECORD_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'feedback-record-cli.mjs');
 const FEEDBACK_TRIAGE = 'feedback-triage';
+const EPIC = 'epic';
 const GROUNDING_FACTS_OUT = '/tmp/review-facts.md';
 const MINTS_RECEIPT = Object.freeze({ mintsReceipt: true });
 const FEEDBACK_BRIDGE_LINES = Object.freeze({
@@ -380,25 +381,28 @@ const groundingPreStepAdvice = (activity, slots, plans) => {
   if (activity === FEEDBACK_TRIAGE) return [];
   if (!slots.some((s) => (s.backends ?? []).includes('agy-review'))) return [];
   const operand = populatedPlan(plans);
-  const planArg = operand === null ? '--plan <path>' : `--plan ${operand}`;
+  const planArg = activity === EPIC ? '' : operand === null ? ' --plan <path>' : ` --plan ${operand}`;
   const reviewOperand = populatedPlan(plans, MINTS_RECEIPT);
   // plan-authoring reviews the plan FILE — a plain name in flight renders the review command populated;
   // the renderability and receipt-carriability fallbacks are the only placeholders a known path produces.
   const reviewForm =
-    activity === 'plan-authoring'
-      ? reviewOperand === null
-        ? 'agy-review plan <plan-file>'
-        : `agy-review plan ${reviewOperand}`
-      : 'agy-review code';
+    activity === EPIC
+      ? 'agy-review plan <brief-file>'
+      : activity === 'plan-authoring'
+        ? reviewOperand === null
+          ? 'agy-review plan <plan-file>'
+          : `agy-review plan ${reviewOperand}`
+        : 'agy-review code';
   // `run:`/`then:` prefixes keep these POPULATED command lines machine-distinguishable from the
   // verbatim contract DESCRIPTORS above (the descriptor drift guard set-equals bare wrapper lines).
   // The TOOL path stays double-quoted (the bridge tier seeds that exact byte-form); the plan operand
   // rides shellQuoteArg — bare when safe, single-quoted otherwise.
   const lines = [
     'Grounding pre-step (agy is dispatched — assemble the verified facts BEFORE the review; grounding.mjs slices verbatim, judgment additions stay yours):',
-    `  run:  node "${GROUNDING_TOOL}" --constraints --autonomy ${planArg} --out ${GROUNDING_FACTS_OUT}`,
+    `  run:  node "${GROUNDING_TOOL}" --constraints --autonomy${planArg} --out ${GROUNDING_FACTS_OUT}`,
     `  then: ${reviewForm} --facts @${GROUNDING_FACTS_OUT}`,
   ];
+  if (activity === EPIC) return lines;
   const fellBack = [operand === null ? '--plan' : null, activity === 'plan-authoring' && reviewOperand === null ? 'agy-review plan' : null].filter(Boolean);
   lines.push(...planDiscoveryCaveat(
     plans,