@farmslot/agent-runtime 0.12.0 → 0.13.0

package/scripts/mark-checklist-step.cjs

@@ -8,11 +8,25 @@ const {
   resolveWorkerTerminalContract,
 } = require('./worker-terminal-contract.cjs');
 const {
-  checklistStepName,
-  enumerateChecklistCheckboxes,
   parseTaskDirMarkArgs,
   terminalContractInputForChecklist,
 } = require('./checklist-target.cjs');
+const {
+  atomicWrite,
+  markStepInLines,
+  parseChecklist,
+  pickSignalPassthrough,
+  readJson,
+  signalContentUnchanged,
+  writeSignal,
+} = require('./mark-io.cjs');
+const { AcceptanceRefusal, requireHandoffAcceptanceCriteria } = require('./acceptance-ledger.cjs');
+const {
+  openSubtaskRefusal,
+  openSubtaskUnits,
+  runSubtaskCommand,
+  subtaskOwningStep,
+} = require('./subtask-unit.cjs');
 
 const START_COMMANDS = new Set(['start']);
 const TERMINAL_COMMANDS = new Set(['complete', 'no-change', 'blocked']);
@@ -49,6 +63,8 @@ function printHelp() {
       'Override: farmslot-agent mark <task-dir> --checklist SELF-REVIEW.md <step> — optional --signal; signal defaults from checklist name.',
       'Bootstrap: ./mark start — role-owned signal with status running (no checklist box).',
       'Progress: ./mark 1, ./mark 2, ... — checks the box and appends checklistTiming.',
+      'Child units: ./mark sub start <id> --step N --from <path|inline:text>, then ./mark sub <id> <n> | complete [--report PATH] [--mark-last] | blocked --reason "..." | status.',
+      '  While a child owns step N, ./mark N is refused; the child complete ticks it. Run ./mark sub --help for the child verbs.',
       'Terminal:',
       '  ./mark complete [--mark-last] [--no-self-review] [--skip-learnings] [--skip-checklist]',
       '  ./mark no-change --reason "..." [--already-fixed] [--mark-last] [--skip-learnings] [--skip-checklist]',
@@ -86,6 +102,11 @@ function resolveMarkInvocation(rawArgs) {
   const firstPath = path.resolve(first);
   const firstIsDir = fs.existsSync(firstPath) && fs.statSync(firstPath).isDirectory();
   if (firstIsDir) {
+    // Child-unit verbs own their own argument grammar (`sub start <id> …`), so
+    // they are routed before the parent step parser sees a non-step token.
+    if (rawArgs[1] === 'sub') {
+      process.exit(runSubtaskCommand(firstPath, rawArgs.slice(2)));
+    }
     const parsed = parseTaskDirMarkArgs(firstPath, rawArgs.slice(1), {
       isMarkStepToken,
       usage,
@@ -139,16 +160,6 @@ if (terminalCommand === 'no-change' || terminalCommand === 'blocked') {
   }
 }
 
-const SIGNAL_PASSTHROUGH_KEYS = ['role', 'contextId', 'attemptId', 'prNumber'];
-
-function pickSignalPassthrough(signal) {
-  const out = {};
-  for (const key of SIGNAL_PASSTHROUGH_KEYS) {
-    if (signal[key] !== undefined) out[key] = signal[key];
-  }
-  return out;
-}
-
 function resolveTerminalPreset(command) {
   switch (command) {
     case 'complete':
@@ -309,6 +320,25 @@ function assertArtifactContract(taskDir, taskPath, contract, terminalCommand) {
   }
   const contractPath = terminalContractPath(taskDir, taskPath);
   const args = [ARTIFACT_CONTRACT_SCRIPT, taskDir];
+  // The ledger blocks `complete` only where the project opted in
+  // (`worker_terminal.acceptance.require`) AND the task registered criteria
+  // (ADR-060). Without the opt-in a template that does not write a ledger yet
+  // still completes; the ledger is watched, projected and preferred for coverage
+  // either way.
+  if (terminalCommand === 'complete' && contract?.acceptance?.require === true) {
+    let criteria;
+    try {
+      criteria = requireHandoffAcceptanceCriteria(taskDir);
+    } catch (err) {
+      // Fail closed, the same way the gateway's backup check does: a handoff the
+      // engine cannot read hides whether the criteria were judged, and dropping
+      // the rule the project asked for is how an unproven run closes.
+      if (!(err instanceof AcceptanceRefusal)) throw err;
+      console.error(err.message);
+      process.exit(1);
+    }
+    if (criteria.length > 0) args.push('--require-acceptance-status');
+  }
   if (fs.existsSync(contractPath)) {
     args.push('--contract', contractPath);
     if (terminalCommand) args.push('--terminal', terminalCommand);
@@ -403,45 +433,6 @@ function buildSignalUpdate(signal, terminal, target, timing, events, now, taskPa
   return next;
 }
 
-function atomicWrite(file, content, mode) {
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.tmp`);
-  fs.writeFileSync(tmp, content, mode ? { mode } : undefined);
-  fs.renameSync(tmp, file);
-}
-
-function readJson(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return {};
-    throw err;
-  }
-}
-
-// Step enumeration is shared with the gateway parsers (generateTaskSchema in
-// tasks/writer.ts and parseCheckboxStates in methods/task.ts) via the
-// checklist-target enumerator: same skip sections, <details> handling, and
-// checkbox shape. Any divergence makes `mark N` check a different box than
-// the one progress reporting counts as step N (checkbox-formatted Acceptance
-// Criteria used to shift every step by the AC count).
-function parseChecklist(markdown) {
-  const lines = markdown.split(/\n/);
-  const items = enumerateChecklistCheckboxes(markdown).map((item) => ({
-    ...item,
-    label: checklistStepName(item.rawLabel),
-  }));
-  return { lines, items };
-}
-
-function markStepInLines(lines, item) {
-  if (item.checked) return false;
-  const before = lines[item.lineIndex];
-  lines[item.lineIndex] = before.replace(/^(\s*- \[)( |x|X)(\])/, '$1x$3');
-  return lines[item.lineIndex] !== before;
-}
-
 function resolveTarget(taskPath, stepNumber, markLast) {
   const original = fs.readFileSync(taskPath, 'utf8');
   const parsed = parseChecklist(original);
@@ -458,6 +449,9 @@ function resolveTarget(taskPath, stepNumber, markLast) {
   }
   let updated = original;
   if (item) {
+    // Also covers `--mark-last`: the parent must not tick a box whose child is
+    // still open, whichever way the row was chosen.
+    assertStepNotOwnedBySubtask(item.stepNumber);
     const nextLines = [...parsed.lines];
     markStepInLines(nextLines, item);
     updated = nextLines.join('\n');
@@ -469,6 +463,36 @@ function resolveTarget(taskPath, stepNumber, markLast) {
 }
 
 const taskDir = path.dirname(signalPath);
+
+/**
+ * A step owned by a child unit belongs to that child until it is settled
+ * (`complete` or `done` — a `blocked` child keeps ownership). The child's
+ * `complete` ticks the box, so a later `mark N` on it is an idempotent no-op.
+ */
+function assertStepNotOwnedBySubtask(stepNumber) {
+  if (stepNumber == null) return;
+  const owner = subtaskOwningStep(taskDir, path.basename(taskPath), stepNumber);
+  if (!owner) return;
+  const open = openSubtaskUnits(taskDir).find((entry) => entry.unit.id === owner.id);
+  if (!open) return;
+  console.error(
+    `step ${stepNumber} is owned by subtask ${owner.id}; finish it with ./mark sub ${owner.id} complete`,
+  );
+  process.exit(1);
+}
+
+/** Every registered child must be settled before the parent reports success. */
+function assertNoOpenSubtasks(command) {
+  const open = openSubtaskUnits(taskDir);
+  if (open.length === 0) return;
+  console.error(openSubtaskRefusal(open, command));
+  process.exit(1);
+}
+
+// `blocked` stays available while a child is open: the run is blocked either way.
+if (terminalCommand === 'complete' || terminalCommand === 'no-change') {
+  assertNoOpenSubtasks(terminalCommand);
+}
 if (
   terminalCommand &&
   (terminalCommand === 'complete' || terminalCommand === 'no-change') &&
@@ -514,14 +538,27 @@ const next = buildSignalUpdate(
   taskPath,
   taskDir,
 );
-atomicWrite(signalPath, `${JSON.stringify(next, null, 2)}\n`, 0o644);
-
-if (isStartCommand) {
-  console.log('signal started');
-} else if (terminalCommand) {
-  console.log(
-    `signal ${terminalCommand}: status=${next.status} disposition=${next.disposition ?? 'n/a'}`,
-  );
+// Re-marking a step that is already done changes nothing: the box was checked
+// and its timing event already exists, so the only difference from the stored
+// signal would be a fresh `timestamp`. Compare content, never the command: that
+// keeps `start` (new attemptId), a terminal mark (new status), a resume from
+// `blocked`, and a box checked by hand without an event all writing as before,
+// while a genuinely empty re-mark stays a no-op.
+const alreadyRecorded = !isStartCommand && !terminalCommand && signalContentUnchanged(signal, next);
+
+if (alreadyRecorded) {
+  console.log(`already marked ${target.stepNumber}: ${target.label}`);
 } else {
-  console.log(`marked ${target.stepNumber}: ${target.label}`);
+  // One signal writer for the parent and child paths, so their bytes and mode
+  // cannot drift (mark-io.cjs writeSignal).
+  writeSignal(signalPath, next);
+  if (isStartCommand) {
+    console.log('signal started');
+  } else if (terminalCommand) {
+    console.log(
+      `signal ${terminalCommand}: status=${next.status} disposition=${next.disposition ?? 'n/a'}`,
+    );
+  } else {
+    console.log(`marked ${target.stepNumber}: ${target.label}`);
+  }
 }

package/scripts/mark-io.cjs

@@ -0,0 +1,118 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { checklistStepName, enumerateChecklistCheckboxes } = require('./checklist-target.cjs');
+
+// One definition of how the mark engine reads and writes task-dir files, shared
+// by the parent mark path and the child-unit (`sub`) verbs so both write the
+// same bytes the same way.
+
+function atomicWrite(file, content, mode) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, content, mode ? { mode } : undefined);
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+/** Signal JSON with a trailing newline and the mode every signal file carries. */
+function writeSignal(signalPath, signal) {
+  atomicWrite(signalPath, `${JSON.stringify(signal, null, 2)}\n`, 0o644);
+}
+
+/** Registry JSON with a trailing newline and the same mode as a signal file. */
+function writeIndex(indexPath, index) {
+  atomicWrite(indexPath, `${JSON.stringify(index, null, 2)}\n`, 0o644);
+}
+
+/**
+ * Stable string for "is this the same signal content?" — key order and object
+ * nesting normalized, so two writers that agree on values but not on insertion
+ * order compare equal.
+ */
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** True when two signals differ only by `timestamp` (or not at all). */
+function signalContentUnchanged(stored, candidate) {
+  const withoutTimestamp = (signal) => {
+    const { timestamp: _timestamp, ...rest } = signal;
+    return canonicalJson(rest);
+  };
+  return withoutTimestamp(stored) === withoutTimestamp(candidate);
+}
+
+const SIGNAL_PASSTHROUGH_KEYS = ['role', 'contextId', 'attemptId', 'prNumber'];
+
+function pickSignalPassthrough(signal) {
+  const out = {};
+  for (const key of SIGNAL_PASSTHROUGH_KEYS) {
+    if (signal[key] !== undefined) out[key] = signal[key];
+  }
+  return out;
+}
+
+// Step enumeration is shared with the gateway parsers (generateTaskSchema in
+// tasks/writer.ts and parseCheckboxStates in methods/task.ts) via the
+// checklist-target enumerator: same skip sections, <details> handling, and
+// checkbox shape. Any divergence makes `mark N` check a different box than
+// the one progress reporting counts as step N (checkbox-formatted Acceptance
+// Criteria used to shift every step by the AC count).
+function parseChecklist(markdown) {
+  const lines = markdown.split(/\n/);
+  const items = enumerateChecklistCheckboxes(markdown).map((item) => ({
+    ...item,
+    label: checklistStepName(item.rawLabel),
+  }));
+  return { lines, items };
+}
+
+function markStepInLines(lines, item) {
+  if (item.checked) return false;
+  const before = lines[item.lineIndex];
+  lines[item.lineIndex] = before.replace(/^(\s*- \[)( |x|X)(\])/, '$1x$3');
+  return lines[item.lineIndex] !== before;
+}
+
+/** Tick one enumerated row in a checklist file. Returns true when the file changed. */
+function markStepInFile(filePath, item) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  const parsed = parseChecklist(original);
+  const lines = [...parsed.lines];
+  markStepInLines(lines, item);
+  const updated = lines.join('\n');
+  if (updated === original) return false;
+  atomicWrite(filePath, updated);
+  return true;
+}
+
+module.exports = {
+  atomicWrite,
+  readJson,
+  writeSignal,
+  writeIndex,
+  canonicalJson,
+  signalContentUnchanged,
+  SIGNAL_PASSTHROUGH_KEYS,
+  pickSignalPassthrough,
+  parseChecklist,
+  markStepInLines,
+  markStepInFile,
+};