@sabaiway/agent-workflow-kit 13.3.0 → 14.1.0

package/tools/held-session.mjs

@@ -2,6 +2,7 @@ import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mj
 import { wrapperCmdFor } from './detect-backends.mjs';
 import { DISPLAY_ALIASES } from './recipes.mjs';
 import { readsBaseline, TERMINAL_RETURN_OUTCOMES } from './dispatch-record.mjs';
+import { readsInsideEpoch, readsTask } from './task-thread.mjs';
 
 const CODE_STEP = 'code';
 const FOLD_KIND = 'fold';
@@ -13,12 +14,6 @@ const UNPOPULATED_HELD_ID = '<held id>';
 export const HELD_RECEIPT_BACKEND = DISPLAY_ALIASES[EXECUTE_BACKEND];
 export const HELD_EXECUTE_WRAPPER = wrapperCmdFor(EXECUTE_BACKEND, 'execute');
 
-const readsInsideEpoch = (dispatch, head) => {
-  if (head.state === 'unborn') return true;
-  const instant = Date.parse(dispatch.timestamp);
-  return Number.isFinite(instant) && Math.floor(instant / 1000) > head.seconds;
-};
-
 const updatesThread = (threads, nonce, update) =>
   threads.map((thread) => (thread.nonce === nonce ? { ...thread, ...update } : thread));
 
@@ -101,15 +96,7 @@ const countsHeldFolds = (records, epochNonces, heldId) => {
   }).length;
 };
 
-export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
-  if (head.state === 'error') {
-    return { state: 'error', cause: 'head', reason: head.reason, heldId: null, folds: 0, substitution: null, threads: [], open: [] };
-  }
-  const dispatches = records.filter((record) =>
-    record.kind === 'dispatch'
-    && record.stepClass === CODE_STEP
-    && record.backend === backend
-    && readsInsideEpoch(record, head));
+const judgeChain = (records, dispatches, degrades) => {
   const epochNonces = new Set(dispatches.map((dispatch) => dispatch.nonce));
   const initial = { epochNonces, dispatches: [], returns: [], heldId: null, substitutions: [], threads: [], open: [] };
   const accumulated = records.reduce(accumulatesFacts(degrades), initial);
@@ -125,6 +112,44 @@ export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
   };
 };
 
+export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
+  if (head.state === 'error') {
+    return { state: 'error', cause: 'head', reason: head.reason, heldId: null, folds: 0, substitution: null, threads: [], open: [] };
+  }
+  const dispatches = records.filter((record) =>
+    record.kind === 'dispatch'
+    && record.stepClass === CODE_STEP
+    && record.backend === backend
+    && readsInsideEpoch(record, head));
+  if (!dispatches.some((dispatch) => readsTask(dispatch) !== null)) return judgeChain(records, dispatches, degrades);
+  const groups = new Map();
+  for (const dispatch of dispatches) {
+    const key = readsTask(dispatch)?.brief ?? null;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(dispatch);
+  }
+  const reports = new Map([...groups].map(([key, entries]) => {
+    const nonces = new Set(entries.map((dispatch) => dispatch.nonce));
+    return [key, judgeChain(records.filter((record) => nonces.has(record.nonce)), entries, degrades)];
+  }));
+  const untasked = reports.get(null);
+  const threads = new Map([...reports].flatMap(([chainKey, report]) =>
+    report.threads.map((thread) => [thread.nonce, { ...thread, chainKey }])));
+  const substitutions = new Map([...reports.values()]
+    .filter((report) => report.substitution !== null)
+    .map((report) => [report.substitution.nonce, report.substitution]));
+  const firstReturn = records.find((record) => record.kind === RETURN_KIND && substitutions.has(record.nonce));
+  return {
+    state: 'ok',
+    heldId: untasked?.heldId ?? null,
+    folds: untasked?.folds ?? 0,
+    substitution: firstReturn === undefined ? null : substitutions.get(firstReturn.nonce),
+    threads: dispatches.map((dispatch) => threads.get(dispatch.nonce)),
+    open: untasked?.open ?? [],
+    chains: [...reports].map(([key, { heldId, folds, open }]) => ({ key, heldId, folds, open })),
+  };
+};
+
 export const threadVerdict = (facts, nonce) => facts.threads.find((thread) => thread.nonce === nonce) ?? null;
 
 export const judgeLedger = (ledger, { backend, degrades = [] }) => {
@@ -150,6 +175,11 @@ export const decideHeldSession = (facts) => {
     const reason = `delegated code thread "${nonce}" substituted held session "${escapeForDisplay(expectedId)}" with "${escapeForDisplay(actualId)}"`;
     return { code: 1, reason, line: `held session: SUBSTITUTED — ${reason}` };
   }
+  if (facts.chains !== undefined) {
+    const entries = facts.chains.map(({ key, heldId, folds }) =>
+      `${key === null ? 'untasked' : escapeForDisplay(key)}: ${heldId === null ? 'none' : escapeForDisplay(heldId)} (${folds})`);
+    return { code: 0, reason: 'task chains have no unresolved substitution', line: `held sessions: ${facts.chains.length} chain(s) — ${entries.join(' · ')}` };
+  }
   if (facts.heldId === null) return { code: 0, reason: 'no held session stands: no folded code thread established one in this commit epoch, or the last one was withdrawn by a checkpoint thread\'s ledger degrade', line: 'held session: none' };
   const heldId = escapeForDisplay(facts.heldId);
   return { code: 0, reason: `held session "${heldId}" is continuous`, line: `held session: ${heldId} — ${facts.folds} fold(s) rode it` };
@@ -164,15 +194,24 @@ const describesLaneCaveat = (facts) => {
   return null;
 };
 
+const chainLaneLines = (facts, chain) => {
+  const substitution = facts.threads.find((thread) => thread.chainKey === chain.key && thread.substituted) ?? null;
+  const caveat = describesLaneCaveat({ state: facts.state, heldId: chain.heldId, substitution });
+  const task = chain.key === null ? '' : `  (task ${escapeForDisplay(chain.key)})`;
+  if (caveat !== null) return [`  caveat: ${caveat}${task}`];
+  return [`  run:  ${HELD_EXECUTE_WRAPPER} --resume ${shellQuoteArg(chain.heldId)} --nonce <nonce> <fold-brief>${task}`];
+};
+
 export const foldLaneLines = (facts) => {
-  const caveat = describesLaneCaveat(facts);
-  const heldId = caveat === null ? shellQuoteArg(facts.heldId) : UNPOPULATED_HELD_ID;
   const lines = [
     'Fold lane (execute = delegated) — a fold rides the delegate\'s HELD session:',
-    `  run:  ${HELD_EXECUTE_WRAPPER} --resume ${heldId} --nonce <nonce> <fold-brief>`,
     '  the fold brief is a dispatch file carrying the finding and the accepted fold; dispatch open precedes the run, then dispatch return and fold follow it',
     '  the orchestrator runs the suites, verifies the returned diff, re-mints the red-proofs and owns the commit',
     '  a fresh session is a forbidden substitution; a retry of a failed thread or, for a head base, a recorded execute degrade is the exception (a checkpoint thread\'s substitution closes by its ledger degrade); the wrapper sidecar is never read',
   ];
+  if (facts.chains !== undefined) return [...lines, ...facts.chains.flatMap((chain) => chainLaneLines(facts, chain))];
+  const caveat = describesLaneCaveat(facts);
+  const heldId = caveat === null ? shellQuoteArg(facts.heldId) : UNPOPULATED_HELD_ID;
+  lines.splice(1, 0, `  run:  ${HELD_EXECUTE_WRAPPER} --resume ${heldId} --nonce <nonce> <fold-brief>`);
   return caveat === null ? lines : [...lines, `  caveat: ${caveat}`];
 };

package/tools/recommendations.mjs

@@ -85,7 +85,7 @@ import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
 import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
 import { NODE_EVIDENCE, NODE_EVIDENCE_SCRIPTS, probeNodeEvidence } from './node-evidence.mjs';
 // The vehicle READINESS comes from the read-only half — the same survey `recipes` and `status` read.
-import { surveyExecutorVehicle, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
+import { surveyExecutorVehicle, readExecutorPosture, executorTemplate, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
 // The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
 // (contract: kit/ack-store) — `status` reads the same store, and a second copy is what drifts.
 import {
@@ -994,11 +994,16 @@ const probeStateBlockHook = ({ root, deps, add, skip }) => {
 // surfaced its absence: `agents` is the family's SECOND `.claude/` writer, the `help` Tune tail
 // advertises it, and the advisor had no entry for it — so a user who never runs `help` never learned
 // it existed while the advisor reported the deployment optimal. Found by the guard, not by an incident.
-// Only a PLACE action counts as a gap: `already-current` is converged and `customized-preserved` is
-// the user's own edit, which the writer never clobbers and the advisor must never nag about.
+// Only a PLACE action counts as a gap: `already-current` is converged; a customized read-only vehicle or lens is
+// the user's own edit the writer never clobbers and the advisor never nags about; the executor is not preserved but re-derived from docs/ai/vehicles.json (its `re-derive` answer is not a gap of this offer).
 const probeCheapAgents = ({ root, deps, add, skip }) => {
   try {
-    const preflight = preflightCheapAgents({ cwd: root }, deps);
+    const { posture, reason } = readExecutorPosture(root, deps);
+    if (posture === null) {
+      skip('agents', new Error(`${reason} — fix that file first`));
+      return;
+    }
+    const preflight = preflightCheapAgents({ cwd: root, derived: [executorTemplate(posture, deps)] }, deps);
     // The writer refuses below the expected lineage, so offering its command would hand the user a
     // guaranteed failure — the honest surface is a stated skip naming the recovery.
     if (!preflight.stampOk) {
@@ -1050,15 +1055,16 @@ const probeExecutorVehicle = ({ root, deps, add, skip }) => {
     const survey = (deps.surveyVehicle ?? surveyExecutorVehicle)(root, deps);
     if (!VEHICLE_BROKEN_STATES.includes(survey.state)) return;
     const reason = safeLine(survey.reason ?? '');
+    const { posture, reason: settingsReason } = readExecutorPosture(root, deps);
     const stamp = readStamp(join(root, WORKFLOW_STAMP), readFsDeps(deps));
     const preconditions = [
       ...(stamp === EXPECTED_WORKFLOW_VERSION ? [] : [`run /agent-workflow-kit upgrade first (deployment stamp ${stamp ?? 'none'}, expected ${EXPECTED_WORKFLOW_VERSION})`]),
-      ...(survey.state === 'unusable' ? [`${reason || 'the vehicle file is unusable'} — fix that`] : []),
+      ...(posture === null ? [`${safeLine(settingsReason)} — fix that`] : []),
     ];
     // The writer refuses on ANY vehicle path it cannot touch (a symlinked read-only vehicle blocks a
-    // missing executor's placement too), so its own preflight is the last precondition — named once.
+    // missing executor's placement too), so its own preflight is the last precondition.
     const blocked = writerBlock(root, deps);
-    if (blocked && blocked !== reason) preconditions.push(`${blocked} — fix that`);
+    if (blocked) preconditions.push(`${blocked} — fix that`);
     const room = templateBudget(WHATS['executor-vehicle']) - String(configured.length).length - survey.state.length - 2;
     add(
       'executor-vehicle',
@@ -1067,8 +1073,8 @@ const probeExecutorVehicle = ({ root, deps, add, skip }) => {
         state: survey.state,
         reason: reason && room > 0 ? `: ${truncatedTo(reason, room)}` : '',
       }),
-      // The writer places a MISSING vehicle; an unusable path (a symlink, a read-only customization)
-      // is kept or refused, so that state's apply is a hand-apply precondition before the writer.
+      // The writer places a missing vehicle and re-derives a placed executor whose bytes differ from the derived body (an invalid
+      // frontmatter or read-only tools included), so those states need no precondition; every precondition above is a refusal the apply would meet.
       `${preconditions.length ? `HAND-APPLY: ${preconditions.join('; ')}, then run: ` : ''}node ${q(toolPath('cheap-agents.mjs'))} --apply --cwd ${q(root)}`,
       'executor-vehicle',
       `hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,

package/tools/task-thread.mjs

@@ -0,0 +1,70 @@
+import { hasPathOverlap } from './claim-relation.mjs';
+
+const TASK_BRIEF = /^docs\/plans\/TASK-[^/]+-T[1-9][0-9]*\.md$/u;
+const INVALID_SEGMENTS = Object.freeze(['', '.', '..', '.git']);
+const HEAD_BASELINE = Object.freeze({ kind: 'head', treeOid: null });
+
+export const byteOrder = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+
+export const readsTask = (dispatch) => Object.hasOwn(dispatch, 'task')
+  ? { brief: dispatch.task.brief, files: [...dispatch.task.files] }
+  : null;
+
+export const validateTask = (task, baseKind) => {
+  if (typeof task.brief !== 'string' || !TASK_BRIEF.test(task.brief)) {
+    return { ok: false, reason: 'task-brief: expected docs/plans/TASK-<stem>-T<n>.md with a positive task number' };
+  }
+  if (!Array.isArray(task.files) || task.files.length === 0) {
+    return { ok: false, reason: 'task-files: expected a non-empty array of paths' };
+  }
+  for (let index = 0; index < task.files.length; index += 1) {
+    const path = task.files[index];
+    if (typeof path !== 'string' || path.split('/').some((segment) => INVALID_SEGMENTS.includes(segment))) {
+      return { ok: false, reason: 'task-files: expected normalized repo-relative paths without empty, dot or .git segments' };
+    }
+    if (index > 0 && byteOrder(task.files[index - 1], path) >= 0) {
+      return { ok: false, reason: 'task-files: paths must be distinct and in byte order' };
+    }
+    if (task.files.slice(0, index).some((earlier) => hasPathOverlap(earlier, path))) {
+      return { ok: false, reason: 'task-files: one path is a prefix of another' };
+    }
+  }
+  if (baseKind === 'head') {
+    return { ok: false, reason: 'task-base: a task requires a checkpoint baseline' };
+  }
+  return { ok: true };
+};
+
+export const readsInsideEpoch = (dispatch, head) => {
+  if (head.state === 'unborn') return true;
+  const instant = Date.parse(dispatch.timestamp);
+  return Number.isFinite(instant) && Math.floor(instant / 1000) > head.seconds;
+};
+
+const collectClaims = (records, head, isTerminal) => {
+  const claims = [];
+  records.forEach((dispatch, index) => {
+    if (dispatch.kind !== 'dispatch' || !readsInsideEpoch(dispatch, head)) return;
+    const task = readsTask(dispatch);
+    if (task === null) return;
+    const later = records.slice(index + 1).filter((record) => record.nonce === dispatch.nonce);
+    const folded = later.some((record) => record.kind === 'fold');
+    if (!folded && later.some(isTerminal)) return;
+    // Keep the baseline reader local to preserve the acyclic ledger boundary.
+    const baseline = Object.hasOwn(dispatch, 'baseline') ? dispatch.baseline : HEAD_BASELINE;
+    claims.push({
+      nonce: dispatch.nonce, brief: task.brief, files: task.files,
+      state: folded ? 'folded' : 'open', treeOid: baseline.treeOid,
+    });
+  });
+  return claims;
+};
+
+export const claimedPaths = (records, treeOid, head, isTerminal) => [...new Set(
+  collectClaims(records, head, isTerminal)
+    .filter((claim) => claim.treeOid === treeOid)
+    .flatMap((claim) => claim.files),
+)].sort(byteOrder);
+
+export const epochClaims = (records, head, isTerminal) => collectClaims(records, head, isTerminal)
+  .map(({ nonce, brief, files, state }) => ({ nonce, brief, files, state }));

package/tools/upgrade-runlist.mjs

@@ -40,10 +40,12 @@ export const UPGRADE_RUNLIST = 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',