atris 3.37.1 → 3.40.0

package/commands/land.js

@@ -1,7 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
-
+const { runGit } = require('../lib/git-spawn');
 const { listWorktrees, statusCounts } = require('./worktree');
 
 const DEFAULT_TTL_DAYS = 7;
@@ -9,12 +8,9 @@ const DEFAULT_STALE_HOURS = 48;
 const WORKTREE_REAP_GRACE_MS = 60 * 60 * 1000;
 const PROTECTED_BRANCHES = new Set(['main', 'master']);
 
-function runGit(args, { cwd = process.cwd(), check = true, maxBuffer } = {}) {
-  const result = spawnSync('git', args, { cwd, encoding: 'utf8', ...(maxBuffer ? { maxBuffer } : {}) });
-  if (check && result.status !== 0) {
-    throw new Error(`git ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}`);
-  }
-  return result;
+// Pluralize a count + noun ("1 change", "2 changes").
+function countLabel(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
 }
 
 function repoRoot(cwd = process.cwd()) {
@@ -89,6 +85,14 @@ function aheadCount(root, base, ref) {
   return Number(result.stdout.trim()) || 0;
 }
 
+// The subject lines of the commits a ref carries beyond base, oldest last —
+// what a stranded worktree is actually holding, so surfacing it names the work.
+function commitSubjects(cwd, base, ref, limit = 6) {
+  const result = runGit(['log', '--format=%s', `${base}..${ref}`], { cwd, check: false });
+  if (result.status !== 0) return [];
+  return result.stdout.split(/\r?\n/).filter(Boolean).slice(0, limit);
+}
+
 function cherryStats(root, base, ref) {
   const result = runGit(['cherry', base, ref], { cwd: root, check: false });
   if (result.status !== 0) return { landedElsewhere: 0, unique: 0 };
@@ -144,11 +148,36 @@ function collectBoard(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_S
     const counts = (light ? null : 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;
+    // Committed-but-unlanded work is invisible in the dirty count — a clean
+    // worktree can still hold commits ahead of base that silently never land.
+    // Carry the ahead/unique counts (and, off the light path, the subjects)
+    // so a stranded worktree is surfaced by what it is actually holding.
+    let ahead = entry ? entry.ahead : 0;
+    let unlandedCommits = entry ? entry.uniqueChanges : 0;
+    let ageDaysVal = entry ? entry.ageDays : null;
+    let subjects = [];
+    if (!branch) {
+      // Detached HEAD has no row in the branch table — ask the worktree itself.
+      const cnt = runGit(['rev-list', '--count', `${base}..HEAD`], { cwd: wt.path, check: false });
+      ahead = cnt.status === 0 ? Number(cnt.stdout.trim()) || 0 : 0;
+      if (ahead > 0) {
+        unlandedCommits = cherryStats(wt.path, base, 'HEAD').unique;
+        const ts = runGit(['log', '-1', '--format=%ct', 'HEAD'], { cwd: wt.path, check: false });
+        if (ts.status === 0) ageDaysVal = ageDays(Number(ts.stdout.trim()), now);
+        if (!light) subjects = commitSubjects(wt.path, base, 'HEAD');
+      }
+    } else if (!light && ahead > 0) {
+      subjects = commitSubjects(root, base, branch);
+    }
     worktrees.push({
       path: wt.path,
       branch,
       dirty,
-      ageDays: entry ? entry.ageDays : null,
+      ahead,
+      unlandedCommits,
+      subjects,
+      stranded: unlandedCommits > 0,
+      ageDays: ageDaysVal,
       ageHours: entry ? entry.ageHours : null,
       state: entry ? entry.state : 'detached',
     });
@@ -174,12 +203,14 @@ function collectBoard(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_S
   const landed = branches.filter((b) => b.state === 'landed');
   const active = branches.filter((b) => b.state === 'active');
   const stale = active.filter((b) => b.stale);
+  const strandedWorktrees = worktrees.filter((w) => w.stranded);
   return {
     base,
     ttlDays,
     staleHours,
     branches,
     worktrees,
+    strandedWorktrees,
     summary: {
       unlanded: branches.length,
       active: active.length,
@@ -187,6 +218,7 @@ function collectBoard(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_S
       landed: landed.length,
       stale: stale.length,
       worktrees: worktrees.length,
+      stranded: strandedWorktrees.length,
     },
   };
 }
@@ -269,12 +301,12 @@ function salvageWorktree(w, dir, receipt) {
 // includeDetached: detached-HEAD worktrees have no branch, so the salvage
 // bundle cannot cover their commits — unattended reaps (autoland) pass false
 // and leave them for a human reap.
-function reap(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_STALE_HOURS, base: baseOverride = '', dryRun = false, remote = true, includeDetached = true, protectCurrent = true, now = Date.now() } = {}) {
+function reap(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_STALE_HOURS, base: baseOverride = '', dryRun = false, remote = true, includeDetached = true, protectCurrent = true, force = false, now = Date.now() } = {}) {
   const board = collectBoard(root, { ttlDays, staleHours, base: baseOverride, now });
   const targets = board.branches.filter((b) => b.state === 'landed' || b.state === 'due');
   const targetNames = new Set(targets.map((b) => b.name));
   const candidateWorktrees = board.worktrees.filter(
-    (w) => targetNames.has(w.branch) || (includeDetached && w.state === 'detached') || (typeof w.ageDays === 'number' && w.ageDays > ttlDays)
+    (w) => targetNames.has(w.branch) || (includeDetached && w.state === 'detached') || (typeof w.ageDays === 'number' && w.ageDays > ttlDays) || w.unlandedCommits > 0
   );
   const protectedWorktrees = [];
   const worktreeTargets = [];
@@ -293,6 +325,18 @@ function reap(root, { ttlDays = DEFAULT_TTL_DAYS, staleHours = DEFAULT_STALE_HOU
       protectedWorktrees.push({ ...w, reason: 'fresh_worktree_grace' });
       continue;
     }
+    // Unlanded commits that no branch salvage bundle will cover are lost by a
+    // force-remove: a detached worktree's commits ride no branch, and an active
+    // branch worktree is not a reap target so its commits are never bundled.
+    // Keep the worktree (and name what it holds) unless the operator forces it.
+    // A due/landed branch worktree still reaps normally — its commits ride the
+    // branch bundle, so removal is loss-free.
+    const bundleCovered = w.branch && targetNames.has(w.branch);
+    if (w.unlandedCommits > 0 && !force && !bundleCovered) {
+      const oldest = typeof w.ageDays === 'number' ? `, oldest ${w.ageDays}d` : '';
+      protectedWorktrees.push({ ...w, reason: `unlanded commits: ${w.unlandedCommits} never landed${oldest}, needs landing` });
+      continue;
+    }
     worktreeTargets.push(w);
   }
   for (const w of protectedWorktrees) {
@@ -472,7 +516,7 @@ function printStory(story) {
   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)`;
+  const age = story.ageDays === null ? '' : ` (${countLabel(story.ageDays, 'day')} ago)`;
   console.log(`  started ${when}, last touched ${last}${age}, by ${who}.`);
   console.log('');
   console.log('  what it tried to do:');
@@ -488,7 +532,7 @@ function printStory(story) {
     console.log('');
   }
   if (story.uniqueChanges === 0) {
-    console.log(`  bottom line: all ${story.changes.length} changes made it into ${story.base}`);
+    console.log(`  bottom line: all ${countLabel(story.changes.length, 'change')} 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`);
@@ -522,8 +566,15 @@ function printBoard(board) {
     console.log(`  ${label.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})`);
+    const bits = [];
+    if (w.stranded) bits.push(w.unlandedCommits === 1 ? '1 commit never landed' : `${w.unlandedCommits} commits never landed`);
+    if (w.dirty > 0) bits.push(w.dirty === 1 ? '1 unsaved edit' : `${w.dirty} unsaved edits`);
+    const age = typeof w.ageDays === 'number' ? `, ${countLabel(w.ageDays, 'day')} old` : '';
+    const detail = bits.length ? ` (${bits.join(', ')}${age})` : '';
+    console.log(`  side copy   ${w.path}${detail}`);
+    if (w.stranded) {
+      for (const s of w.subjects) console.log(`                - ${s}`);
+    }
   }
   console.log('');
   const s = board.summary;
@@ -554,7 +605,9 @@ function printReceipt(receipt) {
     // fresh-grace keeps are healthy active work, not a call to action —
     // "needs a human" on those trained readers to ignore the real ones.
     for (const k of receipt.keptWorktrees || []) {
+      // The receipt keeps the raw codes; the human line speaks in sentences.
       if (String(k).includes('(fresh_worktree_grace)')) console.log(`  in use, left alone: ${k.replace(' (fresh_worktree_grace)', '')}`);
+      else if (String(k).includes('(current_checkout)')) console.log(`  you are standing in it, left alone: ${k.replace(' (current_checkout)', '')}`);
       else console.log(`  ✋ kept, needs a human: ${k}`);
     }
     for (const m of receipt.keptMovedBranches || []) console.log(`  moved since scan, left alone: ${m}`);
@@ -564,7 +617,8 @@ function printReceipt(receipt) {
   console.log('');
 }
 
-function readFlag(args, name, fallback = '') {
+// Preserve split-only parsing and its fallback for missing or falsey values.
+function readFollowingFlag(args, name, fallback = '') {
   const idx = args.indexOf(name);
   if (idx === -1) return fallback;
   return args[idx + 1] || fallback;
@@ -586,6 +640,8 @@ function showHelp() {
   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 --reap --force      also clear side copies holding');
+  console.log('                                 commits that never landed (backs up first)');
   console.log('  atris land --ttl <days>        change the 7-day overdue line');
   console.log('  atris land --json              machine-readable output');
   console.log('');
@@ -603,21 +659,21 @@ function landCommand(args = []) {
     console.error('not a git repository');
     return 1;
   }
-  const ttlRaw = readFlag(args, '--ttl', '');
+  const ttlRaw = readFollowingFlag(args, '--ttl', '');
   const ttlParsed = Number(ttlRaw);
   const ttlDays = ttlRaw !== '' && Number.isFinite(ttlParsed) && ttlParsed >= 0 ? ttlParsed : DEFAULT_TTL_DAYS;
-  const base = readFlag(args, '--base', '');
+  const base = readFollowingFlag(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') });
+    const receipt = reap(root, { ttlDays, base, dryRun: args.includes('--dry-run'), remote: !args.includes('--no-remote'), force: args.includes('--force') });
     if (json) console.log(JSON.stringify(receipt, null, 2));
     else printReceipt(receipt);
     return 0;
   }
 
   const lookupArgs = args[0] === 'status' ? args.slice(1) : args;
-  const name = lookupArgs.find((a) => !a.startsWith('-') && a !== readFlag(lookupArgs, '--ttl') && a !== readFlag(lookupArgs, '--base'));
+  const name = lookupArgs.find((a) => !a.startsWith('-') && a !== readFollowingFlag(lookupArgs, '--ttl') && a !== readFollowingFlag(lookupArgs, '--base'));
   if (name) {
     const story = collectStory(root, name, { base });
     if (!story) {
@@ -637,6 +693,7 @@ function landCommand(args = []) {
 
 module.exports = {
   collectBoard,
+  countLabel,
   landCommand,
   landSummary,
   reap,

package/commands/launchpad.js

@@ -2,23 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const { hasFlag, readFlag } = require('../lib/arg-parser');
 
 const ACTIVE_MISSION_STATUSES = new Set(['planning', 'running', 'ready']);
 
-function hasFlag(args, name) {
-  return args.includes(name);
-}
-
-function readFlag(args, name, fallback = '') {
-  const prefix = `${name}=`;
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = String(args[i]);
-    if (arg === name && args[i + 1] && !String(args[i + 1]).startsWith('--')) return String(args[i + 1]);
-    if (arg.startsWith(prefix)) return arg.slice(prefix.length);
-  }
-  return fallback;
-}
-
 function readJson(file) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -632,7 +619,5 @@ function launchpadCommand(args = []) {
 }
 
 module.exports = {
-  collectLaunchpad,
   launchpadCommand,
-  renderLaunchpad,
 };

package/commands/lesson.js

@@ -213,7 +213,23 @@ function mineLessons(args) {
   }
 }
 
+function printLessonUsage() {
+  console.log('');
+  console.log('  Usage: atris lesson add <slug> <pass|fail> "<text>"');
+  console.log('         atris lesson mine [--json] [--dry-run]');
+  console.log('         atris lesson sweep [--json] [--dry-run]');
+  console.log('         atris lesson resolve [--json] [--dry-run]');
+  console.log('');
+}
+
 function lessonAtris(subcommand, ...args) {
+  // -h/--help is an explicit help request: print usage and exit 0, before any
+  // filesystem check, so `atris lesson --help` works everywhere.
+  if (subcommand === '-h' || subcommand === '--help') {
+    printLessonUsage();
+    process.exit(0);
+  }
+
   const atrisDir = path.join(process.cwd(), 'atris');
   if (!fs.existsSync(atrisDir)) {
     console.error('  ✗ atris/ folder not found. Run "atris init" first.');
@@ -236,12 +252,7 @@ function lessonAtris(subcommand, ...args) {
   }
 
   if (subcommand !== 'add') {
-    console.log('');
-    console.log('  Usage: atris lesson add <slug> <pass|fail> "<text>"');
-    console.log('         atris lesson mine [--json] [--dry-run]');
-    console.log('         atris lesson sweep [--json] [--dry-run]');
-    console.log('         atris lesson resolve [--json] [--dry-run]');
-    console.log('');
+    printLessonUsage();
     process.exit(subcommand ? 1 : 0);
   }
 
@@ -269,4 +280,3 @@ function lessonAtris(subcommand, ...args) {
 
 module.exports = lessonAtris;
 module.exports.autoResolveLessons = autoResolveLessons;
-module.exports.tagLessonResolvedInMd = tagLessonResolvedInMd;

package/commands/lifecycle.js

@@ -168,7 +168,7 @@ async function sleepAtris() {
 }
 
 /**
- * Wake a sleeping workspace so agents resume automatically.
+ * Wake a sleeping workspace: remote wake request, or local wake flag.
  * @returns {Promise<void>}
  */
 async function wakeAtris() {
@@ -179,7 +179,7 @@ async function wakeAtris() {
   if (!slug || slug === '--help' || slug === '-h' || slug === 'help') {
     console.log('Usage: atris wake [business|member] [--loop <loop-id>]');
     console.log('');
-    console.log('  Wake a sleeping workspace. Agents resume automatically.');
+    console.log('  Wake a sleeping workspace. Wake signal sent; loops pick it up on their next pass.');
     console.log('  Or flip a local member / member-loop switch awake.');
     process.exit(0);
   }
@@ -207,13 +207,13 @@ async function wakeAtris() {
     console.log(`Waking business computer '${business.name || slug}'...`);
 
     if (result.data && result.data.status === 'running' && result.data.endpoint) {
-      console.log(`Business computer '${business.name || slug}' is alive. Agents resuming.`);
+      console.log(`Business computer '${business.name || slug}' is alive. Wake signal sent; loops pick it up on their next pass.`);
       return;
     }
 
     const running = await waitForBusinessComputer(creds.token, business);
     if (running) {
-      console.log(`Business computer '${business.name || slug}' is alive. Agents resuming.`);
+      console.log(`Business computer '${business.name || slug}' is alive. Wake signal sent; loops pick it up on their next pass.`);
       return;
     }
 
@@ -246,7 +246,7 @@ async function wakeAtris() {
     });
 
     if (status.ok && status.data && status.data.status === 'running') {
-      console.log(`Workspace '${slug}' is alive. Agents resuming.`);
+      console.log(`Workspace '${slug}' is alive. Wake signal sent; loops pick it up on their next pass.`);
       return;
     }
   }

package/commands/log.js

@@ -97,6 +97,56 @@ function readDigestSection(root, title, relativePath, maxLines = null) {
   };
 }
 
+// Splits a journal body into its ## groups so the digest can show
+// completed / inbox / notes as short labeled blocks instead of a raw dump.
+function journalGroups(lines) {
+  const groups = [];
+  let current = null;
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      current = { heading: heading[1], lines: [] };
+      groups.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  return groups;
+}
+
+function bulletCount(group) {
+  return group.lines.filter((line) => /^\s*-\s+/.test(line)).length;
+}
+
+function digestSummaryLine(date, sections) {
+  let completed = 0;
+  let inbox = 0;
+  for (const section of sections) {
+    for (const group of journalGroups(section.lines)) {
+      if (/^completed/i.test(group.heading)) completed += bulletCount(group);
+      else if (/^inbox/i.test(group.heading)) inbox += bulletCount(group);
+    }
+  }
+  const parts = [`${sections.length} log${sections.length === 1 ? '' : 's'}`];
+  if (completed) parts.push(`${completed} completed`);
+  if (inbox) parts.push(`${inbox} inbox`);
+  return `${date}: ${parts.join(', ')}`;
+}
+
+function renderDigestSection(section) {
+  const groups = journalGroups(section.lines);
+  if (!groups.length) {
+    return [`=== ${section.title} ===`, section.path, ...section.lines].join('\n');
+  }
+  const out = [`=== ${section.title} ===`, section.path];
+  for (const group of groups) {
+    const body = group.lines.filter((line) => line.trim() && line.trim() !== '---');
+    if (!body.length) continue;
+    out.push('', `${group.heading.toLowerCase()} (${bulletCount(group)})`, ...body);
+  }
+  return out.join('\n');
+}
+
 function logsDigest(args = [], options = {}) {
   const root = options.cwd || process.cwd();
   const date = digestDate(args);
@@ -125,11 +175,11 @@ function logsDigest(args = [], options = {}) {
   } else if (sections.length === 0) {
     console.log(`No logs for ${date} yet.`);
   } else {
-    console.log(sections.map((section) => [
-      `=== ${section.title} ===`,
-      section.path,
-      ...section.lines,
-    ].join('\n')).join('\n\n'));
+    console.log([
+      digestSummaryLine(date, sections),
+      '',
+      ...sections.map(renderDigestSection),
+    ].join('\n'));
   }
 
   return payload;

package/commands/loop-front.js

@@ -396,11 +396,9 @@ function loopFront(argv = []) {
 module.exports = {
   routeLoop,
   renderLoopHome,
-  printLoopHome,
   startLocalOptions,
   localRunSummary,
   loopStatusJson,
-  loopSeedMove,
   createNextLoopTask,
   loopReport,
   renderLoopReport,

package/commands/loops.js

@@ -382,6 +382,12 @@ function showLoopsHelp() {
 }
 
 function loopsCommand(subcommand, ...args) {
+  // `loops <sub> --help` is a help request, not a run — tick/start/stop/init
+  // mutate loop state, so never execute a subcommand just to show usage.
+  if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help'
+      || args.includes('--help') || args.includes('-h')) {
+    return showLoopsHelp();
+  }
   switch (subcommand) {
     case undefined:
     case 'audit':
@@ -408,9 +414,4 @@ function loopsCommand(subcommand, ...args) {
 
 module.exports = {
   loopsCommand,
-  showBoard,
-  initLoops,
-  auditLoops,
-  tickLoops,
-  structuralProblems,
 };

package/commands/meet.js

@@ -215,6 +215,4 @@ async function meetCommand(args = [], root = process.cwd()) {
 module.exports = {
   meetCommand,
   slugify,
-  buildBookingProfile,
-  renderProfile,
 };