atris 3.30.8 → 3.31.0

package/commands/land.js

@@ -0,0 +1,442 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { listWorktrees, statusCounts } = require('./worktree');
+
+const DEFAULT_TTL_DAYS = 7;
+const PROTECTED_BRANCHES = new Set(['main', 'master']);
+
+function runGit(args, { cwd = process.cwd(), check = true } = {}) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (check && result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return result;
+}
+
+function repoRoot(cwd = process.cwd()) {
+  const result = runGit(['rev-parse', '--show-toplevel'], { cwd, check: false });
+  if (result.status !== 0) return '';
+  return result.stdout.trim();
+}
+
+function refExists(root, ref) {
+  return runGit(['rev-parse', '--verify', '--quiet', ref], { cwd: root, check: false }).status === 0;
+}
+
+function baseBranch(root, override = '') {
+  if (override && refExists(root, override)) return override;
+  if (refExists(root, 'master')) return 'master';
+  if (refExists(root, 'main')) return 'main';
+  return '';
+}
+
+function ageDays(unixSeconds, now = Date.now()) {
+  return Math.floor((now / 1000 - Number(unixSeconds)) / 86400);
+}
+
+function listBranches(root) {
+  const result = runGit(
+    ['for-each-ref', 'refs/heads', '--format=%(refname:short)%09%(committerdate:unix)'],
+    { cwd: root, check: false }
+  );
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [name, date] = line.split('\t');
+      return { name, lastCommitUnix: Number(date) };
+    });
+}
+
+function aheadCount(root, base, ref) {
+  const result = runGit(['rev-list', '--count', `${base}..${ref}`], { cwd: root, check: false });
+  if (result.status !== 0) return 0;
+  return Number(result.stdout.trim()) || 0;
+}
+
+// Board: every branch and worktree with unlanded state, classified.
+//   landed — no commits ahead of base; the branch pointer is residue
+//   active — has unlanded commits, younger than TTL
+//   due    — has unlanded commits, older than TTL; --reap collects it
+function collectBoard(root, { ttlDays = DEFAULT_TTL_DAYS, base: baseOverride = '' } = {}) {
+  const base = baseBranch(root, baseOverride);
+  if (!base) throw new Error('no master/main branch found');
+
+  const branches = [];
+  for (const branch of listBranches(root)) {
+    if (PROTECTED_BRANCHES.has(branch.name)) continue;
+    const ahead = aheadCount(root, base, branch.name);
+    const age = ageDays(branch.lastCommitUnix);
+    let state = 'active';
+    if (ahead === 0) state = 'landed';
+    else if (age > ttlDays) state = 'due';
+    branches.push({ name: branch.name, ahead, ageDays: age, state });
+  }
+
+  const worktrees = [];
+  const all = listWorktrees(root);
+  for (const wt of all.slice(1)) {
+    const branch = (wt.branch || '').replace(/^refs\/heads\//, '');
+    const counts = statusCounts(wt.path) || { staged: 0, unstaged: 0, untracked: 0 };
+    const dirty = counts.staged + counts.unstaged + counts.untracked;
+    const entry = branches.find((b) => b.name === branch) || null;
+    worktrees.push({
+      path: wt.path,
+      branch,
+      dirty,
+      ageDays: entry ? entry.ageDays : null,
+      state: entry ? entry.state : 'detached',
+    });
+  }
+
+  const due = branches.filter((b) => b.state === 'due');
+  const landed = branches.filter((b) => b.state === 'landed');
+  const active = branches.filter((b) => b.state === 'active');
+  return {
+    base,
+    ttlDays,
+    branches,
+    worktrees,
+    summary: {
+      unlanded: branches.length,
+      active: active.length,
+      due: due.length,
+      landed: landed.length,
+      worktrees: worktrees.length,
+    },
+  };
+}
+
+// Fast counts for the boot banner: no per-branch ahead checks.
+function landSummary(cwd = process.cwd(), ttlDays = DEFAULT_TTL_DAYS) {
+  const root = repoRoot(cwd);
+  if (!root) return null;
+  let branches = 0;
+  let due = 0;
+  for (const branch of listBranches(root)) {
+    if (PROTECTED_BRANCHES.has(branch.name)) continue;
+    branches += 1;
+    if (ageDays(branch.lastCommitUnix) > ttlDays) due += 1;
+  }
+  return { branches, due, ttlDays };
+}
+
+function salvageDir(root) {
+  const stamp = new Date().toISOString().slice(0, 10);
+  const dir = path.join(root, '.atris', 'salvage', stamp);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function timeStamp() {
+  return new Date().toISOString().slice(11, 19).replace(/:/g, '');
+}
+
+function remoteHeads(root) {
+  const result = runGit(['ls-remote', '--heads', 'origin'], { cwd: root, check: false });
+  if (result.status !== 0) return null;
+  const heads = new Set();
+  for (const line of result.stdout.split(/\r?\n/).filter(Boolean)) {
+    const ref = line.split(/\s+/)[1] || '';
+    if (ref.startsWith('refs/heads/')) heads.add(ref.slice('refs/heads/'.length));
+  }
+  return heads;
+}
+
+// Reap: salvage then delete everything landed (residue) or past TTL.
+// Salvage first, always: unlanded commits go into a git bundle, dirty
+// worktrees into patch files, so a reap is never a loss of work.
+function reap(root, { ttlDays = DEFAULT_TTL_DAYS, base: baseOverride = '', dryRun = false, remote = true } = {}) {
+  const board = collectBoard(root, { ttlDays, base: baseOverride });
+  const targets = board.branches.filter((b) => b.state === 'landed' || b.state === 'due');
+  const targetNames = new Set(targets.map((b) => b.name));
+  const worktreeTargets = board.worktrees.filter(
+    (w) => targetNames.has(w.branch) || w.state === 'detached' || (typeof w.ageDays === 'number' && w.ageDays > ttlDays)
+  );
+  for (const w of worktreeTargets) {
+    if (w.branch && !targetNames.has(w.branch)) targetNames.add(w.branch);
+  }
+
+  const receipt = {
+    base: board.base,
+    ttlDays,
+    dryRun,
+    bundle: null,
+    patches: [],
+    removedWorktrees: [],
+    deletedBranches: [],
+    deletedRemote: [],
+    kept: board.branches.filter((b) => !targetNames.has(b.name)).map((b) => b.name),
+  };
+  if (targetNames.size === 0 && worktreeTargets.length === 0) return receipt;
+  if (dryRun) {
+    receipt.removedWorktrees = worktreeTargets.map((w) => w.path);
+    receipt.deletedBranches = [...targetNames];
+    return receipt;
+  }
+
+  const dir = salvageDir(root);
+  const withCommits = [...targetNames].filter((name) => {
+    const entry = board.branches.find((b) => b.name === name);
+    return entry && entry.ahead > 0;
+  });
+  if (withCommits.length > 0) {
+    const bundlePath = path.join(dir, `reap-${timeStamp()}.bundle`);
+    const result = runGit(['bundle', 'create', bundlePath, ...withCommits, '--not', board.base], {
+      cwd: root,
+      check: false,
+    });
+    if (result.status === 0) receipt.bundle = bundlePath;
+  }
+
+  for (const w of worktreeTargets) {
+    if (w.dirty > 0) {
+      const diff = runGit(['diff'], { cwd: w.path, check: false });
+      if (diff.status === 0 && diff.stdout.trim()) {
+        const patchPath = path.join(dir, `${path.basename(w.path)}.dirty.patch`);
+        fs.writeFileSync(patchPath, diff.stdout);
+        receipt.patches.push(patchPath);
+      }
+    }
+    const removed = runGit(['worktree', 'remove', '--force', w.path], { cwd: root, check: false });
+    if (removed.status === 0) receipt.removedWorktrees.push(w.path);
+  }
+
+  for (const name of targetNames) {
+    const deleted = runGit(['branch', '-D', name], { cwd: root, check: false });
+    if (deleted.status === 0) receipt.deletedBranches.push(name);
+  }
+
+  if (remote && receipt.deletedBranches.length > 0) {
+    const heads = remoteHeads(root);
+    if (heads) {
+      const remoteTargets = receipt.deletedBranches.filter((name) => heads.has(name));
+      for (let i = 0; i < remoteTargets.length; i += 25) {
+        const batch = remoteTargets.slice(i, i + 25);
+        const pushed = runGit(['push', 'origin', '--delete', ...batch], { cwd: root, check: false });
+        if (pushed.status === 0) receipt.deletedRemote.push(...batch);
+      }
+    }
+  }
+
+  return receipt;
+}
+
+// The story of one piece of work: what it tried to do, whether it made it
+// into master some other way, and what would be lost if it were cleared.
+function collectStory(root, name, { base: baseOverride = '' } = {}) {
+  const base = baseBranch(root, baseOverride);
+  if (!base) throw new Error('no master/main branch found');
+  if (!refExists(root, name)) return null;
+
+  const logResult = runGit(
+    ['log', '--format=%h%x09%cs%x09%an%x09%s', `${base}..${name}`],
+    { cwd: root, check: false }
+  );
+  const changes = logResult.stdout
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [hash, date, author, subject] = line.split('\t');
+      return { hash, date, author, subject };
+    });
+
+  // git cherry marks a change '-' when an equivalent patch already exists
+  // in base — the honest "it landed some other way" signal.
+  const cherry = runGit(['cherry', base, name], { cwd: root, check: false });
+  const landedHashes = new Set();
+  for (const line of cherry.stdout.split(/\r?\n/).filter(Boolean)) {
+    if (line.startsWith('- ')) landedHashes.add(line.slice(2).trim());
+  }
+  const fullHashes = runGit(['log', '--format=%H %h', `${base}..${name}`], { cwd: root, check: false });
+  const shortToLanded = new Set();
+  for (const line of fullHashes.stdout.split(/\r?\n/).filter(Boolean)) {
+    const [full, short] = line.split(' ');
+    if (landedHashes.has(full)) shortToLanded.add(short);
+  }
+  for (const c of changes) c.landedElsewhere = shortToLanded.has(c.hash);
+
+  const stat = runGit(['diff', '--stat', `${base}...${name}`], { cwd: root, check: false });
+  const statLines = stat.stdout.split(/\r?\n/).filter(Boolean);
+  const files = statLines.slice(0, -1).map((l) => l.split('|')[0].trim());
+
+  const info = listBranches(root).find((b) => b.name === name);
+  return {
+    name,
+    base,
+    ageDays: info ? ageDays(info.lastCommitUnix) : null,
+    changes,
+    landedElsewhere: changes.filter((c) => c.landedElsewhere).length,
+    uniqueChanges: changes.filter((c) => !c.landedElsewhere).length,
+    files,
+  };
+}
+
+function printStory(story) {
+  console.log('');
+  console.log(`what happened in ${story.name}`);
+  console.log('');
+  if (story.changes.length === 0) {
+    console.log(`  everything here is already in ${story.base}. this is an empty leftover,`);
+    console.log("  safe to clear. nothing would be lost.");
+    console.log('');
+    return;
+  }
+  const who = [...new Set(story.changes.map((c) => c.author))].join(', ');
+  const when = story.changes[story.changes.length - 1].date;
+  const last = story.changes[0].date;
+  const age = story.ageDays === null ? '' : ` (${story.ageDays} days ago)`;
+  console.log(`  started ${when}, last touched ${last}${age}, by ${who}.`);
+  console.log('');
+  console.log('  what it tried to do:');
+  for (const c of [...story.changes].reverse()) {
+    const mark = c.landedElsewhere ? 'made it in   ' : 'never made it';
+    console.log(`    ${mark}  ${c.subject}`);
+  }
+  console.log('');
+  if (story.files.length > 0) {
+    const shown = story.files.slice(0, 6).join(', ');
+    const more = story.files.length > 6 ? ` and ${story.files.length - 6} more` : '';
+    console.log(`  it touched: ${shown}${more}`);
+    console.log('');
+  }
+  if (story.uniqueChanges === 0) {
+    console.log(`  bottom line: all ${story.changes.length} changes made it into ${story.base}`);
+    console.log('  some other way. nothing here would be lost by clearing it.');
+  } else if (story.landedElsewhere > 0) {
+    console.log(`  bottom line: ${story.landedElsewhere} of ${story.changes.length} changes made it into ${story.base} another`);
+    console.log(`  way. ${story.uniqueChanges} exist only here (marked "never made it") — they may have`);
+    console.log('  been redone differently, or they may be real lost work. clearing backs');
+    console.log('  them up first either way.');
+  } else {
+    console.log(`  bottom line: none of this is in ${story.base}. this is real work that only`);
+    console.log('  exists here. land it or clear it knowing the backup keeps a copy.');
+  }
+  console.log('');
+  console.log(`  see the actual changes: git diff ${story.base}...${story.name}`);
+  console.log('');
+}
+
+function printBoard(board) {
+  console.log('');
+  console.log('the landing — what is actually done vs still in the air');
+  console.log('');
+  if (board.branches.length === 0 && board.worktrees.length === 0) {
+    console.log('  everything has landed. nothing in the air, nothing stuck.');
+    console.log('');
+    return;
+  }
+  const order = { due: 0, detached: 0, landed: 1, active: 2 };
+  const rows = [...board.branches].sort((a, b) => (order[a.state] ?? 3) - (order[b.state] ?? 3) || b.ageDays - a.ageDays);
+  const labels = { due: 'overdue', landed: 'landed', active: 'in the air' };
+  for (const b of rows) {
+    const changes = b.ahead === 1 ? '1 change ' : `${b.ahead} changes`;
+    console.log(`  ${(labels[b.state] || b.state).padEnd(11)} ${String(b.ageDays).padStart(3)}d  ${changes}  ${b.name}`);
+  }
+  for (const w of board.worktrees) {
+    const edits = w.dirty === 1 ? '1 unsaved edit' : `${w.dirty} unsaved edits`;
+    console.log(`  side copy   ${w.path} (${edits})`);
+  }
+  console.log('');
+  const s = board.summary;
+  console.log(`  ${s.unlanded} pieces of work in the air, ${s.due} overdue, ${s.landed} landed and safe to clear.`);
+  console.log('  work counts as done only when it lands in master.');
+  if (s.due + s.landed > 0) {
+    console.log(`  back up + clear the ${s.due + s.landed} overdue/landed: atris land --reap`);
+  }
+  console.log('');
+}
+
+function printReceipt(receipt) {
+  console.log('');
+  if (receipt.dryRun) {
+    console.log(`landing cleanup preview — would clear ${receipt.deletedBranches.length} pieces of work, ${receipt.removedWorktrees.length} side copies:`);
+    for (const b of receipt.deletedBranches) console.log(`  would clear  ${b}`);
+    for (const w of receipt.removedWorktrees) console.log(`  would remove ${w}`);
+  } else {
+    console.log(`landing cleanup done — ${receipt.deletedBranches.length} pieces cleared, ${receipt.removedWorktrees.length} side copies removed`);
+    if (receipt.bundle) console.log(`  backed up first, nothing lost: ${receipt.bundle}`);
+    for (const p of receipt.patches) console.log(`  unsaved edits saved: ${p}`);
+    if (receipt.deletedRemote.length > 0) console.log(`  also cleared on github: ${receipt.deletedRemote.length}`);
+  }
+  console.log(`  still flying (recent work, left alone): ${receipt.kept.length}`);
+  console.log('');
+}
+
+function readFlag(args, name, fallback = '') {
+  const idx = args.indexOf(name);
+  if (idx === -1) return fallback;
+  return args[idx + 1] || fallback;
+}
+
+function showHelp() {
+  console.log('');
+  console.log('atris land — the landing: what is actually done vs still in the air');
+  console.log('');
+  console.log('work counts as done only when it lands in master. everything else is');
+  console.log('in the air, and this shows it so nothing quietly dies.');
+  console.log('');
+  console.log('  atris land                     show everything still in the air');
+  console.log('  atris land <name>              the story of one piece: what it tried,');
+  console.log('                                 whether it landed some other way, what');
+  console.log('                                 would be lost by clearing it');
+  console.log('  atris land --reap              back up, then clear anything overdue');
+  console.log('                                 or already landed (here and on github)');
+  console.log('  atris land --reap --dry-run    preview what would be cleared');
+  console.log('  atris land --ttl <days>        change the 7-day overdue line');
+  console.log('  atris land --json              machine-readable output');
+  console.log('');
+  console.log('backups go to .atris/salvage/<date>/ — clearing never loses work.');
+  console.log('');
+}
+
+function landCommand(args = []) {
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showHelp();
+    return 0;
+  }
+  const root = repoRoot();
+  if (!root) {
+    console.error('not a git repository');
+    return 1;
+  }
+  const ttlRaw = readFlag(args, '--ttl', '');
+  const ttlParsed = Number(ttlRaw);
+  const ttlDays = ttlRaw !== '' && Number.isFinite(ttlParsed) && ttlParsed >= 0 ? ttlParsed : DEFAULT_TTL_DAYS;
+  const base = readFlag(args, '--base', '');
+  const json = args.includes('--json');
+
+  if (args.includes('--reap')) {
+    const receipt = reap(root, { ttlDays, base, dryRun: args.includes('--dry-run'), remote: !args.includes('--no-remote') });
+    if (json) console.log(JSON.stringify(receipt, null, 2));
+    else printReceipt(receipt);
+    return 0;
+  }
+
+  const name = args.find((a) => !a.startsWith('-') && a !== readFlag(args, '--ttl') && a !== readFlag(args, '--base'));
+  if (name) {
+    const story = collectStory(root, name, { base });
+    if (!story) {
+      console.error(`nothing called '${name}' is in the air right now`);
+      return 1;
+    }
+    if (json) console.log(JSON.stringify(story, null, 2));
+    else printStory(story);
+    return 0;
+  }
+
+  const board = collectBoard(root, { ttlDays, base });
+  if (json) console.log(JSON.stringify(board, null, 2));
+  else printBoard(board);
+  return 0;
+}
+
+module.exports = {
+  collectBoard,
+  landCommand,
+  landSummary,
+  reap,
+};

package/commands/loop-front.js

@@ -14,6 +14,7 @@
 //   atris loop status             liveness, last tick, reward   -> pulse.js
 //   atris loop stop               remove the durable heartbeat  -> pulse.js
 //   atris loop wiki               wiki upkeep (the old `loop`)  -> loop.js
+//   atris loop create-next        create + claim the suggested task
 //
 // The loop reads ROADMAP.md for what to pursue.
 
@@ -21,6 +22,13 @@ function isFlag(arg) {
   return typeof arg === 'string' && arg.startsWith('-');
 }
 
+function flagValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  return value && !isFlag(value) ? value : true;
+}
+
 // Pure router: decide what `atris loop ...` means without executing anything.
 // Kept side-effect-free so it is trivially testable.
 function routeLoop(argv = []) {
@@ -36,6 +44,10 @@ function routeLoop(argv = []) {
       return { action: 'status' };
     case 'stop':
       return { action: 'stop' };
+    case 'create-next':
+    case 'claim-next':
+    case 'take-next':
+      return { action: 'create-next' };
     case 'wiki':
       // Forward the remaining args (e.g. --json, --limit=) to wiki upkeep.
       return { action: 'wiki', rest: argv.filter((a) => a.toLowerCase() !== 'wiki') };
@@ -57,7 +69,7 @@ function routeLoop(argv = []) {
   }
 }
 
-function renderLoopHome(route = { action: 'home' }) {
+function renderLoopHome(route = { action: 'home' }, moves = []) {
   const lines = [
     '',
     'atris loop: the self-improvement loop',
@@ -73,6 +85,7 @@ function renderLoopHome(route = { action: 'home' }) {
     '    atris loop start              run it now, here (local)',
     '    atris loop start --once       one cycle, then stop',
     '    atris loop start --overnight  install the durable heartbeat (~15m)',
+    '    atris loop start --overnight --hours 6',
     '',
     '  watch it',
     '    atris loop status             liveness, last tick, reward',
@@ -85,6 +98,16 @@ function renderLoopHome(route = { action: 'home' }) {
     '  wiki upkeep is at: atris loop wiki',
     '',
   ];
+  if (Array.isArray(moves) && moves.length) {
+    lines.splice(lines.length - 2, 0, '  ranked next moves');
+    moves.slice(0, 3).forEach((move) => {
+      lines.splice(lines.length - 2, 0, `    [${move.source}] ${move.title}`);
+    });
+    lines.splice(lines.length - 2, 0, '');
+  }
+  lines.splice(lines.length - 2, 0, '  act on it');
+  lines.splice(lines.length - 2, 0, '    atris loop create-next       create + claim the suggested task');
+  lines.splice(lines.length - 2, 0, '');
   if (route && route.unknown) {
     lines.splice(1, 0, `  (unknown: "${route.unknown}". here is the loop:)`);
   }
@@ -95,7 +118,11 @@ function renderLoopHome(route = { action: 'home' }) {
 }
 
 function printLoopHome(route) {
-  console.log(renderLoopHome(route));
+  let moves = [];
+  try {
+    moves = require('../lib/next-moves').nextMoves(process.cwd(), 3);
+  } catch { /* next moves are optional on a fresh checkout */ }
+  console.log(renderLoopHome(route, moves));
 }
 
 // Parse the handful of local-run flags `atris loop start` forwards to run.js.
@@ -148,7 +175,7 @@ function printLocalRunSummary() {
 // Combined machine-readable status: the overnight pulse heartbeat and the local
 // runs in one object. Best-effort per engine so a missing one does not fail it.
 function loopStatusJson(root = process.cwd()) {
-  const out = { ok: true, action: 'loop_status', pulse: null, local_runs: { count: 0, latest: null } };
+  const out = { ok: true, action: 'loop_status', pulse: null, local_runs: { count: 0, latest: null }, next_moves: [] };
   try {
     const lp = require('../lib/pulse');
     const { cronInstalled } = require('./pulse');
@@ -158,9 +185,88 @@ function loopStatusJson(root = process.cwd()) {
   try {
     out.local_runs = localRunSummary(require('./run').getRunLogDir());
   } catch { /* runs optional */ }
+  try {
+    out.next_moves = require('../lib/next-moves').nextMoves(root, 5);
+  } catch { /* next moves optional */ }
   return out;
 }
 
+function loopSeedMove(root = process.cwd()) {
+  const moves = require('../lib/next-moves').nextMoves(root, 5);
+  const activeTask = moves.find((move) => move && move.source === 'task');
+  if (activeTask) return { ok: false, reason: 'active_task', move: activeTask, moves };
+  const seed = moves.find((move) => (
+    move
+    && move.source === 'mission'
+    && (
+      move.why === 'active mission has no concrete task queued'
+      || move.why === 'latest proof timeline suggested this self-improvement target'
+    )
+  ));
+  if (!seed) return { ok: false, reason: 'no_seed', moves };
+  return { ok: true, move: seed, moves };
+}
+
+function createNextLoopTask(argv = [], root = process.cwd(), options = {}) {
+  const shouldPrint = options.print !== false;
+  const json = argv.includes('--json');
+  const owner = flagValue(argv, '--as') || flagValue(argv, '--owner') || process.env.ATRIS_AGENT_ID || 'auto-improver';
+  const seed = loopSeedMove(root);
+  if (!seed.ok) {
+    const payload = { ok: false, action: 'create_next_skipped', reason: seed.reason, move: seed.move || null };
+    if (shouldPrint) {
+      if (json) console.log(JSON.stringify(payload, null, 2));
+      else if (seed.reason === 'active_task') console.log(`not created: active task already exists (${seed.move.ref || seed.move.title})`);
+      else console.log('not created: no loop seed is available');
+    }
+    return payload;
+  }
+
+  const note = `Goal: ${seed.move.title}. Files: inspect atris/MAP.md first, then the relevant code. Done: one bounded proof-backed self-improvement task is moved to Review. Check: focused verifier; git diff --check; atris clean --dry-run --json; atris brain compile --root . --verify.`;
+  const taskArgs = [
+    'task',
+    'delegate',
+    seed.move.title,
+    '--tag', 'loop',
+    '--claim',
+    '--as', String(owner),
+    '--note', note,
+    '--json',
+  ];
+  const { spawnSync } = require('child_process');
+  const path = require('path');
+  const cli = path.join(__dirname, '..', 'bin', 'atris.js');
+  const child = spawnSync(process.execPath, [cli, ...taskArgs], {
+    cwd: root,
+    encoding: 'utf8',
+    timeout: 20000,
+    env: { ...process.env, ATRIS_SKIP_UPDATE_CHECK: '1' },
+  });
+  if (child.status !== 0) {
+    const payload = { ok: false, action: 'create_next_failed', reason: 'task_delegate_failed', stderr: child.stderr, stdout: child.stdout };
+    if (shouldPrint) {
+      if (json) console.log(JSON.stringify(payload, null, 2));
+      else console.error(child.stderr || child.stdout || 'task creation failed');
+    }
+    return payload;
+  }
+  let delegated = null;
+  try { delegated = JSON.parse(child.stdout); } catch { delegated = null; }
+  const task = delegated && delegated.task ? delegated.task : null;
+  const payload = { ok: true, action: 'created_next', owner: String(owner), move: seed.move, task, delegated };
+  if (shouldPrint) {
+    if (json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      const ref = task?.display_id || task?.id || 'task';
+      console.log(`created next loop task: ${ref} ${seed.move.title}`);
+      console.log(`claimed by: ${owner}`);
+      console.log(`next: atris task show ${ref}`);
+    }
+  }
+  return payload;
+}
+
 // The evidence that the loop is improving things: ROADMAP items it has handled,
 // what is in flight and queued, and the heartbeat's reward/verify trend. Pure of
 // console so it is testable.
@@ -170,7 +276,7 @@ function loopReport(root = process.cwd()) {
   try {
     roadmap = require('../lib/next-moves').roadmapItemsByState(root);
   } catch { /* roadmap optional */ }
-  return { ok: true, action: 'loop_report', roadmap, pulse: status.pulse, local_runs: status.local_runs };
+  return { ok: true, action: 'loop_report', roadmap, next_moves: status.next_moves, pulse: status.pulse, local_runs: status.local_runs };
 }
 
 function renderLoopReport(rep) {
@@ -193,6 +299,11 @@ function renderLoopReport(rep) {
     lines.push('  next up:');
     r.open.slice(0, 4).forEach((t) => lines.push(`    [ ] ${t}`));
   }
+  if (Array.isArray(rep.next_moves) && rep.next_moves.length) {
+    lines.push('');
+    lines.push('  ranked next:');
+    rep.next_moves.slice(0, 5).forEach((move) => lines.push(`    [${move.source}] ${move.title}`));
+  }
   if (rep.pulse) {
     lines.push('');
     lines.push(`  heartbeat: ${rep.pulse.total_ticks} ticks, reward ${rep.pulse.reward_sum}, verify ${rep.pulse.verify_pass}/${rep.pulse.verify_fail}`);
@@ -236,6 +347,11 @@ function loopFront(argv = []) {
       return Promise.resolve(0);
     }
 
+    case 'create-next': {
+      const result = createNextLoopTask(argv, process.cwd());
+      return Promise.resolve(result.ok ? 0 : 1);
+    }
+
     case 'status': {
       if (jsonFlag.length) {
         // One machine-readable object covering BOTH engines (overnight pulse
@@ -284,6 +400,8 @@ module.exports = {
   startLocalOptions,
   localRunSummary,
   loopStatusJson,
+  loopSeedMove,
+  createNextLoopTask,
   loopReport,
   renderLoopReport,
   loopFront,