@sabaiway/agent-workflow-kit 13.3.0 → 14.1.0

package/tools/cheap-agents.mjs

@@ -7,15 +7,15 @@
 // only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it
 // never commits. `surveyExecutorVehicle` is that vehicle's readiness, for the subagent carrier.
 //
-// The family's second `.claude/` writer, the velocity-profile.mjs writer discipline verbatim:
+// The family's second `.claude/` writer, the velocity-profile.mjs discipline with an executor exception:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
 //   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
 //     head (a dry-run stays usable whatever the stamp says; an unreadable orchestration config
 //     STOPs both, since the derived lenses it names cannot be known);
 //   • symlink-safe — a symlinked `.claude` / `.claude/agents` / target file is a STOP, never a
 //     write-through;
-//   • NEVER overwrites an existing .claude/agents/ file whose content differs from the bundled
-//     template — a customization is REPORTED (`customized — preserved`), never clobbered;
+//   • preserves differing .claude/agents/ files (`customized — preserved`), except the executor:
+//     on apply its body is re-derived from docs/ai/vehicles.json, replacing a hand edit;
 //     an identical file is `already current` (idempotent re-run);
 //   • writes ONLY under .claude/agents/ — never settings.json / settings.local.json, never
 //     commits.
@@ -27,7 +27,7 @@
 //
 // Exit codes: 0 done / dry-run (incl. preserved customizations — a user's file is a legitimate
 // state, not an error); 1 precondition STOP (stamp, symlink, missing bundle, an unreadable
-// orchestration config — the derived lenses it names cannot be known); 2 usage.
+// orchestration config or docs/ai/vehicles.json — their derived bodies cannot be known); 2 usage.
 // Dependency-free, Node >= 22. No side effects on import.
 
 import { mkdirSync, writeFileSync } from 'node:fs';
@@ -38,6 +38,9 @@ import { shellQuoteArg } from './repo-lex.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { lensMembersOf } from './review-roster.mjs';
 import { deriveLensTemplate, lensVehicleSpec } from './review-roster-resolve.mjs';
+import { loadVehicles, resolveExecutor } from './vehicle-settings.mjs';
+import { safeLine } from './carriers.mjs';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
 // The READ core, never a second copy: the bundle, the placement plan and the executor survey live
 // there so the read-only advisor graph can reach them without reaching this writer.
 import {
@@ -47,9 +50,12 @@ import {
   EXPECTED_WORKFLOW_VERSION,
   UTF8,
   CHEAP_AGENTS_STAMP,
+  CHEAP_AGENTS_SYMLINK,
   CHEAP_AGENTS_BUNDLE,
   CHEAP_AGENTS_CONFIG,
+  CHEAP_AGENTS_VEHICLES,
   EXECUTOR_VEHICLE,
+  executorTemplate,
   makeCheapAgentsError,
   readFsDeps,
   readBundledAgents,
@@ -68,6 +74,10 @@ export {
   CHEAP_AGENTS_SYMLINK,
   CHEAP_AGENTS_BUNDLE,
   CHEAP_AGENTS_CONFIG,
+  CHEAP_AGENTS_VEHICLES,
+  readExecutorPosture,
+  executorTemplate,
+  deriveExecutorBody,
   makeCheapAgentsError,
   readBundledAgents,
   planPlacement,
@@ -96,7 +106,9 @@ authoring, or write-capable routine slice the orchestrator verifies, never for r
 it never commits.
 Default is --dry-run (a preview; writes nothing). --apply writes.
 Configured derived review lenses are planned and placed beside the bundled vehicles.
-An existing file with DIFFERENT content is preserved and reported, never overwritten.`;
+An existing file with DIFFERENT content is preserved and reported, never overwritten, except the executor.
+The executor's model and effort come from docs/ai/vehicles.json, and a placed executor whose bytes differ
+from the derived body is re-derived on --apply (a hand edit is replaced, never preserved).`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
@@ -127,6 +139,14 @@ const loadConfigOrStop = (cwd, deps) => {
   }
 };
 
+const loadExecutorPostureOrStop = (cwd, deps) => {
+  try {
+    return resolveExecutor(loadVehicles(cwd, deps.readFile, deps.lstat)).posture;
+  } catch (err) {
+    throw makeCheapAgentsError(CHEAP_AGENTS_VEHICLES, `${err?.message ?? err} — the agents writer cannot derive the executor vehicle — nothing is placed`);
+  }
+};
+
 const configuredDerivedTemplates = (cwd, deps) => {
   const config = loadConfigOrStop(cwd, deps);
   const bundle = readBundledAgents(deps);
@@ -149,9 +169,10 @@ export const applyCheapAgentsCommand = (root) =>
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const fs = writeFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
-  const derived = configuredDerivedTemplates(projectDir, deps);
+  const posture = loadExecutorPostureOrStop(projectDir, deps);
+  const derived = [executorTemplate(posture, deps), ...configuredDerivedTemplates(projectDir, deps)];
   const preflight = preflightCheapAgents({ cwd: projectDir, derived }, deps);
-  if (dryRun) return { wrote: false, dryRun: true, ...preflight };
+  if (dryRun) return { wrote: false, dryRun: true, posture, ...preflight };
 
   if (!preflight.stampOk) {
     throw makeCheapAgentsError(
@@ -159,10 +180,16 @@ export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
       `not a deployed agent-workflow project at lineage ${EXPECTED_WORKFLOW_VERSION} (found ${preflight.stamp ?? 'none'}) — run init/upgrade first`,
     );
   }
-  const toPlace = preflight.plan.filter((item) => item.action === 'place');
-  if (toPlace.length > 0) fs.mkdir(join(preflight.projectDir, AGENTS_DIR), { recursive: true });
-  for (const item of toPlace) fs.writeFile(item.abs, item.content, UTF8);
-  return { wrote: toPlace.length > 0, dryRun: false, ...preflight };
+  const toWrite = preflight.plan.filter((item) => item.action === 'place' || item.action === 're-derive');
+  if (toWrite.length > 0) fs.mkdir(join(preflight.projectDir, AGENTS_DIR), { recursive: true });
+  for (const item of toWrite) {
+    if (item.action === 're-derive') {
+      writeContainedFileAtomic(preflight.projectDir, item.abs, item.content, deps, {
+        label: item.rel, stop: (message) => makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, message),
+      });
+    } else fs.writeFile(item.abs, item.content, UTF8);
+  }
+  return { wrote: toWrite.length > 0, dryRun: false, posture, ...preflight };
 };
 
 // ── report ────────────────────────────────────────────────────────────────────────────
@@ -170,17 +197,20 @@ export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
 const ACTION_LABEL = {
   place: 'place',
   'already-current': 'already current',
+  're-derive': 're-derived — a hand edit was replaced; set the model in docs/ai/vehicles.json',
   'customized-preserved': 'customized — preserved (delete the file to reseed from the bundle)',
 };
 
 export const formatResult = (result) => {
+  const { posture } = result;
   const lines = [
     result.dryRun
       ? 'agent-workflow subagent vehicles — DRY RUN (no changes)'
       : 'agent-workflow subagent vehicles — APPLY',
   ];
   for (const item of result.plan) {
-    const verb = result.dryRun && item.action === 'place' ? 'would place' : ACTION_LABEL[item.action];
+    const verb = result.dryRun && item.action === 'place' ? 'would place'
+      : result.dryRun && item.action === 're-derive' ? 'would re-derive' : ACTION_LABEL[item.action];
     lines.push(`  - ${item.rel}: ${verb}`);
   }
   if (!result.stampOk) {
@@ -191,11 +221,12 @@ export const formatResult = (result) => {
     `${readOnlyCount} vehicles are Claude Code subagents with READ-ONLY tools and NO shell as bundled or derived (a customized file keeps whatever it grants) — so a fan-out on the shipped templates can never turn into a wave of approval prompts.`,
     `three of those ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY}`,
     'executor is the one FULL-TOOL vehicle: dispatched only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it never commits.',
+    `executor posture: model=${safeLine(posture.model)} effort=${safeLine(posture.effort)} fallback=${safeLine(posture.fallback)} (source: ${safeLine(posture.source)}) — set in docs/ai/vehicles.json`,
   );
   // A preview must print the EXACT command that applies it. The advisor renders this dry-run as an
   // item's one-liner, and that flow's contract is "run the printed command, no improvisation" — a
   // bare "re-run with --apply" would leave the caller to reconstruct --cwd and its quoting.
-  if (result.dryRun && result.plan.some((item) => item.action === 'place')) {
+  if (result.dryRun && result.plan.some((item) => item.action === 'place' || item.action === 're-derive')) {
     lines.push(`to apply, run exactly: ${applyCheapAgentsCommand(result.projectDir)}`);
   }
   if (!result.dryRun && result.wrote) {

package/tools/dispatch-record.mjs

@@ -76,6 +76,7 @@
 
 import { createHash } from 'node:crypto';
 import { SAFE_NONCE_RE, flowCanonicalSerialization } from './flow-record.mjs';
+import { validateTask } from './task-thread.mjs';
 
 const deepFreeze = (value) => {
   if (value !== null && typeof value === 'object') {
@@ -133,7 +134,7 @@ const short = (v) => {
 export const DELEGATION_SCHEMA_VERSION = 1;
 export const BASELINE_KINDS = deepFreeze(['head', 'checkpoint']);
 export const HEAD_BASELINE = deepFreeze({ kind: 'head', treeOid: null });
-export const OPTIONAL_FIELDS = deepFreeze({ dispatch: ['baseline'] });
+export const OPTIONAL_FIELDS = deepFreeze({ dispatch: ['baseline', 'task'] });
 const TREE_OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 export const isTreeOid = (v) => typeof v === 'string' && TREE_OID_RE.test(v);
 export const readsBaseline = (dispatch) => Object.hasOwn(dispatch, 'baseline')
@@ -145,7 +146,7 @@ export const DELEGATION_KINDS = deepFreeze(['pre-registration', 'dispatch', 'ret
 // The closed key set per kind (schema + kind are implicit on every record).
 export const DELEGATION_KEY_SETS = deepFreeze({
   'pre-registration': ['waveId', 'stepClasses', 'pairingKey', 'minPerClass', 'meanLThreshold', 'firstPassNum', 'firstPassDen', 'timestamp'],
-  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp', 'baseline'],
+  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp', 'baseline', 'task'],
   return: ['role', 'backend', 'nonce', 'contractDigest', 'preTreeDigest', 'postTreeDigest', 'diffDigest', 'diffLength', 'reportDigest', 'reportLength', 'bundleDigest', 'bundleLength', 'metric', 'outcome', 'exitStatus', 'sessionId', 'wrapperVersion', 'posture', 'timestamp'],
   fold: ['nonce', 'returnDigest', 'treeDigestAtFold', 'verdict', 'timestamp'],
   observation: ['waveId', 'stepClass', 'scope', 'metric', 'planId', 'phase', 'timestamp'],
@@ -346,6 +347,7 @@ const FIELD_CHECKS = {
   firstPassDen: { ok: (v) => Number.isSafeInteger(v) && v >= 1, want: 'a positive integer first-pass denominator' },
   vehicle: { ok: isPlainObject, want: 'the closed vehicle pair {requested, selected}' },
   baseline: { ok: isPlainObject, want: 'the closed baseline pair {kind, treeOid}' },
+  task: { ok: isPlainObject, want: 'the closed task object {brief, files}' },
   // The safe token grammar, not merely non-empty: the backend NAMES an artifact beside the store
   // (the exec receipt and its report), so a name outside this grammar records a dispatch whose own
   // receipt could never be written. One grammar on both sides, or the ledger accepts what the
@@ -519,6 +521,10 @@ export const validateDelegationRecord = (record) => {
       const baseline = validateBaseline('dispatch: baseline', record.baseline);
       if (!baseline.ok) return baseline;
     }
+    if (Object.hasOwn(record, 'task')) {
+      const closed = checkClosedKeys('dispatch: task', record.task, ['brief', 'files']); if (!closed.ok) return closed;
+      const task = validateTask(record.task, readsBaseline(record).kind); if (!task.ok) return refuse(`dispatch: task: ${task.reason}`);
+    }
     return vehicle.ok ? validateDispatchCrossFields(record) : vehicle;
   }
   if (record.kind === 'return') return validateReturnCrossFields(record);

package/tools/dispatch-store-read.mjs

@@ -7,6 +7,9 @@ import {
 } from './dispatch-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { GIT_MAX_BUFFER } from './git-env.mjs';
+import { readsTask, readsInsideEpoch, epochClaims } from './task-thread.mjs';
+import { hasPathOverlap } from './claim-relation.mjs';
+import { HELD_RECEIPT_BACKEND } from './held-session.mjs';
 
 export const DELEGATION_STORE_STOP = 'DELEGATION_STORE_STOP';
 export const delegationStoreStop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'DelegationStoreStop', code: DELEGATION_STORE_STOP });
@@ -127,7 +130,34 @@ const describeClosure = (last) =>
 
 const WAVE_SCOPED_KINDS = ['dispatch', 'observation', 'degrade'];
 
-export const delegationSemanticPreflight = ({ records, snapshot, storePath }) => {
+const checkTaskClaims = (records, snapshot, head) => {
+  if (head.state === 'error') throw stop(`${head.reason}; nothing was written`);
+  const task = readsTask(snapshot);
+  const claims = epochClaims(records, head, isThreadTerminalRecord);
+  if (task === null) {
+    const collision = claims.find((claim) => claim.state === 'open'
+      || (claim.state === 'folded' && snapshot.stepClass === 'code' && snapshot.backend === HELD_RECEIPT_BACKEND));
+    if (collision !== undefined) {
+      throw stop(`mixed-open: untasked dispatch collides with task thread "${collision.nonce}" (${collision.state}); nothing was written`);
+    }
+    return;
+  }
+  const untasked = records.find((record) => record.kind === 'dispatch' && readsTask(record) === null
+    && readsInsideEpoch(record, head) && delegationThreadState(records, record.nonce).open);
+  if (untasked !== undefined) {
+    throw stop(`mixed-open: task dispatch collides with open untasked thread "${untasked.nonce}"; nothing was written`);
+  }
+  for (const claim of claims) {
+    if (claim.state === 'folded' && claim.brief === task.brief) continue;
+    const shared = [...new Set(task.files.flatMap((path) => claim.files.flatMap((other) =>
+      hasPathOverlap(path, other) ? [path, other] : [])))].sort();
+    if (shared.length > 0) {
+      throw stop(`files-overlap: task dispatch overlaps thread "${claim.nonce}" on ${shared.join(', ')}; nothing was written`);
+    }
+  }
+};
+
+export const delegationSemanticPreflight = ({ records, snapshot, storePath, head = null }) => {
   const digest = canonicalDelegationDigest(snapshot);
   if (records.some((record) => canonicalDelegationDigest(record) === digest)) {
     throw stop(`refusing a canonical duplicate: ${storePath} already carries this exact record (${digest.slice(0, 12)}…), however its keys are ordered — a genuine new record carries new content or a new timestamp; nothing was written`);
@@ -180,6 +210,9 @@ export const delegationSemanticPreflight = ({ records, snapshot, storePath }) =>
       if (base.kind !== priorBase.kind || base.treeOid !== priorBase.treeOid) {
         throw stop(`refusing a retry: its base {kind "${base.kind}", treeOid ${base.treeOid}} differs from its retry origin "${snapshot.retryOf}"'s {kind "${priorBase.kind}", treeOid ${priorBase.treeOid}} — a retry chain is measured against ONE base; nothing was written`);
       }
+      if (JSON.stringify(readsTask(snapshot)) !== JSON.stringify(readsTask(prior.dispatch))) {
+        throw stop(`refusing a retry: its task differs from its retry origin "${snapshot.retryOf}" in brief or files — a retry keeps the same task; nothing was written`);
+      }
       const origin = findRetryChainOrigin(records, prior.dispatch);
       if (snapshot.retryIndex > origin.retryCap) {
         throw stop(`refusing a retry: retryIndex ${snapshot.retryIndex} exceeds the retryCap ${origin.retryCap} recorded on the thread's ORIGIN dispatch ("${origin.nonce}") — a fresh contract never manufactures a fresh retry budget; nothing was written`);
@@ -188,6 +221,7 @@ export const delegationSemanticPreflight = ({ records, snapshot, storePath }) =>
         throw stop(`refusing a retry: it retries a contract-refusal thread and must carry a DIFFERENT contractDigest — an unchanged contract would only be refused again, and a retry loop on one contract is exactly what the cap exists to prevent; nothing was written`);
       }
     }
+    if (head !== null) checkTaskClaims(records, snapshot, head);
     return;
   }
   if (state.dispatch === null) {

package/tools/dispatch-store.mjs

@@ -9,8 +9,10 @@ import {
   resolveDelegationStorePath,
   parseDelegationStoreText,
   delegationSemanticPreflight,
+  readHeadInstant,
 } from './dispatch-store-read.mjs';
 import { createStoreAppendLane } from './store-append.mjs';
+import { readsTask } from './task-thread.mjs';
 
 export {
   DELEGATION_STORE_STOP,
@@ -52,6 +54,11 @@ const delegationAppendLane = createStoreAppendLane({
 export const appendDelegationRecord = ({ cwd = process.cwd(), record, env = process.env, deps = {} } = {}) => {
   const { line, snapshot } = delegationAppendLane.captureRecordSnapshot(record);
   return delegationAppendLane.appendResolvedRecord({
-    cwd, env, deps, preflight: delegationSemanticPreflight, makeRecord: () => ({ line, snapshot }),
+    cwd, env, deps, makeRecord: () => ({ line, snapshot }),
+    preflight: ({ records, snapshot, line, storePath }) => delegationSemanticPreflight({
+      records, snapshot, line, storePath, cwd,
+      head: snapshot.kind === 'dispatch' && (readsTask(snapshot) !== null || records.some((record) => readsTask(record) !== null))
+        ? readHeadInstant(cwd) : null,
+    }),
   });
 };

package/tools/dispatch.mjs

@@ -54,7 +54,7 @@
 //   • 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.
+//     nothing here refuses a second one, task threads included; files-overlap and mixed-open additionally refuse conflicting task threads at append time.
 //   • `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.
 //
@@ -99,6 +99,8 @@ import {
   resolveRepoRoot, measureScope, ratio, formatRatio, buildObservationRecord,
 } 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';
 
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
 
@@ -145,6 +147,7 @@ export const OPEN_FLAG_FIELDS = Object.freeze({
   '--rationale': 'rationale',
   '--retry-of': 'retryOf',
   '--checkpoint': 'baseline.treeOid',
+  '--task': 'task',
 });
 // COPIED from the contract header at mint and bound by contractDigest (D3): a dispatch that
 // disagreed with the header it claims to carry is refused by checkDispatchMintConsistency.
@@ -476,7 +479,7 @@ const runObserve = ({ baseCwd, env, argv, now }) => {
 // some other producer wrote — and a verb computing over such a ledger inherits its lie. So every
 // verb that DERIVES anything from the store (`return`, `fold`, `degrade`, `aggregate`) reads it
 // through this one door, which replays the store's own preflight in file order and stops at the
-// first record the append path would have refused, naming its physical line.
+// first record the append path would have refused, except files-overlap and mixed-open, which are judged at append time only, naming its physical line.
 //
 // `open` deliberately has no read-side audit: it derives nothing from the ledger. Its retry and wave
 // rules are evaluated by the store, on the snapshot under the lock, which is the only place they can
@@ -539,6 +542,22 @@ const runOpen = ({ baseCwd, env, argv, now }) => {
     if (!resolved.ok) return refusal('open', resolved.reason);
   }
   const base = oid === undefined ? HEAD_BASELINE : { kind: 'checkpoint', treeOid: oid };
+  const brief = values['--task'];
+  let task = null;
+  if (brief !== undefined) {
+    if (oid === undefined) return refusal('open', 'task-base: --task requires --checkpoint; nothing was written');
+    const root = resolveRepoRoot(cwd);
+    if (root === null) return refusal('open', 'not inside a git work tree — a dispatch is opened against a repository (fail closed); nothing was written');
+    const read = readRegularFileNoFollow(resolve(root, brief));
+    if (read.outcome !== 'ok') {
+      return refusal('open', `cannot read ${brief} (${read.code ?? read.className ?? read.outcome}); nothing was written`);
+    }
+    const parsed = parseBrief(read.content);
+    if (!parsed.ok) return refusal('open', parsed.reason);
+    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 baselineClean = isCleanAgainstBase(cwd, base);
   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');
@@ -571,6 +590,7 @@ const runOpen = ({ baseCwd, env, argv, now }) => {
     preTreeDigest,
     baselineClean,
     baseline: { kind: base.kind, treeOid: base.treeOid },
+    ...(task === null ? {} : { task }),
     deadlineS: contract.deadlineS,
     retryOf: values['--retry-of'] ?? null,
     retryIndex: contract.retry.index,
@@ -1600,7 +1620,7 @@ Usage:
                             [--denominator-bytes <n>] [--cwd <dir>]
   node dispatch.mjs open --contract <dispatch-file> --wave <id> --backend <name>
                          --rationale <text> --wrapper-cap-s <n> --kill-grace-s <n>
-                         [--checkpoint <oid>] [--retry-of <nonce>] [--cwd <dir>]
+                         [--checkpoint <oid>] [--task <brief>] [--retry-of <nonce>] [--cwd <dir>]
   node dispatch.mjs await --nonce <n> [--timeout <s>] [--cwd <dir>]
   node dispatch.mjs return --nonce <n> [--outcome <o>]
                            [--no-receipt --exit-status <n>] [--cwd <dir>]
@@ -1652,6 +1672,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.
 
 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
@@ -1780,7 +1801,7 @@ arrives as a deletion plus a creation, over-counting a plain rename; under a che
 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.
+refuses a second, task threads included; files-overlap and mixed-open additionally refuse conflicting task threads at append time.
 
 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/ensure-configs.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
-// ensure-configs.mjs — ONE runnable command for the seven stamp-independent upgrade ensures:
+// ensure-configs.mjs — ONE runnable command for the stamp-independent upgrade ensures:
 //
 //   orchestration  docs/ai/orchestration.json  seed, or refresh a still-canonical onboarding note
 //   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
 //   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
 //   vehicles       docs/ai/vehicles.json       seed-if-missing (same)
+//   executor       .claude/agents/executor.md  re-derived from docs/ai/vehicles.json when its bytes differ; absent stays absent
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
 //   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, refreshed only on
 //                  + docs/ai/specs/index.md    a shipped prior body, store root seeded behind a current checker
 //   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
-// of seven is deliberate: seven independent runs would be seven chances to skip one, and the mode doc now
-// has a single invocation point whose seven outcome lines it relays.
+// of one per ensure is deliberate: independent runs would be as many chances to skip one, and the mode
+// doc now has a single invocation point whose outcome lines it relays.
 //
 // The contract (pinned by this module's tests):
 //   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
@@ -20,7 +21,7 @@
 //   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
 //     token, and the exit is non-zero when any of them failed.
 //   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
-//     with the gate's own message rather than seven copies of it.
+//     with the gate's own message rather than one copy of it per op.
 //
 // Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
 // Exit codes: 0 every op fine · 1 an op failed, or the deployment gate stopped the run · 2 usage.
@@ -32,14 +33,15 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertDocsAiDeployment } from './atomic-write.mjs';
 import { isDirectRun } from './direct-run.mjs';
+import { ensureExecutor } from './ensure-executor.mjs';
 import { ENSURE_OPS, OWN_IMPLEMENTATIONS, failedOutcome } from './ensure-ops.mjs';
 import { ensureSpecs } from './ensure-specs.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 // The op table this CLI walks — name → implementation, in ENSURE_OPS order. Composed HERE (the one
-// consumer) because the spec-layer ensure imports ensure-ops.mjs for its outcome door and probes.
-export const ENSURE_IMPLEMENTATIONS = Object.freeze({ ...OWN_IMPLEMENTATIONS, specs: ensureSpecs });
+// consumer) because the executor and spec-layer ensures import ensure-ops.mjs for their outcome door and probes.
+export const ENSURE_IMPLEMENTATIONS = Object.freeze({ ...OWN_IMPLEMENTATIONS, executor: ensureExecutor, specs: ensureSpecs });
 
 const EXIT_OK = 0;
 const EXIT_FAILED = 1;
@@ -52,23 +54,25 @@ const EMPTY_ONLY = `--only needs one operation name (${ENSURE_OPS.join(' | ')})
 const REPEATED_ONLY = '--only was passed more than once — this selector names exactly ONE operation';
 const unknownOp = (value) => `--only ${value}: no such operation (${ENSURE_OPS.join(' | ')}) — nothing was run`;
 
-const HELP = `ensure-configs — the seven stamp-independent upgrade ensures, as ONE command.
+const HELP = `ensure-configs — the eight stamp-independent upgrade ensures, as ONE command.
 
 Usage:
   node ensure-configs.mjs --reconcile [--dry-run] [--only <op>] [--cwd <project>]
 
-  --reconcile   required — run the seven ensures (${ENSURE_OPS.join(', ')})
+  --reconcile   required — run the eight ensures (${ENSURE_OPS.join(', ')})
   --dry-run     report what each ensure WOULD do; write nothing
   --only <op>   run EXACTLY ONE of them (an unknown, missing or repeated value is a usage error)
   --cwd <dir>   the target project (default: the current directory)
   --help, -h    this help
 
 Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
-refreshed in place. Three ops refresh instead: the orchestration onboarding note, only while it still
+refreshed in place. Four ops refresh instead: the orchestration onboarding note, only while it still
 matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer reader
 and checker pairs, only while a file's bytes are a body a release shipped (an edited file is
 preserved, and the writes that depend on it — the spec store root included — are withheld behind
-it); and the navigator index — a GENERATED artifact, regenerated
+it); the placed executor vehicle (.claude/agents/executor.md), re-derived from docs/ai/vehicles.json
+whenever its bytes differ from the derived body (a hand edit is replaced, never preserved; an absent
+file is never placed here); and the navigator index — a GENERATED artifact, regenerated
 whenever it is missing or stale. The enforcement-script ensure detects an older ADR-store layout
 FIRST and instructs the opt-in migration instead of seeding.
 
@@ -149,7 +153,7 @@ export const main = (argv = [], ctx = {}) => {
     const cwd = resolve(args.cwd ?? ctx.cwd ?? process.cwd());
     const deps = ctx.deps ?? {};
     // ONE deployment gate for the whole run (see the header): with no docs/ai there is nothing to
-    // reconcile, and seven identical STOPs would read as seven separate problems.
+    // reconcile, and one identical STOP per op would read as that many separate problems.
     assertDocsAiDeployment(cwd, deps, { noun: 'the project configuration', rel: 'under docs/ai' });
     const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps, only: args.only });
     return {

package/tools/ensure-executor.mjs

@@ -0,0 +1,87 @@
+// ensure-executor.mjs — the EIGHTH upgrade ensure, fifth in the fixed order right after `vehicles`:
+// the placed executor vehicle (.claude/agents/executor.md) re-derived from docs/ai/vehicles.json.
+// The agents writer PLACES the vehicle on consent; this ensure never does — it only keeps a placed
+// body equal to the one derived from the settings, and a hand edit is replaced, never preserved.
+//
+// The state table, in the order the cells are proven (the write is the LAST step):
+// | cell | .claude, .claude/agents | placed path | docs/ai/vehicles.json | answer | read before answering |
+// |------|-------------------------|-------------|-----------------------|--------|-----------------------|
+// | 0 | a symlink or not a directory | any | any | failed / wrong-node-kind | nothing |
+// | 1 | absent or directories | a symlink, a directory, another non-regular node | any | failed / wrong-node-kind | nothing |
+// | 2 | absent or directories | no entry | any, malformed included | not-placed | nothing |
+// | 3 | directories | regular file | unreadable (malformed, read or lstat error) | failed / vehicle-settings-unreadable | the settings only |
+// | 4 | directories | regular file | present or absent | failed / bundle-unreadable when the bundled template cannot be read | settings, bundle |
+// | 5 | directories | regular file, bytes equal to the derived body | present or absent | already-current | settings, bundle, placed file |
+// | 6 | directories | regular file, bytes differ | present or absent | dry-run would-re-derive; apply re-derived, or failed / write-refused | settings, bundle, placed file |
+// | 7 | an lstat of `.claude`, `.claude/agents` or the placed path throwing other than ENOENT, or the read of the placed file throwing | | | NOT caught: the error propagates to the CLI's catch-all (`unexpected-error`) | |
+//
+// Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
+import { composeFailure, composeOutcome, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+import { assertDirSafe, AGENTS_DIR, CLAUDE_DIR, CHEAP_AGENTS_SYMLINK, EXECUTOR_VEHICLE_REL, executorTemplate, readExecutorPosture } from './cheap-agents-read.mjs';
+import { VEHICLES_REL } from './vehicle-settings.mjs';
+
+export const EXECUTOR_OP = 'executor';
+
+const BUNDLE_DIR = ['references', 'agents'];
+const ENCODING = 'utf8';
+
+const ok = (token, lines) => composeOutcome(EXECUTOR_OP, token, lines, false);
+const loud = (cause, ...lines) => composeFailure(EXECUTOR_OP, cause, ...lines);
+const causeOf = (err) => String((err && err.message) || err);
+
+export const ensureExecutor = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+
+  try {
+    assertDirSafe(join(cwd, CLAUDE_DIR), CLAUDE_DIR, { lstat });
+    assertDirSafe(join(cwd, AGENTS_DIR), AGENTS_DIR, { lstat });
+  } catch (err) {
+    if (err?.code !== CHEAP_AGENTS_SYMLINK) throw err;
+    return loud('wrong-node-kind', causeOf(err));
+  }
+
+  const target = join(cwd, EXECUTOR_VEHICLE_REL);
+  const probe = probeSeedTarget(target, lstat);
+  if (probe.wrongKind) {
+    return loud('wrong-node-kind', `${EXECUTOR_VEHICLE_REL}: exists but is ${probe.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
+  }
+  if (!probe.present) {
+    return ok('not-placed', [`${EXECUTOR_VEHICLE_REL}: not placed — the agents mode places it on consent; nothing written`]);
+  }
+
+  const { posture, reason } = readExecutorPosture(cwd, deps);
+  if (posture === null) {
+    return loud('vehicle-settings-unreadable', `${EXECUTOR_VEHICLE_REL}: ${reason} — nothing written; fix ${VEHICLES_REL} by hand, then re-run`);
+  }
+
+  let body;
+  try {
+    body = executorTemplate(posture, { ...deps, bundleDir: join(kitRoot, ...BUNDLE_DIR) }).content;
+  } catch (err) {
+    return loud('bundle-unreadable', `${EXECUTOR_VEHICLE_REL}: the bundled executor template could not be read, so nothing was written — reinstall the kit. ${causeOf(err)}`);
+  }
+
+  const existing = read(target, ENCODING);
+  if (existing === body) {
+    return ok('already-current', [`${EXECUTOR_VEHICLE_REL}: the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}, source ${posture.source}) — nothing written`]);
+  }
+  if (dryRun) {
+    return ok('would-re-derive', [`${EXECUTOR_VEHICLE_REL}: differs from the body derived from ${VEHICLES_REL} — would be rewritten (a hand edit is replaced, never preserved)`]);
+  }
+
+  let result;
+  try {
+    result = writeContainedFileAtomic(cwd, target, body, deps, { label: EXECUTOR_VEHICLE_REL });
+  } catch (err) {
+    return loud('write-refused', `${EXECUTOR_VEHICLE_REL}: ${causeOf(err)}`);
+  }
+  return ok('re-derived', [
+    `${EXECUTOR_VEHICLE_REL}: rewritten to the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}) — a hand edit was replaced; set the model in ${VEHICLES_REL}`,
+    ...tmpNote(EXECUTOR_VEHICLE_REL, result.tmpLeftBehind),
+  ]);
+};

package/tools/ensure-ops.mjs

@@ -1,5 +1,5 @@
 // ensure-ops.mjs — the upgrade ensure operations this module owns, one function each, behind one shared
-// outcome shape; the spec-layer ensure (ensure-specs.mjs) composes its outcomes through
+// outcome shape; the leaves that import this module compose their outcomes through
 // the same door and probes exported below. The CLI that orders and runs them is ensure-configs.mjs —
 // it owns the op table, so the import graph stays acyclic; this module owns what each ensure DOES
 // and, more importantly, what it is allowed to CLAIM.
@@ -371,7 +371,7 @@ export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
 };
 
 // The ops this module owns, by name. The CLI composes the full ENSURE_OPS table from these plus
-// the spec-layer ensure (ensure-specs.mjs imports THIS module, so the table cannot live here).
+// the leaves that import THIS module, which join the table in ensure-configs.mjs (so it cannot live here).
 export const OWN_IMPLEMENTATIONS = Object.freeze({
   orchestration: ensureOrchestration,
   gates: ensureGates,

package/tools/ensure-vocabulary.mjs

@@ -10,14 +10,16 @@
 // The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
 // `specs` sits after `scripts` (its reader pair is a scripts/ seed too) and BEFORE `index`: the store
 // root it seeds is a docs/ai file the navigator must count.
-export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'vehicles', 'scripts', 'specs', 'index']);
+// `executor` follows `vehicles`: its body is derived from the settings file that op seeds.
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'vehicles', 'executor', 'scripts', 'specs', 'index']);
 
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
 // walks this set), and each has exactly one `would-` counterpart below. `refreshed` is the spec-layer
 // ensure's pair refresh (reader or checker) — a deployed script on a body a release shipped,
 // rewritten to the bundled one (a custom body is never refreshed).
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate']);
+// `re-derived` is the executor ensure rewriting a placed executor whose bytes differ from the body derived from docs/ai/vehicles.json.
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated', 're-derived']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate', 'would-re-derive']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -29,6 +31,7 @@ export const ENSURE_TOKENS = Object.freeze([
   ...DRY_RUN_TOKENS,
   'already-current',
   'already-present',
+  'not-placed',
   'customized-preserved',
   'malformed-preserved',
   'skipped-no-node-evidence',
@@ -48,6 +51,8 @@ export const FAILURE_CAUSES = Object.freeze([
   // here is unproven, so the ensures that place Node scripts write nothing (contract: kit/node-evidence).
   'node-evidence-unverifiable',
   'wrong-node-kind',
+  // The settings file could not be read, so no body can be derived and nothing is written.
+  'vehicle-settings-unreadable',
   'write-refused',
   'unexpected-error',
   // The navigator ensure drives a SEPARATE PROCESS (the bundled generator), so its failures split by
@@ -74,10 +79,12 @@ export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'note-refreshed',
   'refreshed',
   'regenerated',
+  're-derived',
   'already-current',
   'customized-preserved',
   'malformed-preserved',
   'already-present',
+  'not-placed',
   'skipped-no-node-evidence',
   'old-adr-layout-migration-instructed',
   'failed',