atris 3.37.1 → 3.40.0

package/lib/accept-verify-gate.js

@@ -0,0 +1,126 @@
+'use strict';
+
+// The accept gate used to check that a task's verify field was non-empty, never
+// that it held something that could fail. An audit on 2026-07-26 found 131 of 802
+// accepted proofs (16.3%) were unfalsifiable at the moment they were signed off:
+// 54 an unfilled template sentence, 55 a bare `git diff --check`, 21 a path into a
+// deleted worktree, 1 a bare file path.
+//
+// This module answers one question before a task may be marked done: does the
+// stored verify command actually run, and does it pass? Parsing and execution reuse
+// lib/auto-accept-certified.js so there is one allow-list, not two.
+
+const { parseVerifyCommand, runVerifyCommandCached } = require('./auto-accept-certified');
+
+// Template text shipped in task scaffolding. Present verbatim in 54 accepted proofs.
+const TEMPLATE_PLACEHOLDERS = [
+  'concrete command, file, receipt, or verifier evidence',
+  'command, file, receipt, or verifier evidence',
+  '<command>',
+  'tbd',
+  'n/a',
+  'none',
+];
+
+// Commands that execute cleanly but cannot fail for the reason the task exists.
+// `git diff --check` reports whitespace and conflict markers; it is green on a
+// commit that deletes the feature. 55 accepted proofs stored exactly this.
+const NON_FALSIFYING_COMMANDS = [
+  /^git\s+diff\s+--check\s*$/i,
+  /^git\s+status\s*$/i,
+  /^git\s+log\b/i,
+  /^ls\b/i,
+  /^true\s*$/i,
+];
+
+function storedVerifyCommand(task) {
+  const metadata = (task && task.metadata) || {};
+  const candidates = [metadata.verify, metadata.latest_agent_verify];
+  for (const candidate of candidates) {
+    const text = String(candidate || '').trim();
+    if (text) return text;
+  }
+  return '';
+}
+
+function placeholderIssue(command) {
+  const lower = command.toLowerCase().trim();
+  if (TEMPLATE_PLACEHOLDERS.some((p) => lower === p || lower.startsWith(p))) {
+    return 'the verify field holds unfilled template text, not a command';
+  }
+  // A bare path is a receipt, not a check. `/tmp/x/proof.json` was one of the 131.
+  if (/^[./~]/.test(command) && !/\s/.test(command)) {
+    return 'the verify field holds a file path, not a command that can fail';
+  }
+  return '';
+}
+
+function nonFalsifyingIssue(command) {
+  if (NON_FALSIFYING_COMMANDS.some((re) => re.test(command.trim()))) {
+    return `\`${command.trim()}\` cannot fail for the reason this task exists — it passes on a commit that deletes the work`;
+  }
+  return '';
+}
+
+// Returns { ok, reason, detail, command, ran, exit_code }.
+// ok:true means the stored command parsed, ran, and exited 0.
+function evaluateAcceptVerify(task, workspaceRoot, { cache = null } = {}) {
+  const command = storedVerifyCommand(task);
+  // A task with no stored verify is out of scope here. Every one of the 131
+  // unfalsifiable proofs HAD a command; the defect is a stored check that cannot
+  // fail, not a missing one. Requiring a verify on every accept is a separate,
+  // larger policy change and blocking it here would only get this gate switched off.
+  if (!command) {
+    return { ok: true, reason: 'no_verify_command', detail: '', command: '', ran: false, unchecked: true };
+  }
+
+  const placeholder = placeholderIssue(command);
+  if (placeholder) return { ok: false, reason: 'verify_placeholder', detail: placeholder, command, ran: false };
+
+  const hollow = nonFalsifyingIssue(command);
+  if (hollow) return { ok: false, reason: 'verify_not_falsifying', detail: hollow, command, ran: false };
+
+  // Two different questions got fused here at first: "can this fail?" and "is this
+  // safe to execute at accept time?". Only the first is this gate's business.
+  // Refusing everything outside the execution allow-list flagged 455 accepted tasks,
+  // and sampling them found ordinary verifiers — `npm run type-check`, `npx vitest
+  // run` — sitting beside real prose. A gate that blocks real work gets switched off.
+  // So: refuse what provably cannot fail, run what can be run safely, and mark the
+  // rest unchecked rather than pretend a judgment we cannot make.
+  const parsed = parseVerifyCommand(command);
+  if (!parsed.ok) {
+    return {
+      ok: true,
+      reason: 'verify_not_runnable_here',
+      detail: `the stored verify command cannot be safely executed at accept time (${parsed.reason || 'unknown'}); it was not checked`,
+      command,
+      ran: false,
+      unchecked: true,
+    };
+  }
+
+  const result = runVerifyCommandCached(command, workspaceRoot, cache);
+  if (!result.ok) {
+    const diffCheck = /^git\s+diff\s+--check\b/i.test(command.trim());
+    const fixHint = diffCheck
+      ? '; trailing whitespace in markdown is auto-fixable: npm run audit:markdown-whitespace -- --fix'
+      : '';
+    return {
+      ok: false,
+      reason: result.reason || 'verify_failed',
+      detail: result.reason === 'verify_workdir_missing' || result.reason === 'verify_worktree_missing'
+        ? 'the stored verify command points at a directory that no longer exists'
+        : `the stored verify command did not pass (${result.reason || 'nonzero exit'})${fixHint}`,
+      command,
+      ran: true,
+      exit_code: typeof result.status === 'number' ? result.status : null,
+    };
+  }
+
+  return { ok: true, reason: 'verify_passed', detail: '', command, ran: true, exit_code: 0 };
+}
+
+module.exports = {
+  storedVerifyCommand,
+  evaluateAcceptVerify,
+};

package/lib/activity-stream.js

@@ -154,13 +154,11 @@ function buildHeartbeat(pulseReceipts, now = Date.now()) {
 }
 
 module.exports = {
-  pickTs,
   clip,
   normalizePulse,
   normalizeScorecard,
   normalizeTaskEpisode,
   normalizeXp,
-  normalizeMissionEvent,
   buildActivityStream,
   buildHeartbeat,
 };

package/lib/arg-parser.js

@@ -0,0 +1,41 @@
+'use strict';
+
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+function unquote(value) {
+  const text = String(value);
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function readFlag(args, name, fallback = '') {
+  const prefix = `${name}=`;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i]);
+    if (arg === name && args[i + 1] && !String(args[i + 1]).startsWith('--')) {
+      return unquote(args[i + 1]);
+    }
+    if (arg.startsWith(prefix)) return unquote(arg.slice(prefix.length));
+  }
+  return fallback;
+}
+
+function readIntFlag(args, name, fallback = null) {
+  const raw = readFlag(args, name, '');
+  if (!raw) return fallback;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) ? value : null;
+}
+
+function readNumberFlag(args, name, fallback = null) {
+  const raw = readFlag(args, name, '');
+  if (!raw) return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+module.exports = { hasFlag, readFlag, readIntFlag, readNumberFlag };

package/lib/auto-accept-certified.js

@@ -13,7 +13,7 @@ const AGENT_CERTIFICATION_REVIEW_PASSES = 2;
 // once powered is gone. Passes alone never land work, an independent
 // reviewer does.
 const AUTO_ACCEPT_HIGH_CONFIDENCE_PASSES = 3;
-const DENIED_TAGS = new Set(['billing', 'deploy', 'feedback', 'security', 'customer', 'external']);
+const DENIED_TAGS = new Set(['billing', 'money', 'payments', 'deploy', 'feedback', 'security', 'customer', 'external']);
 
 const SIMPLE_VERIFY_TOKEN_RE = /^[a-zA-Z0-9_./:@=+-]+$/;
 const GIT_WORKTREE_PATH_RE = /^[a-zA-Z0-9_./@=+-]+$/;
@@ -447,7 +447,41 @@ function isAutoCertifyVerifyCommandAllowed(verify) {
   return parseVerifyCommand(verify).ok;
 }
 
+// Re-entrancy guard: every verify child carries ATRIS_VERIFY_IN_PROGRESS=1
+// (see verifyCommandEnv). A verify that shells back into the CLI and reaches
+// another verify would otherwise recurse without bound — that cycle
+// fork-bombed the fleet on 2026-07-29 when a stored pytest called
+// `atris task status` and the read path re-ran the verify. Refuse loudly.
+const VERIFY_IN_PROGRESS_ENV = 'ATRIS_VERIFY_IN_PROGRESS';
+
+// Spawn cap: a single CLI process has no legitimate reason to run dozens of
+// verifies. Beyond the cap something is looping; refuse and report instead
+// of silently bounding.
+const VERIFY_SPAWN_CAP = 25;
+let verifySpawnCount = 0;
+
+function verifyRefusal(unrunnableCause, extra) {
+  return {
+    ok: false,
+    reason: 'verify_unrunnable',
+    unrunnable_cause: unrunnableCause,
+    alarm: true,
+    ...(extra || {}),
+  };
+}
+
 function runVerifyCommand(verify, workspaceRoot) {
+  if (process.env[VERIFY_IN_PROGRESS_ENV]) {
+    return verifyRefusal('verify_reentrant', {
+      detail: `${VERIFY_IN_PROGRESS_ENV} is set: a verify is already running up the call chain; refusing to nest another one`,
+    });
+  }
+  if (verifySpawnCount >= VERIFY_SPAWN_CAP) {
+    return verifyRefusal('verify_spawn_cap', {
+      detail: `this process already ran ${verifySpawnCount} verifies (cap ${VERIFY_SPAWN_CAP}); refusing more`,
+    });
+  }
+  verifySpawnCount += 1;
   const parsed = parseVerifyCommand(verify);
   if (!parsed.ok) return parsed;
   const cwdCheck = validateCommandCwd(parsed, workspaceRoot);
@@ -458,11 +492,29 @@ function runVerifyCommand(verify, workspaceRoot) {
   if (!pythonPathCheck.ok) return pythonPathCheck;
   const result = spawnSync(parsed.argv[0], parsed.argv.slice(1), {
     cwd: cwdCheck.cwd,
-    env: parsed.env ? { ...process.env, ...parsed.env } : process.env,
+    env: verifyCommandEnv(parsed.env),
     shell: false,
     encoding: 'utf8',
     timeout: 120000,
   });
+  // "I could not run the check" is not "the check failed". Collapsing the two
+  // let a broken harness read as broken code: under cron's PATH every
+  // `npm run ...` verifier returned ENOENT, mapped to verify_failed, and 16
+  // landable tasks were skipped silently every hour for 20 days. A verifier
+  // the harness cannot execute must be loud and must never look like a
+  // verdict on the work.
+  const unrunnable = unrunnableVerifyReason(result);
+  if (unrunnable) {
+    return {
+      ok: false,
+      reason: 'verify_unrunnable',
+      unrunnable_cause: unrunnable,
+      alarm: true,
+      command: parsed.argv.join(' '),
+      status: result.status,
+      stderr: String(result.stderr || '').slice(0, 400),
+    };
+  }
   return {
     ok: result.status === 0,
     reason: result.status === 0 ? 'verify_passed' : 'verify_failed',
@@ -471,6 +523,37 @@ function runVerifyCommand(verify, workspaceRoot) {
   };
 }
 
+// Verifiers run with shell:false, so the child gets no PATH resolution beyond
+// whatever the parent inherited. Cron has no Homebrew PATH — that is why every
+// cron entry hardcodes an absolute node path. `npm`, `npx` and friends live in
+// the same bin directory as the node binary currently executing, so seeding
+// PATH with it makes recorded checks runnable from cron with zero config: no
+// crontab PATH line to keep in sync, no new env var.
+function verifyCommandEnv(extraEnv) {
+  const base = extraEnv ? { ...process.env, ...extraEnv } : { ...process.env };
+  const binDir = path.dirname(process.execPath);
+  const current = String(base.PATH || '');
+  const alreadyPresent = current.split(path.delimiter).includes(binDir);
+  if (binDir && !alreadyPresent) {
+    base.PATH = current ? `${binDir}${path.delimiter}${current}` : binDir;
+  }
+  base[VERIFY_IN_PROGRESS_ENV] = '1';
+  return base;
+}
+
+// ENOENT: the binary is not on PATH at all. ETIMEDOUT: the 120s ceiling cut it
+// off before it could reach a verdict. Neither is evidence about the diff.
+function unrunnableVerifyReason(result) {
+  const code = result && result.error ? result.error.code : null;
+  if (code === 'ENOENT') return 'command_not_found';
+  if (code === 'ETIMEDOUT' || result.signal === 'SIGTERM') return 'verify_timed_out';
+  if (code) return String(code).toLowerCase();
+  // spawnSync reports a null status with no error object when the child was
+  // killed outright; treat that as unrunnable rather than a silent failure.
+  if (result && result.status === null) return 'no_exit_status';
+  return null;
+}
+
 function runVerifyCommandCached(verify, workspaceRoot, cache = null) {
   if (!(cache instanceof Map)) return runVerifyCommand(verify, workspaceRoot);
   const key = `${path.resolve(workspaceRoot || process.cwd())}\u0000${String(verify || '').trim()}`;
@@ -480,6 +563,63 @@ function runVerifyCommandCached(verify, workspaceRoot, cache = null) {
   return { ...result, reused: false };
 }
 
+// Pre-land hygiene: dead exports used to surface only AFTER landing, when the
+// full suite's repo-hygiene ratchet went red on master (lesson:
+// engine-dead-exports — engines export every internal helper, the task's own
+// verify command stays green, and the breakage lands). In repos that carry the
+// ratchet (test/repo-hygiene.test.js), run the same detector before landing so
+// the gate refuses the work instead of master discovering it. Memoized per
+// root: one scan covers every task in a sweep.
+const repoHygieneCache = new Map();
+
+function repoHygieneGate(workspaceRoot) {
+  const root = path.resolve(workspaceRoot || process.cwd());
+  if (repoHygieneCache.has(root)) return repoHygieneCache.get(root);
+  let result = { ok: true, skipped: true };
+  if (fs.existsSync(path.join(root, 'test', 'repo-hygiene.test.js'))) {
+    try {
+      const { findDeadCode, findOrphanedExports, listJsFiles } = require('../commands/slop');
+      const dead = findDeadCode(root).dead;
+      const files = ['commands', 'lib'].flatMap((d) => listJsFiles(path.join(root, d)));
+      const orphans = findOrphanedExports(root, files, listJsFiles(root));
+      const offenders = [
+        ...dead.map((f) => path.relative(root, f)),
+        ...orphans.map((o) => `${path.relative(root, o.file)} → ${o.name}`),
+      ];
+      result = offenders.length
+        ? {
+          ok: false,
+          reason: 'dead_exports',
+          offenders: offenders.slice(0, 12),
+          message: 'this work leaves code or exports nothing uses, so the full test suite fails right after landing; delete the unused pieces and land again.',
+        }
+        : { ok: true };
+    } catch (err) {
+      // "I could not run the detector" is not a verdict on the work — same
+      // rule as verify_unrunnable, but hygiene is a repo-wide ratchet the
+      // suite still enforces, so failing open here only delays the red.
+      result = { ok: true, skipped: true, error: String((err && err.message) || err).slice(0, 200) };
+    }
+  }
+  repoHygieneCache.set(root, result);
+  return result;
+}
+
+// Shared by both landing lanes so the check cannot ship in one dispatch branch
+// and silently skip the sibling (lesson: parallel-paths-drift).
+function hygieneBlockResult(task, ref) {
+  const hygiene = repoHygieneGate(task.workspace_root || process.cwd());
+  if (hygiene.ok) return null;
+  return {
+    eligible: false,
+    ref,
+    reason: hygiene.reason,
+    message: hygiene.message,
+    offenders: hygiene.offenders,
+    next_action: 'run `node --test test/repo-hygiene.test.js` in the workspace, delete what it names, then re-certify',
+  };
+}
+
 function strictVerifyMissingResult(ref) {
   return {
     eligible: false,
@@ -507,6 +647,61 @@ function receiptEvidenceBlock(task, ref) {
   return null;
 }
 
+// Authors declare protected lanes in the task text, not the tag field. Match
+// only explicit, deliberate declarations — an unanchored "security" would
+// snag every task that merely mentions the word and wedge the loop shut,
+// which is its own failure mode. Kept narrow on purpose.
+const PROTECTED_LANE_PHRASES = [
+  'protected lane',
+  'never self-land',
+  'never self land',
+  'do not self-land',
+  'human accepts',
+  'human must accept',
+  'human review required',
+  'orchestrator reviews pre-land',
+  'reviews pre-land',
+];
+
+function declaredProtectedLane(task) {
+  const haystack = [
+    task.title,
+    task.objective,
+    task.metadata && task.metadata.protected_lane_note,
+  ]
+    .map((v) => String(v || ''))
+    .join('\n')
+    .toLowerCase();
+  if (!haystack.trim()) return null;
+  const phrase = PROTECTED_LANE_PHRASES.find((p) => haystack.includes(p));
+  return phrase ? { phrase } : null;
+}
+
+// Only consulted when a task carries no tag at all, so this never overrides an
+// author who did classify their work. Terms are concrete nouns from the denied
+// lanes — things you can only be touching on purpose. Deliberately excludes
+// broad words like "auth", "user", or "api" that appear in ordinary frontend
+// work and would hold the whole queue.
+const PROTECTED_LANE_TERMS = [
+  ['billing', ['stripe', 'checkout url', 'checkout_url', 'invoice', 'paywall', 'subscription', 'wallet', 'credit card', 'pricing tier']],
+  ['security', ['session minting', 'mints a', 'service token', 'api key', 'credential', 'secret key', 'csrf', 'access token']],
+  ['deploy', ['render deploy', 'production deploy', 'deploy to prod', 'migration apply']],
+  ['customer', ['send email to', 'customer email', 'outbound email', 'notify users']],
+];
+
+function sniffedProtectedLane(task) {
+  const haystack = [task.title, task.objective]
+    .map((v) => String(v || ''))
+    .join('\n')
+    .toLowerCase();
+  if (!haystack.trim()) return null;
+  for (const [lane, terms] of PROTECTED_LANE_TERMS) {
+    const term = terms.find((t) => haystack.includes(t));
+    if (term) return { lane, term };
+  }
+  return null;
+}
+
 function evaluateAutoAccept(task, options = {}) {
   const {
     strictVerify = true,
@@ -539,12 +734,47 @@ function evaluateAutoAccept(task, options = {}) {
     tag === d || tag.split(/[^a-z0-9]+/).some((w) => w === d || w.replace(/s$/, '') === d));
   if (deniedTag) return { eligible: false, ref, reason: `denied_tag_${deniedTag}` };
 
+  // A protected lane declared in prose is not a protection, it is a note.
+  // WEB-410 said "PROTECTED LANE: auth/session minting ... never self-land"
+  // in its own title, carried tag 'endgame', and auto-landed anyway. Routing
+  // safety through a tag field that authors leave empty fails open, silently.
+  // So read the declaration where authors actually write it.
+  const declared = declaredProtectedLane(task);
+  if (declared) {
+    return {
+      eligible: false,
+      ref,
+      reason: 'declared_protected_lane',
+      declared_lane: declared.phrase,
+      next_action: 'this task declares a protected lane in its own text; a human accepts it with `atris task accept <ref> --as <human>`',
+    };
+  }
+
   // accept-all: the protected lanes above are the only human gate. No
   // certification, pass-count, reviewer, or proof-quality bar — but work
   // is never marked done against evidence it isn't: a proof naming an
   // unmerged draft PR still blocks, and a recorded check that FAILS still
   // blocks (absence of a check does not).
   if (acceptAll) {
+    // In this lane the tag IS the safety system — the only human gate. But
+    // most rows carry no tag at all (13 of 16 in the 2026-07-25 sweep), so
+    // refusing every untagged task would wedge the loop shut, which is the
+    // same outage as failing open, just quieter. Instead: when there is no
+    // tag to route on, read the task text for the denied lanes themselves.
+    // WEB-406 (Stripe checkout + paywall) landed untagged this way.
+    if (!tag) {
+      const sniffed = sniffedProtectedLane(task);
+      if (sniffed) {
+        return {
+          eligible: false,
+          ref,
+          reason: 'untagged_protected_lane_text',
+          declared_lane: sniffed.lane,
+          matched: sniffed.term,
+          next_action: `no tag to route on and the text reads as the ${sniffed.lane} lane; tag it or accept explicitly as a human`,
+        };
+      }
+    }
     const proof = latestProof(task);
     if (proofHasUnmergedPullRequestBoundary(proof)) {
       return unmergedPullRequestBoundaryResult(ref, proof);
@@ -570,8 +800,12 @@ function evaluateAutoAccept(task, options = {}) {
       // into "lands unchecked" the morning after it clears the worktree.
       // A check that merely isn't in the runnable allowlist counts as no
       // check at all.
+      // verify_unrunnable blocks for the same reason worktree_missing does:
+      // it used to arrive here as verify_failed, so leaving it out would turn
+      // "the harness could not run the check" into "landed unchecked".
       if ((tierRequiresStrictVerify && !verifyResult.ok)
         || verifyResult.reason === 'verify_failed'
+        || verifyResult.reason === 'verify_unrunnable'
         || verifyResult.reason === 'verify_worktree_missing') {
         return { eligible: false, ref, reason: verifyResult.reason, verify, ...verifyResult };
       }
@@ -579,6 +813,19 @@ function evaluateAutoAccept(task, options = {}) {
     if (trustTier === 'probation' && !reviewIntegrity.hasIndependentReview(task)) {
       return { eligible: false, ref, reason: 'probation_needs_review' };
     }
+    // The read-only status path (executeVerify:false) must apply the same
+    // command allowlist the landing gate applies, or status promises a landing
+    // the gate will refuse every hour: five rows read "lands itself" for a
+    // whole night while every tick skipped them as verify_command_not_allowed.
+    // Sits after the probation gate so it reports the gate's own refusal
+    // order, not a new one.
+    if (verify && !executeVerify && !isAutoCertifyVerifyCommandAllowed(verify)) {
+      return { eligible: false, ref, reason: 'verify_command_not_allowed', verify };
+    }
+    if (executeVerify) {
+      const hygieneBlock = hygieneBlockResult(task, ref);
+      if (hygieneBlock) return hygieneBlock;
+    }
     return {
       eligible: true,
       ref,
@@ -646,9 +893,18 @@ function evaluateAutoAccept(task, options = {}) {
       if (!verifyResult.ok) {
         return { eligible: false, ref, reason: verifyResult.reason, verify, ...verifyResult };
       }
+    } else if (!isAutoCertifyVerifyCommandAllowed(verify)) {
+      // Same truth rule as above: the read-only path may not promise a
+      // landing the allowlist will refuse.
+      return { eligible: false, ref, reason: 'verify_command_not_allowed', verify };
     }
   }
 
+  if (executeVerify) {
+    const hygieneBlock = hygieneBlockResult(task, ref);
+    if (hygieneBlock) return hygieneBlock;
+  }
+
   return {
     eligible: true,
     ref,
@@ -663,12 +919,14 @@ function evaluateAutoAccept(task, options = {}) {
 
 module.exports = {
   AGENT_CERTIFICATION_REVIEW_PASSES,
-  AUTO_ACCEPT_HIGH_CONFIDENCE_PASSES,
   DENIED_TAGS,
+  declaredProtectedLane,
+  sniffedProtectedLane,
   evaluateAutoAccept,
   isAutoCertifyVerifyCommandAllowed,
   isAgentCertified,
   parseVerifyCommand,
+  repoHygieneGate,
   runVerifyCommand,
   runVerifyCommandCached,
 };

package/lib/autoland.js

@@ -120,6 +120,66 @@ function liveAcceptAuthorization(root = process.cwd()) {
   return { ok: true, actor, policy: 'autoland', strictVerify: policy.strict_verify !== false };
 }
 
+// Tick receipts are local file reads and prove the loop ran. A receipt from
+// the last couple of hours means the hourly pass is alive; older or missing
+// means surfaces must not promise "next tick" landing.
+const HEARTBEAT_LIVE_HOURS = 2;
+const STALE_HEARTBEAT_LANDING = 'once the hourly heartbeat runs (start one with atris autoland tick)';
+
+function lastTickAgeHours(root) {
+  try {
+    const runsDir = path.join(root, 'atris', 'runs');
+    const newest = fs.readdirSync(runsDir)
+      .filter((f) => f.startsWith('autoland-tick-') && f.endsWith('.json'))
+      .sort()
+      .pop();
+    if (!newest) return null;
+    const stamp = fs.statSync(path.join(runsDir, newest)).mtimeMs;
+    return (Date.now() - stamp) / 3_600_000;
+  } catch {
+    return null;
+  }
+}
+
+function heartbeatIsLive(root) {
+  const ageHours = lastTickAgeHours(root);
+  return ageHours !== null && ageHours <= HEARTBEAT_LIVE_HOURS;
+}
+
+function heartbeatLiveness(root, policy) {
+  return typeof policy?.heartbeat_installed === 'boolean' ? policy.heartbeat_installed : null;
+}
+
+function heartbeatStatusText(root, policy) {
+  const ageHours = lastTickAgeHours(root);
+  const ageText = ageHours === null
+    ? null
+    : ageHours < 1 ? 'under an hour' : `${Math.floor(ageHours)}h`;
+  // Evidence first: a receipt from the last couple of hours proves the loop is
+  // alive no matter what the policy file remembers. The hourly cron makes two
+  // missed hours an outage rather than jitter — and a heartbeat that has gone
+  // quiet is the single most useful thing this line can say, because that is
+  // the state nobody notices.
+  if (ageHours !== null && ageHours <= HEARTBEAT_LIVE_HOURS) return `running hourly (last tick ${ageText} ago)`;
+  if (ageHours !== null) return `SILENT - last tick ${ageText} ago; run atris autoland tick`;
+  const installed = heartbeatLiveness(root, policy);
+  if (installed === false) return 'not installed - run atris autoland on';
+  if (installed === true) return 'installed, but no tick has ever run - run atris autoland tick';
+  return 'unknown - run atris autoland on to check and repair';
+}
+
+// Operator-facing schedule: only promise "next tick" when a recent receipt
+// proves the loop is alive. Otherwise name the honest gate.
+function whenAutolandLands(root) {
+  return heartbeatIsLive(root) ? 'on the next tick' : STALE_HEARTBEAT_LANDING;
+}
+
+function certifiedWorkLandsPhrase(root) {
+  return heartbeatIsLive(root)
+    ? 'certified work lands itself'
+    : `certified work lands ${STALE_HEARTBEAT_LANDING}`;
+}
+
 function cronMarker(root) {
   const slug = path.basename(root).replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase();
   return `ATRIS_AUTOLAND_${slug}`;
@@ -654,22 +714,25 @@ function sendImessage(root, to, text) {
 module.exports = {
   DEFAULT_ALARM_HOURS,
   DEFAULT_DIGEST_HOUR,
+  STALE_HEARTBEAT_LANDING,
   acceptedInLastDay,
   buildCronLine,
+  certifiedWorkLandsPhrase,
   clarify,
   composeAlarm,
   composeDigest,
   composeLiveUpdate,
   cronInstalled,
-  cronMarker,
   dueForAlarm,
   digestLine,
   dejargon,
   explainResult,
+  heartbeatIsLive,
+  heartbeatLiveness,
+  heartbeatStatusText,
   installCron,
   liveAcceptAuthorization,
   markAlerted,
-  missionDigestLine,
   operatorReady,
   hasAgentJargon,
   voicePatterns: Object.freeze({
@@ -685,8 +748,8 @@ module.exports = {
   sendImessage,
   statePath,
   uninstallCron,
-  waitingHours,
   waitingOnHuman,
+  whenAutolandLands,
   writePolicy,
   writeState,
 };