@arjunkhera/atlas 0.4.53 → 0.4.55

package/door/lib/install.mjs

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

package/door/lib/refresh-judge.mjs

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

package/door/lib/refresh.mjs

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

package/door/lib/signed-act.mjs

@@ -60,6 +60,8 @@ const HASH = '[0-9a-f]{64}';
 const NUMBER = '[1-9][0-9]{0,8}';
 // A branch name: plain characters only, so a line never holds a space.
 const BRANCH = '[A-Za-z0-9._/-]{1,100}';
+// A time in the form that payloadText writes: UTC, with milliseconds.
+const TIME = '\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z';
 export const BRANCH_FORM = new RegExp(`^${BRANCH}$`);
 
 // Each kind of act, its fields, and the exact form of its line. The order of
@@ -93,6 +95,12 @@ export const ACTS = Object.freeze({
   // audit code, made with `atlas approve audit-code` after the owner read
   // that diff (item f36c6b0f). It names the merge commit and the fingerprint
   // of its audit-code change, so the touch covers only the diff he read.
+  // A signing window (item 4af66381; design docs/design-docs/signing-window/).
+  // It names the repo, the branch, the tip that the owner's morning list
+  // ended at (the seen commit), and the end time. The touch is the start, so
+  // the end needs no act; window.mjs holds the 12-hour rule and the
+  // allow-list.
+  window: { fields: ['repo', 'branch', 'seen', 'ends'], form: `(${REPO}) (${BRANCH}) (${SHA}) (${TIME})` },
   'accept-code': { fields: ['repo', 'pr', 'head', 'merge', 'run', 'diff', 'words', 'check'], form: `(${REPO}) (${NUMBER}) (${SHA}) (${SHA}) ([1-9][0-9]{0,15}) (${HASH}) (${HASH}) ([^\\s].{0,99})` },
 });
 
@@ -122,7 +130,7 @@ export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
 export const AUDIT_CODE = Object.freeze([
   AUDIT_WORKFLOW, '.github/workflows/atlas-gate.yml', '.github/workflows/atlas-jobs.yml', '.github/workflows/release.yml',
   'packages/atlas/bin/atlas', 'packages/atlas/door/cli.mjs', 'packages/atlas/owner-only.yaml', 'packages/atlas/door/jobs/gate-audit.yaml',
-  ...['gate.mjs', 'gate-audit.mjs', 'gate-check.mjs', 'owner-only.mjs', 'jobs.mjs', 'issues.mjs', 'signed-act.mjs'].map((name) => `packages/atlas/door/lib/${name}`),
+  ...['gate.mjs', 'gate-audit.mjs', 'gate-check.mjs', 'owner-only.mjs', 'jobs.mjs', 'issues.mjs', 'signed-act.mjs', 'window.mjs'].map((name) => `packages/atlas/door/lib/${name}`),
   'packages/atlas/shape/check.mjs', 'packages/atlas/work/lib/child-env.mjs',
 ]);
 export const AUDIT_CODE_TEST = 'audit-code';