atris 3.35.0 → 3.36.0

package/commands/improve.js

@@ -11,7 +11,7 @@
  *
  * This is the CLI entrypoint for the headline paid capability. The member
  * loop and the /improve skill both call it. If the backend is unreachable
- * or the user is not logged in, it falls back to a local autopilot tick
+ * or the user is not logged in, it falls back to one local mission tick
  * (same loop, local inference) instead of erroring silently.
  *
  * The orchestrator (runImprove) takes injected deps so the network, auth,
@@ -24,6 +24,11 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { apiRequestJson, getApiBaseUrl } = require('../utils/api');
 const { loadCredentials } = require('../utils/auth');
+const pulse = require('../lib/pulse');
+const { cronInstalled } = require('./pulse');
+const close = require('./close');
+const { readUsage } = require('../lib/usage');
+const { knownCommands } = require('../lib/known-commands');
 
 /**
  * Expand a leading `~` to the real home directory for LOCAL filesystem
@@ -40,8 +45,10 @@ function expandHome(p) {
 }
 
 const SCORECARD_SCHEMA = 'atris.improve_tick.v1';
+const IMPROVE_VITALS_SCHEMA = 'atris.improve_vitals.v1';
 const DEFAULT_TIMEOUT_MS = 300000;
 const VALID_MODES = new Set(['full', 'plan', 'delegate']);
+const DAY_MS = 24 * 60 * 60 * 1000;
 
 /**
  * Resolve the improve endpoint path relative to the configured API base.
@@ -54,6 +61,22 @@ function improveApiPath(baseUrl) {
   return base.endsWith('/api') ? '/improve' : '/api/improve';
 }
 
+function hostedApiCannotReachLocalWorkspace(workspace, baseUrl) {
+  if (!path.isAbsolute(String(workspace || ''))) return false;
+  try {
+    if (!fs.statSync(workspace).isDirectory()) return false;
+    const hostname = new URL(baseUrl).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const loopback = hostname === 'localhost'
+      || hostname.endsWith('.localhost')
+      || hostname === '::1'
+      || hostname === '0.0.0.0'
+      || hostname.startsWith('127.');
+    return !loopback;
+  } catch {
+    return false;
+  }
+}
+
 function parseImproveArgs(argv = []) {
   const args = Array.isArray(argv) ? [...argv] : [];
   const opts = {
@@ -133,7 +156,7 @@ function summarizeImproveResponse(data = {}) {
 }
 
 /**
- * Decide whether to fall back to a local autopilot tick. Fallback only when
+ * Decide whether to fall back to one local mission tick. Fallback only when
  * the backend is genuinely unavailable: no auth, or unreachable (status 0).
  * A real HTTP error (insufficient credits 402, server error 5xx) is reported
  * honestly — we never silently run local work and bill nothing on what was a
@@ -144,9 +167,28 @@ function shouldFallbackLocal({ creds, apiResult } = {}) {
   if (!apiResult) return { fallback: false, reason: 'no_result' };
   if (apiResult.ok) return { fallback: false, reason: 'api_ok' };
   if (apiResult.status === 0) return { fallback: true, reason: 'unreachable' };
+  // The hosted backend validates workspace_path against its own filesystem,
+  // so a local-only folder 403s even for an authed, funded user. That is an
+  // unreachable-workspace condition — run the same tick locally instead of
+  // dying on it. Other 403s (real permission failures) are still reported.
+  if (apiResult.status === 403 && isWorkspaceNotAllowedError(apiResult)) {
+    return { fallback: true, reason: 'workspace_not_on_backend' };
+  }
   return { fallback: false, reason: `api_error_${apiResult.status}` };
 }
 
+const WORKSPACE_NOT_ALLOWED_TEXT = 'workspace_path must be under an allowed directory';
+
+function isWorkspaceNotAllowedError(apiResult = {}) {
+  const candidates = [
+    apiResult.error,
+    apiResult.error && apiResult.error.error,
+    apiResult.data && apiResult.data.detail,
+    apiResult.data && apiResult.data.detail && apiResult.data.detail.error,
+  ];
+  return candidates.some((c) => typeof c === 'string' && c.includes(WORKSPACE_NOT_ALLOWED_TEXT));
+}
+
 function buildScorecardRow(summary = {}, meta = {}) {
   return {
     schema: SCORECARD_SCHEMA,
@@ -249,6 +291,239 @@ function localHourMinute(d = new Date()) {
   return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
 }
 
+function readJsonFile(file, fallback = null) {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readJsonlFile(file) {
+  try {
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, 'utf8')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function timestampMs(value) {
+  const ms = Date.parse(String(value || ''));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+function formatReward(value) {
+  const n = Number(value) || 0;
+  if (Number.isInteger(n)) return String(n);
+  return String(Number(n.toFixed(2)));
+}
+
+function agePhrase(ts, nowMs = Date.now()) {
+  const ms = timestampMs(ts);
+  if (ms == null) return null;
+  const delta = Math.max(0, nowMs - ms);
+  if (delta < 60 * 1000) return 'just now';
+  if (delta < 60 * 60 * 1000) return `${plural(Math.round(delta / (60 * 1000)), 'minute')} ago`;
+  if (delta < DAY_MS) return `${plural(Math.round(delta / (60 * 60 * 1000)), 'hour')} ago`;
+  if (delta < 30 * DAY_MS) return `${plural(Math.round(delta / DAY_MS), 'day')} ago`;
+  return `on ${new Date(ms).toISOString().slice(0, 10)}`;
+}
+
+function plainSentence(value) {
+  return String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function latestByTime(rows, fields) {
+  let latest = null;
+  let latestMs = -Infinity;
+  for (const row of Array.isArray(rows) ? rows : []) {
+    for (const field of fields) {
+      const ms = timestampMs(row && row[field]);
+      if (ms != null && ms > latestMs) {
+        latest = row;
+        latestMs = ms;
+      }
+    }
+  }
+  return latest ? { row: latest, ms: latestMs } : null;
+}
+
+function scoutFindingLanded(row = {}) {
+  if (!row || typeof row !== 'object') return false;
+  if (row.finding_landed === true || row.finding === true) return true;
+  if (Array.isArray(row.findings) && row.findings.length > 0) return true;
+  if (row.result && typeof row.result === 'object') {
+    if (row.result.finding_landed === true || row.result.finding === true) return true;
+    if (Array.isArray(row.result.findings) && row.result.findings.length > 0) return true;
+  }
+  const landing = row.last_landing || (row.result && row.result.landing) || row.landing;
+  if (landing && typeof landing === 'object') {
+    const text = `${landing.finding || ''} ${landing.findings || ''}`.trim();
+    if (text) return true;
+  }
+  return false;
+}
+
+function collectImproveVitals(options = {}, deps = {}) {
+  const root = expandHome(options.workspace || process.cwd());
+  const nowDate = options.now ? new Date(options.now) : new Date();
+  const nowMs = Number.isFinite(nowDate.getTime()) ? nowDate.getTime() : Date.now();
+  const today = localDateKey(new Date(nowMs));
+
+  const readPulse = deps.readPulseReceipts || pulse.readPulseReceipts;
+  const pulsePath = (deps.pulseReceiptsPath || pulse.pulseReceiptsPath)(root);
+  const receipts = readPulse(root);
+  const finished = (Array.isArray(receipts) ? receipts : []).filter((row) => row && row.phase === 'finished');
+  const latestPulse = latestByTime(finished, ['ts']);
+  const rewardSince = nowMs - DAY_MS;
+  const rewardToday = finished.reduce((sum, row) => {
+    const ms = timestampMs(row.ts);
+    return ms != null && ms >= rewardSince ? sum + (Number(row.reward) || 0) : sum;
+  }, 0);
+  const heartbeatAge = latestPulse ? agePhrase(latestPulse.row.ts, nowMs) : null;
+  const heartbeatSentence = latestPulse
+    ? `the scheduled improve heartbeat last beat ${heartbeatAge} and earned ${formatReward(rewardToday)} reward today.`
+    : `the scheduled improve heartbeat has not beaten yet and earned ${formatReward(rewardToday)} reward today.`;
+  const cronFn = deps.cronInstalled || cronInstalled;
+  // Per-repo slots (pr 310): the crontab marker is derived from the root, so
+  // the check must ask about THIS repo's markers, not the legacy default.
+  const slotMarkers = (() => {
+    try { return pulse.resolvePulseSlot(root).markers; } catch { return undefined; }
+  })();
+  const installed = Boolean(slotMarkers ? cronFn(slotMarkers) : cronFn());
+  const installNudge = installed ? null : 'the scheduled improve loop is off. turn it on: atris pulse install --model claude-sonnet-5';
+
+  const experimentsPath = path.join(root, '.atris', 'state', 'experiments-daily.json');
+  const experiments = readJsonFile(experimentsPath, {});
+  const history = Array.isArray(experiments && experiments.history) ? experiments.history : [];
+  const experimentRanToday = String(experiments && experiments.last_run_date || '') === today;
+  const exploitSentence = `${experimentRanToday ? 'todays experiment already ran' : 'no experiment yet today'}, with ${plural(history.length, 'total experiment')}.`;
+
+  const missionsPath = path.join(root, '.atris', 'state', 'missions.jsonl');
+  const missions = readJsonlFile(missionsPath);
+  const scoutMissions = missions.filter((row) => {
+    const owner = String(row && row.owner || '').toLowerCase();
+    return owner === 'scout' || owner === 'signal-scout' || owner.endsWith('-scout');
+  });
+  const latestScout = latestByTime(scoutMissions, [
+    'last_tick_at',
+    'last_tick_finished_at',
+    'finished_at',
+    'updated_at',
+    'created_at',
+    'started_at',
+  ]);
+  const scoutAge = latestScout ? agePhrase(new Date(latestScout.ms).toISOString(), nowMs) : null;
+  const findingLanded = latestScout ? scoutFindingLanded(latestScout.row) : false;
+  const exploreSentence = latestScout
+    ? `the scout last explored ${scoutAge} and ${findingLanded ? 'landed a finding' : 'no finding landed'}.`
+    : 'the scout has not explored yet and no finding landed.';
+
+  const openFlags = (deps.openFlags || close.openFlags)(root, { now: new Date(nowMs) });
+  const sweep = (deps.sweepState || close.sweepState)(root, new Date(nowMs), { dryRun: true });
+  const overdue = Array.isArray(sweep.overdue) ? sweep.overdue : openFlags.filter((flag) => flag && flag.overdue);
+  const topOverdueSentence = overdue[0] ? plainSentence((deps.sweepLine || close.sweepLine)(overdue[0])) : null;
+  const excreteSentence = `the excretion loop has ${plural(openFlags.length, 'open loop')} and ${plural(overdue.length, 'overdue loop')}.`;
+
+  const usageRows = (deps.readUsage || readUsage)(root, { sinceDays: 7, now: new Date(nowMs).toISOString() });
+  const known = deps.knownCommands || knownCommands;
+  const knownSet = new Set(known);
+  const usedThisWeek = new Set((Array.isArray(usageRows) ? usageRows : [])
+    .map((row) => row && row.cmd)
+    .filter((cmd) => knownSet.has(cmd)));
+  const usageSentence = `you used ${usedThisWeek.size} of ${known.length} known commands this week.`;
+
+  const heartbeat = {
+    receipts_path_exists: fs.existsSync(pulsePath),
+    last_finished_at: latestPulse ? latestPulse.row.ts : null,
+    last_finished_ago: heartbeatAge,
+    reward_last_24h: Number(formatReward(rewardToday)),
+    cron_installed: installed,
+    sentence: plainSentence(heartbeatSentence),
+  };
+  const exploit = {
+    ran_today: experimentRanToday,
+    total_experiments: history.length,
+    last_run_date: experiments && experiments.last_run_date || null,
+    sentence: plainSentence(exploitSentence),
+  };
+  const explore = {
+    total_scout_missions: scoutMissions.length,
+    last_tick_at: latestScout ? new Date(latestScout.ms).toISOString() : null,
+    last_tick_ago: scoutAge,
+    finding_landed: findingLanded,
+    sentence: plainSentence(exploreSentence),
+  };
+  const excrete = {
+    open: openFlags.length,
+    overdue: overdue.length,
+    top_overdue_sentence: topOverdueSentence,
+    sentence: plainSentence(excreteSentence),
+  };
+  const usage = {
+    used_this_week: usedThisWeek.size,
+    known_commands: known.length,
+    sentence: plainSentence(usageSentence),
+  };
+
+  const sentences = [
+    heartbeat.sentence,
+    exploit.sentence,
+    explore.sentence,
+    excrete.sentence,
+    ...(topOverdueSentence ? [`the top overdue loop says ${topOverdueSentence}`] : []),
+    usage.sentence,
+  ];
+  const groups = [
+    [heartbeat.sentence, installNudge].filter(Boolean),
+    [exploit.sentence],
+    [explore.sentence],
+    [excrete.sentence, ...(topOverdueSentence ? [`the top overdue loop says ${topOverdueSentence}`] : [])],
+    [usage.sentence],
+  ];
+
+  return {
+    schema: IMPROVE_VITALS_SCHEMA,
+    generated_at: new Date(nowMs).toISOString(),
+    heartbeat,
+    exploit,
+    explore,
+    excrete,
+    usage,
+    install_nudge: installNudge,
+    sentences,
+    groups,
+  };
+}
+
+function formatImproveVitals(vitals = {}) {
+  const groups = Array.isArray(vitals.groups) ? vitals.groups : [];
+  return groups
+    .map((group) => group.filter(Boolean).map(plainSentence).join('\n'))
+    .filter(Boolean)
+    .join('\n\n');
+}
+
 /**
  * Append a human-readable tick entry to today's journal under ## Notes.
  * The skill contract says every tick lands in the journal; the JSONL
@@ -288,23 +563,108 @@ function resolveAtrisBin() {
   return process.env.ATRIS_BIN || 'atris';
 }
 
+// The improve contract is one call -> one tick. Use the mission runtime
+// directly so the tick count and verifier result come back as structured JSON
+// instead of hiding several mission ticks inside one autopilot leg.
+const LOCAL_FALLBACK_ARGS = ['mission', 'run', '--due', '--headless', '--max-ticks', '1', '--complete-on-pass', '--json'];
+
+function localFallbackArgs(budgetSec) {
+  return LOCAL_FALLBACK_ARGS.concat(['--max-wall', String(Math.max(60, Math.round(budgetSec)))]);
+}
+
+function localSummaryText(tick = {}, mission = {}) {
+  const candidates = [
+    tick.claude && tick.claude.summary,
+    tick.atris2 && tick.atris2.summary,
+    tick.drill && tick.drill.summary,
+    mission.objective,
+  ];
+  return String(candidates.find((value) => String(value || '').trim()) || 'verified local improvement')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Turn one mission-run JSON result into the same stable summary the paid API
+ * returns. A local tick earns the conservative local reward (+1) only after
+ * its real verifier passes; missing proof is a failed improve call.
+ */
+function summarizeLocalMissionRun(payload = {}) {
+  const ticks = Array.isArray(payload.ticks) ? payload.ticks : [];
+  const tickCount = Number(payload.tick_count != null ? payload.tick_count : ticks.length);
+  if (!payload.ok || payload.action !== 'mission_run') {
+    throw new Error(`local improve did not run a mission tick${payload.reason ? `: ${payload.reason}` : ''}`);
+  }
+  if (tickCount !== 1 || ticks.length !== 1) {
+    throw new Error(`local improve must run exactly one tick; got ${tickCount}`);
+  }
+  const tick = ticks[0] || {};
+  if (tick.status !== 'ran') {
+    throw new Error(`local improve tick did not run${tick.reason ? `: ${tick.reason}` : ''}`);
+  }
+  if (tick.claude?.skipped === true || ['caller-session-runner', 'no-claude-mode'].includes(tick.reason)) {
+    throw new Error('local improve worker did not run');
+  }
+  if (tick.verifier_passed !== true) {
+    throw new Error('local improve verifier did not pass');
+  }
+  const mission = payload.mission || {};
+  const files = tick.worktree && Array.isArray(tick.worktree.new_since_baseline_sample)
+    ? tick.worktree.new_since_baseline_sample
+    : [];
+  return {
+    shipped: localSummaryText(tick, mission),
+    reward: 1,
+    verify: true,
+    credits: 0,
+    files,
+    model: mission.model || mission.runner || null,
+    taskId: mission.task_id || mission.current_task_id || null,
+    elapsedMs: null,
+    scorecardWritten: false,
+  };
+}
+
 function runLocalFallback(opts = {}) {
   const bin = resolveAtrisBin();
   const isScript = bin.endsWith('.js');
   const cmd = isScript ? process.execPath : bin;
-  const argv = (isScript ? [bin] : []).concat(['autopilot', '--auto', '--iterations=1']);
+  // Tell autopilot its time budget so it lands gracefully ("budget spent")
+  // instead of being SIGKILLed mid-leg and reporting a failed tick. The spawn
+  // timeout stays as a backstop, one minute past the budget.
+  const budgetSec = Math.max(60, Number(opts.timeoutSec) || 600);
+  const argv = (isScript ? [bin] : []).concat(localFallbackArgs(budgetSec));
   const r = spawnSync(cmd, argv, {
     cwd: opts.workspace || process.cwd(),
     encoding: 'utf8',
     env: process.env,
-    stdio: opts.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-    timeout: Math.max(60, Number(opts.timeoutSec) || 600) * 1000,
+    // Mission output is JSON even for the human-facing improve command because
+    // proof must be parsed before improve can claim success or write a receipt.
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: (budgetSec + 60) * 1000,
   });
+  let payload = null;
+  let summary = null;
+  let error = null;
+  if (r.status === 0) {
+    try {
+      payload = JSON.parse(String(r.stdout || '').trim());
+      summary = summarizeLocalMissionRun(payload);
+    } catch (e) {
+      error = e.message;
+    }
+  } else {
+    error = String(r.stderr || '').trim().split('\n').filter(Boolean).slice(-1)[0]
+      || `local improve exited ${r.status == null ? 1 : r.status}`;
+  }
   return {
-    ok: r.status === 0,
+    ok: r.status === 0 && Boolean(summary),
     status: r.status == null ? 1 : r.status,
     stdout: r.stdout || '',
     stderr: r.stderr || '',
+    payload,
+    summary,
+    error,
   };
 }
 
@@ -330,23 +690,89 @@ async function runImprove(opts = {}, deps = {}) {
   const timeoutSec = Math.round((opts.timeoutMs || DEFAULT_TIMEOUT_MS) / 1000);
   const startedAt = now();
   const creds = loadCreds();
+  const shippingTick = (opts.mode || 'full') === 'full' && !opts.dryRun;
+  const localFallbackEligible = opts.fallback && shippingTick;
+
+  const finishLocalFallback = (reason, apiResult = null) => {
+    const local = localFn({ workspace, json: opts.json, timeoutSec });
+    const finishedAt = now();
+    if (!local.ok || !local.summary || local.summary.verify !== true) {
+      return {
+        ok: false,
+        source: 'local',
+        reason,
+        error: local.error || 'local improve verifier did not pass',
+        local,
+        ...(apiResult ? { apiResult } : {}),
+        startedAt,
+        finishedAt,
+      };
+    }
+    const row = buildScorecardRow(local.summary, {
+      source: 'local',
+      mode: opts.mode || 'full',
+      ts: finishedAt,
+      member: opts.member,
+    });
+    let scorecardPath;
+    let journalPath;
+    try {
+      scorecardPath = writeRow(workspace, row);
+      journalPath = writeJournal(workspace, local.summary, { source: 'local', member: opts.member });
+    } catch (e) {
+      return {
+        ok: false,
+        source: 'local',
+        reason,
+        error: `local improve receipt write failed: ${e.message}`,
+        local,
+        ...(apiResult ? { apiResult } : {}),
+        startedAt,
+        finishedAt,
+      };
+    }
+    return {
+      ok: true,
+      source: 'local',
+      reason,
+      summary: local.summary,
+      scorecardPath,
+      journalPath,
+      receipt: 'written',
+      row,
+      local,
+      ...(apiResult ? { apiResult } : {}),
+      startedAt,
+      finishedAt,
+    };
+  };
 
   // No auth → local fallback (or report if fallback disabled).
   if (!creds || !creds.token) {
-    if (!opts.fallback) {
+    if (!localFallbackEligible) {
       return {
         ok: false, source: 'none', reason: 'no_auth',
-        error: 'Not logged in and --no-fallback set. Run: atris login',
+        error: shippingTick
+          ? 'Not logged in and --no-fallback set. Run: atris login'
+          : 'Not logged in. Plan, delegate, and dry-run modes require the hosted API; run: atris login',
         startedAt, finishedAt: now(),
       };
     }
-    log('not logged in — falling back to a local autopilot tick');
-    const local = localFn({ workspace, json: opts.json, timeoutSec });
-    return { ok: local.ok, source: 'local', reason: 'no_auth', local, startedAt, finishedAt: now() };
+    log('not logged in — falling back to one local mission tick');
+    return finishLocalFallback('no_auth');
+  }
+
+  // A hosted backend cannot read an absolute workspace that only exists on
+  // this machine. Skip the known-impossible request and use the same verified
+  // local mission fallback that its workspace-path 403 would have selected.
+  const apiBase = baseFn();
+  if (localFallbackEligible && hostedApiCannotReachLocalWorkspace(workspace, apiBase)) {
+    log('hosted backend cannot reach local workspace; falling back to one local mission tick');
+    return finishLocalFallback('workspace_not_on_backend');
   }
 
   // Attempt the paid API tick.
-  const apiPath = improveApiPath(baseFn());
+  const apiPath = improveApiPath(apiBase);
   const body = buildImprovePayload({ ...opts, workspace });
   const apiResult = await apiFn(apiPath, {
     method: 'POST',
@@ -361,7 +787,7 @@ async function runImprove(opts = {}, deps = {}) {
     // Only a real, shipping tick earns a receipt. Plan/delegate/dry-run ship
     // nothing, and an error inside an ok envelope (e.g. "workspace not found")
     // is not a shipped change — none of these should write a scorecard/journal.
-    const shipped = (opts.mode || 'full') === 'full' && !opts.dryRun && !summary.error;
+    const shipped = shippingTick && !summary.error;
     if (!shipped) {
       return { ok: true, source: 'api', summary, scorecardPath: null, journalPath: null, receipt: 'skipped', startedAt, finishedAt };
     }
@@ -382,10 +808,9 @@ async function runImprove(opts = {}, deps = {}) {
   }
 
   const decide = shouldFallbackLocal({ creds, apiResult });
-  if (decide.fallback && opts.fallback) {
-    log(`backend ${decide.reason} — falling back to a local autopilot tick`);
-    const local = localFn({ workspace, json: opts.json, timeoutSec });
-    return { ok: local.ok, source: 'local', reason: decide.reason, local, apiResult, startedAt, finishedAt: now() };
+  if (decide.fallback && localFallbackEligible) {
+    log(`backend ${decide.reason} — falling back to one local mission tick`);
+    return finishLocalFallback(decide.reason, apiResult);
   }
 
   // Real, answerable failure (e.g. insufficient credits, server error). Report it.
@@ -417,9 +842,16 @@ function formatImproveReport(result = {}) {
   }
   if (result.source === 'local') {
     lines.push(result.ok ? 'improved (local fallback).' : 'local fallback tick failed.');
-    lines.push(`  reason:  backend ${result.reason} — ran a local autopilot tick instead`);
-    if (result.local && !result.ok && result.local.stderr) {
-      lines.push(`  error:   ${result.local.stderr.trim().split('\n').slice(-1)[0]}`);
+    lines.push(`  reason:  backend ${result.reason} — ran one local mission tick instead`);
+    if (result.ok) {
+      const s = result.summary || {};
+      lines.push(`  task:    ${s.shipped || '(no description returned)'}`);
+      lines.push(`  verify:  pass`);
+      lines.push(`  reward:  ${s.reward != null ? s.reward : '?'}`);
+      if (s.files && s.files.length) lines.push(`  files:   ${s.files.join(', ')}`);
+      if (result.scorecardPath) lines.push(`  scorecard: ${path.relative(process.cwd(), result.scorecardPath)}`);
+    } else if (result.error) {
+      lines.push(`  error:   ${result.error}`);
     }
     return lines.join('\n');
   }
@@ -430,16 +862,21 @@ function formatImproveReport(result = {}) {
 }
 
 function showHelp() {
-  console.log(`atris improve — run one paid RL improvement tick
+  console.log(`atris improve - show the self-improvement metabolism vitals
 
 Usage:
-  atris improve [mode] [options]
+  atris improve
+  atris improve --json
+  atris improve doctor [--json] [--fix] [--check <kind>]
+  atris improve tick [mode] [options]
+  atris improve [mode|history] [options]
 
 Modes (positional or --mode):
   full        plan + build + verify + score (default)
   plan        return the plan only, no changes
   delegate    queue the tick for a local Claude Code session
   history     show the tick history (reward trend, credits, pass rate)
+  doctor      scan loop receipts and optionally file one repair mission
 
 Options:
   --member <name>  attribute the tick to a member (the loop's owner)
@@ -448,17 +885,183 @@ Options:
   --no-fallback    do not fall back to a local tick if the backend is down
   --workspace <p>  workspace path (default: cwd)
   --timeout <sec>  request timeout in seconds (default: 300)
+  --check <kind>   exit 0 when the doctor finding is absent, or 1 when present
   --json           machine-readable output (for the member loop)
   -h, --help       this help
 
 Calls POST /api/improve, which ships one verifiable change and deducts
 Atris credits per successful tick. Writes a per-tick scorecard to
-.atris/state/scorecards.jsonl. Falls back to a local autopilot tick when
+.atris/state/scorecards.jsonl. Falls back to one local mission tick when
 the backend is unreachable or you are not logged in.`);
 }
 
-async function run(argv = []) {
-  const opts = parseImproveArgs(argv);
+function isBareVitalsArgs(argv = []) {
+  return argv.length === 0 || (argv.length === 1 && argv[0] === '--json');
+}
+
+const LOOP_DOCTOR_OPEN_STATUSES = new Set(['planning', 'ready', 'running', 'paused', 'blocked']);
+
+function loopDoctorKey(finding) {
+  return `[loop-doctor:${finding.kind}]`;
+}
+
+function openLoopDoctorMission(root, finding) {
+  const key = loopDoctorKey(finding);
+  const rows = readJsonlFile(path.join(root, '.atris', 'state', 'missions.jsonl'));
+  const latest = new Map();
+  rows.forEach((row, index) => {
+    const mission = row && row.mission && typeof row.mission === 'object' ? row.mission : row;
+    if (mission && typeof mission === 'object') latest.set(String(mission.id || `row-${index}`), mission);
+  });
+  return [...latest.values()].find((mission) => LOOP_DOCTOR_OPEN_STATUSES.has(String(mission.status || '').toLowerCase())
+    && String(mission.objective || '').includes(key)) || null;
+}
+
+function formatLoopDoctor(findings, fix = null, closed = []) {
+  const lines = [`loop doctor: ${findings.length} finding${findings.length === 1 ? '' : 's'}`];
+  findings.forEach((finding, index) => {
+    lines.push(`${index + 1}. ${finding.kind}: ${finding.evidence.detail} (${finding.count})`);
+    lines.push(`   repair: ${finding.suggested_mission.objective}`);
+  });
+  if (!findings.length) lines.push('the recent improve-loop receipts are clean.');
+  if (fix && fix.action === 'mission_started') lines.push(`filed one mission: ${fix.mission.id}`);
+  if (fix && fix.action === 'mission_exists') lines.push(`no mission filed: ${fix.mission.id} already covers the top finding.`);
+  if (Array.isArray(closed) && closed.length) {
+    lines.push(`credited ${closed.length} verified repair${closed.length === 1 ? '' : 's'}: ${closed.map((row) => row.kind).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+// Close the reward loop the doctor opens. When it files a repair it writes a
+// reward-0 loop_doctor row; the fix only earns once its finding is provably
+// gone. This reconciles those open rows against the current findings: a filed
+// row whose kind no longer fires gets one closing credit, so the scorecard
+// reads filed then paid instead of a pile of zero-reward filings. Deduped by
+// mission id so a finding that clears stays closed even if it flickers back.
+function reconcileLoopDoctorRewards(root, findings, now, appendScorecard) {
+  // Read the raw rows, not readTickHistory: that filters to improve_tick
+  // schema and would drop the loop_doctor rows this reconciliation is about.
+  const rows = readJsonlFile(path.join(expandHome(root), '.atris', 'state', 'scorecards.jsonl'));
+  const openByMission = new Map();
+  const closedMissions = new Set();
+  for (const row of rows) {
+    if (!row || row.schema !== 'atris.loop_doctor.v1' || !row.mission_id) continue;
+    if (row.closed === true) { closedMissions.add(String(row.mission_id)); continue; }
+    if (Number(row.reward) === 0) openByMission.set(String(row.mission_id), row);
+  }
+  const liveKinds = new Set(findings.map((finding) => finding.kind));
+  const closed = [];
+  for (const [missionId, row] of openByMission) {
+    if (closedMissions.has(missionId)) continue;
+    if (liveKinds.has(row.kind)) continue; // finding still fires, repair not proven yet
+    const closingRow = {
+      schema: 'atris.loop_doctor.v1',
+      ts: now.toISOString(),
+      source: 'loop_doctor',
+      kind: row.kind,
+      mission_id: missionId,
+      reward: 3,
+      closed: true,
+      note: 'repair verified: the finding it filed against is no longer present',
+    };
+    appendScorecard(root, closingRow);
+    closedMissions.add(missionId);
+    closed.push(closingRow);
+  }
+  return closed;
+}
+
+function runLoopDoctor(argv = [], deps = {}) {
+  const args = Array.isArray(argv) ? argv : [];
+  const json = args.includes('--json');
+  const fixRequested = args.includes('--fix');
+  const checkIndex = args.indexOf('--check');
+  const checkRequested = checkIndex !== -1;
+  const checkKind = checkRequested ? String(args[checkIndex + 1] || '').trim() : null;
+  const root = process.cwd();
+  const scan = deps.scanLoopReceipts || require('../lib/loop-doctor').scanLoopReceipts;
+  const findings = scan({ root, now: deps.now || new Date() });
+  let fix = null;
+
+  if (checkRequested) {
+    const finding = checkKind && findings.find((item) => item.kind === checkKind);
+    const check = {
+      kind: checkKind,
+      ok: Boolean(checkKind) && !finding,
+      reason: !checkKind ? 'missing finding kind' : (finding ? `${checkKind} is still present` : null),
+    };
+    const payload = { schema: 'atris.loop_doctor.v1', findings, fix, check };
+    if (json) console.log(JSON.stringify(payload));
+    else if (check.ok) console.log(`loop doctor check passed: no ${checkKind} finding.`);
+    else console.log(`loop doctor check failed: ${check.reason}.`);
+    return payload;
+  }
+
+  // Credit any past filing whose finding has since cleared. This runs on plain
+  // `doctor` and `doctor --fix`, never on `--check` (a pure verifier that must
+  // not write), so the reward closes on the next observation after a repair.
+  const reconcileNow = deps.now || new Date();
+  const reconcileAppend = deps.appendScorecardRow || appendScorecardRow;
+  const closed = reconcileLoopDoctorRewards(deps.workspace || root, findings, reconcileNow, reconcileAppend);
+
+  if (fixRequested && findings.length) {
+    const finding = findings[0];
+    const existing = openLoopDoctorMission(root, finding);
+    if (existing) {
+      fix = { action: 'mission_exists', finding_kind: finding.kind, mission: existing };
+    } else {
+      const suggested = finding.suggested_mission;
+      const objective = `${loopDoctorKey(finding)} ${suggested.objective}`;
+      const start = deps.startMission || require('./mission').startMission;
+      const started = start([
+        objective,
+        '--owner', suggested.owner,
+        '--verify', suggested.verifier,
+        '--cadence', suggested.cadence,
+        '--runner', 'auto',
+        '--always-on',
+      ], { silent: true });
+      fix = { action: 'mission_started', finding_kind: finding.kind, mission: started.mission };
+      const workspace = deps.workspace || root;
+      const appendScorecard = deps.appendScorecardRow || appendScorecardRow;
+      appendScorecard(workspace, {
+        schema: 'atris.loop_doctor.v1',
+        ts: (deps.now || new Date()).toISOString(),
+        source: 'loop_doctor',
+        kind: finding.kind,
+        mission_id: started.mission.id,
+        reward: 0,
+        note: 'repair filed; reward is earned by the repair tick, not the filing',
+      });
+    }
+  }
+
+  const payload = { schema: 'atris.loop_doctor.v1', findings, fix, closed };
+  if (json) console.log(JSON.stringify(payload));
+  else console.log(formatLoopDoctor(findings, fix, closed));
+  return payload;
+}
+
+async function run(argv = [], deps = {}) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  if (args[0] === 'doctor') {
+    const result = runLoopDoctor(args.slice(1), deps);
+    return result.check && !result.check.ok ? 1 : 0;
+  }
+  if (isBareVitalsArgs(args)) {
+    const vitals = (deps.collectImproveVitals || collectImproveVitals)({ workspace: process.cwd() }, deps);
+    if (args.includes('--json')) console.log(JSON.stringify(vitals));
+    else console.log(formatImproveVitals(vitals));
+    // Keep the live page in step with what the terminal just said.
+    try {
+      const file = require('../lib/improve-vitals-html').writeVitalsHtml(process.cwd(), deps);
+      if (!args.includes('--json')) console.log(`\nlive page: ${file} (open it once, it refreshes itself)`);
+    } catch { /* page is a bonus, never a failure */ }
+    return 0;
+  }
+
+  const routedArgs = args[0] === 'tick' ? args.slice(1) : args;
+  const opts = parseImproveArgs(routedArgs);
   if (opts.help) { showHelp(); return 0; }
 
   if (opts.history) {
@@ -468,7 +1071,8 @@ async function run(argv = []) {
     return 0;
   }
 
-  const result = await runImprove(opts, {
+  const improveFn = deps.runImprove || runImprove;
+  const result = await improveFn(opts, {
     log: opts.json ? () => {} : (m) => console.error(`  ${m}`),
   });
 
@@ -491,11 +1095,23 @@ module.exports = {
   appendScorecardRow,
   appendTickToJournal,
   expandHome,
+  collectImproveVitals,
+  formatImproveVitals,
+  isBareVitalsArgs,
   readTickHistory,
   summarizeTickHistory,
   formatTickHistory,
   improveApiPath,
   formatImproveReport,
+  runLoopDoctor,
+  reconcileLoopDoctorRewards,
+  formatLoopDoctor,
+  openLoopDoctorMission,
+  loopDoctorKey,
   runLocalFallback,
+  summarizeLocalMissionRun,
+  LOCAL_FALLBACK_ARGS,
+  localFallbackArgs,
   SCORECARD_SCHEMA,
+  IMPROVE_VITALS_SCHEMA,
 };