@farmslot/agent-runtime 0.8.1 → 0.10.0

package/scripts/cursor-session-discovery.cjs

@@ -0,0 +1,48 @@
+// Read-only recovery for older terminal launches that did not persist their chat ID.
+const fs = require('node:fs');
+const path = require('node:path');
+const input = JSON.parse(process.argv.at(-1));
+const root = input.root.replace(/^~(?=\/|$)/, process.env.HOME);
+const matches = [];
+if (
+  !path.isAbsolute(input.cwd) ||
+  !Number.isFinite(input.startedAt) ||
+  !Number.isFinite(input.completedAt) ||
+  input.completedAt < input.startedAt
+)
+  throw Error('Invalid session discovery bounds');
+function directories(parent) {
+  try {
+    return fs
+      .readdirSync(parent, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(parent, entry.name));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+for (const workspace of directories(root))
+  for (const chat of directories(workspace)) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(path.basename(chat))) continue;
+    let meta;
+    try {
+      meta = JSON.parse(fs.readFileSync(path.join(chat, 'meta.json'), 'utf8'));
+    } catch (error) {
+      // Concurrently created or truncated metadata is not evidence of a recoverable chat.
+      if (error.code === 'ENOENT' || error instanceof SyntaxError) continue;
+      throw error;
+    }
+    if (
+      meta.schemaVersion === 1 &&
+      meta.hasConversation === true &&
+      meta.cwd === input.cwd &&
+      Number.isFinite(meta.createdAtMs) &&
+      meta.createdAtMs >= input.startedAt &&
+      meta.createdAtMs <= input.completedAt
+    )
+      matches.push({ sessionId: path.basename(chat) });
+  }
+if (matches.length > 1)
+  throw Error('Several chats match the review workspace; session recovery is ambiguous');
+process.stdout.write(JSON.stringify(matches[0] ?? null));

package/scripts/execution-template-cli.mjs

@@ -17,10 +17,12 @@ function usage(exitCode = 0) {
     'list   --dir <path> --domain-dir <domain=path> --project-worker <path> --package-templates <path>',
     '       [--project-name name] [--package-id id] [--flow f] [--run-mode m]',
     '       [--platform p] [--domain d] [--no-include-shadowed] [--json]',
-    'materialize <output> --flow f --run-mode m --platform p [--domain d] [--id id]',
+    'materialize <output> --flow f --platform p [--run-mode m] [--domain d] [--id id]',
     '       [the same source options as list] [--provenance path] [--json]',
     'lint   <file-or-dir> [--json]',
-    'new    <path> [--flow f] [--run-mode m] [--platform p] [--title t] [--force] [--json]',
+    'new    <path> [--flow f] [--platform p] [--title t] [--force] [--json]',
+    '',
+    '--run-mode is the run mode used to match project default rules; templates have none.',
   ].join('\n');
   (exitCode === 0 ? console.log : console.error)(text);
   process.exit(exitCode);
@@ -32,7 +34,7 @@ function takeValue(args, i, flag) {
   return value;
 }
 
-async function loadRuntime() {
+export async function loadRuntime() {
   if (!existsSync(distEntry)) {
     throw new Error(
       `compiled package missing at ${distEntry}; run yarn workspace @farmslot/agent-runtime build`,
@@ -58,7 +60,7 @@ function parseDomainDir(value) {
   return { domain, root: value.slice(separator + 1) };
 }
 
-function parseCatalogArgs(args, { materialize = false } = {}) {
+export function parseCatalogArgs(args, { materialize = false } = {}) {
   const opts = {
     dirs: [],
     domainDirs: [],
@@ -101,7 +103,7 @@ function parseCatalogArgs(args, { materialize = false } = {}) {
   return opts;
 }
 
-function buildSources(opts, runtime) {
+export function buildSources(opts, runtime) {
   const sources = [];
   const domainSourceIds = new Set();
   for (const [index, dir] of opts.dirs.entries()) {
@@ -174,18 +176,17 @@ async function cmdList(args, runtime) {
   if (opts.id) throw new Error('--id is only valid with materialize');
   const sources = buildSources(opts, runtime);
   const templates =
-    opts.flow && opts.platform && opts.runMode
+    opts.flow && opts.platform
       ? runtime.listCompatibleExecutionTemplates({
           sources,
           flow: opts.flow,
           platform: opts.platform,
-          runMode: opts.runMode,
+          ...(opts.runMode ? { runMode: opts.runMode } : {}),
           ...(opts.domain ? { domain: opts.domain } : {}),
         })
       : runtime.listExecutionTemplates({
           sources,
           flow: opts.flow,
-          runMode: opts.runMode,
           platform: opts.platform,
           domain: opts.domain,
           includeShadowed: opts.includeShadowed,
@@ -203,7 +204,7 @@ async function cmdList(args, runtime) {
   for (const entry of catalog) {
     const shadow = entry.shadowedBy ? ` (shadowed by ${entry.shadowedBy})` : '';
     process.stdout.write(
-      `${entry.id}\t${entry.flow}\t${entry.runMode ?? '-'}\t${entry.platforms.join(',')}\t${entry.sourceId}${shadow}\n`,
+      `${entry.id}\t${entry.flow}\t${entry.platforms.join(',')}\t${entry.sourceId}${shadow}\n`,
     );
   }
 }
@@ -212,7 +213,6 @@ async function cmdMaterialize(args, runtime) {
   const opts = parseCatalogArgs(args, { materialize: true });
   if (!opts.output) throw new Error('materialize requires <output>');
   if (!opts.flow) throw new Error('materialize requires --flow');
-  if (!opts.runMode) throw new Error('materialize requires --run-mode');
   if (!opts.platform) throw new Error('materialize requires --platform');
   const output = resolve(opts.output);
   if (existsSync(output)) {
@@ -227,7 +227,7 @@ async function cmdMaterialize(args, runtime) {
     sources: buildSources(opts, runtime),
     flow: opts.flow,
     platform: opts.platform,
-    runMode: opts.runMode,
+    ...(opts.runMode ? { runMode: opts.runMode } : {}),
     ...(opts.domain ? { domain: opts.domain } : {}),
     ...(opts.id ? { explicitId: opts.id } : {}),
   });
@@ -282,7 +282,6 @@ async function cmdNew(args, runtime) {
   let pathArg = null;
   const opts = {
     flow: undefined,
-    runMode: undefined,
     platforms: undefined,
     title: undefined,
     force: false,
@@ -291,7 +290,6 @@ async function cmdNew(args, runtime) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--flow') opts.flow = takeValue(args, i++, arg);
-    else if (arg === '--run-mode') opts.runMode = parseRunMode(takeValue(args, i++, arg));
     else if (arg === '--platform') {
       opts.platforms = takeValue(args, i++, arg)
         .split(',')
@@ -308,7 +306,6 @@ async function cmdNew(args, runtime) {
   const created = runtime.createExecutionTemplate({
     path: pathArg,
     flow: opts.flow,
-    runMode: opts.runMode,
     platforms: opts.platforms,
     title: opts.title,
     force: opts.force,
@@ -328,7 +325,9 @@ async function main() {
   else usage(2);
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/mark-checklist-step.cjs

@@ -44,7 +44,7 @@ function printHelp() {
     [
       usageLine,
       '',
-      'Task-dir mode: farmslot-agent mark <task-dir> <step> — requires checklist-target.json written by the gateway at task creation or role switch.',
+      'Task-dir mode: farmslot-agent mark <task-dir> <step> — marks CHECKLIST.md (or TASK.md) unless checklist-target.json, written by a role switch, points elsewhere.',
       '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.',

package/scripts/review-filesystem.cjs

@@ -0,0 +1,39 @@
+const { accessSync, constants } = require('node:fs');
+const { mkdir, realpath } = require('node:fs/promises');
+const { join } = require('node:path');
+
+function available() {
+  if (process.platform !== 'darwin') return false;
+  try {
+    accessSync('/usr/bin/sandbox-exec', constants.X_OK);
+    return true;
+  } catch (error) {
+    if (['ENOENT', 'EACCES'].includes(error.code)) return false;
+    throw error;
+  }
+}
+async function sandbox(policy, runtimeRoots) {
+  if (!available())
+    throw new Error('This runner needs the macOS review sandbox on its execution node');
+  const temporaryDirectory = join(policy.writableRoots[0], '.review-runtime', 'tmp');
+  await mkdir(temporaryDirectory, { recursive: true, mode: 0o700 });
+  const writable = await Promise.all(policy.writableRoots.map((root) => realpath(root)));
+  const readOnly = await Promise.all(policy.readOnlyRoots.map((root) => realpath(root)));
+  for (const root of runtimeRoots) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    writable.push(await realpath(root));
+  }
+  const profile = [
+    '(version 1)',
+    '(allow default)',
+    '(deny file-write*)',
+    ...writable.map((root) => `(allow file-write* (subpath ${JSON.stringify(root)}))`),
+    '(allow file-write* (literal "/dev/null") (literal "/dev/tty"))',
+    ...readOnly.map((root) => `(deny file-write* (subpath ${JSON.stringify(root)}))`),
+  ].join('\n');
+  return {
+    sandbox: { executable: '/usr/bin/sandbox-exec', args: ['-p', profile] },
+    temporaryDirectory,
+  };
+}
+module.exports = { available, sandbox };

package/scripts/review-session.cjs

@@ -0,0 +1,45 @@
+// Persist a runner-owned chat identity before launching a managed review terminal.
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+const input = JSON.parse(process.argv[2]);
+const file = path.join(input.task, '.runner-session.json');
+const identity = { runId: input.runId, workspaceId: input.workspaceId, runner: input.runner };
+if (!path.isAbsolute(input.task) || !path.isAbsolute(input.cwd))
+  throw Error('Invalid session workspace');
+if (fs.existsSync(file)) {
+  const saved = JSON.parse(fs.readFileSync(file, 'utf8'));
+  for (const key of Object.keys(identity))
+    if (saved[key] !== identity[key]) throw Error('Runner session identity changed');
+  if (input.resumeSessionId && saved.sessionId !== input.resumeSessionId)
+    throw Error('Retained session changed');
+  process.stdout.write(JSON.stringify(saved));
+} else {
+  let sessionId = input.resumeSessionId;
+  if (!sessionId) {
+    const env = { ...process.env, ...input.environment.set };
+    for (const key of [
+      ...input.environment.unset,
+      'FARMSLOT_NODE_TOKEN',
+      'FARMSLOT_GATEWAY_TOKEN',
+      'FARMSLOT_GATEWAY_PASSWORD',
+      'CLAUDECODE',
+    ])
+      delete env[key];
+    const result = cp.spawnSync(input.argv[0], input.argv.slice(1), {
+      cwd: input.cwd,
+      env,
+      encoding: 'utf8',
+      timeout: 20000,
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw Error(result.stderr || 'Could not reserve runner session');
+    sessionId = result.stdout.trim();
+  }
+  // create-chat documents a UUID result. Never infer identity from terminal text.
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(sessionId))
+    throw Error('Runner returned an invalid chat ID');
+  const saved = { ...identity, sessionId };
+  fs.writeFileSync(file, JSON.stringify(saved), { flag: 'wx', mode: 0o600 });
+  process.stdout.write(JSON.stringify(saved));
+}

package/scripts/review-terminal.cjs

@@ -0,0 +1,134 @@
+// Runner-neutral terminal lifecycle. Inputs come from the owning gateway, never PR content.
+const fs = require('node:fs'),
+  path = require('node:path'),
+  cp = require('node:child_process');
+const { sandbox } = require('./review-filesystem.cjs');
+const input = JSON.parse(process.argv[2]);
+const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
+const tmux = (args) => cp.spawnSync('tmux', args, { encoding: 'utf8' });
+const check = (result) => {
+  if (result.status !== 0)
+    throw Error(result.stderr || result.error?.message || 'Terminal operation failed');
+  return result.stdout.trim();
+};
+const target = input.session;
+async function main() {
+  if (
+    !/^[a-zA-Z0-9_-]+$/.test(input.session) ||
+    !path.isAbsolute(input.task) ||
+    !path.isAbsolute(input.cwd)
+  )
+    throw Error('Invalid review terminal identity');
+  const marker = path.join(input.task, '.terminal-launch.json');
+  const cancelled = path.join(input.task, '.terminal-cancelled');
+  const existing = fs.existsSync(marker) ? JSON.parse(fs.readFileSync(marker, 'utf8')) : undefined;
+  if (
+    existing &&
+    (existing.runId !== input.runId ||
+      existing.workspaceId !== input.workspaceId ||
+      existing.session !== input.session)
+  )
+    throw Error('Review terminal identity changed');
+  const has = tmux(['has-session', '-t', '=' + target]);
+  if (![0, 1].includes(has.status)) check(has);
+  if (
+    has.status === 0 &&
+    check(tmux(['show-option', '-v', '-t', target, '@farmslot-review-workspace'])) !==
+      input.workspaceId
+  )
+    throw Error('Review terminal belongs to another workspace');
+  if (input.action === 'stop') {
+    fs.writeFileSync(cancelled, input.runId, { mode: 0o600 });
+    if (has.status === 0) check(tmux(['kill-session', '-t', target]));
+    process.stdout.write(JSON.stringify({ stopped: true }));
+    return;
+  }
+  if (input.action === 'inspect') {
+    process.stdout.write(JSON.stringify({ exists: has.status === 0, launch: existing }));
+    return;
+  }
+  if (fs.existsSync(cancelled)) throw new Error('Review terminal launch was cancelled');
+  if (existing) {
+    if (has.status !== 0) throw Error('Review terminal exited; explicit retry required');
+    process.stdout.write(JSON.stringify(existing));
+    return;
+  }
+  if (has.status === 0) throw Error('Review terminal exists without a launch record');
+  const cwd = fs.realpathSync(input.cwd),
+    task = fs.realpathSync(input.task);
+  const gitRoot = check(
+    cp.spawnSync('git', ['-C', cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf8',
+    }),
+  );
+  const policy = {
+    readOnlyRoots: [
+      cwd,
+      fs.realpathSync(gitRoot),
+      ...(input.support ? [fs.realpathSync(input.support)] : []),
+    ],
+    writableRoots: [task],
+  };
+  const runtimeRoots = input.runtimeRoots.map((root) =>
+    root.replace(/^~(?=\/|$)/, process.env.HOME),
+  );
+  const guard = await sandbox(policy, runtimeRoots);
+  const promptFile = path.join(task, '.terminal-prompt.txt');
+  fs.writeFileSync(promptFile, input.prompt, { mode: 0o600 });
+  if (input.setup) check(cp.spawnSync('/bin/sh', ['-c', input.setup], { cwd, encoding: 'utf8' }));
+  const environment = {
+    ...process.env,
+    ...input.environment.set,
+    TMPDIR: guard.temporaryDirectory,
+    DISABLE_OMX: '1',
+    DISABLE_OMC: '1',
+  };
+  for (const key of [
+    ...input.environment.unset,
+    'CLAUDECODE',
+    'FARMSLOT_NODE_TOKEN',
+    'FARMSLOT_GATEWAY_TOKEN',
+    'FARMSLOT_GATEWAY_PASSWORD',
+  ])
+    delete environment[key];
+  const commandFile = path.join(task, '.terminal-start.cjs');
+  const record = {
+    runId: input.runId,
+    workspaceId: input.workspaceId,
+    session: input.session,
+    startedAt: new Date().toISOString(),
+  };
+  const launch = `const cp=require('node:child_process');const env={...process.env};for(const key of ['FARMSLOT_NODE_TOKEN','FARMSLOT_GATEWAY_TOKEN','FARMSLOT_GATEWAY_PASSWORD','CLAUDECODE'])delete env[key];const r=cp.spawnSync(${JSON.stringify(guard.sandbox.executable)},${JSON.stringify([...guard.sandbox.args, '/bin/sh', '-c', input.command])},{cwd:${JSON.stringify(cwd)},env,stdio:'inherit'});process.exit(r.status??1);`;
+  fs.writeFileSync(commandFile, launch, { mode: 0o600 });
+  const envArgs = Object.entries(environment)
+    .filter(([, value]) => typeof value === 'string')
+    .flatMap(([name, value]) => ['-e', name + '=' + value]);
+  fs.writeFileSync(marker, JSON.stringify(record), { mode: 0o600, flag: 'wx' });
+  check(
+    tmux([
+      'new-session',
+      '-d',
+      ...envArgs,
+      '-s',
+      input.session,
+      '-c',
+      cwd,
+      `${quote(process.execPath)} ${quote(commandFile)}`,
+      ';',
+      'set-option',
+      '-t',
+      target,
+      '@farmslot-review-workspace',
+      input.workspaceId,
+    ]),
+  );
+  if (fs.existsSync(cancelled)) {
+    check(tmux(['kill-session', '-t', target]));
+    throw new Error('Review terminal launch was cancelled');
+  }
+  process.stdout.write(JSON.stringify(record));
+}
+main().catch((error) => {
+  process.stderr.write(String(error));
+  process.exitCode = 1;
+});

package/scripts/task-init-cli.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * `farmslot-agent task init`: write a task directory from a selected execution
+ * template. Thin wrappers (mm-harness) add their own defaults and forward here.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { buildSources, loadRuntime, parseCatalogArgs } from './execution-template-cli.mjs';
+
+function usage(exitCode = 0) {
+  const text = [
+    'Usage: task init <task-dir> --flow f --platform p --template id --title t [options]',
+    '',
+    '  Template sources: --dir <path> --domain-dir <domain=path> --project-worker <path>',
+    '                    --package-templates <path> [--package-id id] [--project-name name] [--domain d]',
+    '  Run:              [--run-mode m] — run mode used to match project default rules',
+    '  Task:             --title t [--task-text s | --task-file path] [--ticket key] [--source-ref url]',
+    '  Identity:         [--surface s] [--project name] [--repo owner/name] [--attempt-id id]',
+    '  Rendering:        [--var KEY=VALUE]... [--task-dir-label label] [--mode-preamble text]',
+    '                    [--addendum-file path] [--mark-command "cmd"] [--json]',
+    '',
+    'Writes TASK.md, CHECKLIST.md, mark, inputs/handoff.json, inputs/worker-terminal-contract.json.',
+  ].join('\n');
+  (exitCode === 0 ? console.log : console.error)(text);
+  process.exit(exitCode);
+}
+
+function takeValue(args, i, flag) {
+  const value = args[i + 1];
+  if (value === undefined) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseArgs(args) {
+  const opts = {
+    taskDir: null,
+    template: null,
+    title: null,
+    taskText: null,
+    taskFile: null,
+    ticket: null,
+    sourceRef: null,
+    surface: 'cli',
+    project: null,
+    repo: null,
+    attemptId: null,
+    vars: {},
+    taskDirLabel: null,
+    modePreamble: null,
+    addendumFile: null,
+    markCommand: null,
+    json: false,
+  };
+  const catalogArgs = [];
+  // The task dir is the first positional, before any flag, as the usage line says.
+  if (args[0] && !args[0].startsWith('-')) opts.taskDir = args.shift();
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--template') opts.template = takeValue(args, i++, arg);
+    else if (arg === '--title') opts.title = takeValue(args, i++, arg);
+    else if (arg === '--task-text') opts.taskText = takeValue(args, i++, arg);
+    else if (arg === '--task-file') opts.taskFile = takeValue(args, i++, arg);
+    else if (arg === '--ticket') opts.ticket = takeValue(args, i++, arg);
+    else if (arg === '--source-ref') opts.sourceRef = takeValue(args, i++, arg);
+    else if (arg === '--surface') opts.surface = takeValue(args, i++, arg);
+    else if (arg === '--project') opts.project = takeValue(args, i++, arg);
+    else if (arg === '--repo') opts.repo = takeValue(args, i++, arg);
+    else if (arg === '--attempt-id') opts.attemptId = takeValue(args, i++, arg);
+    else if (arg === '--task-dir-label') opts.taskDirLabel = takeValue(args, i++, arg);
+    else if (arg === '--mode-preamble') opts.modePreamble = takeValue(args, i++, arg);
+    else if (arg === '--addendum-file') opts.addendumFile = takeValue(args, i++, arg);
+    else if (arg === '--mark-command') opts.markCommand = takeValue(args, i++, arg);
+    else if (arg === '--var') {
+      const pair = takeValue(args, i++, arg);
+      const eq = pair.indexOf('=');
+      if (eq <= 0) throw new Error('--var must use KEY=VALUE');
+      opts.vars[pair.slice(0, eq)] = pair.slice(eq + 1);
+    } else if (arg === '--json') {
+      opts.json = true;
+      catalogArgs.push(arg);
+    } else if (arg === '-h' || arg === '--help') usage(0);
+    else catalogArgs.push(arg);
+  }
+  if (!opts.taskDir) throw new Error('task init requires <task-dir>');
+  if (!opts.template) throw new Error('task init requires --template <id>');
+  if (!opts.title) throw new Error('task init requires --title');
+  const catalog = parseCatalogArgs([...catalogArgs, '--id', opts.template]);
+  if (!catalog.flow) throw new Error('task init requires --flow');
+  if (!catalog.platform) throw new Error('task init requires --platform');
+  return { opts, catalog };
+}
+
+function gitOutput(args) {
+  try {
+    return execFileSync('git', args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Not a git checkout, or no remote: identity falls back to the directory name.
+    return '';
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '-h' || args[0] === '--help') usage(0);
+  const { opts, catalog } = parseArgs(args);
+  const runtime = await loadRuntime();
+
+  const description = opts.taskFile
+    ? readFileSync(path.resolve(opts.taskFile), 'utf8').trim()
+    : (opts.taskText ?? '').trim();
+  const toplevel = gitOutput(['rev-parse', '--show-toplevel']);
+  const originUrl = gitOutput(['remote', 'get-url', 'origin']);
+  const repo = opts.repo ?? (originUrl ? runtime.portableRepoIdentity(originUrl) : undefined);
+  const project =
+    opts.project ??
+    (repo ? repo.split('/').pop() : path.basename(toplevel || process.cwd())).toLowerCase();
+  // Rendered inside taskInit with the same vars as the checklist, so an addendum
+  // that works on the farm works here.
+  const addendum = opts.addendumFile ? readFileSync(path.resolve(opts.addendumFile), 'utf8') : null;
+
+  const result = await runtime.taskInit({
+    taskDir: path.resolve(opts.taskDir),
+    taskDirLabel: opts.taskDirLabel ?? opts.taskDir,
+    flow: catalog.flow,
+    ...(catalog.runMode ? { runMode: catalog.runMode } : {}),
+    platform: catalog.platform,
+    ...(catalog.domain ? { domain: catalog.domain } : {}),
+    template: { sources: buildSources(catalog, runtime), explicitId: opts.template },
+    task: {
+      title: opts.title,
+      description,
+      sourceKind: opts.taskFile ? 'file' : 'text',
+      ...(opts.ticket ? { ticket: opts.ticket } : {}),
+      ...(opts.sourceRef ? { sourceRef: opts.sourceRef } : {}),
+    },
+    handoff: {
+      surface: opts.surface,
+      project,
+      ...(repo ? { repo } : {}),
+      ...(opts.attemptId ? { attemptId: opts.attemptId } : {}),
+    },
+    vars: opts.vars,
+    ...(opts.modePreamble ? { modePreamble: opts.modePreamble } : {}),
+    addendum,
+    ...(opts.markCommand ? { markCommand: opts.markCommand } : {}),
+  });
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`Task document: ${result.taskDocument}\nChecklist: ${result.checklist}\n`);
+  }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/worker-terminal-contract.cjs

@@ -286,8 +286,11 @@ function templateBodyScope(content) {
 /**
  * Deterministic structure checks beyond terminal artifact contract.
  * @param {string} templateContent
+ * @param {{ roleChecklist?: boolean }} [options] roleChecklist: a nested-loop role
+ *   checklist (self-review, self-review-fix, ci-fix) rendered beside an existing
+ *   task dir; it may keep its own `## Task` block.
  */
-function lintWorkerTemplateStructure(templateContent) {
+function lintWorkerTemplateStructure(templateContent, options = {}) {
   /** @type {string[]} */
   const issues = [];
   if (/(?<!\{)\{TASK_DIR\}(?!\})/.test(templateContent)) {
@@ -302,8 +305,17 @@ function lintWorkerTemplateStructure(templateContent) {
     issues.push('terminal template missing `## Checklist` or `## Completion signal` section');
   }
 
-  if (!templateContent.includes('## Task') && !templateContent.includes('TASK_DIR:')) {
-    issues.push('missing `## Task` block or `TASK_DIR:` metadata');
+  // The task writer generates TASK.md (ticket block, description, acceptance
+  // criteria) and renders the flow template into CHECKLIST.md. A flow template
+  // that still carries the old `## Task` header duplicates that block inside
+  // the checklist.
+  if (
+    !options.roleChecklist &&
+    (/^## Task\s*$/m.test(templateContent) || /^TASK_DIR:\s/m.test(templateContent))
+  ) {
+    issues.push(
+      'carries a `## Task` block or `TASK_DIR:` line — the task writer generates TASK.md; keep only the checklist',
+    );
   }
 
   const scope = templateBodyScope(templateContent);