@arjunkhera/atlas 0.3.45 → 0.3.46

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.45",
+  "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

@@ -140,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.
@@ -169,9 +171,9 @@ export const FLAGS = Object.freeze({
   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.

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.45",
+  "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 |
@@ -110,3 +110,25 @@ set. A test keeps the two lists equal.
 
 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) {