atris 3.82.15 → 3.82.17

package/commands/ninety-nine.js

@@ -6,8 +6,20 @@ const { randomUUID } = require('node:crypto');
 const { argsWantHelp } = require('../lib/noninteractive');
 const { getAtrisDir, loadCredentials } = require('../utils/auth');
 const { stateHome } = require('../lib/state-home');
-const { validateSync, checkpointKey, syncLines } = require('../lib/ninety-nine-sync');
+const tty = require('node:tty');
+const { apiRequestJson } = require('../utils/api');
+const { validateSync, checkpointKey, syncLines, syncBlocks, blockAccountKey } = require('../lib/ninety-nine-sync');
 const {
+  OUTCOMES,
+  INTENTION_MAX,
+  BLOCK_NOTE_MAX,
+  oneLine,
+  localDate,
+  withOutcome,
+  answerRecord,
+  unansweredBlocks,
+  blocksToday,
+  blocksLine,
   validLength,
   parseSessionLog,
   foldSessions,
@@ -24,16 +36,16 @@ const {
 
 function usage() {
   return [
-    'usage: atris 99 focus <25|50|90>',
+    'usage: atris 99 focus <25|50|90> ["what you will get done"]',
     '       atris 99 meditate <10|20|30>',
     '       atris 99                         show the timer and today',
-    '       atris 99 <25|50|90>              start focus',
+    '       atris 99 <25|50|90> [intention]  start focus',
     '       atris 99 <10|20|30>              start meditation',
     '       atris 99 f <25|50|90>',
     '       atris 99 m <10|20|30>',
     '       atris 99 start <focus|meditate> <minutes>',
     '       atris 99 again                   repeat the last finished session',
-    '       atris 99 stop [note words]',
+    '       atris 99 stop [--outcome yes|partly|no] [--note text] [note words]',
     '       atris 99 pause',
     '       atris 99 resume',
     '       atris 99 status [--json]',
@@ -41,6 +53,10 @@ function usage() {
     '       atris 99 sync [--dry-run]',
     '       atris 99 help | --help',
     '',
+    'a focus block that runs its full time asks "Did you get it done? (yes/partly/no)" in a terminal;',
+    '--outcome and --note answer it without asking. Scripts are never asked.',
+    'with sync on, each finished focus block also goes to your Project 99 day, so every face shows one count.',
+    '',
     'sync is off without a sync block in ~/.atris/99/config.json (ATRIS_99_CONFIG overrides it).',
     'personal: {"sync":{"target":"personal","app_slug":"project-99"}}',
     'workspace: {"sync":{"target":"workspace","business":"your-business","workspace":"optional-id"}}',
@@ -67,7 +83,7 @@ function saveSyncState(file, state) {
   }
 }
 
-async function syncNinetyNine(args, { log, logPath, configPath, statePath, request, credentials = loadCredentials }) {
+async function syncNinetyNine(args, { log, logPath, configPath, statePath, request, credentials = loadCredentials, now = () => new Date() }) {
   if (args.length > 1 || (args.length === 1 && args[0] !== '--dry-run')) {
     log('usage: atris 99 sync [--dry-run]');
     return 2;
@@ -107,6 +123,9 @@ async function syncNinetyNine(args, { log, logPath, configPath, statePath, reque
     }
     const key = checkpointKey(config.sync, creds);
     const checkpoint = state.targets[key] || {};
+    if (state.blocks !== undefined && (!state.blocks || typeof state.blocks !== 'object' || Array.isArray(state.blocks))) {
+      throw new Error('check the 99 sync-state json');
+    }
     if ((checkpoint.known !== undefined && (!Array.isArray(checkpoint.known) || !checkpoint.known.every((item) => typeof item === 'string')))
       || (checkpoint.since != null && !Number.isFinite(Date.parse(checkpoint.since)))) {
       throw new Error('check the 99 sync-state json');
@@ -128,7 +147,7 @@ async function syncNinetyNine(args, { log, logPath, configPath, statePath, reque
       saveSyncState(stateFile, state);
       log(`sent ${result.send.length} lines and pulled ${result.pull.length} lines (${config.sync.target})`);
     }
-    return 0;
+    return await sendBlocks({ records: [...records, ...result.pull], state, stateFile, creds, dryRun, request, now, log });
   } catch (error) {
     const message = error.code === 'EEXIST' ? 'session sync is busy; try again'
       : error.code ? 'check the sync file paths and permissions' : error.message;
@@ -144,6 +163,38 @@ async function syncNinetyNine(args, { log, logPath, configPath, statePath, reque
   }
 }
 
+async function sendBlocks({ records, state, stateFile, creds, dryRun, request, now, log }) {
+  const key = blockAccountKey(creds);
+  const sent = state.blocks?.[key];
+  let result;
+  try {
+    result = await syncBlocks({
+      records, credentials: creds, dryRun, request, now: now(),
+      sent: sent && typeof sent === 'object' && !Array.isArray(sent) ? sent : {},
+    });
+  } catch (error) {
+    log(`could not send focus blocks: ${String(error.message).replace(/\s+/g, ' ')}`);
+    return 1;
+  }
+  const count = result.send.length;
+  const blocks = `${count} focus block${count === 1 ? '' : 's'}`;
+  if (dryRun) {
+    if (count) log(`would send ${blocks}`);
+    for (const block of result.send) log(`block: ${JSON.stringify(block)}`);
+    return 0;
+  }
+  if (result.locked) {
+    log('focus blocks stay on this computer: deep work needs Project 99 Plus');
+    return 0;
+  }
+  state.blocks = { ...(state.blocks || {}), [key]: result.sent };
+  saveSyncState(stateFile, state);
+  if (result.refused) log(`the 99 server refused some focus blocks (${result.refused}); they will not be sent again`);
+  else if (count) log(`sent ${blocks}`);
+  if (result.line) log(`Deep work today: ${result.line}`);
+  return 0;
+}
+
 function readLog(logPath) {
   try { return fs.readFileSync(logPath, 'utf8'); } catch (error) {
     if (error.code === 'ENOENT') return '';
@@ -163,6 +214,122 @@ function todayLine(result) {
   return `Today: ${result.counts.focus} focus, ${result.counts.meditate} meditate, ${result.finished_minutes} min`;
 }
 
+function parseOutcome(text) {
+  const answer = String(text ?? '').trim().toLowerCase();
+  if (['y', 'yes'].includes(answer)) return 'yes';
+  if (['p', 'partly', 'partial'].includes(answer)) return 'partly';
+  if (['n', 'no'].includes(answer)) return 'no';
+  return answer ? undefined : null;
+}
+
+// One line from the terminal, read without a stream so the command stays synchronous.
+function askTerminal(question) {
+  process.stdout.write(question);
+  const bytes = [];
+  const one = Buffer.alloc(1);
+  for (;;) {
+    let read;
+    try { read = fs.readSync(0, one, 0, 1, null); } catch (error) {
+      if (error.code === 'EAGAIN') {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50); // stdin not ready yet
+        continue;
+      }
+      return '';
+    }
+    if (read === 0 || one[0] === 10) break;
+    bytes.push(one[0]);
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
+// "Did you get it done?" until a clear answer, at most twice. Empty skips it: null.
+function askOutcome(ask, lead) {
+  for (let tries = 0; tries < 2; tries++) {
+    const answer = parseOutcome(ask(`${lead}Did you get it done? (yes/partly/no) `));
+    if (answer !== undefined) return answer;
+  }
+  return null;
+}
+
+// The sessions as the command finds them: who is running, what stop would end, and
+// the ends to write for timers that finished or pauses that ran out.
+function observe(records, time, action) {
+  const sessions = foldSessions(records);
+  const active = runningSession(sessions, time);
+  const stopTarget = action === 'stop'
+    ? active || sessions.findLast((session) => automaticEndRecord(session, time)?.status === 'done')
+    : null;
+  const ends = sessions.filter((session) => session !== stopTarget)
+    .map((session) => automaticEndRecord(session, time)).filter(Boolean);
+  return { sessions, active, stopTarget, ends };
+}
+
+function lead(session) {
+  return `Focus ${session.planned_min} ended${session.intention ? ` (${session.intention})` : ''}. `;
+}
+
+// The questions this command would ask, asked now: block id -> yes, partly, no or null.
+// A log that cannot be read asks nothing; the locked read reports it.
+function askFirst(text, time, action, stopping, ask) {
+  const answers = new Map();
+  let records;
+  let seen;
+  try {
+    records = parseSessionLog(text);
+    seen = observe(records, time, action);
+  } catch {
+    return answers;
+  }
+  records.push(...seen.ends);
+  const unanswered = unansweredBlocks(records, time);
+  if (action === 'stop') {
+    if (stopping.outcome !== undefined) return answers;
+    const target = seen.stopTarget;
+    if (target) {
+      if (target.kind === 'focus' && endRecord(target, time).status === 'done') answers.set(target.id, askOutcome(ask, ''));
+    } else if (unanswered.length) {
+      const last = unanswered.at(-1);
+      answers.set(last.id, askOutcome(ask, lead(last)));
+    }
+    return answers;
+  }
+  for (const session of unanswered) answers.set(session.id, askOutcome(ask, lead(session)));
+  return answers;
+}
+
+async function fetchSuggestion(time, { request = apiRequestJson, credentials = loadCredentials } = {}) {
+  try {
+    const creds = credentials();
+    if (!creds?.token) return '';
+    const query = new URLSearchParams({ day: localDate(time), tz_offset_minutes: String(-time.getTimezoneOffset()) });
+    const response = await request(`/99/focus/suggestion?${query}`, {
+      method: 'GET', token: creds.token, timeoutMs: 6000, retries: 0,
+    });
+    const line = response?.ok && typeof response.data?.suggestion === 'string' ? response.data.suggestion : '';
+    return oneLine(line, 120);
+  } catch {
+    return '';
+  }
+}
+
+function stopArgs(words) {
+  const out = { note: [], outcome: undefined, flagNote: undefined };
+  for (let index = 0; index < words.length; index++) {
+    const word = words[index];
+    const [flag, inline] = word.startsWith('--') ? [word.split('=')[0], word.includes('=') ? word.slice(word.indexOf('=') + 1) : undefined] : [];
+    if (flag === '--outcome' || flag === '--note') {
+      const value = inline !== undefined ? inline : words[++index];
+      if (value === undefined) return { error: true };
+      if (flag === '--outcome') {
+        if (!OUTCOMES.includes(value)) return { error: true };
+        out.outcome = value;
+      } else out.flagNote = value;
+    } else out.note.push(word);
+  }
+  const note = out.flagNote !== undefined ? [out.flagNote, ...out.note].join(' ') : out.note.join(' ');
+  return { outcome: out.outcome, note: oneLine(note, BLOCK_NOTE_MAX) };
+}
+
 function kindName(kind) {
   return kind === 'focus' ? 'Focus' : 'Meditate';
 }
@@ -172,6 +339,11 @@ function timeLeft(session, time) {
   return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
 }
 
+function runningLine(active, time) {
+  return `${kindName(active.kind)} · ${timeLeft(active, time)} left${active.status === 'paused' ? ' · paused' : ''}`
+    + (active.intention ? ` · ${active.intention}` : '');
+}
+
 function localEndTime(end) {
   return end.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', hour12: true });
 }
@@ -184,6 +356,9 @@ function ninetyNineAtris(args = process.argv.slice(3), {
   statePath,
   request,
   credentials,
+  interactive = tty.isatty(0),
+  ask = askTerminal,
+  suggestion = (time) => fetchSuggestion(time, { request, credentials }),
 } = {}) {
   let [action, ...rest] = args;
   const overview = args.length === 0;
@@ -192,7 +367,7 @@ function ninetyNineAtris(args = process.argv.slice(3), {
     log(usage());
     return 0;
   }
-  if (action === 'sync') return syncNinetyNine(rest, { log, logPath, configPath, statePath, request, credentials });
+  if (action === 'sync') return syncNinetyNine(rest, { log, logPath, configPath, statePath, request, credentials, now });
   if (action === 'start' && ['focus', 'meditate', 'f', 'm'].includes(rest[0])) [action, ...rest] = rest;
   if (action === 'f') action = 'focus';
   if (action === 'm') action = 'meditate';
@@ -204,16 +379,29 @@ function ninetyNineAtris(args = process.argv.slice(3), {
     }
   }
   const json = rest.includes('--json');
+  let intention = '';
+  let stopping;
   if (action === 'focus' || action === 'meditate') {
     const lengths = action === 'focus' ? '25 | 50 | 90' : '10 | 20 | 30';
     if (rest.length === 0) {
       log(`Pick a length: atris 99 ${action} ${lengths}`);
       return 1;
     }
-    if (rest.length !== 1 || !validLength(action, Number(rest[0])) || String(Number(rest[0])) !== rest[0]) {
+    // Focus takes what the block is for after its length; meditation takes nothing more.
+    const words = rest.slice(1);
+    if ((action === 'focus' ? words.some((word) => word.startsWith('--')) : words.length)
+      || !validLength(action, Number(rest[0])) || String(Number(rest[0])) !== rest[0]) {
       log(`Allowed ${action} lengths: ${lengths.replaceAll(' | ', ', ')} minutes.`);
       return 1;
     }
+    intention = oneLine(words.join(' '), INTENTION_MAX);
+    rest = [rest[0]];
+  } else if (action === 'stop') {
+    stopping = stopArgs(rest);
+    if (stopping.error) {
+      log('usage: atris 99 stop [--outcome yes|partly|no] [--note text] [note words]');
+      return 2;
+    }
   } else if (action === 'status' || action === 'today') {
     if (rest.length > 1 || (rest.length === 1 && !json)) {
       log(`usage: atris 99 ${action} [--json]`);
@@ -232,12 +420,16 @@ function ninetyNineAtris(args = process.argv.slice(3), {
   let lock;
   let lockPath;
   try {
+    const time = now();
     const override = logPath || process.env.ATRIS_99_LOG;
     const file = override || path.join(getAtrisDir(), '99', 'sessions.jsonl');
     const dir = path.dirname(file);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     // An override may live in a shared folder. Only tighten our own folder.
     if (!override) fs.chmodSync(dir, 0o700);
+    // Ask a person at a terminal before taking the lock, so an open question never
+    // makes another command or the Mac app wait. Scripts and json readers are never asked.
+    const answers = interactive && !json ? askFirst(readLog(file), time, action, stopping, ask) : new Map();
     lockPath = `${file}.lock`;
     try { lock = fs.openSync(lockPath, 'wx', 0o600); } catch (error) {
       if (error.code === 'EEXIST') throw new Error('session log is busy; try again');
@@ -245,27 +437,41 @@ function ninetyNineAtris(args = process.argv.slice(3), {
     }
     let text = readLog(file);
     const records = parseSessionLog(text);
-    let sessions = foldSessions(records);
-    const time = now();
-    let active = runningSession(sessions, time);
-    const stopTarget = action === 'stop'
-      ? active || sessions.findLast((session) => automaticEndRecord(session, time)?.status === 'done')
-      : null;
+    const seen = observe(records, time, action);
+    let sessions = seen.sessions;
+    let active = seen.active;
+    const stopTarget = seen.stopTarget;
+    for (const end of seen.ends) {
+      text = appendRecord(file, text, end);
+      records.push(end);
+    }
 
-    for (const session of sessions) {
-      const end = automaticEndRecord(session, time);
-      if (end && session !== stopTarget) {
-        text = appendRecord(file, text, end);
-        records.push(end);
+    const answer = (session, outcome) => {
+      const record = answerRecord(session, time, outcome);
+      text = appendRecord(file, text, record);
+      records.push(record);
+    };
+    if (action !== 'stop') {
+      for (const session of unansweredBlocks(records, time)) {
+        if (answers.has(session.id)) answer(session, answers.get(session.id));
       }
     }
 
     if (action === 'stop') {
       if (!stopTarget) {
+        // Nothing running: --outcome, or the question, answers the last block that ended on its own.
+        const last = unansweredBlocks(records, time).at(-1);
+        const outcome = last && (stopping.outcome ?? answers.get(last.id));
+        if (last && outcome !== undefined) {
+          answer(last, outcome);
+          log(`Focus ${last.planned_min}: ${outcome || 'skipped'}.`);
+          return 0;
+        }
         log('Nothing running. Start one: atris 99 50');
         return 1;
       }
-      const end = endRecord(stopTarget, time, rest.join(' '));
+      const end = endRecord(stopTarget, time, stopping.note);
+      withOutcome(end, stopTarget, stopping.outcome ?? answers.get(stopTarget.id));
       appendRecord(file, text, end);
       records.push(end);
       log(end.status === 'done'
@@ -289,7 +495,7 @@ function ninetyNineAtris(args = process.argv.slice(3), {
     }
     if (overview) {
       if (!active) log('Nothing running.');
-      else log(`${kindName(active.kind)} · ${timeLeft(active, time)} left${active.status === 'paused' ? ' · paused' : ''}`);
+      else log(runningLine(active, time));
       log(todayLine(sessionsToday(sessions, time)));
       log('Start: atris 99 50   Again: atris 99 again   Help: atris 99 help');
     } else if (action === 'focus' || action === 'meditate') {
@@ -297,9 +503,20 @@ function ninetyNineAtris(args = process.argv.slice(3), {
         log('a session is already running; use atris 99 stop first');
         return 1;
       }
-      appendRecord(file, text, startRecord(action, Number(rest[0]), time, randomUUID()));
+      appendRecord(file, text, startRecord(action, Number(rest[0]), time, randomUUID(), intention));
       const end = new Date(time.getTime() + Number(rest[0]) * 60000);
       log(`${kindName(action)} ${rest[0]} started. Ends at ${localEndTime(end)}.`);
+      if (action === 'focus' && !intention && suggestion) {
+        // The timer has started; the hint never delays it and a failure prints nothing.
+        const hint = suggestion(time);
+        const show = (line) => {
+          const text = oneLine(line, 120);
+          if (text) log(`Suggestion: ${text}`);
+          return 0;
+        };
+        if (hint && typeof hint.then === 'function') return hint.then(show, () => 0);
+        show(hint);
+      }
     } else if (action === 'pause' || action === 'resume') {
       if (!active) {
         log('Nothing running. Start one: atris 99 50');
@@ -324,13 +541,19 @@ function ninetyNineAtris(args = process.argv.slice(3), {
       const result = sessionStatus(active, time);
       if (json) log(JSON.stringify(result));
       else if (!active) log('nothing running');
-      else log(`${kindName(active.kind)} · ${timeLeft(active, time)} left${active.status === 'paused' ? ' · paused' : ''}`);
+      else log(runningLine(active, time));
     } else {
       const result = sessionsToday(sessions, time);
       const health = healthToday(records, time);
       if (health) result.health_day = health;
+      const blocks = blocksToday(sessions, time);
+      result.deep_work = { block_count: blocks.count, block_minutes: blocks.minutes };
       if (json) log(JSON.stringify(result));
-      else log(todayLine(result));
+      else {
+        log(todayLine(result));
+        const line = blocksLine(blocks);
+        if (line) log(`Deep work: ${line}`);
+      }
     }
     return 0;
   } catch (error) {

package/commands/usage.js

@@ -41,6 +41,8 @@ function renderUsage(data = {}) {
   return lines.join('\n');
 }
 
+const USAGE_NEEDS_KEY = 'usage is counted per developer key, not per sign-in. make one with atris api-key create, then run ATRIS_API_KEY=<key> atris usage';
+
 async function usageCommand(args = [], deps = {}) {
   if (wantsHelp(args)) {
     showUsageHelp();
@@ -51,14 +53,21 @@ async function usageCommand(args = [], deps = {}) {
   const io = { log: deps.log || console.log, err: deps.err || console.error };
   const load = deps.loadCredentials || loadCredentials;
   const request = deps.apiRequestJson || apiRequestJson;
+  const devKeyEarly = String(((deps.env || process.env).ATRIS_API_KEY) || '').trim();
   const token = tokenFrom(load());
-  if (!token) {
+  if (!token && !devKeyEarly) {
     printResult({ json, ok: false, error: NOT_LOGGED_IN, payload: { ok: false, error: NOT_LOGGED_IN } }, io);
     return 1;
   }
 
   try {
-    const result = await request('/developer/usage', { method: 'GET', token });
+    // The usage endpoint reads only X-API-Key: it reports one developer key's
+    // usage. Send a developer key when one is set; a sign-in token is refused.
+    const env = deps.env || process.env;
+    const devKey = String(env.ATRIS_API_KEY || '').trim();
+    const result = devKey
+      ? await request('/developer/usage', { method: 'GET', headers: { 'X-API-Key': devKey } })
+      : await request('/developer/usage', { method: 'GET', token });
     if (isNotFound(result)) {
       printResult({
         json,
@@ -69,7 +78,8 @@ async function usageCommand(args = [], deps = {}) {
       return 1;
     }
     if (!result || !result.ok) {
-      const error = oneLine(result && result.error);
+      let error = oneLine(result && result.error);
+      if (!devKey && [401, 403, 422].includes(result && result.status)) error = `${error}. ${USAGE_NEEDS_KEY}`;
       printResult({ json, ok: false, error, payload: { ok: false, error, status: result && result.status } }, io);
       return 1;
     }

package/lib/campaign-engine-stall.js

@@ -0,0 +1,95 @@
+// When the owner's engine gives a campaign nothing (no judge draft, no
+// missions), say which engine was asked and why it likely failed, then one
+// next step. Used by campaign new (lib/campaign-new.js) and propose and step
+// (lib/campaign-loop.js). It never invents work; it only ends the stall in
+// something a person can do.
+
+'use strict';
+
+const NOT_INSTALLED = /not installed|command not found|\benoent\b/i;
+const SIGNED_OUT = /not (?:logged|signed) in|please log ?in|log ?in required|login required|not authenticated|unauthori[sz]ed|auth(?:entication)? (?:expired|required)|\b401\b/i;
+const USAGE_LIMIT = /usage[ _-]?limit|rate[ _-]?limit|insufficient credits|purchase more credits|quota|payment required/i;
+
+// The ask runner's answer, cut to what the stall line needs. A clean answer
+// stays { text, engine, ok }; the runner's reason, exit and stderr ride along
+// only when it failed and said something.
+function askSummary(answer, engine, extra = {}) {
+  const a = answer || {};
+  const summary = { text: a.stdout || '', engine, ok: Boolean(a.ok) };
+  if (!summary.ok) {
+    if (a.reason) summary.reason = a.reason;
+    if (Number.isInteger(a.exit_code)) summary.exit_code = a.exit_code;
+    if (a.stderr) summary.stderr = String(a.stderr).slice(-2000);
+    if (a.timed_out) summary.timed_out = true;
+  }
+  for (const [key, value] of Object.entries(extra)) if (value) summary[key] = value;
+  return summary;
+}
+
+// What went wrong, from what the runner saw. Fakes and older callers pass
+// only { text, engine }; those read as "ran but sent back nothing".
+function stallCause(answer = {}) {
+  const engine = answer.engine || 'unknown';
+  const said = `${answer.reason || ''}\n${answer.stderr || ''}`;
+  const text = String(answer.text || '').trim();
+  if (answer.reason === 'spawn_error' || (!answer.ok && NOT_INSTALLED.test(said))) {
+    // With no ready engine the ask falls back to one; say so when that one is missing too.
+    return { kind: answer.no_engine ? 'no_engine' : 'not_installed', engine };
+  }
+  if (!answer.ok && SIGNED_OUT.test(said)) return { kind: 'signed_out', engine };
+  if (!answer.ok && USAGE_LIMIT.test(said)) return { kind: 'usage_limit', engine };
+  if (answer.reason === 'timeout' || answer.timed_out) return { kind: 'timed_out', engine };
+  if (/^exit_/.test(answer.reason || '') && answer.exit_code !== 0) return { kind: 'exited', engine, exit: answer.exit_code };
+  if (!text) return { kind: 'empty', engine };
+  return { kind: 'unusable', engine };
+}
+
+// The engine's own sign-in command, from the login table engine login uses.
+function signInStep(engine) {
+  try {
+    const { ENGINE_LOGIN_MANIFESTS } = require('../commands/engine');
+    const hint = ENGINE_LOGIN_MANIFESTS[engine] && ENGINE_LOGIN_MANIFESTS[engine].missingHint;
+    if (hint) return hint.replace(/\s+first$/, '');
+  } catch {}
+  return `sign in to ${engine}`;
+}
+
+// The engine is the problem when it never ran or could not answer; then the
+// next step is to fix it. Otherwise it ran and the next step is by hand.
+const ENGINE_KINDS = new Set(['no_engine', 'not_installed', 'signed_out', 'exited']);
+
+// owner: the member asked. wanted: what it was asked for ("a judge script",
+// "missions"). byHand: the exact command to do it without the engine.
+// again: what to run once the engine works.
+function explainStall({ owner, answer, wanted, byHand, again }) {
+  const cause = stallCause(answer);
+  const e = cause.engine;
+  const why = {
+    no_engine: `no engine on this computer is ready to do ${owner}'s work and the fallback ${e} is not installed`,
+    not_installed: `${owner}'s engine is ${e} and ${e} is not installed on this computer`,
+    signed_out: `${owner}'s engine is ${e} and ${e} is not signed in`,
+    usage_limit: `${owner}'s engine is ${e} and ${e} hit its usage limit`,
+    timed_out: `${owner}'s engine is ${e} and ${e} ran out of time before it answered`,
+    exited: `${owner}'s engine is ${e} and ${e} stopped with exit ${cause.exit} before it answered`,
+    empty: `${owner}'s engine is ${e} and ${e} ran but sent back nothing`,
+    unusable: `${owner}'s engine is ${e} and ${e} answered without ${wanted} atris could use`,
+  }[cause.kind];
+  const fix = {
+    no_engine: 'install codex or claude code',
+    not_installed: `install ${e}`,
+    signed_out: signInStep(e),
+    exited: `run atris engine test ${e} to see why it stopped`,
+  }[cause.kind];
+  const next = ENGINE_KINDS.has(cause.kind) && again
+    ? `${fix}, then run ${again} again`
+    : byHand;
+  return { kind: cause.kind, engine: e, why, next, line: `${why}.\nnext: ${next}`, inline: `${why}. next: ${next}` };
+}
+
+// True when asking again cannot help: the engine never ran.
+function engineCannotRun(answer) {
+  const kind = stallCause(answer).kind;
+  return kind === 'no_engine' || kind === 'not_installed' || kind === 'signed_out';
+}
+
+module.exports = { askSummary, engineCannotRun, explainStall };

package/lib/campaign-loop.js

@@ -15,6 +15,7 @@ const { getCampaign, openCampaignStore } = require('./campaign-store');
 const { defaultReserve, missionCost, reconcileCampaign } = require('./campaign-missions');
 const { confirmedReading, judgeRanData, latestJudgeOutput } = require('./campaign-reading');
 const { LANE_ASK_KIND, pausedLane, laneAskOpen, laneQuestion, openLaneAsks } = require('./campaign-lanes');
+const { explainStall } = require('./campaign-engine-stall');
 
 const TERMINAL = new Set(['stopped', 'complete']);
 
@@ -182,10 +183,11 @@ function parseProposals(text, view, count, rsiSummary = null, events = null) {
 async function askOwner(root, view, prompt) {
   const { resolveEngineForMember } = require('./member-engine');
   const { runEngineAskJobs } = require('./engine-ask');
+  const { askSummary } = require('./campaign-engine-stall');
   const pick = resolveEngineForMember(view.owner, root) || {};
   const engine = (pick.engine && pick.engine.id) || 'claude';
   const [answer] = await runEngineAskJobs([{ engine, model: pick.model || '', prompt, label: `campaign ${view.id} plan` }], { root, timeoutMs: PROPOSE_TIMEOUT_MS });
-  return { text: (answer && answer.stdout) || '', engine, ok: Boolean(answer && answer.ok) };
+  return askSummary(answer, engine, { no_engine: !(pick.engine && pick.engine.id) });
 }
 
 // Run one atris command and resolve with its exit code and output.
@@ -241,6 +243,9 @@ function makeLoop(root, options = {}, deps = {}) {
   const view = (id) => getCampaign(store, id);
   const append = (id, type, data, as = actor) => store.append({ campaign_id: id, type, actor: as, data });
 
+  // Why the last propose came back empty plus the one next step.
+  let lastStall = null;
+
   async function propose(id, count = parallel) {
     const events = store.read(id);
     const current = events.length ? fold(events) : null;
@@ -259,6 +264,13 @@ function makeLoop(root, options = {}, deps = {}) {
     const prompt = proposalPrompt(current, count, latestJudgeOutput(events), deps.lessons ? deps.lessons(id) : '', rsiSummary, events, brief);
     const answer = await ask(root, current, prompt);
     const proposals = parseProposals(answer.text, current, count, rsiSummary, events);
+    lastStall = proposals.length ? null : explainStall({
+      owner: current.owner,
+      answer,
+      wanted: 'missions',
+      byHand: `add one yourself: atris mission start "<what to do next>" --campaign ${id} --owner ${current.owner}`,
+      again: `atris campaign step ${id}`,
+    });
     // Planning costs money too. It rides on the first mission it produced as a
     // step, so it is counted when that mission ends without making the judge
     // due. A plan that produced nothing is not failed work: the step saves a
@@ -421,7 +433,8 @@ function makeLoop(root, options = {}, deps = {}) {
       const data = await readJudge(id, current, () => WAIT_FIRST_MS);
       if (data.passed) return { stop: false, did: 'judge' };
       const next = data.wait ? `; next check at ${clockTime(data.wait.wake_at)}` : '';
-      return { ok: false, stop: true, reason: `${current.owner} proposed nothing usable${next}` };
+      const why = lastStall ? `. ${lastStall.inline}` : '';
+      return { ok: false, stop: true, reason: `${current.owner} proposed nothing usable${next}${why}`, ...(lastStall ? { engine: lastStall.engine, cause: lastStall.kind, next_step: lastStall.next } : {}) };
     }
     for (const p of proposals) log(`  proposed for ${p.member}: ${p.objective}`);
     return { stop: false, did: 'propose' };
@@ -445,7 +458,7 @@ function makeLoop(root, options = {}, deps = {}) {
     return { steps: maxSteps, reason: `stopped after ${maxSteps} steps`, campaign: view(id) };
   }
 
-  return { step, tick, run, propose };
+  return { step, tick, run, propose, lastStall: () => lastStall };
 }
 
 module.exports = { ACTIVITY_LINE, askOwner, briefPath, makeLoop, parseProposals, proposalPrompt, rankCampaignMembers, readBrief, readingKey, runCli };