@arjunkhera/atlas 0.4.52 → 0.4.54

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.52",
+  "version": "0.4.54",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/.mcp.json

@@ -3,7 +3,7 @@
     "atlas-work": {
       "command": "node",
       "args": [
-        "${CLAUDE_PLUGIN_ROOT}/work/mcp.mjs"
+        "${CLAUDE_PLUGIN_ROOT}/work/start.mjs"
       ],
       "env": {
         "ATLAS_ENGRAM": "",

package/door/cli.mjs

@@ -155,6 +155,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       --json                           print the whole answer as JSON
   atlas runner claim --repo <owner/name> --issue <n> --holder <run id>   claim one atlas-job issue; the oldest live claim holds it
   atlas runner line --from <file>      print the last line of a run, from a JSON file of ids and counts
+      --notice                         print the comment that hands the run facts to the notice workflow
+  atlas runner notice --repo <owner/name> --issue <n> --comment <id>   in the notice workflow only: post the run line of one run comment as the bot
                                        Until the A2 exit test, the runner works on the scratch repo only
 
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, stale pages, and in a pull request its tracker item, its changed designs and STE on its changed lines
@@ -236,7 +238,7 @@ export const FLAGS = Object.freeze({
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
-  runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', json: 'switch' },
+  runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', comment: 'value', notice: 'switch', json: 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', from: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
   approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
@@ -497,7 +499,7 @@ function jobsVerb(chosen) {
 }
 
 function runnerVerb(chosen) {
-  return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+  return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, comment: chosen.comment, notice: Boolean(chosen.notice), json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
 }
 
 function upkeepVerb(chosen) {

package/door/lib/install.mjs

@@ -9,7 +9,7 @@
 // Code to add the catalog and install the plugin. It writes no settings file.
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -332,6 +332,51 @@ export function notesLines({ gh, repo, from, to }) {
   return out;
 }
 
+// Every entry under root is a plain file or a folder. A link would make the
+// file walk read what it points at (security review of item ade7d96a).
+export function onlyPlainEntries(root) {
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const stat = lstatSync(join(dir, entry));
+      if (stat.isDirectory()) { if (!walk(join(dir, entry))) return false; } else if (!stat.isFile()) return false;
+    }
+    return true;
+  };
+  return walk(root);
+}
+
+// Pack one release from npm into `work` and prove it: the integrity that npm
+// records, a release run record of this exact tarball on a master commit that
+// was once the tip, and every file equal to that commit with the version
+// stamped. The upgrade and the cloud refresh share it (item ade7d96a). It
+// returns the lines of a refusal, or the files, the tarball path and the run.
+// The package folder holds no file until the proof passed: the caller copies
+// `unpacked` only after it.
+export function provenRelease({ name, version, repo, gh, exec, work, line = () => {} }) {
+  const integrity = exec('npm', ['view', `${name}@${version}`, 'dist.integrity']).trim();
+  exec('npm', ['pack', `${name}@${version}`, '--pack-destination', work]);
+  const tarballName = readdirSync(work).find((entry) => entry.endsWith('.tgz'));
+  if (!tarballName) throw new Error('npm pack wrote no tarball');
+  const tarball = join(work, tarballName);
+  const bytes = readFileSync(tarball);
+  if (sha512Integrity(bytes) !== integrity) return { code: 'integrity', refused: ['Refused: the tarball does not match the integrity npm records.'] };
+  const { run, commit, problem, code } = findRelease({ gh, repo, version, sha256: createHash('sha256').update(bytes).digest('hex') });
+  if (problem) return { code, refused: [`Refused: ${problem}. It may have been published from a branch.`] };
+  line(`  tag v${version}, recorded by release run ${run.id}, on master commit ${commit.slice(0, 12)}`);
+  const unpacked = join(work, 'unpacked');
+  mkdirSync(unpacked);
+  exec('tar', ['-xzf', tarball, '-C', unpacked]);
+  if (!onlyPlainEntries(unpacked)) return { code: 'special-entry', refused: ['Refused: the tarball holds a link or another entry that is not a plain file.'] };
+  const files = filesUnder(join(unpacked, 'package'));
+  const tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${commit}?recursive=1`]).tree;
+  let stamped;
+  try { stamped = stampedBlobs({ gh, repo, commit, version }); } catch (error) { return { code: 'stamp', refused: [`Refused: the version files of that commit cannot take the stamp: ${error.message}`] }; }
+  const problems = matchTree({ tree, files, stamped });
+  if (problems.length) return { code: 'files', refused: ['Refused: the tarball is not the commit that run built.', ...problems.slice(0, 20).map((problem) => `  ${problem}`)] };
+  line(`  every one of ${files.size} files matches that commit`);
+  return { files, tarball, unpacked: join(unpacked, 'package'), run, commit };
+}
+
 export async function upgrade({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec, ask = defaultAsk }) {
   const { name, version: installed } = packageJson(packageRoot);
   const repo = repoOf(packageRoot);
@@ -339,34 +384,13 @@ export async function upgrade({ packageRoot, options = {}, line = console.log, e
   const target = options.version && options.version !== true ? String(options.version) : exec('npm', ['view', name, 'version']).trim();
   if (!EXACT_VERSION.test(target)) throw new Error(`npm answered "${target}", which is not a version`);
   if (target === installed) { line(`Atlas ${installed} is the newest release. Nothing to do.`); return 0; }
-  const integrity = exec('npm', ['view', `${name}@${target}`, 'dist.integrity']).trim();
-
   line(`Atlas ${installed} → ${target}`);
 
   const work = mkdtempSync(join(tmpdir(), 'atlas-upgrade-'));
   try {
-    exec('npm', ['pack', `${name}@${target}`, '--pack-destination', work]);
-    const tarball = readdirSync(work).find((entry) => entry.endsWith('.tgz'));
-    if (!tarball) throw new Error('npm pack wrote no tarball');
-    const bytes = readFileSync(join(work, tarball));
-    if (sha512Integrity(bytes) !== integrity) { line('Refused: the tarball does not match the integrity npm records.'); return 1; }
-    const { run, commit, problem } = findRelease({ gh, repo, version: target, sha256: createHash('sha256').update(bytes).digest('hex') });
-    if (problem) { line(`Refused: ${problem}. It may have been published from a branch.`); return 1; }
-    line(`  tag v${target}, recorded by release run ${run.id}, on master commit ${commit.slice(0, 12)}`);
-    const unpacked = join(work, 'unpacked');
-    mkdirSync(unpacked);
-    exec('tar', ['-xzf', join(work, tarball), '-C', unpacked]);
-    const files = filesUnder(join(unpacked, 'package'));
-    const tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${commit}?recursive=1`]).tree;
-    let stamped;
-    try { stamped = stampedBlobs({ gh, repo, commit, version: target }); } catch (error) { line(`Refused: the version files of that commit cannot take the stamp: ${error.message}`); return 1; }
-    const problems = matchTree({ tree, files, stamped });
-    if (problems.length) {
-      line('Refused: the tarball is not the commit that run built.');
-      for (const problem of problems.slice(0, 20)) line(`  ${problem}`);
-      return 1;
-    }
-    line(`  every one of ${files.size} files matches that commit`);
+    const proven = provenRelease({ name, version: target, repo, gh, exec, work, line });
+    if (proven.refused) { for (const text of proven.refused) line(text); return 1; }
+    const { files, tarball } = proven;
     line('');
     for (const text of notesLines({ gh, repo, from: installed, to: target })) line(text);
 
@@ -376,7 +400,7 @@ export async function upgrade({ packageRoot, options = {}, line = console.log, e
     line('');
     if (!options.yes && !(await ask(`Install Atlas ${target}?`))) { line('Nothing was changed.'); return 1; }
 
-    exec('npm', ['install', '-g', '--ignore-scripts', join(work, tarball)]);
+    exec('npm', ['install', '-g', '--ignore-scripts', tarball]);
     writeFileSync(catalogFile(env), `${JSON.stringify(catalogFor({ name, version: target }), null, 2)}\n`);
     exec('claude', ['plugin', 'marketplace', 'update', CATALOG_NAME]);
     exec('claude', ['plugin', 'update', PLUGIN_ID]);

package/door/lib/refresh-judge.mjs

@@ -0,0 +1,132 @@
+// The loaded copy judges the merges before a refresh moves (item ade7d96a;
+// the owner picked "1: The loaded copy judges" on 31 October 2026, decision
+// 6869a363). The push audit workflow runs the code of the commit it judges,
+// so a push can change what it says. Here the loaded Atlas, which this
+// session already trusts, judges each first-parent commit of master after
+// the loaded release, up to the new release commit. Each commit passes three
+// checks, each in a process or call of its own, all at the same time:
+//   1. `atlas gate audit --commit`: a pull request merged it after its
+//      required checks were green, and each gate run came from the base copy.
+//   2. `atlas gate hold --commit <sha> --from <its parent>`: the gate judges
+//      the merge again and must say success, or the owner signed an act for
+//      it. An owner or a red answer holds (security re-review of #292, S1).
+//   3. The pull request that merged it targeted master.
+//
+// refresh.mjs starts this file as its own process group before the release
+// proof, so the two run at the same time. The arguments are one JSON object:
+// { repo, fromCommit, toCommit, work, deadline }; the clone goes in
+// work/clone. At the deadline (epoch ms) the judge ends its whole process
+// group. It prints one JSON line:
+// { code: null } when each merge is green, or { code, commits }.
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { mkdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// More merges than this since the loaded release are too many to judge in
+// the start time. The refresh keeps the copy and says so.
+export const MAX_MERGES = 8;
+const CALL_MS = 10_000;
+const HOLD_EXIT = 3;
+const FETCH_MS = 30_000;
+// The folder of the package in the repo, and how far back the start may move.
+export const PACKAGE_DIR = 'packages/atlas';
+const MAX_LOOK_BACK = 200;
+const SHA = /^[0-9a-f]{40}$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const bin = fileURLToPath(new URL('../../bin/atlas', import.meta.url));
+
+const git = (clone, args, timeout = CALL_MS) => execFileSync('git', ['-C', clone, ...args], { encoding: 'utf8', timeout, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+const has = (clone, sha) => { try { git(clone, ['cat-file', '-e', `${sha}^{commit}`]); return true; } catch { return false; } };
+
+// The commits to judge, oldest first, from a full clone of master: a gate
+// judgement needs the merge base of each pull request, so the clone is never
+// shallow.
+export function mergesSince({ repo, fromCommit, toCommit, clone, remote = `https://github.com/${repo}.git` }) {
+  mkdirSync(clone, { recursive: true });
+  git(clone, ['init', '-q']);
+  git(clone, ['-c', 'credential.helper=', '-c', 'credential.helper=!gh auth git-credential', 'fetch', '-q', '--no-tags', remote, '+refs/heads/master:refs/remotes/origin/master'], FETCH_MS);
+  if (!has(clone, fromCommit) || !has(clone, toCommit)) return { code: 'audit-silent' };
+  // The loaded release must sit on the first-parent line of the new one.
+  const line = git(clone, ['rev-list', '--first-parent', '--reverse', toCommit]).split('\n').filter(Boolean);
+  let at = line.indexOf(fromCommit);
+  if (at < 0) return { code: 'audit-silent' };
+  // A tag can move to a later commit with the same package files, so the
+  // range starts where those files first appeared on the line: each commit
+  // after that is judged (security re-review of #292, S1).
+  const treeOf = (sha) => { try { return git(clone, ['rev-parse', '--verify', '-q', `${sha}:${PACKAGE_DIR}`]); } catch { return null; } };
+  const loaded = treeOf(fromCommit);
+  if (!loaded) return { code: 'audit-silent' };
+  let steps = 0;
+  while (at > 0 && treeOf(line[at - 1]) === loaded) {
+    at -= 1;
+    steps += 1;
+    if (steps > MAX_LOOK_BACK) return { code: 'audit-silent' };
+  }
+  const commits = line.slice(at + 1);
+  if (!commits.length || commits.at(-1) !== toCommit) return { code: 'audit-silent' };
+  if (commits.length > MAX_MERGES) return { code: 'audit-many' };
+  return { commits: commits.map((sha) => ({ sha, parent: git(clone, ['rev-parse', '--verify', `${sha}^1`]) })) };
+}
+
+// One program run; its exit code, or 2 when it could not run.
+function exitOf(run, args, env) {
+  return new Promise((done) => {
+    const child = run(process.execPath, [bin, ...args], { env, stdio: 'ignore' });
+    child.on('error', () => done(2));
+    child.on('exit', (code) => done(code ?? 2));
+  });
+}
+
+// The base branch of the pull request that merged `sha`, or null.
+export function mergedInto({ repo, sha, env }) {
+  return new Promise((done) => {
+    execFile('gh', ['api', '--method', 'GET', `repos/${repo}/commits/${sha}/pulls`], { encoding: 'utf8', timeout: CALL_MS, env, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+      if (error) return done(null);
+      try {
+        const pull = (JSON.parse(stdout) ?? []).find((each) => each?.merged_at && each.merge_commit_sha === sha);
+        done(typeof pull?.base?.ref === 'string' ? pull.base.ref : null);
+      } catch { done(null); }
+    });
+  });
+}
+
+// Each commit at the same time. Its state is green, red or unread.
+export function judgeAll({ repo, clone, commits, env, run = spawn, base = mergedInto }) {
+  return Promise.all(commits.map(async ({ sha, parent }) => {
+    const [audit, hold, into] = await Promise.all([
+      exitOf(run, ['gate', 'audit', '--repo', repo, '--commit', sha, '--root', clone], env),
+      exitOf(run, ['gate', 'hold', '--repo', repo, '--commit', sha, '--from', parent, '--root', clone], env),
+      base({ repo, sha, env }),
+    ]);
+    if (audit === 1 || hold === HOLD_EXIT || (into !== null && into !== 'master')) return { sha, state: 'red' };
+    if (audit !== 0 || hold !== 0 || into === null) return { sha, state: 'unread' };
+    return { sha, state: 'green' };
+  }));
+}
+
+export async function judgeMerges({ repo, fromCommit, toCommit, clone, env = process.env, run, base, remote }) {
+  if (!REPO.test(String(repo)) || !SHA.test(String(fromCommit)) || !SHA.test(String(toCommit))) return { code: 'audit-silent' };
+  let found;
+  try { found = mergesSince({ repo, fromCommit, toCommit, clone, ...(remote ? { remote } : {}) }); } catch { return { code: 'audit-silent' }; }
+  if (found.code) return found;
+  const results = await judgeAll({ repo, clone, commits: found.commits, env, ...(run ? { run } : {}), ...(base ? { base } : {}) });
+  // A red audit, a held merge, or a merge into another branch is red. Any
+  // other failure means a check could not judge, never that it is green.
+  const red = results.filter((one) => one.state === 'red').map((one) => one.sha);
+  if (red.length) return { code: 'audit-judged-red', commits: red };
+  if (results.some((one) => one.state !== 'green')) return { code: 'audit-silent' };
+  return { code: null, commits: found.commits.map((one) => one.sha) };
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  let answer;
+  try {
+    const args = JSON.parse(process.argv[2] ?? '{}');
+    // The judge's own deadline: it ends itself and each check it started.
+    const left = Number(args.deadline) - Date.now();
+    setTimeout(() => { try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(2); } }, Number.isFinite(left) ? Math.max(left, 0) : 0).unref();
+    answer = await judgeMerges({ repo: args.repo, fromCommit: args.fromCommit, toCommit: args.toCommit, clone: join(String(args.work), 'clone') });
+  } catch { answer = { code: 'audit-silent' }; }
+  process.stdout.write(`${JSON.stringify(answer)}\n`);
+}

package/door/lib/refresh.mjs

@@ -0,0 +1,320 @@
+// The cloud refresh (item ade7d96a; the owner picked "C: Atlas refreshes
+// itself" and "1: Wait for a green push audit" on 31 October 2026, decisions
+// b929c81d and 9e9615f1). The cloud saves the result of its setup script as a
+// checkpoint, and a new session starts from that checkpoint, so a new session
+// can load an old Atlas. At the start of each cloud session, work/start.mjs
+// runs this file as its own process, with the short child environment: never
+// the Engram key. It moves the loaded plugin folder to the newest release on
+// npm, and only to a release that the release proof and the push audit
+// accept. On any failure it keeps the folder it has.
+//
+// Design: docs/design-docs/cloud-self-refresh/.
+//
+// The rules:
+// 1. Only in a Claude cloud session, only for a copy under
+//    ~/.claude/plugins/cache/, and never with ATLAS_REFRESH=off.
+// 2. Only forward: npm must name a newer version than the loaded one.
+// 3. The release proof is the upgrade's: provenRelease in install.mjs.
+// 4. The push audit approves the release: its run on the release commit, and
+//    each of its runs on a master commit after the loaded release, ended in
+//    success, and no gate-audit or gate-files issue is open.
+// 4a. The loaded copy judges too (the owner's pick of 31 October, decision
+//    6869a363): refresh-judge.mjs runs this copy's own `atlas gate audit` on
+//    each of those commits, at the same time as the proof. The workflow runs
+//    the code it judges, so its green alone is not enough.
+// 5. The folder is written from the checked bytes, and a tarball with a link
+//    or another special entry is refused.
+// 6. The swap is two renames on one disk. A failed second rename puts the old
+//    folder back.
+// 7. The record holds fixed codes, versions, run ids, commits and issue
+//    numbers only: no text from npm or GitHub reaches the lead.
+import { execFileSync, spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, cpSync, openSync, closeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newer, onlyPlainEntries, provenRelease, proveCopy, repoOf, tagCommit } from './install.mjs';
+import { childEnvironment } from '../../work/lib/child-env.mjs';
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+const SHA = /^[0-9a-f]{40}$/;
+// The refresh before the swap may take this long. Each program call has its
+// own limit too, so one call that hangs cannot hold the session.
+export const BUDGET_MS = 20_000;
+// With MCP_TIMEOUT set in the cloud environment, work/start.mjs gives the
+// refresh a longer budget in ATLAS_REFRESH_BUDGET_MS. It is never shorter
+// than BUDGET_MS and never longer than MAX_BUDGET_MS.
+export const MAX_BUDGET_MS = 100_000;
+export function budgetOf(env) {
+  const asked = Number(env.ATLAS_REFRESH_BUDGET_MS);
+  return Number.isInteger(asked) ? Math.min(Math.max(asked, BUDGET_MS), MAX_BUDGET_MS) : BUDGET_MS;
+}
+export const CALL_MS = 10_000;
+// Claude Code writes this marker into a plugin copy that is in use.
+const IN_USE = '.in_use';
+// A lock older than this is left from a process that died.
+const STALE_LOCK_MS = 5 * 60_000;
+export const AUDIT_WORKFLOW = 'atlas-gate-audit.yml';
+export const AUDIT_LABELS = Object.freeze(['job:gate-audit', 'job:gate-files']);
+
+// Each reason the refresh can give, in fixed words. The lead says the words;
+// the record holds only the code and typed values.
+export const REASONS = Object.freeze({
+  'not-cloud': 'not a cloud session',
+  off: 'ATLAS_REFRESH=off',
+  'not-in-cache': 'the loaded copy is not in ~/.claude/plugins/cache/',
+  'no-package': 'the loaded package.json could not be read',
+  locked: 'another refresh runs',
+  'npm-silent': 'npm did not give the newest version',
+  'npm-odd': 'npm did not answer with a version',
+  integrity: 'the tarball does not match the integrity npm records',
+  'no-tag': 'no tag names the release commit',
+  'not-on-master': 'the release commit is not on master',
+  'never-tip': 'the release commit was never the tip of master',
+  'no-record': 'no master release run recorded this tarball',
+  stamp: 'the version files of the release commit cannot take the stamp',
+  files: 'the tarball is not the commit that its release run built',
+  'proof-stopped': 'the release proof stopped: GitHub or npm did not answer',
+  'audit-pending': 'the push audit of the release has not finished',
+  'audit-red': 'a push audit run since the loaded release did not end in success',
+  'audit-issue': 'an audit issue is open',
+  'audit-silent': 'GitHub did not give every push audit run or issue',
+  'audit-judged-red': 'the loaded Atlas judged a merge since the loaded release as red',
+  'audit-many': 'too many merges came after the loaded release to judge at the start',
+  'no-from-tag': 'no tag names the commit of the loaded release, so the audit cannot find the range',
+  'from-unproven': 'the loaded copy is not proven to be the release that its tag names, so the range of new merges is not known',
+  'special-entry': 'the tarball holds a link or another entry that is not a plain file',
+  timeout: 'the refresh used up its start time (MCP_TIMEOUT gives it more)',
+  'swap-failed': 'the swap failed, and the old folder is back',
+  stopped: 'the refresh stopped',
+});
+
+const JUDGE_FILE = fileURLToPath(new URL('./refresh-judge.mjs', import.meta.url));
+
+// Start the loaded copy's judge of the merges as its own process group. The
+// refresh runs only in a cloud session, so the judge and each audit it starts
+// keep the cloud proxy that their `gh` needs (child-env.mjs). It
+// gives { wait(deadline), stop() }: wait blocks until the judge answers or
+// the deadline passes, and stop ends the judge and each audit it started.
+export function startJudge({ repo, fromCommit, toCommit, work, env, deadline, now = Date.now }) {
+  const out = join(work, 'judge.json');
+  const fd = openSync(out, 'w');
+  let child;
+  try { child = spawn(process.execPath, [JUDGE_FILE, JSON.stringify({ repo, fromCommit, toCommit, work, deadline })], { env: { ...childEnvironment(env), CLAUDE_CODE_REMOTE: 'true' }, stdio: ['ignore', fd, 'ignore'], detached: true }); } finally { closeSync(fd); }
+  child.unref();
+  const stop = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* it ended */ } };
+  const cell = new Int32Array(new SharedArrayBuffer(4));
+  const wait = (deadline) => {
+    for (;;) {
+      const text = readFileSync(out, 'utf8');
+      if (text.endsWith('\n')) { try { return JSON.parse(text); } catch { return { code: 'audit-silent' }; } }
+      if (now() >= deadline) { stop(); return { code: 'timeout' }; }
+      Atomics.wait(cell, 0, 0, 100);
+    }
+  };
+  return { wait, stop };
+}
+
+export const refreshFile = (env) => join(env.HOME, '.atlas', 'refresh.json');
+
+function childExec(env) {
+  return (command, args) => execFileSync(command, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: CALL_MS, stdio: ['pipe', 'pipe', 'pipe'], env: childEnvironment(env) });
+}
+
+// Is packageRoot the installed copy that Claude Code loads, and not a working
+// tree, a test copy or a dev copy? Real paths on both sides.
+export function inPluginCache(packageRoot, env) {
+  if (typeof env.HOME !== 'string' || !env.HOME) return false;
+  try {
+    const cache = realpathSync(join(env.HOME, '.claude', 'plugins', 'cache'));
+    return realpathSync(packageRoot).startsWith(cache + sep);
+  } catch { return false; }
+}
+
+// The push audit approves the release (the owner's answer to the S1). It
+// returns null, or a refusal with its code and typed values.
+export function auditApproves({ gh, repo, fromCommit, toCommit }) {
+  // Only runs made since the loaded release: one page holds them, and a
+  // count above the page means a run was not read, so the refresh refuses.
+  const since = gh(['api', '--method', 'GET', `repos/${repo}/commits/${fromCommit}`]).commit?.committer?.date;
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(String(since))) return { code: 'audit-silent', runs: [] };
+  const page = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/${AUDIT_WORKFLOW}/runs?branch=master&event=push&per_page=100&created=${encodeURIComponent(`>=${since.slice(0, 10)}`)}`]);
+  const runs = page.workflow_runs ?? [];
+  if (!Number.isInteger(page.total_count) || page.total_count > runs.length) return { code: 'audit-silent', runs: [] };
+  const ours = runs.filter((run) => run.event === 'push' && run.head_branch === 'master' && run.path === `.github/workflows/${AUDIT_WORKFLOW}`);
+  const judge = (list) => {
+    const open = list.filter((run) => run.status !== 'completed');
+    if (open.length) return { code: 'audit-pending', runs: open.map((run) => run.id) };
+    const red = list.filter((run) => run.conclusion !== 'success');
+    if (red.length) return { code: 'audit-red', runs: red.map((run) => run.id) };
+    return null;
+  };
+  const target = ours.filter((run) => run.head_sha === toCommit);
+  if (!target.length) return { code: 'audit-pending', runs: [] };
+  const targetVerdict = judge(target);
+  if (targetVerdict) return targetVerdict;
+  // Each push after the loaded release has its own audit run. The compare
+  // lists at most 250 commits; a longer range is refused, never guessed.
+  const compare = gh(['api', '--method', 'GET', `repos/${repo}/compare/${fromCommit}...${toCommit}`]);
+  const listed = compare.commits ?? [];
+  if (!Number.isInteger(compare.total_commits) || compare.total_commits > listed.length) return { code: 'audit-silent', runs: [] };
+  const between = new Set(listed.map((commit) => commit.sha));
+  const verdict = judge(ours.filter((run) => between.has(run.head_sha)));
+  if (verdict) return verdict;
+  const issues = [];
+  for (const label of AUDIT_LABELS) {
+    for (const issue of gh(['api', '--method', 'GET', `repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}&per_page=20`]) ?? []) {
+      if (Number.isInteger(issue.number) && !issues.includes(issue.number)) issues.push(issue.number);
+    }
+  }
+  return issues.length ? { code: 'audit-issue', issues } : null;
+}
+
+// Write the checked bytes into `next`, with the file modes of the unpacked
+// tarball, so an executable stays executable.
+export function writeFolder({ files, unpacked, next }) {
+  rmSync(next, { recursive: true, force: true });
+  for (const [path, bytes] of files) {
+    const target = join(next, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, bytes);
+    chmodSync(target, statSync(join(unpacked, path)).mode & 0o755);
+  }
+}
+
+// Put the folder `next` where `packageRoot` is. Two renames on one disk; when
+// the second fails, the first is undone.
+export function swapFolder({ packageRoot, next, rename = renameSync }) {
+  const old = `${packageRoot}.old`;
+  rmSync(old, { recursive: true, force: true });
+  rename(packageRoot, old);
+  try { rename(next, packageRoot); } catch (error) {
+    rename(old, packageRoot);
+    throw error;
+  }
+  rmSync(old, { recursive: true, force: true });
+}
+
+function takeLock(lock, now) {
+  try { mkdirSync(lock); return true; } catch {
+    // A stale lock moves aside under a name of this process first, so two
+    // processes cannot both clear it and both take it.
+    try {
+      if (now() - statSync(lock).mtimeMs > STALE_LOCK_MS) {
+        const aside = `${lock}.stale-${process.pid}`;
+        renameSync(lock, aside);
+        rmSync(aside, { recursive: true, force: true });
+        mkdirSync(lock);
+        return true;
+      }
+    } catch { /* another process has it */ }
+    return false;
+  }
+}
+
+// One refresh. It returns a record: state moved, current, kept or skipped,
+// with from, to, a code and typed values. It never throws.
+export function refresh({ packageRoot, env = process.env, exec = childExec(env), now = Date.now, rename = renameSync, judge = startJudge, proveFrom = proveCopy }) {
+  const started = now();
+  const budget = budgetOf(env);
+  let from = null;
+  let to = null;
+  const done = (state, extra = {}) => ({ state, from, to, ...extra, seconds: Math.round((now() - started) / 100) / 10, at: new Date(now()).toISOString() });
+  const kept = (code, extra = {}) => done('kept', { code, ...extra });
+  if (env.CLAUDE_CODE_REMOTE !== 'true') return done('skipped', { code: 'not-cloud' });
+  if (env.ATLAS_REFRESH === 'off') return done('skipped', { code: 'off' });
+  if (!inPluginCache(packageRoot, env)) return done('skipped', { code: 'not-in-cache' });
+  let name;
+  try {
+    ({ name, version: from } = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')));
+    if (!EXACT_VERSION.test(from)) throw new Error('no version');
+  } catch { from = null; return kept('no-package'); }
+  const lock = `${packageRoot}.refresh-lock`;
+  if (!takeLock(lock, now)) return kept('locked');
+  const work = mkdtempSync(join(tmpdir(), 'atlas-refresh-'));
+  const next = `${packageRoot}.next`;
+  let judged = null;
+  try {
+    let newest;
+    try { newest = exec('npm', ['view', name, 'version']).trim(); } catch { return kept('npm-silent'); }
+    if (!EXACT_VERSION.test(newest)) return kept('npm-odd');
+    if (!newer(newest, from)) return done('current', { to: from });
+    to = newest;
+    const repo = repoOf(packageRoot);
+    const gh = (args) => JSON.parse(exec('gh', args));
+    // The range to judge: the commits of the two tags. The loaded copy
+    // starts to judge it now, while the proofs run. Anyone who can push can
+    // move a tag, so the start must be the commit that the loaded copy's own
+    // proof finds (security re-review of #292, S1).
+    let fromCommit;
+    let toCommit;
+    try { fromCommit = tagCommit(gh, repo, from); toCommit = tagCommit(gh, repo, to); } catch { return kept('audit-silent'); }
+    if (!SHA.test(fromCommit ?? '')) return kept('no-from-tag');
+    if (SHA.test(toCommit ?? '')) judged = judge({ repo, fromCommit, toCommit, work, env, deadline: started + budget, now });
+    let loaded;
+    try { loaded = proveFrom({ packageRoot, exec }); } catch { loaded = null; }
+    if (loaded?.state !== 'match' || loaded.commit !== fromCommit) return kept('from-unproven');
+    // Any master commit can make a release record with its own release.yml,
+    // and the tag can move to it. npm never takes a version twice, so the
+    // proven run must have started before npm published the loaded version
+    // (third security review of #292, S1).
+    try {
+      const published = JSON.parse(exec('npm', ['view', `${name}@${from}`, 'time', '--json']))?.[from];
+      const run = gh(['api', '--method', 'GET', `repos/${repo}/actions/runs/${Number(loaded.run)}`]);
+      const ran = Date.parse(String(run?.created_at));
+      if (!Number.isInteger(loaded.run) || run?.head_sha !== fromCommit || !(ran < Date.parse(String(published)))) return kept('from-unproven');
+    } catch { return kept('from-unproven'); }
+    let proven;
+    try { proven = provenRelease({ name, version: to, repo, gh, exec, work }); } catch { return kept('proof-stopped'); }
+    if (proven.refused) return kept(REASONS[proven.code] ? proven.code : 'files');
+    if (!judged || proven.commit !== toCommit) return kept('audit-silent', { commit: proven.commit });
+    let refusal;
+    try { refusal = auditApproves({ gh, repo, fromCommit, toCommit: proven.commit }); } catch { return kept('audit-silent', { commit: proven.commit }); }
+    if (refusal) return kept(refusal.code, { commit: proven.commit, ...(refusal.runs ? { runs: refusal.runs.filter(Number.isInteger).slice(0, 10) } : {}), ...(refusal.issues ? { issues: refusal.issues.slice(0, 10) } : {}) });
+    const verdict = judged.wait(started + budget);
+    if (verdict?.code !== null) return kept(REASONS[verdict?.code] ? verdict.code : 'audit-silent', { commit: proven.commit, ...(Array.isArray(verdict?.commits) ? { commits: verdict.commits.filter((one) => SHA.test(String(one))).map((one) => one.slice(0, 12)).slice(0, 10) } : {}) });
+    // provenRelease refused a link already; this is the second look, at the
+    // folder that the swap copies from.
+    if (!onlyPlainEntries(proven.unpacked)) return kept('special-entry', { commit: proven.commit });
+    if (now() - started > budget) return kept('timeout', { commit: proven.commit });
+    writeFolder({ files: proven.files, unpacked: proven.unpacked, next });
+    if (existsSync(join(packageRoot, IN_USE))) cpSync(join(packageRoot, IN_USE), join(next, IN_USE), { recursive: true });
+    try { swapFolder({ packageRoot, next, rename }); } catch { return kept('swap-failed', { commit: proven.commit }); }
+    // The plugin moved. The `atlas` command moves to the same checked file.
+    let command = 'moved';
+    try { exec('npm', ['install', '-g', '--ignore-scripts', proven.tarball]); } catch { command = 'behind'; }
+    return done('moved', { run: proven.run.id, commit: proven.commit, files: proven.files.size, command });
+  } catch {
+    return kept('stopped');
+  } finally {
+    judged?.stop();
+    // The lock goes first, so a folder that will not go away never leaves the
+    // lock behind. The refresh never throws.
+    try { rmSync(lock, { recursive: true, force: true }); } catch { /* a stale lock clears in 5 min */ }
+    for (const folder of [next, work]) { try { rmSync(folder, { recursive: true, force: true, maxRetries: 3 }); } catch { /* a temp folder */ } }
+  }
+}
+
+// The words of a record, for the lead and the log.
+export function describe(record) {
+  if (!record || typeof record !== 'object') return 'no refresh record';
+  const reason = REASONS[record.code] ?? '';
+  if (record.state === 'moved') return `Atlas moved from ${record.from} to ${record.to} at the start of this session.`;
+  if (record.state === 'current') return `Atlas ${record.from} is the newest release.`;
+  if (record.state === 'kept') return `The refresh kept Atlas ${record.from ?? '(unknown)'}${record.to ? ` and did not move to ${record.to}` : ''}: ${reason}.`;
+  return `No refresh: ${reason}.`;
+}
+
+export function writeRecord(env, record) {
+  if (typeof env.HOME !== 'string' || !env.HOME) return;
+  try { mkdirSync(dirname(refreshFile(env)), { recursive: true }); writeFileSync(refreshFile(env), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 }); } catch { /* the record is advice */ }
+}
+
+// Run as a program by work/start.mjs: one refresh of the package this file is
+// in, one JSON line on stdout.
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  const packageRoot = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '');
+  const record = refresh({ packageRoot, env: process.env });
+  writeRecord(process.env, record);
+  process.stdout.write(`${JSON.stringify(record)}\n`);
+}

package/door/lib/runner.mjs

@@ -3,7 +3,8 @@
 //
 //   atlas runner start --repo <owner/name> [--json]
 //   atlas runner claim --repo <owner/name> --issue <n> --holder <run id>
-//   atlas runner line --from <file>
+//   atlas runner line --from <file> [--notice]
+//   atlas runner notice --repo <owner/name> --issue <n> --comment <id>
 //
 // The runner is one scheduled Claude session for each repo. It follows the
 // atlas:runner skill, and that skill calls these commands. The commands read
@@ -15,6 +16,12 @@
 //   claim  posts one claim on an issue, then reads the claims back. The
 //          oldest live claim holds the issue, so two runs build it once.
 //   line   prints the last line of a run, built by code from ids and counts.
+//          With --notice it prints the comment that hands the run facts to
+//          the notice workflow.
+//   notice runs in the notice workflow, as github-actions[bot]. It reads one
+//          run comment of the owner's login, builds the run line again from
+//          its facts, and posts the line, so GitHub tells the owner's phone
+//          (R25 line 10). It never copies the comment's text.
 //
 // Rules that hold everywhere here:
 // 1. Until the owner records the A2 exit test as passed, the runner works on
@@ -28,7 +35,7 @@
 // 4. No call here merges, pushes or changes a branch.
 import { readFileSync } from 'node:fs';
 import { jobMarker, typedFindings, JOBS_LABEL, atlasJobs } from './jobs.mjs';
-import { repoOk, TOKEN_SHAPE, DEFAULT_BOT } from './issues.mjs';
+import { repoOk, TOKEN_SHAPE, DEFAULT_BOT, api, apiBase } from './issues.mjs';
 import { ghApi } from './gate.mjs';
 import { PACKAGE_NAME } from './gate-audit.mjs';
 
@@ -253,14 +260,56 @@ export function runLine({ repo, at, you = [], landed = [], opened = [], open_job
   return parts.join(' · ');
 }
 
+// ------------------------------------------------------------ the notice
+
+// R25 line 10. The runner session acts as the owner's login, and GitHub does
+// not tell a person about his own comment. So the session posts its run facts
+// in one comment on the notice issue, and the notice workflow posts the run
+// line as the bot. The workflow trusts no text: it reads the facts as JSON,
+// and runLine refuses any field that is not an id, a count or a known form.
+export const RUN_MARKER = '<!-- atlas-runner:run -->';
+export const NOTICE_LABEL = 'atlas-notice';
+export const noticeBody = (facts) => [RUN_MARKER, '```json', JSON.stringify(facts), '```'].join('\n');
+
+export function factsOf(body) {
+  const text = String(body ?? '');
+  if (!text.startsWith(`${RUN_MARKER}\n`)) return null;
+  const blocks = [...text.matchAll(/```json\n([\s\S]*?)\n```/g)];
+  if (blocks.length !== 1) return null;
+  try { return JSON.parse(blocks[0][1]); } catch { return null; }
+}
+
+export async function runnerNotice({ repo, issue, comment, env = process.env, call = null, allowed = RUNNER_REPOS }) {
+  if (!repoAllowed(repo, allowed)) throw usage(`${repo} is not a runner repo`);
+  const gh = call ?? ((method, path, body) => api(apiBase(env), env.GITHUB_TOKEN, method, path, body));
+  if (!call && !env.GITHUB_TOKEN) throw usage('the notice needs GITHUB_TOKEN, the token of the workflow run');
+  const got = await gh('GET', `/repos/${repo}/issues/comments/${comment}`);
+  if (!got.ok) return { posted: false, why: `GitHub answered ${got.status} for comment ${comment}` };
+  const note = got.data;
+  if (!String(note?.issue_url ?? '').endsWith(`/repos/${repo}/issues/${issue}`)) return { posted: false, why: `comment ${comment} is not on issue #${issue}` };
+  if (note?.author_association !== 'OWNER') return { posted: false, why: `comment ${comment} is not by the owner's login, so no runner wrote it` };
+  const thread = await gh('GET', `/repos/${repo}/issues/${issue}`);
+  const labels = (thread.data?.labels ?? []).map((one) => (typeof one === 'string' ? one : one?.name));
+  if (!thread.ok || !labels.includes(NOTICE_LABEL)) return { posted: false, why: `issue #${issue} is not the notice issue (label ${NOTICE_LABEL})` };
+  const facts = factsOf(note.body);
+  if (!facts) return { posted: false, why: `comment ${comment} holds no run facts` };
+  if (String(facts.repo ?? '').toLowerCase() !== repo.toLowerCase()) return { posted: false, why: `the run facts name ${facts.repo}, not ${repo}` };
+  const runLineText = runLine(facts);
+  const posted = await gh('POST', `/repos/${repo}/issues/${issue}/comments`, { body: runLineText });
+  if (!posted.ok) return { posted: false, why: `GitHub answered ${posted.status} to the notice` };
+  return { posted: true, line: runLineText };
+}
+
 // ------------------------------------------------------------ the command
 
-export async function runnerCommand({ what, repo, issue, holder, from, json = false, args = [] }, line, env = process.env) {
+export async function runnerCommand({ what, repo, issue, holder, from, comment, notice = false, json = false, args = [] }, line, env = process.env) {
   try {
     if ([...args, repo, holder, from].some((a) => typeof a === 'string' && TOKEN_SHAPE.test(a))) throw usage('a token must never be an argument');
     if (what === 'line') {
       if (!from) throw usage('give the run as --from <file>, a JSON object of ids and counts');
-      line(runLine(JSON.parse(readFileSync(from, 'utf8'))));
+      const facts = JSON.parse(readFileSync(from, 'utf8'));
+      const text = runLine(facts);
+      line(notice ? noticeBody(facts) : text);
       return 0;
     }
     if (!repoOk(repo)) throw usage('give the repo as --repo <owner/name>');
@@ -278,7 +327,14 @@ export async function runnerCommand({ what, repo, issue, holder, from, json = fa
       line(result.held ? `HELD: issue #${issue} is this run's` : `TAKEN: issue #${issue} is held by ${result.holder}; leave it`);
       return result.held ? 0 : 1;
     }
-    throw usage('use atlas runner start, atlas runner claim or atlas runner line');
+    if (what === 'notice') {
+      if (!/^[1-9][0-9]{0,8}$/.test(String(issue ?? ''))) throw usage('give the notice issue as --issue <number>');
+      if (!/^[1-9][0-9]{0,11}$/.test(String(comment ?? ''))) throw usage('give the run comment as --comment <id>');
+      const result = await runnerNotice({ repo, issue: Number(issue), comment: Number(comment), env });
+      line(result.posted ? `POSTED: ${result.line}` : `NOT POSTED: ${result.why}`);
+      return result.posted ? 0 : 1;
+    }
+    throw usage('use atlas runner start, claim, line or notice');
   } catch (error) {
     line(`atlas runner: ${error.message}`);
     return error.usage ? 2 : 1;

package/door/lib/tooling.mjs

@@ -63,6 +63,11 @@ function packagedPinned(packageRoot, source) {
 export const packagedJobsWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_JOBS_SOURCE);
 export const packagedUpkeepWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_UPKEEP_SOURCE);
 export const packagedProceduresWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_PROCEDURES_SOURCE);
+// The notice workflow of the runner (R25 line 10). It is not in PINNED: until
+// the owner records the A2 exit test, only the scratch repo gets it, by hand.
+export const RUNNER_NOTICE_PATH = '.github/workflows/atlas-runner-notice.yml';
+export const PACKAGE_RUNNER_NOTICE_SOURCE = 'door/templates/atlas-runner-notice.yml';
+export const packagedRunnerNotice = (packageRoot) => packagedPinned(packageRoot, PACKAGE_RUNNER_NOTICE_SOURCE);
 const pinOf = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
 const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
 // written, refreshed, unchanged or kept: what the writer does with one pinned workflow.

package/door/templates/atlas-runner-notice.yml

@@ -0,0 +1,41 @@
+name: atlas-runner-notice
+# The notice of the Atlas runner (roadmap R25 line 10). Atlas wrote this file
+# from the Atlas package; do not edit it by hand.
+#
+# A runner session acts as the owner's login, and GitHub does not tell a
+# person about his own comment. So the session posts its run facts in one
+# comment on the notice issue (label atlas-notice), and this job posts the run
+# line as github-actions[bot]. GitHub then tells the owner's phone.
+#
+# It holds no secret, only issues write. It never copies the comment's text:
+# Atlas code reads the facts as JSON and builds the line from ids and counts.
+# Until the owner records the A2 exit test, only the scratch repo has it.
+on:
+  issue_comment:
+    types: [created]
+
+permissions: {}
+
+jobs:
+  notice:
+    if: >-
+      github.event.comment.author_association == 'OWNER' &&
+      startsWith(github.event.comment.body, '<!-- atlas-runner:run -->') &&
+      contains(github.event.issue.labels.*.name, 'atlas-notice')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Post the run line as the bot
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number }}
+          COMMENT: ${{ github.event.comment.id }}
+        run: |
+          set -euo pipefail
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ runner notice --repo "$GITHUB_REPOSITORY" --issue "$ISSUE" --comment "$COMMENT" | tee -a "$GITHUB_STEP_SUMMARY"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.52",
+  "version": "0.4.54",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -147,16 +147,24 @@ Claude cloud session, do these steps before the first reply.
 1. Call the `atlas_upgrade` tool with `check: true`. It writes no Atlas
    state.
 2. When `behind` is true, put one line in the reply: "This session runs
-   Atlas <loaded>; npm has <newest>. A new session from the cloud
-   environment loads the newest." Use the two versions from the answer.
-3. When `provenance.state` is `differs` or `unproven`, the loaded Atlas
+   Atlas <loaded>; npm has <newest>." Use the two versions from the answer.
+3. Read `refresh`, the record of the refresh at session start. The tools
+   server moves a cloud session to the newest release that the release
+   proof and the push audit accept.
+   - `moved`: say nothing more. Read the `atlas:lead` skill once, because
+     the lead printed at the start can be the old one.
+   - `kept`: put one line in the reply, as loud as the line of step 2:
+     "The refresh kept Atlas <from>: <reason>." Use `from` and `reason`
+     from the record.
+   - No `refresh`, or `skipped`: go on.
+4. When `provenance.state` is `differs` or `unproven`, the loaded Atlas
    is not proven to be its release. Say so, with the first reason. Then
    stop all Atlas work until the owner answers.
-4. When `provenance.state` is `not checked`, say so in one line, with the
+5. When `provenance.state` is `not checked`, say so in one line, with the
    reason. Then go on.
-5. When the tool is missing, or its answer has no `provenance`, this Atlas
+6. When the tool is missing, or its answer has no `provenance`, this Atlas
    is too old for the check. Say so in one line, and go on.
-6. When the tool refuses the check, give its error in one line, and go on.
+7. When the tool refuses the check, give its error in one line, and go on.
 
 The check runs from the copy it checks. It finds stale or drifted files. It
 cannot find a package made to lie, so never call it a security proof.

package/skills/runner/SKILL.md

@@ -72,9 +72,12 @@ its environment come from `trigger.yaml` beside this file.
    `the merge door is off in the runner`, `start stopped`. A landed pull
    request carries its `number`, its `release`, and the id of its proof
    comment as `proof`. The command refuses any other text.
-8. Run `atlas runner line --from <file>`. Its output is the last message of
-   the run, word for word. The notice workflow posts it on the repo's notice
-   issue.
+8. Run `atlas runner line --from <file> --notice`. Post its output, word for
+   word, as one comment on the repo's notice issue (label `atlas-notice`).
+   The notice workflow reads the facts and posts the run line as the bot,
+   so GitHub tells the owner.
+9. Run `atlas runner line --from <file>`. Its output is the last message of
+   the run, word for word.
 
 ## Until the exit test
 

package/work/mcp.mjs

@@ -29,9 +29,30 @@ import { createMcpServer } from './lib/mcp-stdio.mjs';
 import { childEnvironment, CLOUD_NODE_VARIABLES } from './lib/child-env.mjs';
 import { ROLES, roleOf, allow, whoCell } from './lib/roles.mjs';
 import { upgrade, proveCopy } from '../door/lib/install.mjs';
+import { REASONS as REFRESH_REASONS } from '../door/lib/refresh.mjs';
 export { childEnvironment };
 
 const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+// The record of the cloud refresh (item ade7d96a). work/start.mjs ran the
+// refresh before it started this process, and passes its record here. Only
+// typed fields pass: the record carries no text from npm or GitHub.
+const REFRESH_STATES = new Set(['moved', 'current', 'kept', 'skipped']);
+const VERSION_TEXT = /^\d+\.\d+\.\d+$/;
+export function refreshRecord(env) {
+  let raw;
+  try { raw = JSON.parse(env.ATLAS_REFRESH_RECORD ?? 'null'); } catch { return null; }
+  if (!raw || typeof raw !== 'object' || !REFRESH_STATES.has(raw.state)) return null;
+  const out = { state: raw.state };
+  if (typeof raw.code === 'string' && /^[a-z-]{1,20}$/.test(raw.code)) out.code = raw.code;
+  for (const key of ['from', 'to']) if (typeof raw[key] === 'string' && VERSION_TEXT.test(raw[key])) out[key] = raw[key];
+  if (typeof raw.commit === 'string' && /^[0-9a-f]{40}$/.test(raw.commit)) out.commit = raw.commit;
+  if (Number.isInteger(raw.run)) out.run = raw.run;
+  for (const key of ['runs', 'issues']) if (Array.isArray(raw[key])) out[key] = raw[key].filter(Number.isInteger).slice(0, 10);
+  if (Array.isArray(raw.commits)) out.commits = raw.commits.filter((one) => typeof one === 'string' && /^[0-9a-f]{12}$/.test(one)).slice(0, 10);
+  if (raw.command === 'moved' || raw.command === 'behind') out.command = raw.command;
+  if (typeof raw.seconds === 'number' && Number.isFinite(raw.seconds)) out.seconds = raw.seconds;
+  return out;
+}
 const S = (description, extra = {}) => ({ type: 'string', description, ...extra });
 const ORIGIN = { type: 'object', description: "The owner's words, verbatim, with where and when they were said.", required: ['text', 'source', 'date'], properties: { text: S('Verbatim words of the owner.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), date: S('ISO date, in the form YYYY-MM-DD.') } };
 // Roadmap R23: the origin of a new item. The owner's words, or a typed
@@ -81,7 +102,7 @@ const TOOL_LIST = [
   { name: 'where_are_we', description: 'Answer "where are we with X" in six parts: live support and known limits from the code read at question time, then in progress, delivered and proposed from the items, then the current priority decision. Every row carries a citation: a path and a line, an entity id, a pull request, or a decision date. The code half comes from the sub-agent digests, which are refused when they cite a never-read path or quote a never-quote path, and every string is scrubbed by pattern. Computed at read time and never stored. Scope: read, every role.', inputSchema: { type: 'object', required: ['product', 'capability', 'code'], properties: { product: S('Product registry id.'), capability: S('The capability the question is about, the X.'), code: { type: 'array', description: 'One digest per repo, from the sub-agents briefed by code_read_brief. At least one is required: an answer with no code read says nothing about what the code does today.', items: CODE_DIGEST }, items: { type: 'array', description: 'Item ids the lead judges to answer this question.', items: { type: 'string' } }, match: { type: 'array', description: 'Terms to match against item titles, summaries and tags. Give items, match, or both.', items: { type: 'string' } }, movement_repos: { type: 'array', description: "Narrow the movement read to these registered repo ids. Default: every repo of the product. The digests' own repos are always read.", items: { type: 'string' } }, since: S('ISO date. Adds what changed since then.') }, additionalProperties: false } },
   { name: 'built_pending_possible', description: 'Answer "what are we building, what is built, what is pending and what can be done": delivered items by date, active items, paused items with their reason, proposed items with their age, and the decisions that set the order. Item records, delivery marks and decisions only; no code read and no GitHub read. Computed at read time and never stored. Scope: read, every role.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Limits built and the decisions to what came after it.') }, additionalProperties: false } },
   { name: 'design_index', description: 'List every design: each work item with a design-doc link, in any lifecycle, newest change first, with its product, its state for the hub ("Waiting on the owner", "Building", "Paused", "Shipped", "Dropped"), its design docs and its pages. Also returns design_hub_url, the one hub page. When: before the lead rebuilds the "Design docs" hub, after each design publish, lock and done. Item records only; computed at read time and never stored. Scope: read, every role.', inputSchema: { type: 'object', properties: { product: S('Limit the list to one product id.') }, additionalProperties: false } },
-  { name: 'atlas_upgrade', description: 'Move Atlas on this Mac to the newest release: the same steps as the "atlas upgrade --yes" command. It checks that a master release run built the release, installs it and updates the plugin. When: the owner asks to upgrade Atlas. Use this tool and not the command: the Bash sandbox blocks the writes to ~/.npm, ~/.atlas and ~/.claude/plugins, and this server runs outside it. With check true it writes no Atlas state: it reports the loaded and the newest version, and checks that the loaded files are the files of their master release commit (provenance: match, differs, unproven or not checked). The check runs from the copy it checks, so it finds stale or drifted files, not a package made to lie. The check runs anywhere and in every role, also in a Claude cloud session; the lead calls it at the first reply of a cloud session. Scope: this Mac, no tracker write. The upgrade itself never runs in a Claude cloud session: a new cloud session installs the newest release.', inputSchema: { type: 'object', properties: { check: { type: 'boolean', description: 'True: report the versions and the provenance of the loaded copy, and install nothing.' } }, additionalProperties: false } },
+  { name: 'atlas_upgrade', description: 'Move Atlas on this Mac to the newest release: the same steps as the "atlas upgrade --yes" command. It checks that a master release run built the release, installs it and updates the plugin. When: the owner asks to upgrade Atlas. Use this tool and not the command: the Bash sandbox blocks the writes to ~/.npm, ~/.atlas and ~/.claude/plugins, and this server runs outside it. With check true it writes no Atlas state: it reports the loaded and the newest version, and checks that the loaded files are the files of their master release commit (provenance: match, differs, unproven or not checked). The check runs from the copy it checks, so it finds stale or drifted files, not a package made to lie. The check runs anywhere and in every role, also in a Claude cloud session; the lead calls it at the first reply of a cloud session. Scope: this Mac, no tracker write. The upgrade itself never runs in a Claude cloud session: there the tools server refreshes itself at start, and check true returns that record as refresh (state moved, current, kept or skipped, with a code).', inputSchema: { type: 'object', properties: { check: { type: 'boolean', description: 'True: report the versions and the provenance of the loaded copy, and install nothing.' } }, additionalProperties: false } },
 ];
 // Roadmap R20: each description ends with who may call the tool, read from
 // the role table, so the text and the guard cannot differ.
@@ -310,9 +331,10 @@ export async function runUpgrade({ args = {}, env = process.env, role = 'crew',
     if (!PROOFS.has(proveFn)) PROOFS.set(proveFn, new Map());
     const proofs = PROOFS.get(proveFn);
     if (!proofs.has(packageRoot)) proofs.set(packageRoot, proveFn({ packageRoot, exec }));
-    return { loaded, newest, behind: newest !== loaded, provenance: proofs.get(packageRoot) };
+    const refresh = refreshRecord(env);
+    return { loaded, newest, behind: newest !== loaded, provenance: proofs.get(packageRoot), ...(refresh ? { refresh: { ...refresh, ...(REFRESH_REASONS[refresh.code] ? { reason: REFRESH_REASONS[refresh.code] } : {}) } } : {}) };
   }
-  if (inClaudeCloud(env)) refuse('atlas_upgrade does not run in a Claude cloud session. A new cloud session installs the newest release.');
+  if (inClaudeCloud(env)) refuse('atlas_upgrade does not run in a Claude cloud session. The tools server refreshes itself at the start of each cloud session; check true gives that record.');
   const lines = [];
   let code;
   try { code = await upgradeFn({ packageRoot, options: { yes: true }, line: (text) => lines.push(text), env, exec }); } catch (error) {
@@ -345,6 +367,8 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
   const verbsFor = (boundClient) => createVerbs({ client, store, writer: { token_id: connection.tokenId }, session, agent, role, roleFrom, boundClient, readGitHub: readGitHub ?? githubReader(), readLive: live });
   let verbs = connection.state === 'ok' ? verbsFor(null) : null;
   const health = { package_version: ATLAS_VERSION, started_at: new Date().toISOString(), pid: process.pid, node: process.version, connection: connection.state, connection_expires: connection.expires ?? connection.expired ?? null, role, role_from: roleFrom, gh: findOnPath('gh', env), engram: connection.state === 'ok' ? 'not checked yet' : connection.message };
+  const refresh = refreshRecord(env);
+  if (refresh) health.refresh = refresh;
   writeHealth(env, health);
   if (client) {
     client.getPublisher().then(() => { health.engram = 'answered'; }, (error) => { health.engram = `did not answer: ${error.message}`; }).finally(() => writeHealth(env, health));
@@ -352,6 +376,11 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
   const instructions = connection.state === 'ok'
     ? `Atlas work verbs. Session ${session}; role: ${role}, from ${roleFrom}. The role table (packages/atlas/work/lib/roles.mjs) says which tools this role may call; the others refuse. Call registry_list first to learn the product and repo ids, needs_me to see the open questions, and in_flight to see the active work. Every write needs a request_id. The server stamps writer.session and the bound client; never pass writer, session, actor or role. Unknown product or repo ids are refused. The server cannot tell a sub-agent from the lead in one session, so an Atlas crew holds no MCP tool: its tools line names none.`
     : `Atlas work verbs. They cannot reach Engram yet: ${connection.message}`;
+  // The lead hook printed the lead at the start, maybe from the old copy, at
+  // the same time as the refresh ran. So a moved copy asks for one fresh read.
+  const refreshLine = refresh?.state === 'moved'
+    ? ` Atlas moved from ${refresh.from} to ${refresh.to} at the start of this session. The lead text printed at the start may be the old one: read the atlas:lead skill once now.`
+    : refresh?.state === 'kept' ? ` The cloud refresh kept Atlas ${refresh.from ?? ''} (${refresh.code ?? 'stopped'}). Call atlas_upgrade with check true, and say so at the first reply.` : '';
   // Roadmap R15: the step-in rows of the hook become marks at the server's
   // start and before each write verb. A failed flush leaves the rows for the
   // next one and never stops the verb. With ATLAS_HOOKS=off nothing counts
@@ -372,7 +401,7 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
     flush(),
     env.ATLAS_HOOKS === 'off' ? verbs.stepIns.notCounted(claudeSession).catch((error) => say(`step-ins: the "not counted" mark was not written: ${error.message}`)) : null,
   ]) : Promise.resolve();
-  const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions, tools: TOOLS, input, output, log, call: async (name, args, boundTo) => {
+  const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions: `${instructions}${refreshLine}`, tools: TOOLS, input, output, log, call: async (name, args, boundTo) => {
     // The upgrade needs no Engram connection: an old key must not block a new release.
     if (name === 'atlas_upgrade') return runUpgrade({ args, env, role: upgradeRole.role, roleFrom: upgradeRole.from });
     if (!verbs) throw new Error(connection.message);

package/work/start.mjs

@@ -0,0 +1,63 @@
+// The entry of the Atlas tools server (item ade7d96a, design
+// docs/design-docs/cloud-self-refresh/). Claude Code starts this file in
+// every session, from .mcp.json.
+//
+// 1. In a Claude cloud session it first runs the refresh, door/lib/refresh.mjs,
+//    as its own process with the short child environment: never the Engram
+//    key. The refresh may put a newer, proven and audited release in this
+//    folder.
+// 2. Then it starts the tools server, work/mcp.mjs, as a new process from the
+//    files now in place, so no module of the old copy runs next to the new
+//    one. The server reads the refresh record from ATLAS_REFRESH_RECORD.
+//
+// This process loads one module of the package, the child environment, and
+// never the server code. The server and the refresh each run in a process of
+// their own, so old and new modules never mix in one process.
+import { spawn, spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { childEnvironment } from './lib/child-env.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(here);
+const say = (line) => process.stderr.write(`atlas-work start: ${line}\n`);
+// The refresh has 20 s before its swap and 10 s for each program call. This
+// limit stops a refresh that hangs, before Claude Code gives up on the tools
+// server (security review of item ade7d96a). Claude Code waits about 30 s
+// for a server to start, or MCP_TIMEOUT ms when the environment sets it
+// (probe, 31 October 2026). With MCP_TIMEOUT, the refresh gets that time
+// less 15 s, up to the refresh's own cap.
+const REFRESH_LIMIT_MS = 25_000;
+export function limitsOf(env) {
+  const wait = Number(env.MCP_TIMEOUT);
+  if (!Number.isInteger(wait) || wait <= 30_000) return { limit: REFRESH_LIMIT_MS, budget: null };
+  const limit = Math.min(wait - 15_000, 105_000);
+  return { limit: Math.max(limit, REFRESH_LIMIT_MS), budget: Math.max(limit - 5_000, 20_000) };
+}
+
+export function refreshFirst({ env = process.env, root = packageRoot, run = spawnSync } = {}) {
+  if (env.CLAUDE_CODE_REMOTE !== 'true' || env.ATLAS_REFRESH === 'off') return null;
+  const { limit, budget } = limitsOf(env);
+  const childEnv = { ...childEnvironment(env), CLAUDE_CODE_REMOTE: 'true', ...(budget ? { ATLAS_REFRESH_BUDGET_MS: String(budget) } : {}) };
+  const result = run(process.execPath, [join(root, 'door', 'lib', 'refresh.mjs')], { env: childEnv, encoding: 'utf8', timeout: limit, stdio: ['ignore', 'pipe', 'pipe'] });
+  const last = String(result.stdout ?? '').trim().split('\n').at(-1) ?? '';
+  try { return JSON.parse(last); } catch { return { state: 'kept', code: 'stopped' }; }
+}
+
+export function startServer({ env = process.env, root = packageRoot, record = null, start = spawn } = {}) {
+  const serverEnv = { ...env };
+  if (record) serverEnv.ATLAS_REFRESH_RECORD = JSON.stringify(record);
+  const child = start(process.execPath, [join(root, 'work', 'mcp.mjs')], { env: serverEnv, stdio: 'inherit' });
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+  child.on('exit', (code, signal) => { process.exitCode = code ?? (signal ? 1 : 0); });
+  return child;
+}
+
+// Real paths on both sides, as in mcp.mjs: a plugin cache can sit behind a link.
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  let record = null;
+  try { record = refreshFirst(); } catch (error) { record = { state: 'kept', code: 'stopped' }; say(`the refresh stopped: ${error.message}`); }
+  if (record) say(`refresh ${record.state}${record.code ? ` (${record.code})` : ''}: ${record.from ?? '?'} -> ${record.to ?? record.from ?? '?'}`);
+  startServer({ record });
+}