@arjunkhera/atlas 0.4.53 → 0.4.55

package/.claude-plugin/plugin.json

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

package/.mcp.json

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

package/door/cli.mjs

@@ -15,35 +15,17 @@ import { resolve, join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { open } from './lib/pull-request.mjs';
-import { write as writeTooling, changes as toolingChanges, ToolingRefusal, CHECK_PATH, WORKFLOW_PATH } from './lib/tooling.mjs';
-import { statusMany, copies } from './lib/status.mjs';
 import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs';
 import { packagePackageVersion } from './lib/releases.mjs';
-import { install, upgrade, doctor } from './lib/install.mjs';
-import { checkPaths, LIMITS } from './lib/ste.mjs';
-import { checkDesignFolder, designFolderOf, repoRootFrom } from './lib/design.mjs';
-import { writeDesignPage, readTracker } from './lib/design-build.mjs';
-import { listDesigns, freezeDesign } from './lib/design-freeze.mjs';
-import { writePage } from './lib/page.mjs';
-import { writeViewPage, viewCapabilities } from './lib/view.mjs';
-import { loadPrivateTerms } from './lib/privacy.mjs';
-import { checkCommand as testsCheck, writeCommand as testsWrite } from './lib/tests.mjs';
-import { proofCommand as testsProof } from './lib/proof.mjs';
-import { verdictCommand as testsVerdict, namedCommand as testsNamed, rerunCommand as testsRerun } from '../tests/verdict.mjs';
-import { runKept } from '../tests/kept.mjs';
-import { sweepCommand as testsSweep, coversCommand as testsCovers } from '../tests/sweep.mjs';
-import { issuesCommand as testsIssues } from './lib/issues.mjs';
-import { jobsCommand } from './lib/jobs.mjs';
-import { runnerCommand } from './lib/runner.mjs';
-import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
-import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
-import { afterCommand as testsAfter } from './lib/passes-after.mjs';
-import { upkeepCommand } from './lib/upkeep.mjs';
-import { gateCommand, mergeList } from './lib/gate.mjs';
-import { judgeCommand } from './lib/judge.mjs';
-import { approveCommand } from './lib/approve.mjs';
-
+// Each command loads its own code when it runs, with a plain `import()`. So
+// `atlas gate check` loads only the gate's code, and a file that no gate
+// command imports cannot change the gate (the signing window, item 4af66381,
+// rule 1: the gate's import closure is its own code).
+
+// The commands of the Mac setup, loaded when one runs.
+const install = async (...args) => (await import('./lib/install.mjs')).install(...args);
+const upgrade = async (...args) => (await import('./lib/install.mjs')).upgrade(...args);
+const doctor = async (...args) => (await import('./lib/install.mjs')).doctor(...args);
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ATLAS_VERSION = packagePackageVersion(PACKAGE_ROOT);
 
@@ -182,6 +164,9 @@ const HELP = `atlas — the door into a repo's Atlas files
       --body <file>                    the pull request text, for the "behaviour change: no" of a refactor
       --json                           print the answer as JSON
       --summary <file> --output <file> append the text to a job summary, and result= and class= to an output file
+  atlas gate hold --repo <owner/name> --commit <sha>   the release job's owner hold: exit 3 when a merge since the owner's last seen commit has an owner change that no merge act signed
+      --branch <name>                  the branch; default GitHub's default branch
+      --root <repo>                    the clone with the history (default: this folder)
   atlas gate replay [--days 30]        the static rules of the gate over the first-parent commits of the main branch; the owner share. Writes nothing
       --root <repo>                    the clone to read (default: this folder)
       --branch <name>                  the branch; default origin/HEAD
@@ -195,6 +180,9 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas approve act <kind>             sign one other act and print its block: brake-clear --repo --commit, ready --repo --item, lock --item --card <file>, decision --item --words <file>, waiver --repo --pr --head --decision --check
       --out <file>                     write the block here; default the terminal
   atlas approve audit [<pr>...]        the owner's acceptance of the night's audit reds, on his Mac: list each open audit issue of an owner merge that no touch signed, then one touch signs an accept act for each, the block goes on each pull request, each audit issue closes, and it prints the one message for the lead
+  atlas approve window                 the signing window, on his Mac in a clone: list each merge since the last seen commit, then one touch marks the tip seen and opens a window of up to 12 hours; the block goes on the atlas-window issue
+      --hours <n>                      the length of the window, 0 to 12; default 12. With 0 the touch only marks the list seen
+      --list                           show the list and sign nothing
   atlas approve verify --file <file>   check each signed block of a file against atlas/owner-signers; exit 0 when one counts
       --signers <file>                 the key file; default atlas/owner-signers under --root
   atlas approve key-check              one touch signs a test text, and the key's own public half checks it: does the key count for the gate
@@ -241,7 +229,7 @@ export const FLAGS = Object.freeze({
   runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', comment: 'value', notice: 'switch', json: 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', from: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
-  approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
+  approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value', hours: 'value', list: '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', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -287,7 +275,9 @@ let readerClosed = false;
 const line = (text = '') => { if (!readerClosed) process.stdout.write(`${text}\n`); };
 process.stdout.on('error', (error) => { if (error.code === 'EPIPE') { readerClosed = true; return; } throw error; });
 
-function toolingCommand(chosen) {
+async function toolingCommand(chosen) {
+  const { open } = await import('./lib/pull-request.mjs');
+  const { write: writeTooling, changes: toolingChanges, ToolingRefusal } = await import('./lib/tooling.mjs');
   const root = rootOf(chosen);
   const what = chosen._[1] ?? 'write';
   const replaceUnknown = Boolean(chosen['replace-unknown']);
@@ -320,9 +310,11 @@ function toolingCommand(chosen) {
   }
 }
 
-function statusCommand(chosen) {
+async function statusCommand(chosen) {
+  const { statusMany } = await import('./lib/status.mjs');
+  const { mergeList } = await import('./lib/gate.mjs');
   const roots = chosen._.slice(1).length ? chosen._.slice(1).map((one) => resolve(one)) : [rootOf(chosen)];
-  if (chosen.all || chosen.json) return copiesCommand(roots, { all: Boolean(chosen.all), json: Boolean(chosen.json) });
+  if (chosen.all || chosen.json) return await copiesCommand(roots, { all: Boolean(chosen.all), json: Boolean(chosen.json) });
   const rows = statusMany(roots, PACKAGE_ROOT);
   for (const row of rows) {
     line(`${row.state.toUpperCase().padEnd(8)} ${row.root}`);
@@ -339,7 +331,8 @@ function statusCommand(chosen) {
 
 // One row for each Atlas copy (roadmap item R19). Exit 1 when a copy is
 // behind or broken, so a watcher can act on the exit alone.
-function copiesCommand(roots, { all, json }) {
+async function copiesCommand(roots, { all, json }) {
+  const { copies } = await import('./lib/status.mjs');
   const repos = roots.map((root) => copies({ root, packageRoot: PACKAGE_ROOT, all }));
   const decided = `Decided by the release lists in Atlas ${ATLAS_VERSION}, never by git history or the network.`;
   if (json) {
@@ -360,7 +353,9 @@ function copiesCommand(roots, { all, json }) {
   return repos.some((repo) => repo.rows.some((one) => bad.includes(one.state))) ? 1 : 0;
 }
 
-function steCommand(chosen) {
+async function steCommand(chosen) {
+  const { checkPaths, LIMITS } = await import('./lib/ste.mjs');
+  const { loadPrivateTerms } = await import('./lib/privacy.mjs');
   const paths = chosen._.slice(1);
   if (!paths.length) throw new Error('give a file or a folder: atlas ste <path> [--share]');
   const share = Boolean(chosen.share);
@@ -377,7 +372,10 @@ function steCommand(chosen) {
   return count ? 1 : 0;
 }
 
-function designCommand(chosen) {
+async function designCommand(chosen) {
+  const { checkDesignFolder, designFolderOf, repoRootFrom } = await import('./lib/design.mjs');
+  const { writeDesignPage, readTracker } = await import('./lib/design-build.mjs');
+  const { listDesigns, freezeDesign } = await import('./lib/design-freeze.mjs');
   const what = chosen._[1];
   const folders = chosen._.slice(2);
   if (what === 'folder') {
@@ -443,7 +441,9 @@ function designCommand(chosen) {
   return count ? 1 : 0;
 }
 
-function pageCommand(chosen) {
+async function pageCommand(chosen) {
+  const { writePage } = await import('./lib/page.mjs');
+  const { checkPaths } = await import('./lib/ste.mjs');
   const sources = chosen._.slice(2);
   if (chosen._[1] !== 'build') throw new Error('use atlas page build <file or folder>');
   if (sources.length !== 1) throw new Error('give one markdown file or one folder: atlas page build <file or folder>');
@@ -463,7 +463,8 @@ function pageCommand(chosen) {
   return findings.length ? 1 : 0;
 }
 
-function viewCommand(chosen) {
+async function viewCommand(chosen) {
+  const { writeViewPage, viewCapabilities } = await import('./lib/view.mjs');
   if (chosen._[1] !== 'build' || chosen._.length > 2) throw new Error('use atlas view build --product <id>');
   const product = chosen.product;
   const out = resolve(chosen.out ?? join('docs', 'artifacts', `${product}-view.html`));
@@ -477,49 +478,56 @@ async function testsCommand(chosen) {
   const root = rootOf(chosen);
   const what = chosen._[1];
   if (what === 'check') {
-    return testsCheck({ halves: chosen.halves, evidence: chosen.evidence, tests: chosen.tests, guardsFrom: chosen['guards-from'], run: chosen.run }, root, line, PACKAGE_ROOT);
+    return (await import('./lib/tests.mjs')).checkCommand({ halves: chosen.halves, evidence: chosen.evidence, tests: chosen.tests, guardsFrom: chosen['guards-from'], run: chosen.run }, root, line, PACKAGE_ROOT);
   }
-  if (what === 'write') return testsWrite({ dryRun: Boolean(chosen['dry-run']) }, root, PACKAGE_ROOT, line);
-  if (what === 'proof') return testsProof({ run: chosen.run, own: chosen.own, evidence: chosen.evidence, base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
-  if (what === 'verdict') return testsVerdict({ run: chosen.run, base: chosen.base, evidence: chosen.evidence, covers: Boolean(chosen.covers) }, root, line);
-  if (what === 'changed') return testsChanged({ base: chosen.base, head: chosen.head, out: chosen.out, text: Boolean(chosen.text) }, root, line);
-  if (what === 'after') return testsAfter({ base: chosen.base, head: chosen.head, list: chosen.list, out: chosen.out, text: Boolean(chosen.text) }, root, line);
-  if (what === 'before') return testsBefore({ base: chosen.base, head: chosen.head, list: chosen.list, out: chosen.out, side: chosen.side, old: chosen.old, new: chosen.new, text: Boolean(chosen.text) }, root, line);
-  if (what === 'named') return testsNamed({ base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
-  if (what === 'sweep') return testsSweep({ evidence: chosen.evidence, since: chosen.since, base: chosen.base, out: chosen.out, text: Boolean(chosen.text) }, root, line);
-  if (what === 'covers') return testsCovers({ itemId: chosen._[2], evidence: chosen.evidence, json: Boolean(chosen.json) }, root, line);
-  if (what === 'kept') return (await runKept({ root, evidenceDir: chosen.evidence, only: chosen.scenario ?? null, write: (text) => process.stdout.write(text) })).exit;
-  if (what === 'rerun') return testsRerun({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests, language: chosen.language ?? 'javascript' }, root, line);
-  if (what === 'issues') return testsIssues({ findings: chosen.findings, repo: chosen.repo, max: chosen.max, bot: chosen.bot, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+  if (what === 'write') return (await import('./lib/tests.mjs')).writeCommand({ dryRun: Boolean(chosen['dry-run']) }, root, PACKAGE_ROOT, line);
+  if (what === 'proof') return (await import('./lib/proof.mjs')).proofCommand({ run: chosen.run, own: chosen.own, evidence: chosen.evidence, base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
+  if (what === 'verdict') return (await import('../tests/verdict.mjs')).verdictCommand({ run: chosen.run, base: chosen.base, evidence: chosen.evidence, covers: Boolean(chosen.covers) }, root, line);
+  if (what === 'changed') return (await import('./lib/changed-tests.mjs')).changedCommand({ base: chosen.base, head: chosen.head, out: chosen.out, text: Boolean(chosen.text) }, root, line);
+  if (what === 'after') return (await import('./lib/passes-after.mjs')).afterCommand({ base: chosen.base, head: chosen.head, list: chosen.list, out: chosen.out, text: Boolean(chosen.text) }, root, line);
+  if (what === 'before') return (await import('./lib/fails-before.mjs')).beforeCommand({ base: chosen.base, head: chosen.head, list: chosen.list, out: chosen.out, side: chosen.side, old: chosen.old, new: chosen.new, text: Boolean(chosen.text) }, root, line);
+  if (what === 'named') return (await import('../tests/verdict.mjs')).namedCommand({ base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
+  if (what === 'sweep') return (await import('../tests/sweep.mjs')).sweepCommand({ evidence: chosen.evidence, since: chosen.since, base: chosen.base, out: chosen.out, text: Boolean(chosen.text) }, root, line);
+  if (what === 'covers') return (await import('../tests/sweep.mjs')).coversCommand({ itemId: chosen._[2], evidence: chosen.evidence, json: Boolean(chosen.json) }, root, line);
+  if (what === 'kept') return (await (await import('../tests/kept.mjs')).runKept({ root, evidenceDir: chosen.evidence, only: chosen.scenario ?? null, write: (text) => process.stdout.write(text) })).exit;
+  if (what === 'rerun') return (await import('../tests/verdict.mjs')).rerunCommand({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests, language: chosen.language ?? 'javascript' }, root, line);
+  if (what === 'issues') return (await import('./lib/issues.mjs')).issuesCommand({ findings: chosen.findings, repo: chosen.repo, max: chosen.max, bot: chosen.bot, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
   throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, changed, before, after, sweep, covers, kept, issues or rerun.`);
 }
 
-function jobsVerb(chosen) {
+async function jobsVerb(chosen) {
+  const { jobsCommand } = await import('./lib/jobs.mjs');
   return jobsCommand({ what: chosen._[1], root: rootOf(chosen), repo: chosen.repo, branch: chosen.branch, out: chosen.out, findings: chosen.findings, max: chosen.max, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
 }
 
-function runnerVerb(chosen) {
+async function runnerVerb(chosen) {
+  const { runnerCommand } = await import('./lib/runner.mjs');
   return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, comment: chosen.comment, notice: Boolean(chosen.notice), json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
 }
 
-function upkeepVerb(chosen) {
+async function upkeepVerb(chosen) {
+  const { upkeepCommand } = await import('./lib/upkeep.mjs');
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last, base: chosen.base }, rootOf(chosen), line);
 }
 
-function gateVerb(chosen) {
+async function gateVerb(chosen) {
+  const { gateCommand } = await import('./lib/gate.mjs');
   return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, from: chosen.from, base: chosen.base, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch, errors: Boolean(chosen.errors), forced: Boolean(chosen.forced), findings: chosen.findings }, line);
 }
 
-function approveVerb(chosen) {
+async function approveVerb(chosen) {
+  const { approveCommand } = await import('./lib/approve.mjs');
   const flags = { repo: chosen.repo, commit: chosen.commit, item: chosen.item, card: chosen.card, words: chosen.words, pr: chosen.pr, head: chosen.head, decision: chosen.decision, check: chosen.check };
-  return approveCommand({ words: chosen._.slice(1), repo: chosen.repo, root: chosen.root === undefined ? undefined : rootOf(chosen), key: chosen.key, provider: chosen.provider, yes: Boolean(chosen.yes), out: chosen.out, file: chosen.file, signers: chosen.signers, flags }, line);
+  return approveCommand({ words: chosen._.slice(1), repo: chosen.repo, root: chosen.root === undefined ? undefined : rootOf(chosen), key: chosen.key, provider: chosen.provider, yes: Boolean(chosen.yes), out: chosen.out, file: chosen.file, signers: chosen.signers, flags, hours: chosen.hours, list: Boolean(chosen.list) }, line);
 }
 
-function judgeVerb(chosen) {
+async function judgeVerb(chosen) {
+  const { judgeCommand } = await import('./lib/judge.mjs');
   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);
 }
 
-function checkCommand(chosen) {
+async function checkCommand(chosen) {
+  const { mergeList } = await import('./lib/gate.mjs');
   const root = rootOf(chosen);
   const report = scan({ root, repoId: chosen.repo ?? null });
   const decision = verdict(report, chosen['fail-on'] ?? 'error');

package/door/lib/approve.mjs

@@ -28,14 +28,15 @@
 // a hardware key needs an ssh-keygen that reads it. No signing call runs in a
 // test: each one takes `deps`, which a test replaces.
 import { execFileSync, spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir, tmpdir, platform } from 'node:os';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
-import { ghApi, pinnedRuns, commitAudit } from './gate.mjs';
-import { GATE_CHECK } from './gate-check.mjs';
+import { ghApi, pinnedRuns, commitAudit, prComments, windowComments } from './gate.mjs';
+import { GATE_CHECK, judge } from './gate-check.mjs';
+import { WINDOW_HOURS, WINDOW_LABEL, WINDOW_TITLE, windowActs, seenAt, holdsCommit } from './window.mjs';
 import {
   ACTS, MAX_ACTS, AUDIT_CHECK, AUDIT_CHECKS, AUDIT_TEST, AUDIT_CODE, AUDIT_CODE_TEST, AUDIT_WORKFLOW, auditCodeDiff, NAMESPACE, SIGNERS_FILE, payloadText, blockText, parseSigners, verifyBlock, verifyTexts, fingerprint, wordsFingerprint, SignedActError,
   preKeyKeys,
@@ -610,12 +611,120 @@ export async function approveAuditCode({ prs = [], repo, root, key, provider, ye
   return 0;
 }
 
+// ------------------------------------------------------------ atlas approve window
+
+// `atlas approve window` (item 4af66381; design docs/design-docs/signing-window/).
+// It runs on the owner's Mac, in a clone of the repo. It builds the morning
+// list from git and the signed acts: each first-parent merge of the default
+// branch after the newest seen commit, judged again with the code of this
+// Mac's Atlas. It reads no issue for the list (rule 3). One touch then signs
+// one window act that names the tip of the list as seen and an end time at
+// most WINDOW_HOURS on (rule 2). With --hours 0 the touch only marks the list
+// seen. With --list it signs nothing. Exit 0 when the act is posted.
+export const LIST_MAX = 200;
+export function windowRow(deps, { repo, root, sha }) {
+  const out = { sha };
+  let pull;
+  try { pull = (deps.gh('GET', `repos/${repo}/commits/${sha}/pulls`) ?? []).find((each) => each.merged_at && each.merge_commit_sha === sha); } catch { return { ...out, state: 'UNREAD', why: 'GitHub did not say which pull request merged it' }; }
+  if (!pull) return { ...out, state: 'PUSH', why: 'it reached the branch with no pull request: a push past the gate' };
+  Object.assign(out, { pr: Number(pull.number), title: plainText(pull.title).slice(0, 100), merged_at: String(pull.merged_at) });
+  let parent;
+  try { parent = execFileSync('git', ['-C', root, 'rev-parse', '--verify', `${sha}^1`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return { ...out, state: 'UNREAD', why: 'its parent is not in this clone' }; }
+  let texts = null;
+  try { texts = [...prComments(deps.gh, repo, pull.number), ...windowComments(deps.gh, repo)]; } catch { texts = null; }
+  let answer;
+  try { answer = judge({ root, base: parent, head: pull.head?.sha, body: String(pull.body ?? ''), now: new Date(pull.merged_at), signed: { repo, pr: Number(pull.number), baseRef: pull.base?.ref ?? null, texts } }); } catch (error) { return { ...out, state: 'UNREAD', why: plainText(error?.message ?? error).slice(0, 160) }; }
+  const shown = (kind) => answer.rows.filter((row) => row.kind === kind).slice(0, 4).map((row) => plainText(`${row.class}${row.path ? ` ${row.path}` : ''}`).slice(0, 160));
+  if (answer.result === 'red') return { ...out, state: 'RED', rows: [...shown('red'), ...shown('owner')] };
+  if (answer.result === 'owner') return { ...out, state: 'OWNER, NO ACT', rows: shown('owner') };
+  if (answer.signed?.window) return { ...out, state: 'WINDOW', rows: shown('signed') };
+  if (answer.signed) return { ...out, state: 'SIGNED', rows: shown('signed') };
+  return { ...out, state: 'GREEN', rows: [] };
+}
+
+export async function approveWindow({ repo, root, key, provider, yes = false, hours, list = false }, line, deps = DEPS) {
+  const name = repoOf({ repo, root });
+  const length = hours === undefined || hours === true ? WINDOW_HOURS : Number(hours);
+  if (!Number.isInteger(length) || length < 0 || length > WINDOW_HOURS) throw new ApproveError(`--hours must be a whole number from 0 to ${WINDOW_HOURS}.`);
+  const clone = resolve(root ?? '.');
+  const git = (args) => execFileSync('git', ['-C', clone, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 }).trim();
+  let origin = '';
+  try { origin = git(['remote', 'get-url', 'origin']); } catch { origin = ''; }
+  if (!new RegExp(`^(https://|ssh://git@|git@)github\\.com[:/]${name.replace(/[.]/g, '\\.')}(\\.git)?$`, 'i').test(origin)) throw new ApproveError(`${clone} is not a clone of ${name}; run the command in the clone.`);
+  const branch = String(deps.gh('GET', `repos/${name}`)?.default_branch ?? '');
+  if (!branch) throw new ApproveError(`GitHub gave no default branch of ${name}.`);
+  (deps.fetch ?? ((one) => git(['fetch', '--quiet', 'origin', one])))(branch);
+  const tip = git(['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
+  const { keys } = signersOn(deps, name, branch);
+  const acts = windowActs(verifyTexts(windowComments(deps.gh, name), keys), { repo: name, branch });
+  const seen = seenAt(acts, (one) => holdsCommit(clone, one, tip));
+  let start = seen?.act.seen ?? null;
+  if (!start) {
+    const added = git(['log', '--first-parent', '--diff-filter=A', '--format=%H', tip, '--', 'packages/atlas/door/lib/window.mjs']).split('\n').filter(Boolean);
+    start = added.at(-1) ?? git(['rev-list', '--first-parent', '--max-count=1', '--skip=20', tip]) ?? null;
+  }
+  const commits = start ? git(['rev-list', '--first-parent', '--reverse', `${start}..${tip}`]).split('\n').filter(Boolean) : [];
+  line(`atlas approve window: ${name}, ${branch}. Merges since ${seen ? `your last seen commit ${start.slice(0, 7)} (${seen.signed_at})` : `${start ? start.slice(0, 7) : 'the start'}, with no window act before`}: ${commits.length}.`);
+  if (commits.length > LIST_MAX) line(`  Only the newest ${LIST_MAX} are judged here; ${commits.length - LIST_MAX} older merge(s) are counted, not listed.`);
+  const rows = commits.slice(-LIST_MAX).map((sha) => windowRow(deps, { repo: name, root: clone, sha }));
+  const text = [];
+  for (const row of rows) {
+    text.push(`  ${row.pr ? `#${row.pr}` : row.sha.slice(0, 7)}${row.merged_at ? `  merged ${row.merged_at}` : ''}  ${row.state}  ${row.title ?? ''}`.trimEnd());
+    for (const one of row.rows ?? []) text.push(`        ${one}`);
+    if (row.why) text.push(`        ${row.why}`);
+  }
+  for (const one of text) line(one);
+  const counts = ['WINDOW', 'SIGNED', 'GREEN', 'OWNER, NO ACT', 'RED', 'PUSH', 'UNREAD'].map((state) => [state, rows.filter((row) => row.state === state).length]).filter(([, n]) => n);
+  line(`  ${counts.map(([state, n]) => `${n} ${state}`).join(', ') || 'no merge'}.`);
+  const at = deps.now();
+  const stamp = new Date(at).toISOString().slice(0, 16).replace(':', '-');
+  const folder = deps.listFolder ?? join(homedir(), '.atlas', 'window');
+  try {
+    mkdirSync(folder, { recursive: true });
+    const file = join(folder, `${name.replace('/', '-')}-${stamp}.md`);
+    writeFileSync(file, [`# ${name} ${branch}: merges up to ${tip}`, '', `Built ${new Date(at).toISOString()} from git and the signed acts.`, '', '```text', ...text, '```', ''].join('\n'));
+    line(`The list is in ${file}`);
+  } catch (error) { line(`The list could not be written to ${folder} (${plainText(error?.message ?? error).slice(0, 120)}).`); }
+  if (list) { line('Nothing signed: --list only shows the list.'); return 0; }
+  const ends = new Date(new Date(at).getTime() + length * 3600 * 1000).toISOString();
+  const question = length ? `Mark ${tip.slice(0, 7)} as seen, and open a window for ${name} ${branch} until ${ends}?` : `Mark ${tip.slice(0, 7)} as seen, with no window?`;
+  if (!yes && !(await deps.ask(question))) { line('Nothing signed.'); return 1; }
+  const setup = (deps.setup ?? signingSetup)({ key, provider });
+  const trusted = (deps.trusted ?? trustedKeys)(setup);
+  const strange = keys.filter((one) => !trusted.has(one.fingerprint));
+  if (strange.length) {
+    line(`STOP: ${SIGNERS_FILE} on ${branch} holds a key that is not yours: ${strange.map((one) => one.fingerprint).join(', ')}.`);
+    line('Nothing was signed. Remove that key in a pull request, or pin it in ~/.config/atlas/signing.json if it is yours.');
+    return 1;
+  }
+  const payload = payloadText([{ kind: 'window', repo: name, branch, seen: tip, ends }], at);
+  line(`Touch the key now (${setup.key}${setup.provider ? `, provider ${setup.provider}` : ''}).`);
+  const signature = deps.sign(payload, setup);
+  const proof = verifyBlock({ payload, signature }, keys);
+  if (proof.error) { line(`The signature does not count on ${branch}: ${proof.error}`); line('Nothing was posted.'); return 1; }
+  let issue = null;
+  try {
+    const open = deps.gh('GET', `repos/${name}/issues?labels=${WINDOW_LABEL}&state=open&per_page=5`) ?? [];
+    issue = (Array.isArray(open) ? open : []).find((one) => !one?.pull_request)?.number ?? null;
+    if (!issue) issue = deps.gh('POST', `repos/${name}/issues`, { title: WINDOW_TITLE, labels: [WINDOW_LABEL], body: 'Each comment here holds one window act, signed with `atlas approve window` on the owner\'s Mac. The gate reads them. A deleted comment only ends a window sooner.' })?.number ?? null;
+    if (!issue) throw new Error('GitHub gave no issue number');
+    const summary = counts.map(([state, n]) => `${n} ${state}`).join(', ') || 'no merge';
+    deps.gh('POST', `repos/${name}/issues/${issue}/comments`, { body: `${blockText(payload, signature)}\nThe owner saw the list up to ${tip.slice(0, 7)} (${summary})${length ? ` and opened a window until ${ends}` : ''}, with \`atlas approve window\`.\n` });
+  } catch (error) { line(`GitHub refused a write (${plainText(error?.message ?? error).slice(0, 200)}). Nothing was posted; run the command again.`); return 1; }
+  line(`  posted on issue #${issue} (${WINDOW_LABEL})`);
+  // `atlas upgrade` trusts only a push run of the release, so the command
+  // starts no run: the next merge into the branch publishes what was held.
+  line(`  the next merge into ${branch} publishes what the release held`);
+  return 0;
+}
+
 // The act that `atlas approve act <kind>` builds from its flags.
 export function actFrom(kind, flags, read = (path) => readFileSync(resolve(path), 'utf8')) {
-  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => !['merge', 'accept', 'accept-code'].includes(each)).join(', ')}; a pull request takes atlas approve <pr>.`);
+  if (!Object.hasOwn(ACTS, kind ?? '')) throw new ApproveError(`there is no act "${kind ?? ''}". Use ${Object.keys(ACTS).filter((each) => !['merge', 'accept', 'accept-code', 'window'].includes(each)).join(', ')}; a pull request takes atlas approve <pr>.`);
   if (kind === 'merge') throw new ApproveError('a pull request takes atlas approve <pr>, which reads its gate first.');
   if (kind === 'accept') throw new ApproveError('an audit red takes atlas approve audit, which reads the audit issues first.');
   if (kind === 'accept-code') throw new ApproveError('the audit red of an audit-code merge takes atlas approve audit-code <pr>, which shows its diff first.');
+  if (kind === 'window') throw new ApproveError('a signing window takes atlas approve window, which shows the list of the last window first.');
   const need = (flag) => {
     const value = flags[flag];
     if (value === undefined || value === true || value === '') throw new ApproveError(`atlas approve act ${kind} needs --${flag}.`);
@@ -683,11 +792,12 @@ export async function keyCheck({ key, provider }, line, deps = DEPS) {
 
 // The verb. `words` are the words after "approve"; `flags` are the fields of
 // an act.
-export async function approveCommand({ words = [], repo, root, key, provider, yes = false, out, file, signers, flags = {} }, line, deps = DEPS) {
+export async function approveCommand({ words = [], repo, root, key, provider, yes = false, out, file, signers, flags = {}, hours, list = false }, line, deps = DEPS) {
   const common = { key, provider, yes };
   try {
     if (words[0] === 'act') return await approveAct({ ...common, kind: words[1], flags, out }, line, deps);
     if (words[0] === 'audit-code') return await approveAuditCode({ ...common, prs: words.slice(1), repo, root }, line, deps);
+    if (words[0] === 'window') return await approveWindow({ ...common, repo, root, hours, list }, line, deps);
     if (words[0] === 'audit') return await approveAudit({ ...common, prs: words.slice(1), repo, root }, line, deps);
     if (words[0] === 'verify') return approveVerify({ file, signers, root }, line);
     if (words[0] === 'key-check') return await keyCheck(common, line, deps);

package/door/lib/gate-audit.mjs

@@ -134,6 +134,7 @@ export const GATE_FILE_GROUPS = Object.freeze([
     ['packages/atlas/door/lib/gate.mjs', 'door/lib/gate.mjs'],
     ['packages/atlas/door/lib/gate-check.mjs', 'door/lib/gate-check.mjs'],
     ['packages/atlas/door/lib/owner-only.mjs', 'door/lib/owner-only.mjs'],
+    ['packages/atlas/door/lib/window.mjs', 'door/lib/window.mjs'],
     ['packages/atlas/owner-only.yaml', 'owner-only.yaml'],
   ] },
   { group: 'audit', files: [

package/door/lib/gate-check.mjs

@@ -44,6 +44,7 @@ import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
 import { parseSigners, verifyTexts, findAct, SIGNERS_FILE, BRANCH_FORM } from './signed-act.mjs';
 import { brakeState, undoOf, tripText } from './brake.mjs';
 import { kindsAt, nameKinds, kindRows } from './kinds.mjs';
+import { windowOn, protectedSet, clearable, windowActs, openAt, holdsCommit, WINDOW_KEY } from './window.mjs';
 
 export const VERSION = 1;
 export const GATE_CHECK = 'gate';
@@ -313,7 +314,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
   if (terms !== undefined) answer.rows.push(...termRows(top, baseSha, headSha, changes, terms));
   answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules: ruleRef, undo }));
-  if (signed) signedRows(top, baseSha, headSha, signed, answer, ruleRef);
+  if (signed) signedRows(top, baseSha, headSha, signed, answer, ruleRef, now);
   return finish(answer);
 }
 
@@ -324,7 +325,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
 // the base after the touch does not carry it (security review S1). A head job
 // named like a check is never cleared: the owner's view of the gate could be
 // that job's forgery (security review S1).
-function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer, ruleRef = baseSha) {
+function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer, ruleRef = baseSha, now = new Date()) {
   if (!answer.rows.some((row) => row.kind === 'owner') || answer.rows.some((row) => row.kind === 'red')) return;
   const note = (cause) => answer.rows.push({ kind: 'note', class: 'signed', cause });
   if (texts === null) { note('the comments of the pull request could not be read, so no signed act counts'); return; }
@@ -340,6 +341,7 @@ function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer
     carried = carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef, ruleRef }, answer);
     if (carried?.found) found = carried.found;
   }
+  if (!found && windowClear(root, baseSha, verified, { repo, baseRef, now }, answer)) return;
   if (!found) {
     for (const row of verified.filter((each) => each.error).slice(0, 3)) note(`a signed act that does not count: ${row.error}`);
     if (carried?.why) note(`a signed act for an older head does not carry: ${carried.why}`);
@@ -355,6 +357,43 @@ function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer
   else note(`the owner signed this head with key ${found.key} at ${found.signed_at}`);
 }
 
+// The signing window (item 4af66381; design docs/design-docs/signing-window/).
+// With no merge act for this head, a window act that is open now clears the
+// owner rows, but only when each one is a row of the repo's own list, of a
+// class that the window names, on a path outside the protected set (rule 1).
+// One row that it does not cover keeps the pull request OWNER: a window never
+// clears part of a pull request. The brake, a head job named like a check, a
+// floor path and a sign are never covered. Returns true when it cleared.
+function windowClear(root, baseSha, verified, { repo, baseRef, now }, answer) {
+  const note = (cause) => answer.rows.push({ kind: 'note', class: 'window', cause });
+  const acts = windowActs(verified, { repo, branch: baseRef });
+  if (!acts.length) return false;
+  if (!windowOn(root, baseSha)) { note(`a window act counts only where atlas.yaml on the base says ${WINDOW_KEY}: on`); return false; }
+  const got = openAt(acts, { now, isSeen: (sha) => holdsCommit(root, sha, baseSha) });
+  if (!got.open) { note(`no window counts: ${got.why}`); return false; }
+  // A window never clears while the brake is on: only the owner's signed
+  // clear ends a trip (rule 2; security review of 31 October, S2).
+  if (answer.brake?.on) { note('no window counts: the brake is on'); return false; }
+  const guard = protectedSet(root, baseSha);
+  if (guard.why) { note(`no window counts: ${guard.why}`); return false; }
+  let floorRules;
+  try { floorRules = rulesAt({ root, ref: baseSha }).rules.filter((rule) => String(rule.cause).startsWith('floor: ')); } catch (error) { note(`no window counts: the owner-only floor at the base cannot be read (${String(error?.message ?? error).split('\n')[0].slice(0, 120)})`); return false; }
+  guard.floor = (path) => onList(floorRules, path) !== null;
+  const owner = answer.rows.filter((row) => row.kind === 'owner');
+  const kept = owner.filter((row) => !clearable(row, guard));
+  const { act, signed_at: signedAt, key, verified: touched } = got.open;
+  if (kept.length) {
+    const first = kept[0];
+    const why = first.path && guard.paths.has(first.path) ? 'a protected file' : `${first.cause}`;
+    note(`the window open until ${act.ends} does not cover ${kept.length} owner row(s); the first is ${first.class}${first.path ? ` ${first.path}` : ''}: ${why}`);
+    return false;
+  }
+  for (const row of owner) row.kind = 'signed';
+  answer.signed = { key, signed_at: signedAt, verified: touched, window: { seen: act.seen, ends: act.ends } };
+  note(`the owner's window, signed ${signedAt} with key ${key}, is open until ${act.ends}; each owner row is a row of the repo's list outside the protected set`);
+  return true;
+}
+
 // At most this many new commits between a signed head and this head.
 export const CARRY_LIMIT = 20;
 // At most this many signed heads are tried, so copies of one block cost little.
@@ -572,6 +611,7 @@ export function renderText(answer) {
   if (answer.result === 'red') out.push(`RED: ${oneLine(answer.rows.find((row) => row.kind === 'red').cause)}. Fix it; red wins over owner.`);
   else if (answer.result === 'owner') out.push(`OWNER: ${oneLine(answer.class)}. ${answer.signed_act}`);
   else if (answer.signed?.carried_from) out.push(`SUCCESS: the owner signed head ${oneLine(answer.signed.carried_from).slice(0, 7)}, and this head only merges in the base.`);
+  else if (answer.signed?.window) out.push(`SUCCESS: the owner's signing window covers this pull request until ${oneLine(answer.signed.window.ends)}.`);
   else if (answer.signed) out.push('SUCCESS: the owner signed this head.');
   else out.push('SUCCESS: no rule holds this pull request.');
   return out;

package/door/lib/gate.mjs

@@ -23,6 +23,7 @@ import { parseYaml } from '../../shape/check.mjs';
 import { checkCommand, replayCommand, judge, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
 import { keepFindings, gateErrors, pinCode, slug, AUDIT_JOB } from './gate-audit.mjs';
 import { MARKER as SIGNED_MARKER, SIGNERS_FILE, AUDIT_CHECK, parseSigners, verifyTexts, findAct, auditCodeDiff } from './signed-act.mjs';
+import { WINDOW_LABEL } from './window.mjs';
 import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
@@ -601,7 +602,7 @@ export function ownerUnsigned({ root, repo, pull, parent }, gh) {
   const has = (sha) => { try { execFileSync('git', ['-C', root, 'cat-file', '-e', `${sha}^{commit}`], { stdio: 'ignore' }); return true; } catch { return false; } };
   if (!/^[0-9a-f]{40}$/.test(String(head)) || !/^[0-9a-f]{40}$/.test(String(parent)) || !has(head) || !has(parent)) return 'unread';
   let texts = null;
-  try { texts = prComments(gh, repo, pull.number); } catch { texts = null; }
+  try { texts = [...prComments(gh, repo, pull.number), ...windowComments(gh, repo)]; } catch { texts = null; }
   const answer = judge({ root, base: parent, head, body: String(pull.body ?? ''), now: new Date(pull.merged_at), signed: { repo, pr: Number(pull.number), baseRef: pull.base?.ref ?? null, texts } });
   return answer.result === 'owner' ? 'owner' : null;
 }
@@ -708,6 +709,28 @@ export function prComments(gh, repo, pr) {
   return kept;
 }
 
+// The comment texts of the window issues that carry the signed-act marker:
+// where `atlas approve window` posts each window act (item 4af66381). The
+// newest five issues with the label, open or closed, and three pages of
+// comments of each. A read that fails gives no text, so no window counts;
+// a hidden or deleted act only makes the gate and the hold stricter.
+export const WINDOW_ISSUES = 5;
+export function windowComments(gh, repo) {
+  const texts = [];
+  let issues;
+  try { issues = gh('GET', `repos/${repo}/issues?labels=${WINDOW_LABEL}&state=all&sort=created&direction=desc&per_page=${WINDOW_ISSUES}`); } catch { return []; }
+  for (const issue of (Array.isArray(issues) ? issues : []).filter((one) => !one?.pull_request).slice(0, WINDOW_ISSUES)) {
+    for (let page = 1; page <= 3; page += 1) {
+      let rows;
+      try { rows = gh('GET', `repos/${repo}/issues/${issue.number}/comments?per_page=100&page=${page}`); } catch { break; }
+      if (!Array.isArray(rows)) break;
+      for (const row of rows) if (typeof row?.body === 'string' && row.body.includes(SIGNED_MARKER)) texts.push(row.body);
+      if (rows.length < 100) break;
+    }
+  }
+  return texts;
+}
+
 // `atlas gate hold --root <clone> --commit <sha> --from <sha>` (item 4af66381,
 // the release hold). The release job runs it from the trusted copy, the
 // version that npm holds as latest, never from the commit that it judges.
@@ -768,6 +791,11 @@ export function holdRow({ repo, root, sha }, gh, git) {
   try { git(['cat-file', '-e', `${head}^{commit}`]); } catch { return `#${pull.number}: its head ${head.slice(0, 7)} is not in this clone`; }
   let texts;
   try { texts = prComments(gh, repo, pull.number); } catch { return `#${pull.number}: GitHub did not give its comments, so no act of the owner can be read`; }
+  // The window acts too (S1 of 31 October, hole 1). The judge below counts a
+  // window act only when it was open at the merge time, on the rules of the
+  // parent. So a window clears in the hold just the merges that it cleared at
+  // the gate. An act that GitHub hides or that an agent deletes only holds more.
+  texts = [...texts, ...windowComments(gh, repo)];
   let answer;
   try {
     const at = new Date(pull.merged_at);
@@ -857,7 +885,7 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
   const named = repo && repo !== true && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
   if (what === 'check') {
     const number = /^[1-9][0-9]{0,8}$/.test(String(pr ?? '')) ? Number(pr) : null;
-    return checkCommand({ root, base, head, body, json, summary, output, repo: named ? repo : null, pr: pr === undefined ? null : pr, baseRef: baseRef ?? null }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo), clears: { repo, commentsOf: (sha) => commitComments(gh, repo, sha) } } }) : null, named && number ? () => prComments(gh, repo, number) : null);
+    return checkCommand({ root, base, head, body, json, summary, output, repo: named ? repo : null, pr: pr === undefined ? null : pr, baseRef: baseRef ?? null }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo), clears: { repo, commentsOf: (sha) => commitComments(gh, repo, sha) } } }) : null, named && number ? () => [...prComments(gh, repo, number), ...windowComments(gh, repo)] : null);
   }
   if (what === 'replay') return replayCommand({ root, days, branch, json }, line);
   if (!named) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);