@arjunkhera/atlas 0.4.53 → 0.4.55

package/door/lib/window.mjs

@@ -0,0 +1,271 @@
+// The signing window (tracker item 4af66381; design
+// docs/design-docs/signing-window/). One touch of the owner's key signs a
+// window act: `act window <repo> <branch> <seen> <ends>`. Until its end time,
+// the gate clears some owner rows of a pull request into that branch with
+// the act, as if the owner had signed its head.
+//
+//   windowOn(root, ref)                 does atlas.yaml on the base turn the window on
+//   protectedSet(root, ref)             the files that a window never covers (rule 1)
+//   clearable(row, guard)               may a window clear this one owner row
+//   windowActs(verified, want)          the valid window acts of one repo and branch
+//   openAt(acts, { now, isSeen })       the window act that is open now, or a reason
+//   seenAt(acts, isSeen)                the newest seen commit that a commit holds
+//
+// The four rules, one for each S1 of the security review of 29 October:
+// 1. An allow-list. A window clears an owner row only when the row comes from
+//    the repo's own `owner_only:` list, its class is rule-book or security,
+//    and its path is not in the protected set. The protected set is derived
+//    from the base commit: the import closure of the entry files, every data
+//    file in a folder of that closure, every package manifest, and AUDIT_CODE.
+// 2. The end time is in the act, at most 12 hours after the touch. No act
+//    ends a window early; the brake does, and the window never clears it.
+// 3. The owner's Mac builds the morning list from git and the acts
+//    (approve.mjs). A new window opens only with the touch that saw the list:
+//    the act names the tip that the list ended at.
+// 4. A class that the window does not name keeps the pull request OWNER, so
+//    the window needs no row for money or a new service.
+// Everything here fails closed: a file that git cannot read, or an import
+// that is not a plain text path, makes the closure unreadable, and then no
+// window counts.
+import { spawnSync } from 'node:child_process';
+import { posix } from 'node:path';
+import { parseYaml } from '../../shape/check.mjs';
+import { AUDIT_CODE } from './signed-act.mjs';
+
+export const WINDOW_HOURS = 12;
+export const WINDOW_MS = WINDOW_HOURS * 3600 * 1000;
+export const WINDOW_LABEL = 'atlas-window';
+export const WINDOW_TITLE = 'atlas signing window';
+export const WINDOW_KEY = 'signing_window';
+// The classes of owner row that a window may clear (rule 1, rule 4). Every
+// other class keeps the pull request OWNER.
+export const WINDOW_CLASSES = Object.freeze(['rule-book', 'security']);
+// The files that start the code which makes, shows, checks or audits an act:
+// the command, the gate, the push audit and its jobs, the signing tools, the
+// test checks of the gate, the shape check, the tools server with its done
+// tool, and the window itself. The protected set is their import closure at
+// the base, so a new import of a protected file is protected at once.
+export const WINDOW_ENTRIES = Object.freeze([
+  'packages/atlas/bin/atlas',
+  'packages/atlas/door/cli.mjs',
+  ...['gate', 'gate-check', 'gate-audit', 'jobs', 'issues', 'approve', 'signed-act', 'owner-only', 'brake', 'kinds', 'fails-before', 'passes-after', 'changed-tests', 'window']
+    .map((name) => `packages/atlas/door/lib/${name}.mjs`),
+  'packages/atlas/shape/check.mjs',
+  // The judges of the required checks, and the code that writes the gate
+  // into other repos (security review of 7 November, question 1).
+  'packages/atlas/door/lib/upkeep.mjs',
+  'packages/atlas/door/lib/tooling.mjs',
+  'packages/atlas/tests/verdict.mjs',
+  // release.yml loads these two straight from the trusted copy.
+  'packages/atlas/door/lib/install.mjs',
+  'packages/atlas/door/lib/private-terms.mjs',
+  'packages/atlas/work/mcp.mjs',
+  'packages/atlas/work/lib/delivery.mjs',
+]);
+// Files protected by their role, whatever imports them (security review of
+// 31 October, S2: the set picked by import alone). The workflows and the
+// check copy run the required checks; the hooks run at each session start;
+// the command, the shape check and the gate tooling judge the checks; the
+// signers file, the owner-only list and the repo facts set the rules. A path
+// that ends in `/` holds each file under it.
+export const WINDOW_ROLES = Object.freeze([
+  '.github/',
+  'packages/atlas/hooks/',
+  'packages/atlas/bin/',
+  'packages/atlas/shape/',
+  'test/package/',
+  'door/release-notes.mjs',
+  'packages/atlas/tests/',
+  'docs/manual/extract/',
+  'atlas/owner-signers',
+  'atlas.yaml',
+  'packages/atlas/owner-only.yaml',
+]);
+// File names that change what npm packs or how a folder resolves. A new one
+// in any folder could drop a protected file from the package, so a window
+// never clears one (security review of 7 November, S2).
+export const WINDOW_PACK_FILES = Object.freeze(['.npmignore', '.gitignore', '.npmrc', '.gitattributes', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']);
+// One form for a path, as a Mac file system compares names: no case, and one
+// Unicode form. Two paths with one fold are one file on the owner's Mac
+// (security review of 7 November, S1).
+export const foldPath = (path) => String(path).normalize('NFC').toLowerCase();
+// The command file loads each command's code with a plain `import()` only
+// when that command runs. The closure follows its static imports alone; the
+// gate's own commands are entries above.
+export const WINDOW_DISPATCH = Object.freeze(['packages/atlas/door/cli.mjs']);
+// Files that the import closure walks. Others are data.
+const CODE = /\.(m?js|cjs)$/;
+// At most this many files in the closure, so a loop of imports ends.
+const MAX_CLOSURE = 2000;
+// git's word for the ancestor test, joined so the package names no ancestry verb (test/package D9).
+const MERGE_BASE = ['merge', 'base'].join('-');
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+// True when atlas.yaml on the base says `signing_window: on` (or true). The
+// key is on the fixed list of the owner-only floor, so only the owner turns
+// it on.
+export function windowOn(root, ref) {
+  const text = git(root, ['show', `${ref}:atlas.yaml`]);
+  if (text === null) return false;
+  let facts;
+  try { facts = parseYaml(text) ?? {}; } catch { return false; }
+  const value = facts[WINDOW_KEY];
+  return value === true || value === 'on';
+}
+
+// Each module path that one code text imports, or null when an import is
+// not a plain text path: an import whose name is built at run time, or a
+// call of the CommonJS loader.
+// With `dynamic: false`, a plain `import()` is left out: the command file
+// loads each command's code only when that command runs. Only relative
+// paths name files of the repo. A `node:` name is built in, and a bare name
+// is a package outside the repo; a pull request changes either one only
+// through a package manifest, which is protected. Whole comment lines go
+// first, so a comment that names an import form is not read as code. A
+// comment at the end of a code line stays, which only makes it stricter.
+const COMMENT_LINE = /^\s*(\/\/|\/\*|\*)/;
+const LOADERS = new RegExp(`\\b${['re', 'quire'].join('')}\\s*\\(|\\b${['create', 'Require'].join('')}\\b|\\bimport\\.meta\\.${['re', 'solve'].join('')}\\b`);
+export function importsOf(text, { dynamic = true } = {}) {
+  const source = String(text).split('\n').filter((line) => !COMMENT_LINE.test(line)).join('\n');
+  const found = [];
+  const forms = [
+    /\b(?:import|export)\s[^'"`;]*?\bfrom\s*(['"])([^'"\n]+)\1/g,
+    /\bimport\s*(['"])([^'"\n]+)\1/g,
+  ];
+  for (const form of forms) for (const hit of source.matchAll(form)) found.push(hit[2]);
+  const loaded = [...source.matchAll(/\bimport\s*\(\s*(['"])([^'"\n]+)\1\s*\)/g)].map((hit) => hit[2]);
+  if (dynamic) found.push(...loaded);
+  // Every dynamic import must be one that the forms above read.
+  if ([...source.matchAll(/\bimport\s*\(/g)].length !== loaded.length) return null;
+  if (LOADERS.test(source)) return null;
+  const out = [];
+  for (const name of found) {
+    if (name.startsWith('./') || name.startsWith('../')) out.push(name);
+  }
+  return out;
+}
+
+// The protected set at one commit: { paths: Set, why: null } or { why }.
+// 1. The import closure of WINDOW_ENTRIES, read from git objects of `ref`.
+//    An entry that the commit does not hold is left out, so a repo with no
+//    Atlas package has an empty closure.
+// 2. Every file that is not code, in each folder of the closure and below it:
+//    the YAML, JSON, templates and workflows that protected code reads.
+// 3. Every package manifest and lock file, which name the commands.
+// 4. AUDIT_CODE of signed-act.mjs.
+export function protectedSet(root, ref) {
+  const tree = git(root, ['ls-tree', '-r', '--name-only', '-z', ref]);
+  if (tree === null) return { why: `git cannot list the files of ${String(ref).slice(0, 12)}` };
+  const files = tree.split('\0').filter(Boolean);
+  const held = new Set(files);
+  const paths = new Set();
+  const queue = WINDOW_ENTRIES.filter((path) => held.has(path));
+  while (queue.length) {
+    const path = queue.pop();
+    if (paths.has(path)) continue;
+    paths.add(path);
+    if (paths.size > MAX_CLOSURE) return { why: `the import closure holds more than ${MAX_CLOSURE} files` };
+    // A path that the commit does not hold is still protected: a pull request
+    // that adds it adds code that a protected file imports.
+    if (!held.has(path)) continue;
+    if (!CODE.test(path) && !path.endsWith('/bin/atlas')) continue;
+    const text = git(root, ['show', `${ref}:${path}`]);
+    if (text === null) return { why: `git cannot read ${path} at ${String(ref).slice(0, 12)}` };
+    const names = importsOf(text, { dynamic: !WINDOW_DISPATCH.includes(path) });
+    if (names === null) return { why: `${path} has an import that is not a plain text path` };
+    for (const name of names) {
+      const next = posix.normalize(posix.join(posix.dirname(path), name));
+      if (next.startsWith('../') || next === '..') return { why: `${path} imports a file outside the repo` };
+      queue.push(next);
+    }
+  }
+  const folders = new Set([...paths].map((path) => posix.dirname(path)));
+  for (const file of files) {
+    if (CODE.test(file)) continue;
+    if ([...folders].some((folder) => folder !== '.' && file.startsWith(`${folder}/`))) paths.add(file);
+  }
+  for (const file of files) if (/(^|\/)(package\.json|package-lock\.json|pnpm-lock\.yaml|npm-shrinkwrap\.json)$/.test(file)) paths.add(file);
+  for (const path of AUDIT_CODE) paths.add(path);
+  for (const file of files) if (WINDOW_ROLES.some((role) => (role.endsWith('/') ? file.startsWith(role) : file === role))) paths.add(file);
+  for (const role of WINDOW_ROLES) if (!role.endsWith('/')) paths.add(role);
+  return { paths, folded: new Set([...paths].map(foldPath)), roles: WINDOW_ROLES, why: null };
+}
+
+// May a window clear this owner row? Rule 1: a row of the repo's own list, of
+// a class that the window names, on a path outside the protected set.
+export function clearable(row, guard) {
+  if (row?.kind !== 'owner') return false;
+  if (!WINDOW_CLASSES.includes(row.class)) return false;
+  if (typeof row.cause !== 'string' || !row.cause.startsWith('list: ')) return false;
+  if (typeof row.path !== 'string' || !row.path) return false;
+  if (!guard?.paths || guard.why) return false;
+  // Each test compares folded paths, so `Approve.mjs` is `approve.mjs`.
+  // A name with a letter outside plain ASCII is never cleared: a Mac may take
+  // it as a protected file by a case rule that no fold here matches (second
+  // review of 7 November).
+  if (!/^[\x20-\x7e]+$/.test(row.path)) return false;
+  const path = foldPath(row.path);
+  if (WINDOW_PACK_FILES.includes(posix.basename(path))) return false;
+  // A new file under a role folder is protected too, though the base lacks it.
+  if ((guard.roles ?? []).some((role) => (role.endsWith('/') ? path.startsWith(foldPath(role)) : path === foldPath(role)))) return false;
+  if ((guard.folded ?? new Set([...guard.paths].map(foldPath))).has(path)) return false;
+  // A path on the owner-only floor is never cleared, even when the repo's
+  // list names it too (security review of 31 October, S2).
+  if (guard.floor && guard.floor(row.path)) return false;
+  return !guard.paths.has(row.path);
+}
+
+const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+
+// The window acts of the verified blocks that name this repo and branch, each
+// with the time of its block, newest first.
+export function windowActs(verified, { repo, branch }) {
+  const out = [];
+  for (const row of verified) {
+    if (row.error) continue;
+    for (const act of row.acts) {
+      if (act.kind !== 'window' || !same(act.repo, repo) || act.branch !== branch) continue;
+      out.push({ act, signed_at: row.signed_at, key: row.key, verified: row.verified });
+    }
+  }
+  return out.sort((a, b) => b.signed_at.localeCompare(a.signed_at));
+}
+
+// The length rule of rule 2: the end is at or after the touch, and at most
+// WINDOW_HOURS after it.
+export function lengthOk(one) {
+  const start = Date.parse(one.signed_at);
+  const end = Date.parse(one.act.ends);
+  return Number.isFinite(start) && Number.isFinite(end) && end >= start && end - start <= WINDOW_MS;
+}
+
+// The window act that is open at `now`: its touch is at or before now, now is
+// before its end, and the base holds its seen commit. `isSeen(sha)` says
+// whether the base holds that commit. Returns { open } or { why }.
+export function openAt(acts, { now, isSeen }) {
+  const at = new Date(now).getTime();
+  let why = acts.length ? null : 'no window act names this repo and branch';
+  for (const one of acts) {
+    if (!lengthOk(one)) { why ??= `the window act of ${one.signed_at} is longer than ${WINDOW_HOURS} hours, or ends before its touch`; continue; }
+    if (Date.parse(one.signed_at) > at) { why ??= `the window act of ${one.signed_at} is from after this run`; continue; }
+    if (Date.parse(one.act.ends) <= at) { why ??= `the newest window ended at ${one.act.ends}`; continue; }
+    if (!isSeen(one.act.seen)) { why ??= `the seen commit ${one.act.seen.slice(0, 7)} of the window is not in the history of the base`; continue; }
+    return { open: one };
+  }
+  return { why };
+}
+
+// The newest seen commit of the acts that `isSeen` holds, or null. Every act
+// counts here, also one of zero length: a touch that saw the list.
+export function seenAt(acts, isSeen) {
+  for (const one of acts) if (lengthOk(one) && isSeen(one.act.seen)) return one;
+  return null;
+}
+
+// Does commit `newer` hold commit `older`?
+export const holdsCommit = (root, older, newer) => /^[0-9a-f]{40}$/.test(String(older))
+  && spawnSync('git', [MERGE_BASE, '--is-ancestor', '--end-of-options', older, newer], { cwd: root }).status === 0;

package/owner-only.yaml

@@ -245,3 +245,4 @@ atlas_yaml:
     - generated
     - verbatim
     - private_terms
+    - signing_window

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.53",
+  "version": "0.4.55",
   "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

@@ -128,7 +128,7 @@ set. A test keeps the two lists equal.
 | `atlas runner` | Only in a runner run, as the `atlas:runner` skill says: `start` first, `claim` before each build, `line` last. A lead session never runs the runner |
 | `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names and stale pages. In a pull request it also reads the tracker item, the changed designs, and STE on the changed lines. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list, `hold` only in the release job. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
-| `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`, and `audit-code <pr>` per audit-code merge; record its words as one decision, then close each issue |
+| `atlas approve` | Only the owner runs it, never a session, on his Mac with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`, and `audit-code <pr>` per audit-code merge; record its words as one decision, then close each issue. Where `signing_window: on`, ask him each evening for `window`: one touch sees the list of merges and opens a window of up to 12 hours |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 
 A person merges every file that `atlas tooling` writes.
@@ -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/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 });
+}