@arjunkhera/atlas 0.3.19 → 0.3.20

package/.claude-plugin/plugin.json

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

package/package.json

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

@@ -92,7 +92,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 gives the word for a new release |
+| `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 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 |

package/work/mcp.mjs

@@ -25,6 +25,7 @@ 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';
 export { childEnvironment };
 
 const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -72,6 +73,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 } },
 ];
 
 // The Engram connection: the address and the key, in one setting, separated by
@@ -233,6 +235,34 @@ function writeHealth(env, health) {
   try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(health, null, 2)}\n`, { mode: 0o600 }); } catch { /* health is advice, never a reason to stop */ }
 }
 
+// The atlas_upgrade tool (owner, 12 October 2026: "Atlas upgrade tool"). An
+// agent's Bash runs in a sandbox that cannot write to ~/.npm, ~/.atlas or
+// ~/.claude/plugins, so `atlas upgrade` fails there. This server runs outside
+// that sandbox. The tool runs the same upgrade steps as the command, with the
+// short child environment: never the Engram key.
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const ATLAS_VERSION_OF = (root) => JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+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 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);
+  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 };
+  }
+  const lines = [];
+  let code;
+  try { code = await upgradeFn({ packageRoot, options: { yes: true }, line: (text) => lines.push(text), env, exec }); } catch (error) {
+    refuse(`the upgrade stopped: ${String(error.stderr || error.message).trim().split('\n').slice(0, 6).join(' ')}`);
+  }
+  return { ok: code === 0, loaded, output: lines, next: code === 0 ? 'Restart the Claude Code sessions on this Mac to load the new release.' : 'Nothing was installed. Read the output.' };
+}
+
 export function buildServer({ env = process.env, input, output, readGitHub, readLive, log, allowLoopbackHttp = false } = {}) {
   const hostile = hostileVariables(env);
   if (hostile.length) throw new Error(`refusing to start: ${hostile.join(', ')} ${hostile.length === 1 ? 'is' : 'are'} set, and could send the Engram key elsewhere or turn certificate checks off. Unset ${hostile.length === 1 ? 'it' : 'them'}.`);
@@ -256,6 +286,8 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
     ? `Atlas work verbs for the owner's session. Session ${session}; owner present: ${ownerPresent ? 'yes' : 'no: the owner-only tools refuse'}. Call registry_list first to learn the product and repo ids, needs_me to see the open questions, and in_flight to see the active work. Every write needs a request_id. The server stamps writer.session and the bound client; never pass writer, session, actor or role. Unknown product or repo ids are refused. Sub-agents must not receive this server.`
     : `Atlas work verbs. They cannot reach Engram yet: ${connection.message}`;
   const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions, tools: TOOLS, input, output, log, call: (name, args, boundTo) => {
+    // The upgrade needs no Engram connection: an old key must not block a new release.
+    if (name === 'atlas_upgrade') return runUpgrade({ args, env, ownerPresent });
     if (!verbs) throw new Error(connection.message);
     // The writer names the one client this server is bound to (D6 R3): stamped by the server, never by the caller.
     if (boundTo && boundTo.session !== bound) { bound = boundTo.session; verbs = verbsFor(bound); }