@arjunkhera/atlas 0.3.44 → 0.3.46

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -36,6 +36,7 @@ import { issuesCommand as testsIssues } from './lib/issues.mjs';
 import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
 import { upkeepCommand } from './lib/upkeep.mjs';
+import { gateCommand } from './lib/gate.mjs';
 import { judgeCommand } from './lib/judge.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -124,6 +125,11 @@ const HELP = `atlas — the door into a repo's Atlas files
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
 
+  atlas gate apply --repo <owner/name> set the gate: two rulesets from atlas.yaml required_checks, and auto-merge
+      --root <repo>                    the checkout to read atlas.yaml from (default: this folder)
+      --dry-run                        print each call; change nothing
+      --off | --on                     break glass: turn both rulesets off, or back on
+
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
   atlas judge run <tasks.md> <id> --out <dir>   one fresh agent does one sealed task, in a clean clone at the sealed commit
@@ -134,8 +140,10 @@ const HELP = `atlas — the door into a repo's Atlas files
                                        compare the judge's verdict with the sealed tasks and the runs; exit 0 only when all pass
 
   atlas install                        install Atlas for every folder on this Mac
+      --cloud                          in a cloud setup script: skip the checks that need a started session
   atlas upgrade [--version <v>]        check, show and install a newer release
   atlas doctor                         is Atlas installed and working here
+      --cloud                          before the first cloud session: skip the checks that need a started session
 
 Atlas ${ATLAS_VERSION}. Check version ${CHECK_VERSION}; it reads spec ${Object.keys(SPECS).join(', ')}.
 A person merges every file the tooling writer writes.
@@ -161,10 +169,11 @@ 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' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
-  install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
+  install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
-  doctor: {},
+  doctor: { cloud: 'switch' },
 });
 
 // Every command takes --help.
@@ -371,6 +380,10 @@ function upkeepVerb(chosen) {
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json) }, rootOf(chosen), line);
 }
 
+function gateVerb(chosen) {
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on) }, line);
+}
+
 function judgeVerb(chosen) {
   return judgeCommand({ what: chosen._[1], file: chosen._[2], task: chosen._[3], tasks: chosen.tasks, verdict: chosen.verdict, seal: chosen.seal, runs: chosen.runs, out: chosen.out, repo: chosen.repo, budget: chosen.budget, model: chosen.model }, line, PACKAGE_ROOT);
 }
@@ -408,6 +421,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
     case 'upkeep': return upkeepVerb(chosen);
+    case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }

package/door/lib/gate.mjs

@@ -0,0 +1,193 @@
+// `atlas gate apply`: the setup command of the gate (roadmap R9, design
+// docs/design-docs/gate-apply/). The owner runs it with his own GitHub login.
+// It sets two rulesets from the repo's atlas.yaml and allows auto-merge:
+//   1. "atlas gate" on the default branch: a pull request with no approval,
+//      each required check from GitHub Actions, no force push, no delete;
+//   2. "atlas release tags" on v* tags: no update, no delete.
+// The bypass list stays empty. --off and --on are the break glass.
+//
+// The plan is built by pure functions, so a test reads it without GitHub. The
+// gh calls sit in one place, behind `gh`, which a test replaces.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { childEnvironment } from '../../work/lib/child-env.mjs';
+import { parseYaml } from '../../shape/check.mjs';
+
+export const BRANCH_RULESET = 'atlas gate';
+export const TAG_RULESET = 'atlas release tags';
+// The app that posts GitHub Actions check runs. A status that another app posts
+// under the same name does not count.
+export const ACTIONS_APP_ID = 15368;
+
+export class GateError extends Error {}
+
+// What the gate reads from atlas.yaml.
+export function gateFacts(root) {
+  const path = join(root, 'atlas.yaml');
+  if (!existsSync(path)) throw new GateError(`there is no atlas.yaml in ${root}. Nothing was changed.`);
+  const facts = parseYaml(readFileSync(path, 'utf8')) ?? {};
+  const checks = facts.required_checks;
+  if (!Array.isArray(checks) || checks.length === 0 || checks.some((name) => typeof name !== 'string' || !name.trim())) {
+    throw new GateError('atlas.yaml lists no required_checks. Nothing was changed.');
+  }
+  if (facts.up_to_date !== undefined && typeof facts.up_to_date !== 'boolean') throw new GateError('atlas.yaml up_to_date must be true or false. Nothing was changed.');
+  return { checks: [...checks], upToDate: facts.up_to_date === true };
+}
+
+// The two ruleset bodies, as the GitHub rulesets API takes them.
+export function rulesets({ checks, upToDate }, enforcement = 'active') {
+  return [
+    {
+      name: BRANCH_RULESET,
+      target: 'branch',
+      enforcement,
+      bypass_actors: [],
+      conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+      rules: [
+        {
+          type: 'pull_request',
+          parameters: {
+            required_approving_review_count: 0,
+            dismiss_stale_reviews_on_push: false,
+            require_code_owner_review: false,
+            require_last_push_approval: false,
+            required_review_thread_resolution: false,
+          },
+        },
+        {
+          type: 'required_status_checks',
+          parameters: {
+            strict_required_status_checks_policy: upToDate,
+            required_status_checks: checks.map((context) => ({ context, integration_id: ACTIONS_APP_ID })),
+          },
+        },
+        { type: 'non_fast_forward' },
+        { type: 'deletion' },
+      ],
+    },
+    {
+      name: TAG_RULESET,
+      target: 'tag',
+      enforcement,
+      bypass_actors: [],
+      conditions: { ref_name: { include: ['refs/tags/v*'], exclude: [] } },
+      rules: [{ type: 'update' }, { type: 'deletion' }],
+    },
+  ];
+}
+
+// The calls of one run. `existing` is the list GitHub gives for the repo's
+// rulesets: [{ id, name }]. A ruleset that exists is updated, never doubled.
+// In a dry run, a ruleset that does not exist yet shows as <id>.
+export function plan({ repo, facts, existing = [], mode = 'apply', dryRun = false }) {
+  const ids = new Map(existing.map((ruleset) => [ruleset.name, ruleset.id]));
+  if (mode === 'off' || mode === 'on') {
+    const enforcement = mode === 'off' ? 'disabled' : 'active';
+    return [BRANCH_RULESET, TAG_RULESET].map((name) => {
+      if (!ids.has(name) && !dryRun) throw new GateError(`the repo has no ruleset "${name}". Run "atlas gate apply" first.`);
+      return { method: 'PUT', path: `repos/${repo}/rulesets/${ids.get(name) ?? '<id>'}`, name, body: { enforcement } };
+    });
+  }
+  const calls = rulesets(facts).map((body) => (ids.has(body.name)
+    ? { method: 'PUT', path: `repos/${repo}/rulesets/${ids.get(body.name)}`, name: body.name, body }
+    : { method: 'POST', path: `repos/${repo}/rulesets`, name: body.name, body }));
+  calls.push({ method: 'PATCH', path: `repos/${repo}`, name: 'allow auto-merge', body: { allow_auto_merge: true } });
+  return calls;
+}
+
+// One readable block for each call, for the dry run and the log.
+export function describe(call) {
+  const lines = [`${call.method.padEnd(6)} ${call.path}   ${call.name}`];
+  const body = call.body;
+  if (body.rules) {
+    const on = body.target === 'branch' ? `branch ${body.conditions.ref_name.include.join(', ')}` : `tag ${body.conditions.ref_name.include.join(', ')}`;
+    lines.push(`       ${on}, enforcement ${body.enforcement}, bypass ${body.bypass_actors.length ? body.bypass_actors.length : 'none'}`);
+    for (const rule of body.rules) {
+      if (rule.type === 'pull_request') lines.push(`       pull_request: ${rule.parameters.required_approving_review_count} approvals`);
+      else if (rule.type === 'required_status_checks') {
+        lines.push(`       required_status_checks (strict ${rule.parameters.strict_required_status_checks_policy}), from GitHub Actions (${ACTIONS_APP_ID}):`);
+        for (const check of rule.parameters.required_status_checks) lines.push(`         ${check.context}`);
+      } else lines.push(`       ${rule.type}`);
+    }
+  } else {
+    lines.push(`       ${Object.entries(body).map(([key, value]) => `${key} ${value}`).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+// What a read-back must hold, compared key by key. Returns the differences.
+export function compare(wanted, got) {
+  const problems = [];
+  if (got.enforcement !== wanted.enforcement) problems.push(`${wanted.name}: enforcement is ${got.enforcement}, not ${wanted.enforcement}`);
+  if ((got.bypass_actors ?? []).length !== 0) problems.push(`${wanted.name}: the bypass list is not empty`);
+  if (JSON.stringify(got.conditions?.ref_name?.include ?? []) !== JSON.stringify(wanted.conditions.ref_name.include)) problems.push(`${wanted.name}: it holds for ${JSON.stringify(got.conditions?.ref_name?.include)}`);
+  for (const rule of wanted.rules) {
+    const found = (got.rules ?? []).find((each) => each.type === rule.type);
+    if (!found) { problems.push(`${wanted.name}: the rule ${rule.type} is missing`); continue; }
+    if (rule.type === 'pull_request' && found.parameters?.required_approving_review_count !== 0) problems.push(`${wanted.name}: pull_request asks for ${found.parameters?.required_approving_review_count} approvals`);
+    if (rule.type === 'required_status_checks') {
+      const key = (check) => `${check.context}|${check.integration_id}`;
+      const want = rule.parameters.required_status_checks.map(key).sort();
+      const have = (found.parameters?.required_status_checks ?? []).map(key).sort();
+      if (JSON.stringify(want) !== JSON.stringify(have)) problems.push(`${wanted.name}: the required checks are ${JSON.stringify(have)}, not ${JSON.stringify(want)}`);
+      if (Boolean(found.parameters?.strict_required_status_checks_policy) !== rule.parameters.strict_required_status_checks_policy) problems.push(`${wanted.name}: up to date is ${found.parameters?.strict_required_status_checks_policy}`);
+    }
+  }
+  return problems;
+}
+
+// The gh door. Each call is `gh api` with a JSON body on stdin.
+export function ghApi(method, path, body) {
+  const args = ['api', '--method', method, path, '-H', 'Accept: application/vnd.github+json'];
+  if (body !== undefined) args.push('--input', '-');
+  const out = execFileSync('gh', args, { encoding: 'utf8', input: body === undefined ? undefined : JSON.stringify(body), env: childEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] });
+  return out.trim() ? JSON.parse(out) : null;
+}
+
+const explain = (error) => {
+  const text = `${error.stderr ?? ''}${error.message ?? ''}`;
+  if (/HTTP 403|Upgrade to GitHub Pro|403/.test(text)) return 'GitHub refused the ruleset (403). A private repo needs GitHub Pro for rulesets, and only a repo admin may set one.';
+  return text.trim().split('\n').slice(-3).join(' ');
+};
+
+// `atlas gate apply`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false }, line, gh = ghApi) {
+  if (what !== 'apply') throw new GateError(`there is no gate verb "${what ?? ''}". Use apply.`);
+  if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError('atlas gate apply needs --repo <owner/name>.');
+  if (off && on) throw new GateError('pick --off or --on, not both.');
+  const mode = off ? 'off' : on ? 'on' : 'apply';
+  const facts = mode === 'apply' ? gateFacts(root) : null;
+  if (dryRun) line('atlas gate apply: dry run, nothing changes.');
+  if (facts) line(`atlas.yaml read from ${root}: ${facts.checks.length} required check(s), up_to_date ${facts.upToDate}.`);
+  line(`GET    repos/${repo}/rulesets`);
+  let existing;
+  try { existing = gh('GET', `repos/${repo}/rulesets`) ?? []; } catch (error) {
+    if (!dryRun) { line(`atlas gate apply: ${explain(error)} Nothing was changed.`); return 1; }
+    line(`       (the read failed: ${explain(error)} The plan below assumes no ruleset exists.)`);
+    existing = [];
+  }
+  const calls = plan({ repo, facts, existing, mode, dryRun });
+  for (const call of calls) line(describe(call));
+  if (dryRun) return 0;
+  const written = [];
+  for (const call of calls) {
+    try { written.push({ call, answer: gh(call.method, call.path, call.body) }); } catch (error) {
+      line(`atlas gate apply: ${call.method} ${call.path} failed: ${explain(error)}`);
+      line(written.length ? `Done before the failure: ${written.map((each) => each.call.name).join(', ')}.` : 'Nothing was changed.');
+      return 1;
+    }
+  }
+  if (mode !== 'apply') { line(`atlas gate apply: both rulesets are ${mode === 'off' ? 'disabled' : 'active'}.`); return 0; }
+  const problems = [];
+  for (const wanted of rulesets(facts)) {
+    const id = written.find((each) => each.call.name === wanted.name)?.answer?.id ?? existing.find((ruleset) => ruleset.name === wanted.name)?.id;
+    const got = gh('GET', `repos/${repo}/rulesets/${id}`);
+    problems.push(...compare(wanted, got ?? {}));
+  }
+  const settings = gh('GET', `repos/${repo}`);
+  if (settings?.allow_auto_merge !== true) problems.push('the repo does not allow auto-merge');
+  if (problems.length) { for (const problem of problems) line(`  ✗ ${problem}`); line('atlas gate apply: the read-back differs. Look at the repo settings.'); return 1; }
+  line(`atlas gate apply: the gate is on for ${repo}. Read back: ${BRANCH_RULESET}, ${TAG_RULESET}, allow_auto_merge true.`);
+  return 0;
+}

package/door/lib/install.mjs

@@ -140,9 +140,12 @@ export async function install({ packageRoot, options = {}, line = console.log, e
   const installArgs = ['plugin', 'install', PLUGIN_ID, '--scope', 'user'];
   exec('claude', installArgs);
   line('');
-  for (const text of connectionSteps(env)) line(text);
+  // A cloud setup script runs before any session: the key comes from the
+  // environment variable, and no tools server has started yet (item 92cfbba3).
+  if (options.cloud) line('Installed. In a cloud session the key comes from the environment, and the lead checks the version at its first reply.');
+  else for (const text of connectionSteps(env)) line(text);
   line('');
-  return doctor({ packageRoot, options, line, env, exec });
+  return doctor({ packageRoot, options: { cloud: Boolean(options.cloud) }, line, env, exec });
 }
 
 // ---------------------------------------------------------------- upgrade
@@ -151,13 +154,15 @@ export async function install({ packageRoot, options = {}, line = console.log, e
 export const blobSha = (bytes) => createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
 export const sha512Integrity = (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
 
-function filesUnder(root) {
+function filesUnder(root, skip = () => false) {
   const out = new Map();
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
       const full = join(dir, entry);
+      const path = relative(root, full).split('\\').join('/');
+      if (skip(path)) continue;
       if (statSync(full).isDirectory()) walk(full);
-      else out.set(relative(root, full).split('\\').join('/'), readFileSync(full));
+      else out.set(path, readFileSync(full));
     }
   };
   walk(root);
@@ -201,6 +206,36 @@ export function matchTree({ tree, files }) {
   return problems;
 }
 
+// Claude Code writes `.in_use/` into a plugin copy to mark it in use. It is
+// not part of the package, so the proof of a loaded copy skips it.
+const COPY_MARKER = /^\.in_use(\/|$)/;
+const firstLines = (error, count = 3) => String(error?.stderr || error?.message || error).trim().split('\n').slice(0, count).join(' ');
+
+// Is the copy at packageRoot the copy that a master release run built? The
+// same proof as the upgrade, run on files already loaded. It reads only.
+// The proof runs from the copy it checks, so it catches stale, broken or
+// drifted files, not a package made to lie (security review of atlas#187).
+// "unproven" is the upgrade's refusal: no master run built this version.
+// "not checked" is never a pass: the caller says the reason.
+export function proveCopy({ packageRoot, exec = defaultExec }) {
+  try {
+    const { version } = packageJson(packageRoot);
+    const repo = repoOf(packageRoot);
+    const gh = (args) => JSON.parse(exec('gh', args));
+    let run;
+    try { run = findReleaseRun({ gh, repo, version }); } catch (error) { return { state: 'not checked', reason: `GitHub did not answer: ${firstLines(error)}` }; }
+    if (!run) return { state: 'unproven', reason: `no successful release run on a commit of master built ${version}. It may have been published from a branch.` };
+    let tree;
+    try { tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${run.head_sha}?recursive=1`]).tree; } catch (error) { return { state: 'not checked', reason: `GitHub did not give the file tree: ${firstLines(error)}` }; }
+    const files = filesUnder(packageRoot, (path) => COPY_MARKER.test(path));
+    const problems = matchTree({ tree, files });
+    const found = { run: run.id, commit: run.head_sha };
+    return problems.length ? { state: 'differs', ...found, problems: problems.slice(0, 20) } : { state: 'match', ...found, files: files.size };
+  } catch (error) {
+    return { state: 'not checked', reason: `the proof stopped: ${firstLines(error)}` };
+  }
+}
+
 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);
@@ -276,11 +311,18 @@ export function doctor({ packageRoot, options = {}, line = console.log, env = pr
   }
 
   // Off the cloud, the key lives only in the connection file. The cloud passes it as a variable.
-  if (env.CLAUDE_CODE_REMOTE !== 'true') {
+  if (env.CLAUDE_CODE_REMOTE !== 'true' && !options.cloud) {
     const connection = readConnection({ HOME: env.HOME });
     check('connection', connection.state === 'ok', connection.state === 'ok' ? `the Engram connection file is in place; the key expires ${connection.expires}` : connection.message);
   }
 
+  // A cloud setup runs before the first session, so the three checks of a
+  // started tools server cannot pass yet. The lead checks at its first reply.
+  if (options.cloud) {
+    for (const row of rows) line(`${row.pass ? 'PASS' : 'FAIL'}  ${row.name.padEnd(12)} ${row.detail}`);
+    line('SKIP  tools server, engram and gh: no session has started yet');
+    return rows.every((row) => row.pass) ? 0 : 1;
+  }
   let health = null;
   try { health = JSON.parse(readFileSync(join(env.HOME, '.atlas', 'health.json'), 'utf8')); } catch { /* never started */ }
   check('tools server', Boolean(health), health ? `last started ${health.started_at}, Atlas ${health.package_version}` : 'the Atlas tools server has not started yet. Open a Claude Code session, then run "atlas doctor" again.');

package/package.json

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

@@ -93,7 +93,7 @@ set. A test keeps the two lists equal.
 | Command | When to call it |
 |---|---|
 | `atlas install` | Once on a new Mac, when the owner asks for Atlas there |
-| `atlas upgrade` | When the owner asks to upgrade Atlas. Call the `atlas_upgrade` tool instead: the Bash sandbox blocks this command. Run the command by hand only where that tool is missing |
+| `atlas upgrade` | When the owner asks to upgrade Atlas. Call the `atlas_upgrade` tool instead: the Bash sandbox blocks this command. Run the command by hand only where that tool is missing. In a cloud session, call the tool with `check: true` at the first reply, as section 7 says |
 | `atlas doctor` | When Atlas seems missing or broken in a session |
 | `atlas check` | Before you ask for a merge in a repo that has the shape check |
 | `atlas status` | To learn whether a repo's check is current or behind |
@@ -105,7 +105,30 @@ set. A test keeps the two lists equal.
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
+| `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 |
 | `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.
 A person merges every file that `atlas tests write` writes.
+
+## 7. The first reply of a cloud session
+
+A cloud session can start from an old setup and run an old Atlas. So in a
+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
+   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
+   reason. Then go on.
+5. 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.
+
+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/lib/child-env.mjs

@@ -8,6 +8,11 @@ const CHILD_VARIABLES = ['PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'T
 // proxy is a loopback address (owner, 7 October 2026: "yes fix it and test").
 const CLOUD_PROXY_VARIABLES = ['HTTPS_PROXY', 'https_proxy'];
 const CLOUD_NO_PROXY_VARIABLES = ['NO_PROXY', 'no_proxy'];
+// The two fixed values of Claude's cloud proxy (owner, 7 October 2026, "Narrow
+// exception"). The tools server accepts exactly these values. A child gets the
+// CA file only when it is this exact value: without it, npm behind the proxy
+// waits about 70 seconds before it answers (item 92cfbba3, 24 October 2026).
+export const CLOUD_NODE_VARIABLES = Object.freeze({ NODE_EXTRA_CA_CERTS: '/root/.ccr/ca-bundle.crt', NODE_PATH: '/usr/local/lib/node_modules_global' });
 const LOOPBACK_PROXY = /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d{1,5}\/?$/;
 
 export function childEnvironment(env = process.env) {
@@ -19,6 +24,7 @@ export function childEnvironment(env = process.env) {
     const proxies = CLOUD_PROXY_VARIABLES.filter((name) => env[name] !== undefined);
     if (proxies.length && proxies.every((name) => LOOPBACK_PROXY.test(env[name]))) {
       for (const name of [...proxies, ...CLOUD_NO_PROXY_VARIABLES]) if (env[name] !== undefined) out[name] = env[name];
+      if (env.NODE_EXTRA_CA_CERTS === CLOUD_NODE_VARIABLES.NODE_EXTRA_CA_CERTS) out.NODE_EXTRA_CA_CERTS = env.NODE_EXTRA_CA_CERTS;
     }
   }
   return out;

package/work/mcp.mjs

@@ -24,8 +24,8 @@ import { createVerbs, STAGES, TIERS, DRIVERS, LINK_KINDS, REPO_KINDS, WAITS_ON,
 import { COST_MEANING, DECISION_KINDS } from './lib/questions.mjs';
 import { FATAL_CONCLUSIONS } from './lib/delivery.mjs';
 import { createMcpServer } from './lib/mcp-stdio.mjs';
-import { childEnvironment } from './lib/child-env.mjs';
-import { upgrade } from '../door/lib/install.mjs';
+import { childEnvironment, CLOUD_NODE_VARIABLES } from './lib/child-env.mjs';
+import { upgrade, proveCopy } from '../door/lib/install.mjs';
 export { childEnvironment };
 
 const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -74,7 +74,7 @@ export const TOOLS = [
   { 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, no owner flag needed.', 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, no owner flag needed.', 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, no owner flag needed.', 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 only reports the loaded and the newest version. Scope: this Mac, no tracker write. Owner present only. Not 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 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, also in a Claude cloud session and with the owner flag off; the lead calls it at the first reply of a cloud session. Scope: this Mac, no tracker write. The upgrade itself is owner present only, and never 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 } },
 ];
 
 // The Engram connection: the address and the key, in one setting, separated by
@@ -156,7 +156,7 @@ export const HOSTILE_NODE_VARIABLES = Object.freeze(['NODE_TLS_REJECT_UNAUTHORIZ
 // that proxy. The owner accepted that proxy on 7 October 2026 ("Narrow
 // exception"): the server accepts exactly these values, and only when the
 // cloud's own marker is set. Any other value stays hostile, in the cloud too.
-export const CLOUD_NODE_VARIABLES = Object.freeze({ NODE_EXTRA_CA_CERTS: '/root/.ccr/ca-bundle.crt', NODE_PATH: '/usr/local/lib/node_modules_global' });
+export { CLOUD_NODE_VARIABLES };
 export const inClaudeCloud = (env) => env.CLAUDE_CODE_REMOTE === 'true';
 export function hostileVariables(env) {
   const cloud = inClaudeCloud(env);
@@ -246,16 +246,24 @@ const ATLAS_VERSION_OF = (root) => JSON.parse(readFileSync(join(root, 'package.j
 function childExec(env) {
   return (command, args) => execFileSync(command, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 600_000, stdio: ['pipe', 'pipe', 'pipe'], env: childEnvironment(env) });
 }
-export async function runUpgrade({ args = {}, env = process.env, ownerPresent, packageRoot = PACKAGE_ROOT, exec = childExec(env), upgradeFn = upgrade } = {}) {
+const PROOFS = new WeakMap();
+export async function runUpgrade({ args = {}, env = process.env, ownerPresent, packageRoot = PACKAGE_ROOT, exec = childExec(env), upgradeFn = upgrade, proveFn = proveCopy } = {}) {
   const refuse = (message) => { const error = new Error(message); error.name = 'VerbError'; throw error; };
-  if (!ownerPresent) refuse('atlas_upgrade needs the owner-present flag on the server host (ATLAS_WORK_OWNER_PRESENT=1)');
-  if (inClaudeCloud(env)) refuse('atlas_upgrade does not run in a Claude cloud session. A new cloud session installs the newest release.');
   const loaded = ATLAS_VERSION_OF(packageRoot);
+  // The check reads only, so it runs in a cloud session and with the owner
+  // flag off (item 92cfbba3): a cloud session states its lag at its first reply.
   if (args.check) {
     let newest;
     try { newest = exec('npm', ['view', '@arjunkhera/atlas', 'version']).trim(); } catch (error) { refuse(`npm could not read the newest version: ${String(error.stderr || error.message).trim().split('\n').slice(0, 3).join(' ')}`); }
-    return { loaded, newest, behind: newest !== loaded };
+    // The loaded copy cannot change within a server's life, so one proof per
+    // copy: a repeated check makes no new GitHub reads.
+    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) };
   }
+  if (!ownerPresent) refuse('atlas_upgrade needs the owner-present flag on the server host (ATLAS_WORK_OWNER_PRESENT=1)');
+  if (inClaudeCloud(env)) refuse('atlas_upgrade does not run in a Claude cloud session. A new cloud session installs the newest release.');
   const lines = [];
   let code;
   try { code = await upgradeFn({ packageRoot, options: { yes: true }, line: (text) => lines.push(text), env, exec }); } catch (error) {