atris 3.82.16 → 3.82.18

package/README.md

@@ -269,7 +269,7 @@ The owner makes the client once. The secret is shown one time, or written to a
 private file with `--secret-file`:
 
 ```bash
-atris agent-client create --name nightly-bot --scopes mcp:read,x-search --secret-file ./bot.secret
+atris agent-client create --name nightly-bot --scopes mcp:workspace:read,x-search --secret-file ./bot.secret
 atris agent-client list
 atris agent-client rotate <client_id>
 atris agent-client revoke <client_id>

package/commands/agent-client.js

@@ -10,7 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { apiRequestJson } = require('../utils/api');
-const { ensureValidCredentials, readActiveCredentials } = require('../utils/auth');
+const { ensureValidCredentials, readActiveCredentials, listProfiles, loadProfile, getSessionProfile } = require('../utils/auth');
 const agentClient = require('../utils/agent-client');
 const { readFlag } = require('../lib/arg-parser');
 const { wantsJson, wantsHelp, oneLine } = require('../lib/developer-api');
@@ -19,7 +19,52 @@ const BASE_PATH = '/auth/agent-clients';
 const ACTIONS = new Set(['create', 'list', 'revoke', 'rotate']);
 const VALUE_FLAGS = ['--name', '--scopes', '--daily-credit-cap', '--ttl', '--secret-file'];
 const SHOWN_ONCE = 'store this secret now, it will not be shown again:';
-const AGENT_CLIENT_CANNOT_MANAGE = 'agent clients are managed with your own login, not an agent client. run: atris switch <you> or atris login --force';
+// Scopes an agent client can carry today. The server holds the real list and
+// rejects anything else; this is what help and the unknown-scope hint show.
+const COMMON_SCOPES = [
+  'x-search', 'youtube', 'gmail-read', 'calendar-read',
+  'files:read', 'files:write', 'scoreboard:read', 'ai:complete',
+  'mcp:workspace:read', 'mcp:publish',
+];
+
+// The person's own saved logins, so the error can name a real switch command.
+function humanProfileNames(deps = {}) {
+  const list = deps.listProfiles || listProfiles;
+  const load = deps.loadProfile || loadProfile;
+  try {
+    return list().filter((name) => {
+      const profile = load(name);
+      return profile && profile.token && !agentClient.isAgentClientCredential(profile);
+    });
+  } catch {
+    return [];
+  }
+}
+
+// The switch command that actually reaches the login in use. ATRIS_PROFILE
+// beats everything, then this terminal's own pick, then the global login, so
+// a --global switch would not help a terminal that picked its own account.
+function switchCommandFor(name, deps = {}) {
+  const env = deps.env || process.env;
+  if (String(env.ATRIS_PROFILE || '').trim()) return `export ATRIS_PROFILE=${name}`;
+  let session = null;
+  try { session = (deps.getSessionProfile || getSessionProfile)(); } catch { session = null; }
+  return session ? `atris switch ${name}` : `atris switch ${name} --global`;
+}
+
+function cannotManageMessage(deps = {}) {
+  const names = humanProfileNames(deps);
+  const lead = 'agent clients are managed with your own login, not an agent client.';
+  if (names.length === 1) return `${lead} switch back: ${switchCommandFor(names[0], deps)}`;
+  if (names.length > 1) return `${lead} switch back with one of: ${names.map((n) => switchCommandFor(n, deps)).join(' | ')}`;
+  return `${lead} sign in as yourself: atris login --force`;
+}
+
+function withScopeHint(message) {
+  const text = String(message || '');
+  if (!/unknown scope/i.test(text)) return text;
+  return `${text}. scopes you can use: ${COMMON_SCOPES.join(', ')}`;
+}
 
 function showAgentClientHelp(log = console.log) {
   log('usage: atris agent-client create --name <name> --scopes <a,b> [--daily-credit-cap N] [--ttl SECONDS] [--secret-file <path>]');
@@ -30,6 +75,7 @@ function showAgentClientHelp(log = console.log) {
   log('an agent client lets an agent sign itself in, with no person in the loop.');
   log('create and rotate show the secret once. --secret-file writes it to a private file instead.');
   log('the agent then runs: atris login --client-id <atc_...> --client-secret-file <path>');
+  log(`scopes you can use: ${COMMON_SCOPES.join(', ')}`);
   log('needs your own login. add --json for machine output.');
 }
 
@@ -170,7 +216,7 @@ async function agentClientCommand(args = [], deps = {}) {
 
   const readActive = deps.readActiveCredentials || readActiveCredentials;
   if (agentClient.isAgentClientCredential(readActive())) {
-    return fail(AGENT_CLIENT_CANNOT_MANAGE);
+    return fail(cannotManageMessage(deps));
   }
 
   const request = deps.apiRequestJson || apiRequestJson;
@@ -180,7 +226,7 @@ async function agentClientCommand(args = [], deps = {}) {
     return fail('not logged in. run: atris login');
   }
   if (ensured.source === agentClient.AUTH_TYPE || agentClient.isAgentClientCredential(ensured.credentials)) {
-    return fail(AGENT_CLIENT_CANNOT_MANAGE);
+    return fail(cannotManageMessage(deps));
   }
   const token = ensured.credentials.token;
 
@@ -211,7 +257,7 @@ async function agentClientCommand(args = [], deps = {}) {
     const secret = result && result.data && result.data.client_secret;
     const message = status === 404 && parsed.action !== 'revoke' && parsed.action !== 'rotate'
       ? 'agent clients are not live on the server yet. try again after the backend update.'
-      : agentClient.scrub(oneLine(result && (result.data || result.error)), [token, secret]);
+      : withScopeHint(agentClient.scrub(oneLine(result && (result.data || result.error)), [token, secret]));
     return fail(message, { status: status || 0 });
   }
 

package/commands/campaign.js

@@ -821,7 +821,9 @@ async function driveLoop(args, ctx, verb, view) {
   if (verb === 'propose') {
     const proposals = await loop.propose(view.id);
     const after = getCampaign(ctx.store, view.id);
-    ctx.out(proposals.length ? `${proposals.length} proposed and claimed\n${renderShow(after)}` : 'nothing usable was proposed', { ok: proposals.length > 0, proposals, campaign: after, next: decide(after) });
+    const stall = proposals.length ? null : loop.lastStall();
+    const empty = stall ? `nothing usable was proposed: ${stall.line}` : 'nothing usable was proposed';
+    ctx.out(proposals.length ? `${proposals.length} proposed and claimed\n${renderShow(after)}` : empty, { ok: proposals.length > 0, proposals, campaign: after, next: decide(after), ...(stall ? { engine: stall.engine, cause: stall.kind, next_step: stall.next } : {}) });
     return proposals.length ? 0 : 1;
   }
   if (verb === 'step') {

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

@@ -15,12 +15,38 @@ const {
 
 function showUsageHelp() {
   console.log('usage: atris usage [--json]');
-  console.log('show developer api usage for the logged-in account.');
+  console.log('show developer api usage: every key you own when signed in, or one key with ATRIS_API_KEY.');
+}
+
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+// Signed in as a person, the server answers with every developer key you own
+// plus a total. One line per key, then the total.
+function renderKeyBreakdown(usage) {
+  const total = usage.total && typeof usage.total === 'object' ? usage.total : {};
+  const days = Number(total.period_days) || 30;
+  const lines = [`last ${days} days, ${plural(usage.keys.length, 'developer key')}:`];
+  for (const entry of usage.keys) {
+    const u = (entry && entry.usage) || {};
+    const label = `${entry.agent_name || 'key'} (${u.api_key || 'key'})`;
+    const errors = Number(u.error_count) || 0;
+    lines.push(`  ${label}: ${plural(Number(u.total_requests) || 0, 'request')}${errors ? `, ${plural(errors, 'error')}` : ''}`);
+  }
+  const totalErrors = Number(total.error_count) || 0;
+  lines.push(`total: ${plural(Number(total.total_requests) || 0, 'request')}${totalErrors ? `, ${plural(totalErrors, 'error')} (${total.error_rate}%)` : ''}`);
+  const endpoints = Object.entries(total.endpoints || {}).sort((a, b) => b[1] - a[1]).slice(0, 5);
+  if (endpoints.length) lines.push(`busiest: ${endpoints.map(([name, count]) => `${name} ${count}`).join(', ')}`);
+  return lines.join('\n');
 }
 
 function renderUsage(data = {}) {
   const raw = data && typeof data === 'object' ? data : {};
   const usage = raw.usage && typeof raw.usage === 'object' ? raw.usage : raw;
+  if (Array.isArray(usage.keys)) {
+    return usage.keys.length ? renderKeyBreakdown(usage) : 'no developer keys yet. make one with atris api-key create';
+  }
   const lines = [];
   if (raw.agent_name || raw.agent_id) {
     lines.push(`${raw.agent_name || 'agent'} ${raw.agent_id || ''}`.trim());
@@ -41,6 +67,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 +79,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 +104,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 };

package/lib/campaign-new.js

@@ -9,6 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const { newCampaignId } = require('./campaign-store');
+const { engineCannotRun, explainStall } = require('./campaign-engine-stall');
 
 const DEFAULT_BUDGET = 20;
 const DEFAULT_OWNER = 'mission-lead';
@@ -100,10 +101,11 @@ function parseDraft(text, members) {
 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 new judge' }], { root, timeoutMs: ASK_TIMEOUT_MS });
-  return { text: (answer && answer.stdout) || '', engine, ok: Boolean(answer && answer.ok) };
+  return askSummary(answer, engine, { no_engine: !(pick.engine && pick.engine.id) });
 }
 
 function writeJudge(root, id, script) {
@@ -135,7 +137,9 @@ async function draftJudge({ root, goal, owner, idFlag, timeout, ask, judge }) {
     const draft = parseDraft(answer.text, members);
     if (!draft) {
       previous = 'the reply was not one JSON object with a judge_script';
-      last = { error: `${owner}'s engine (${answer.engine || 'unknown'}) did not return a judge script` };
+      last = { error: `${owner}'s engine (${answer.engine || 'unknown'}) did not return a judge script`, answer };
+      // Asking again cannot help an engine that never ran.
+      if (engineCannotRun(answer)) break;
       continue;
     }
     if (!draft.title) draft.title = goal.slice(0, 80);
@@ -218,11 +222,18 @@ async function draftAndStart(args, ctx, deps = {}) {
     judge: ctx.judge,
   });
   if (!result.ok) {
+    const byHand = `write the judge yourself: atris campaign start ${shellQuote(goal.slice(0, 80))} --judge "<command that fails today>" --budget ${budget}`;
+    // No draft came back: name the engine and why, then the one next step.
+    const stall = result.answer
+      ? explainStall({ owner, answer: result.answer, wanted: 'a judge script', byHand, again: 'atris campaign new' })
+      : null;
+    const error = stall ? stall.why : result.error;
+    const next = stall ? stall.next : byHand;
     if (ctx.asJson) {
-      console.log(JSON.stringify({ ok: false, error: result.error, draft: result.draft || null, reading: result.reading || null }));
+      console.log(JSON.stringify({ ok: false, error, next, engine: stall ? stall.engine : result.engine || null, cause: stall ? stall.kind : null, draft: result.draft || null, reading: result.reading || null }));
       return 1;
     }
-    return ctx.fail(`${result.error}. Write the judge yourself: atris campaign start "<title>" --judge "<command that fails today>" --budget ${budget}`, 1);
+    return ctx.fail(`${error}.\nnext: ${next}`, 1);
   }
 
   const draft = { id: result.id, title: result.draft.title, judge: result.command, judge_file: result.judgeFile, why: result.draft.why, seats: result.draft.seats, owner, budget, engine: result.engine };

package/lib/design-api.js

@@ -34,14 +34,25 @@ function readKeyFile(file = DESIGN_KEY_FILE) {
 }
 
 // Returns the bearer token for design calls, or null when nothing is set up.
+// A developer key (env, then the saved key file) comes before the login token:
+// the design server only accepts developer keys, so a saved key must never be
+// shadowed by being signed in.
 function resolveDesignKey(env = process.env, deps = {}) {
   const fromEnv = env.ATRIS_API_KEY && env.ATRIS_API_KEY.trim();
   if (fromEnv) return fromEnv;
+  const fromFile = (deps.readKeyFile || readKeyFile)();
+  if (fromFile) return fromFile;
   const load = deps.loadCredentials || loadCredentials;
   const creds = load();
   const token = creds && typeof creds.token === 'string' ? creds.token.trim() : '';
-  if (token) return token;
-  return (deps.readKeyFile || readKeyFile)();
+  return token || null;
+}
+
+// A design call that was refused for a sign-in token gets a next step.
+const DESIGN_NEEDS_KEY = 'design tools take a developer key, not your sign-in. make one with atris api-key create, then set ATRIS_API_KEY or save it to ~/.atris/design-api-key';
+
+function isDeveloperKey(key) {
+  return /^atris_/.test(String(key || '').trim());
 }
 
 // One JSON call against the design API. Returns { ok, status, data, error }.
@@ -68,9 +79,10 @@ async function designRequest(pathname, options = {}) {
   let data = null;
   try { data = text ? JSON.parse(text) : null; } catch { data = null; }
   const ok = res.status >= 200 && res.status < 300;
-  const error = !ok
+  let error = !ok
     ? (data && typeof data === 'object' && (data.detail || data.error || data.message)) || text.slice(0, 200) || `http ${res.status}`
     : undefined;
+  if (res.status === 401 && !isDeveloperKey(key)) error = `${typeof error === 'string' ? error : 'unauthorized'}. ${DESIGN_NEEDS_KEY}`;
   return { ok, status: res.status, data, error };
 }
 

package/lib/ninety-nine-sync.js

@@ -3,7 +3,7 @@
 const { createHash } = require('node:crypto');
 const { apiRequestJson, getApiBaseUrl } = require('../utils/api');
 const { decodeJwtClaims } = require('../utils/auth');
-const { parseSessionLog, lineIdentity, uniqueLines } = require('./ninety-nine');
+const { parseSessionLog, lineIdentity, uniqueLines, localBlocks, localDate, blocksLine, openDays } = require('./ninety-nine');
 
 const WORKSPACE_DIRECTORY = 'atris/99';
 
@@ -153,4 +153,74 @@ async function syncLines({ records, sync, checkpoint = {}, deviceId, credentials
   };
 }
 
-module.exports = { validateSync, checkpointKey, syncLines };
+// The account the day endpoint saves to, whatever the session sync target is.
+function blockAccountKey(credentials) {
+  const account = credentials.user_id || decodeJwtClaims(credentials.token)?.sub || credentials.email
+    || createHash('sha256').update(credentials.token).digest('hex');
+  return createHash('sha256').update(JSON.stringify([getApiBaseUrl(), account, 'blocks'])).digest('hex');
+}
+
+function blockPrint(block) {
+  return createHash('sha256').update(JSON.stringify(block)).digest('hex').slice(0, 16);
+}
+
+const BLOCKS_PER_SAVE = 24;
+const SENT_KEEP_DAYS = 7;
+
+// Each finished focus block made here goes once to PUT /api/99/day/{day} under
+// habits.deep_work.blocks, with done, as the phone and web send it. `sent` maps
+// block id to "day|print" of the copy the server took. A save the server refuses
+// for good (400, or 429 for a full day) settles its blocks so one bad block never holds the rest.
+async function syncBlocks({ records, sent = {}, credentials, now = new Date(), dryRun = false, request = apiRequestJson }) {
+  const open = new Set(openDays(now));
+  const pending = localBlocks(records).filter(({ day, block }) => open.has(day)
+    && sent[block.id] !== `${day}|${blockPrint(block)}`);
+  const next = { ...sent };
+  const result = { send: pending.map((item) => item.block), sent: next, line: null, refused: null, locked: false };
+  if (dryRun || !pending.length) return result;
+  const byDay = new Map();
+  for (const item of pending) {
+    if (!byDay.has(item.day)) byDay.set(item.day, []);
+    byDay.get(item.day).push(item);
+  }
+  for (const [day, items] of byDay) {
+    for (let offset = 0; offset < items.length; offset += BLOCKS_PER_SAVE) {
+      const batch = items.slice(offset, offset + BLOCKS_PER_SAVE);
+      const query = new URLSearchParams({ tz_offset_minutes: String(batch[0].tz_offset_minutes) });
+      let response;
+      try {
+        response = await request(`/99/day/${day}?${query}`, {
+          method: 'PUT', token: credentials.token,
+          body: { habits: { deep_work: { done: true, blocks: batch.map((item) => item.block) } } },
+        });
+      } catch {
+        throw new Error('could not reach the 99 server; try again');
+      }
+      if (response?.status === 402) {
+        result.locked = true;
+        return result;
+      }
+      if ([401, 403].includes(response?.status)) throw new Error('sync needs your signed-in user login; run atris login');
+      if ([400, 429].includes(response?.status)) {
+        result.refused = String(response?.data?.detail?.error || 'refused').slice(0, 40);
+      } else if (!response?.ok) {
+        throw new Error(`the 99 server did not take the focus blocks${response?.status ? ` (http ${response.status})` : ''}; try again`);
+      } else {
+        const deep = response.data?.habits?.deep_work;
+        if (Number.isInteger(deep?.block_count) && Number.isInteger(deep?.block_minutes)) {
+          result.line = blocksLine({ count: deep.block_count, minutes: deep.block_minutes });
+        }
+      }
+      for (const item of batch) next[item.block.id] = `${item.day}|${blockPrint(item.block)}`;
+    }
+  }
+  const oldest = new Date(now);
+  oldest.setDate(oldest.getDate() - SENT_KEEP_DAYS);
+  const cutoff = localDate(oldest);
+  for (const [id, value] of Object.entries(next)) {
+    if (typeof value !== 'string' || value.slice(0, 10) < cutoff) delete next[id];
+  }
+  return result;
+}
+
+module.exports = { validateSync, checkpointKey, syncLines, syncBlocks, blockAccountKey };

package/lib/ninety-nine.js

@@ -4,6 +4,10 @@ const LENGTHS = { focus: [25, 50, 90], meditate: [10, 20, 30] };
 const SOURCES = ['cli', 'mac', 'ios'];
 const PAUSE_LIMIT_MS = 30 * 60000;
 const HEALTH_FIELDS = ['sleep_min', 'steps', 'workout_min', 'mindful_min'];
+const OUTCOMES = ['yes', 'partly', 'no'];
+const INTENTION_MAX = 200;
+const BLOCK_NOTE_MAX = 500;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 function lineIdentity(record) {
   return `${record.type}|${record.type === 'health_day' ? record.date : record.id}|${record.at}|${record.source}`;
@@ -19,6 +23,14 @@ function uniqueLines(records) {
   });
 }
 
+function oneLineText(value) {
+  return typeof value === 'string' && !/[\r\n\u2028\u2029]/.test(value);
+}
+
+function oneLine(value, limit) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, limit).trim();
+}
+
 function validLength(kind, minutes) {
   return Object.hasOwn(LENGTHS, kind) && LENGTHS[kind].includes(minutes);
 }
@@ -31,10 +43,12 @@ function parseSessionLog(text) {
     const common = record && record.v === 1 && SOURCES.includes(record.source)
       && typeof record.at === 'string' && Number.isFinite(Date.parse(record.at));
     const session = typeof record?.id === 'string' && record.id;
-    const start = record?.type === 'start' && validLength(record.kind, record.planned_min);
+    const start = record?.type === 'start' && validLength(record.kind, record.planned_min)
+      && (record.intention === undefined || oneLineText(record.intention));
     const end = record?.type === 'end' && ['done', 'partial'].includes(record.status)
       && (record.inferred === undefined || typeof record.inferred === 'boolean')
-      && (record.note === undefined || (typeof record.note === 'string' && !/[\r\n\u2028\u2029]/.test(record.note)));
+      && (record.note === undefined || oneLineText(record.note))
+      && (record.outcome === undefined || record.outcome === null || OUTCOMES.includes(record.outcome));
     const pause = ['pause', 'resume'].includes(record?.type);
     const health = record?.type === 'health_day' && typeof record.date === 'string'
       && /^\d{4}-\d{2}-\d{2}$/.test(record.date)
@@ -54,6 +68,7 @@ function foldSessions(records) {
   const sessions = new Map();
   const events = new Map();
   const ends = new Map();
+  const outcomes = new Map();
   // Stable sort preserves append order when timestamps tie, without rewriting the log.
   for (const record of uniqueLines(records).sort((a, b) => Date.parse(a.at) - Date.parse(b.at))) {
     if (record.type === 'health_day') continue;
@@ -68,6 +83,7 @@ function foldSessions(records) {
         ended_at: null,
         status: 'running',
       });
+      if (record.intention) sessions.get(record.id).intention = record.intention;
       events.set(record.id, []);
     } else {
       const session = sessions.get(record.id);
@@ -76,6 +92,11 @@ function foldSessions(records) {
         events.get(record.id).push(record);
         continue;
       }
+      // How the block went counts from any end record: the newest answer wins, and
+      // null (asked, skipped) only stands when there is no answer at all.
+      if (record.outcome !== undefined && (record.outcome !== null || !outcomes.has(record.id))) {
+        outcomes.set(record.id, record.outcome);
+      }
       const previous = ends.get(record.id);
       // A person's end wins over an automatic observation, in either log order.
       if (!previous || (previous.inferred === true && record.inferred !== true)
@@ -115,6 +136,7 @@ function foldSessions(records) {
       session.status = end.status;
       if (end.note !== undefined) session.note = end.note;
       if (end.inferred === true) session.inferred = true;
+      if (outcomes.has(session.id)) session.outcome = outcomes.get(session.id);
     }
   }
   return [...sessions.values()];
@@ -127,9 +149,50 @@ function runningSession(sessions, now) {
   return running[0] || null;
 }
 
-function startRecord(kind, plannedMin, now, id) {
+function startRecord(kind, plannedMin, now, id, intention = '') {
   if (!validLength(kind, plannedMin)) throw new Error('choose a supported session length');
-  return { v: 1, type: 'start', id, kind, planned_min: plannedMin, at: now.toISOString(), source: 'cli' };
+  const record = { v: 1, type: 'start', id, kind, planned_min: plannedMin, at: now.toISOString(), source: 'cli' };
+  const line = kind === 'focus' ? oneLine(intention, INTENTION_MAX) : '';
+  if (line) record.intention = line;
+  return record;
+}
+
+// How a finished focus block went: yes, partly, no, or null for asked and skipped.
+// Only a focus block that ran its full time carries it.
+function withOutcome(record, session, outcome) {
+  if ((outcome === null || OUTCOMES.includes(outcome)) && session.kind === 'focus' && record.status === 'done') {
+    record.outcome = outcome;
+  }
+  return record;
+}
+
+// One more end line that adds the answer to a block that already ended. It sits after
+// the real end, so every face keeps the earliest end and its time; only the answer is new.
+function answerRecord(session, now, outcome) {
+  const at = Math.max(now.getTime(), Date.parse(session.ended_at) + 1);
+  return {
+    v: 1, type: 'end', id: session.id, status: 'done', at: new Date(at).toISOString(), source: 'cli', inferred: true, outcome,
+  };
+}
+
+// The server takes saves for the local today, and for yesterday until 3 in the morning.
+function openDays(now) {
+  const days = [localDate(now)];
+  if (now.getHours() < 3) {
+    const yesterday = new Date(now);
+    yesterday.setDate(yesterday.getDate() - 1);
+    days.push(localDate(yesterday));
+  }
+  return days;
+}
+
+// Finished focus blocks made on this computer, still open for a save, never asked about.
+function unansweredBlocks(records, now) {
+  const sources = new Map(records.filter((record) => record.type === 'start').map((record) => [record.id, record.source]));
+  const open = new Set(openDays(now));
+  return foldSessions(records).filter((session) => session.kind === 'focus' && session.status === 'done'
+    && session.outcome === undefined && ['cli', 'mac'].includes(sources.get(session.id))
+    && open.has(localDate(new Date(session.started_at))));
 }
 
 function endRecord(session, now, note = '') {
@@ -208,6 +271,72 @@ function sessionsToday(sessions, now) {
   };
 }
 
+// A focus block counts on the local day it started, as on the phone.
+function blocksToday(sessions, now) {
+  const date = localDate(now);
+  const blocks = sessions.filter((session) => session.kind === 'focus' && session.status === 'done'
+    && localDate(new Date(session.started_at)) === date);
+  return { count: blocks.length, minutes: blocks.reduce((sum, session) => sum + session.planned_min, 0) };
+}
+
+// 125 is "2 hours 5 minutes", 60 is "1 hour", 25 is "25 minutes".
+function blockDuration(minutes) {
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  const hourText = hours === 1 ? '1 hour' : `${hours} hours`;
+  const minuteText = rest === 1 ? '1 minute' : `${rest} minutes`;
+  if (hours === 0) return minuteText;
+  return rest === 0 ? hourText : `${hourText} ${minuteText}`;
+}
+
+// "3 blocks, 2 hours 5 minutes"; null with no finished block.
+function blocksLine({ count, minutes }) {
+  if (!count) return null;
+  return `${count === 1 ? '1 block' : `${count} blocks`}, ${blockDuration(minutes)}`;
+}
+
+function offsetMinutesAt(date) {
+  return -date.getTimezoneOffset();
+}
+
+// ISO 8601 with the local offset at that moment, whole seconds, like the phone writes.
+function isoWithOffset(date) {
+  const offset = offsetMinutesAt(date);
+  const local = new Date(date.getTime() + offset * 60000).toISOString().slice(0, 19);
+  if (offset === 0) return `${local}Z`;
+  const sign = offset < 0 ? '-' : '+';
+  const abs = Math.abs(offset);
+  return `${local}${sign}${String(Math.floor(abs / 60)).padStart(2, '0')}:${String(abs % 60).padStart(2, '0')}`;
+}
+
+// A finished focus block in the shape of "Contract: blocks" in project99's deep-work idea.
+// Only blocks made on this computer go; the phone sends its own.
+function blockFromSession(session) {
+  if (session.kind !== 'focus' || session.status !== 'done' || !UUID.test(session.id)) return null;
+  const started = new Date(session.started_at);
+  return {
+    day: localDate(started),
+    tz_offset_minutes: offsetMinutesAt(started),
+    block: {
+      id: session.id,
+      minutes: session.planned_min,
+      intention: oneLine(session.intention, INTENTION_MAX),
+      started_at: isoWithOffset(started),
+      ended_at: isoWithOffset(new Date(session.ended_at)),
+      outcome: session.outcome ?? null,
+      note: oneLine(session.note, BLOCK_NOTE_MAX),
+    },
+  };
+}
+
+function localBlocks(records) {
+  const sources = new Map(records.filter((record) => record.type === 'start').map((record) => [record.id, record.source]));
+  return foldSessions(records)
+    .filter((session) => ['cli', 'mac'].includes(sources.get(session.id)))
+    .map(blockFromSession)
+    .filter(Boolean);
+}
+
 function healthToday(records, now) {
   const date = localDate(now);
   let latest;
@@ -228,6 +357,21 @@ function healthSummary(record) {
 }
 
 module.exports = {
+  OUTCOMES,
+  INTENTION_MAX,
+  BLOCK_NOTE_MAX,
+  oneLine,
+  localDate,
+  withOutcome,
+  answerRecord,
+  openDays,
+  unansweredBlocks,
+  blocksToday,
+  blockDuration,
+  blocksLine,
+  isoWithOffset,
+  blockFromSession,
+  localBlocks,
   validLength,
   parseSessionLog,
   foldSessions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.82.16",
+  "version": "3.82.18",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof. project memory your coding agents share across sessions.",
   "mcpName": "io.github.atrislabs/atris",
   "main": "bin/atris.js",