atris 3.73.1 → 3.74.1

package/lib/gm-phone.js

@@ -16,6 +16,10 @@ const crypto = require('crypto');
 
 const CARD_LIMIT = 5;
 const CONFIRM_MS = 5000;
+// a typed send's id, and how many and how long sends are remembered
+const SEND_ID = /^[a-z0-9]{8,32}$/;
+const SENDS_KEPT = 50;
+const SENDS_MS = 10 * 60 * 1000;
 const UNDO_MS = 5000;
 // the server keeps an undo a little past the toast so a slow tap still counts
 const UNDO_GRACE_MS = 3000;
@@ -505,11 +509,14 @@ function createPhoneHandler(deps) {
   async function betAction(p, body) {
     let out;
     if (p === '/bet/think') out = bet.next({ sharper: body.sharper === true });
-    else if (p === '/bet/answer') out = bet.answer({ choice: String(body.choice || ''), text: String(body.text || '') });
+    // typed words in something else are read first, like say something: a
+    // question back or confusion is explained and nothing is saved
+    else if (p === '/bet/answer' && body.choice === 'other') out = await bet.say({ text: String(body.text || ''), card: String(body.card || '') });
+    else if (p === '/bet/answer') out = bet.answer({ choice: String(body.choice || ''), text: String(body.text || ''), card: String(body.card || '') });
     else if (p === '/bet/report') out = bet.report({ value: body.value });
     else if (p === '/bet/pick') out = bet.pick({ id: String(body.id || '') });
     else if (p === '/bet/steer') out = await bet.talk({ member: String(body.member || ''), text: String(body.text || ''), confirm: body.confirm === true, note: body.note === true });
-    else if (p === '/bet/say') out = await bet.say({ text: String(body.text || ''), confirm: body.confirm === true, note: body.note === true });
+    else if (p === '/bet/say') out = await bet.say({ text: String(body.text || ''), confirm: body.confirm === true, note: body.note === true, card: String(body.card || '') });
     else if (p === '/bet/skip') out = bet.skip();
     else if (p === '/bet/do') {
       if (body.confirm !== true) return { status: 409, body: { ok: false, reason: 'needs_confirm', confirm_ms: CONFIRM_MS } };
@@ -524,6 +531,26 @@ function createPhoneHandler(deps) {
     return { status: out.ok ? 200 : 409, body: out };
   }
 
+  // A typed send carries its own id, made on the phone when the words are
+  // first sent and the same on every retry of those words. A repeat of a
+  // send that went through, or is still going, gets the first answer and
+  // nothing is sent again; one that did nothing is tried again. The newest
+  // SENDS_KEPT are remembered for SENDS_MS.
+  const sends = new Map();
+  function sendOnce(p, body) {
+    const id = typeof body.send === 'string' && SEND_ID.test(body.send) ? `${p} ${body.send}` : null;
+    if (!id) return betAction(p, body);
+    const seen = sends.get(id);
+    if (seen && now() - seen.at < SENDS_MS) return seen.out;
+    sends.delete(id);
+    const out = betAction(p, body);
+    sends.set(id, { at: now(), out });
+    const forget = () => { if (sends.get(id) && sends.get(id).out === out) sends.delete(id); };
+    out.then(r => { if (!r.body || r.body.ok !== true) forget(); }, forget);
+    while (sends.size > SENDS_KEPT) sends.delete(sends.keys().next().value);
+    return out;
+  }
+
   const send = (res, status, body, type = 'application/json; charset=utf-8', extra = {}) => {
     res.writeHead(status, {
       'content-type': type,
@@ -561,7 +588,7 @@ function createPhoneHandler(deps) {
           return send(res, err.message === 'too_large' ? 413 : 400, { ok: false, reason: 'bad_body' });
         }
         if (check.path.startsWith('/bet/')) {
-          const out = await betAction(check.path, body || {});
+          const out = await sendOnce(check.path, body || {});
           return send(res, out.status, out.body);
         }
         const out = check.path === '/action' ? act(body || {}) : doUndo(body || {});

package/lib/handoff-wake.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// A handoff wakes the member it hands to.
+//
+// `atris member handoff <from> <to> "<step>"` used to only write the baton
+// down, so the phone said "validator has it" while no validator run existed
+// (live 2026-10-22, mission #266). Now the receiver is started on the
+// handed-off step through the member runtime (member run, detached), the same
+// bounded work step `atris member wake <name>` runs, and only when the team
+// rules allow it: not asleep, not a person, under the limit of members
+// working at once (the `atris member up` limit), with an engine named in the
+// roster. When it cannot start, the outcome says why in plain words and is
+// written onto the handoff, so nothing claims the member has the work.
+//
+// The team, the engine lookup and the start are passed in, so tests drive the
+// decision without starting anything.
+
+const fs = require('fs');
+const path = require('path');
+const { DEFAULT_MAX } = require('./member-up');
+
+// Two handoffs at the same moment once both counted 5 working and both
+// started one, past the limit of 6. Count-and-start now holds one lock file
+// in the state folder, and each start is written to a short list of recent
+// wakes, so the next handoff counts it even before its mission says running.
+const LOCK_FILE = 'handoff-wake.lock';
+const RECENT_FILE = 'handoff-wakes.json';
+// A holder that died, or one stuck past this long, no longer holds.
+const STALE_LOCK_MS = 5 * 60 * 1000;
+const WAIT_LOCK_MS = 3 * 60 * 1000;
+const RECENT_MS = 30 * 60 * 1000;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+function takeLock(file, { staleMs, waitMs, now }) {
+  const until = now() + waitMs;
+  for (;;) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now() }));
+      return fd;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    try {
+      const stat = fs.statSync(file);
+      let owner = null;
+      try { owner = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {}
+      const dead = owner && Number.isInteger(owner.pid) && !pidAlive(owner.pid);
+      const old = now() - stat.mtimeMs > staleMs;
+      if ((dead || old) && fs.statSync(file).ino === stat.ino) {
+        fs.unlinkSync(file);
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    if (now() >= until) return null;
+    sleepSync(100);
+  }
+}
+
+// Runs fn() while holding an exclusive lock file. A holder that died, or
+// one older than staleMs, is cleared. Throws when the lock stays held past
+// waitMs, so a caller never writes without it.
+function withFileLock(lockFile, fn, { staleMs = STALE_LOCK_MS, waitMs = WAIT_LOCK_MS, now = Date.now } = {}) {
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+  const fd = takeLock(lockFile, { staleMs, waitMs, now });
+  if (fd === null) throw new Error(`${path.basename(lockFile)} stayed locked by another writer`);
+  try {
+    return fn();
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+// Runs fn({ recent, record }) while holding the wake lock. recent: wakes from
+// the last half hour whose run is still alive; record(entry) adds one.
+// Returns { busy: true } when the lock stayed held past waitMs.
+function withWakeReservation(stateDir, fn, { staleMs = STALE_LOCK_MS, waitMs = WAIT_LOCK_MS, now = Date.now } = {}) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  const lockFile = path.join(stateDir, LOCK_FILE);
+  const recentFile = path.join(stateDir, RECENT_FILE);
+  const fd = takeLock(lockFile, { staleMs, waitMs, now });
+  if (fd === null) return { busy: true };
+  try {
+    let recent = [];
+    try { recent = JSON.parse(fs.readFileSync(recentFile, 'utf8')).wakes || []; } catch {}
+    recent = recent.filter((w) => w && w.member && now() - Number(w.at || 0) < RECENT_MS && pidAlive(w.pid));
+    const out = fn({ recent, record: (entry) => recent.push({ ...entry, at: now() }) });
+    const tmp = `${recentFile}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ wakes: recent }));
+    fs.renameSync(tmp, recentFile);
+    return out;
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+function notStarted(to, reason, why) {
+  return {
+    status: 'not_started',
+    reason,
+    text: `${to} did not start: ${why}. nobody is working on this step yet. to start it: atris member wake ${to}`,
+  };
+}
+
+// deps: { listMembers() -> [{ name, live, sleeping, parked, human }],
+//         awake(name), engine(name), start(name, step) -> { ok, mission_id, pid, worktree, error },
+//         max }
+// deps.reserve(fn), when given, holds the shared wake lock around the
+// count-and-start (withWakeReservation); without it the decision runs bare.
+function wakeHandoffReceiver(handoff, deps) {
+  const to = String(handoff && handoff.to || '').trim();
+  if (typeof deps.reserve !== 'function') return decideAndStart(handoff, deps, { recent: [], record: () => {} });
+  const out = deps.reserve((reservation) => decideAndStart(handoff, deps, reservation));
+  if (out && out.busy) return notStarted(to, 'busy', 'another handoff held the start lock for minutes, so this one gave up');
+  return out;
+}
+
+function decideAndStart(handoff, deps, { recent, record }) {
+  const to = String(handoff && handoff.to || '').trim();
+  const step = String(handoff && handoff.summary || '').trim();
+  const recentNames = new Set(recent.map((w) => w.member));
+  const team = (deps.listMembers() || []).map((member) => (member && recentNames.has(member.name) ? { ...member, live: true } : member));
+  const seat = team.find((member) => member && member.name === to);
+  if (!seat) return notStarted(to, 'not_on_team', `${to} is not on the team`);
+  if (seat.human) return notStarted(to, 'person', `${to} is a person, so no engine starts for them`);
+  if (seat.live) {
+    return {
+      status: 'already_working',
+      reason: 'already_working',
+      text: `${to} is already working; the step is queued as its next push`,
+    };
+  }
+  if (seat.sleeping || deps.awake(to) === false) return notStarted(to, 'asleep', `${to} is asleep`);
+  if (seat.parked) return notStarted(to, 'parked', `${to} is parked`);
+  const max = Math.max(1, Number(deps.max) || DEFAULT_MAX);
+  const working = team.filter((member) => member && member.live).length;
+  if (working >= max) {
+    return notStarted(to, 'at_limit', `${working} members are already working and the limit is ${max}`);
+  }
+  const engine = deps.engine(to);
+  if (!engine) return notStarted(to, 'no_engine', `the roster names no engine for ${to}`);
+  let run;
+  try {
+    run = deps.start(to, step) || {};
+  } catch (error) {
+    run = { ok: false, error: error && error.message };
+  }
+  if (!run.ok || !run.mission_id) {
+    const why = String(run.error || 'the run did not start').split('\n')[0].trim().slice(0, 200);
+    return notStarted(to, 'start_failed', why);
+  }
+  record({ member: to, mission_id: run.mission_id, pid: run.pid || null });
+  return {
+    status: 'started',
+    reason: 'started',
+    mission_id: run.mission_id,
+    pid: run.pid || null,
+    worktree: run.worktree || null,
+    engine: (engine.engine && engine.engine.id) || engine.id || null,
+    text: `${to} is working on it now (mission ${run.mission_id})`,
+  };
+}
+
+module.exports = {
+  withFileLock,
+  wakeHandoffReceiver,
+  withWakeReservation,
+};

package/lib/manifest.js

@@ -2,7 +2,6 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { stateHome } = require('./state-home');
-const { computeContentHash } = require('./journal');
 
 /**
  * Get the manifest file path for a business slug.
@@ -35,14 +34,6 @@ function saveManifest(slug, manifest) {
   fs.writeFileSync(p, JSON.stringify(manifest, null, 2));
 }
 
-/**
- * Compute SHA-256 hash of normalized content.
- * Delegates to journal.js computeContentHash.
- */
-function computeFileHash(content) {
-  return computeContentHash(content);
-}
-
 /**
  * Build a manifest object from a set of files.
  * files: { [path]: { hash, size } }
@@ -247,7 +238,6 @@ function threeWayCompare(localFiles, remoteFiles, manifest) {
 module.exports = {
   loadManifest,
   saveManifest,
-  computeFileHash,
   buildManifest,
   computeLocalHashes,
   threeWayCompare,

package/lib/member-switches.js

@@ -70,17 +70,6 @@ function asleepMembers(root = process.cwd()) {
   return Object.keys(members).filter((name) => normalizeMemberEntry(members[name]).awake === false).sort();
 }
 
-function isMemberLoopAwake(name, loopId, root = process.cwd()) {
-  const entry = getMemberSwitch(name, root);
-  if (entry.awake === false) return false;
-  const id = String(loopId || '').trim();
-  if (!id) return entry.awake !== false;
-  if (Object.prototype.hasOwnProperty.call(entry.loops, id)) {
-    return entry.loops[id] !== false;
-  }
-  return true;
-}
-
 function ensureMemberEntry(state, name) {
   if (!state.members[name] || typeof state.members[name] !== 'object') {
     state.members[name] = { awake: true, loops: {} };

package/lib/member-up.js

@@ -346,11 +346,25 @@ function createMemberUp(deps, options = {}) {
   }
 
   // One pass over the team. Returns the members it started (or would start).
+  // Count-and-start runs under the wake lock that
+  // handoffs share (deps.reserve), and counts the members a handoff or
+  // another start just woke, so neither path goes past the limit.
   function check() {
+    if (typeof deps.reserve !== 'function' || dryRun) return checkUnder({ recent: [], record: () => {} });
+    const out = deps.reserve((reservation) => checkUnder(reservation));
+    if (out && out.busy) {
+      print('another start held the start lock, so nobody was started this pass');
+      return [];
+    }
+    return out;
+  }
+
+  function checkUnder({ recent, record }) {
     const now = deps.now();
     callOutStalls(now);
     putBackDropped(now);
     const started = [];
+    const recentNames = new Set((recent || []).map((w) => w && w.member).filter(Boolean));
     const taken = new Set(Array.from(running.values()).map((run) => run.taskId).filter(Boolean));
     const team = deps.listMembers();
     const members = only ? team.filter((m) => m && only.has(m.name)) : team;
@@ -362,11 +376,11 @@ function createMemberUp(deps, options = {}) {
         print(`${name} is not on the team, skipping`);
       }
     }
-    liveElsewhere = new Set(members.filter((m) => m && m.name && m.live).map((m) => m.name));
+    liveElsewhere = new Set(members.filter((m) => m && m.name && (m.live || recentNames.has(m.name))).map((m) => m.name));
     for (const member of members) {
       const name = member && member.name;
       if (!name || member.parked || member.human || member.sleeping) continue;
-      if (running.has(name) || member.live) continue;
+      if (running.has(name) || liveElsewhere.has(name)) continue;
       if (working() + (dryRun ? started.length : 0) >= max) break;
       const s = seat(name);
       if (now < s.nextCheckAt) continue;
@@ -391,10 +405,11 @@ function createMemberUp(deps, options = {}) {
       const run = { taskId: task.id || null, title, startedAt: now, lastStepAt: now, announced: false };
       running.set(name, run);
       try {
-        deps.spawn(name, (code, result) => {
+        const child = deps.spawn(name, (code, result) => {
           deps.flushProgress?.();
           if (running.get(name) === run) finish(name, code, result);
         }, (claimedTask) => claimed(name, run, claimedTask));
+        record({ member: name, pid: child && child.pid ? child.pid : null });
       } catch (error) {
         running.delete(name);
         print(`${name} failed to start: ${oneLine(error && error.message || error)}`);

package/lib/mission-protected-lane.js

@@ -238,16 +238,24 @@ function gitSubcommand(args) {
 // Tools that can publish, post, send, or merge. With a mission id, each one
 // found on PATH gets a wrapper that checks the mission's your-yes lock first
 // (lib/yes-lock.js); with no lock file the wrapper just runs the tool.
+const { GUARD_DIR_PREFIX } = require('./spawn-env');
+const GUARD_MISSION_FILE = 'mission.json';
 const YES_LOCK_TOOLS = ['npm', 'yarn', 'pnpm', 'npx', 'pnpx', 'bunx', 'gh', 'atris'];
 
 // The lines every wrapper shares: ask the lock, refuse with its message, run
-// the real tool, and close the steps a yes allowed once that run succeeds.
+// the real tool (with the words the lock gave back, when it gave any: a
+// branch push in a woken run runs with tags and mirroring forced off), and
+// close the steps a yes allowed once that run succeeds.
 function yesLockLines(toolExpr, binExpr) {
   return [
     `const yesLock = require(${JSON.stringify(path.join(__dirname, 'yes-lock.js'))});`,
     `const verdict = config.missionId ? yesLock.check({ stateDir: config.stateDir, missionId: config.missionId, seal: config.seal, tool: ${toolExpr}, args, gitBin: config.gitBin || null, cwd: process.cwd(), env: process.env }) : null;`,
     `if (verdict && verdict.hold) { process.stderr.write(verdict.message + '\\n'); process.exit(yesLock.HELD_EXIT); }`,
-    `const runReal = () => { const child = spawnSync(${binExpr}, args, { cwd: process.cwd(), stdio: 'inherit' }); const ok = !child.error && child.status === 0; if (verdict && verdict.consume) yesLock.consume(config.stateDir, config.missionId, config.seal, verdict.consume, { ok, claims: verdict.claims }); if (child.error) { process.stderr.write(child.error.message + '\\n'); process.exit(1); } process.exit(child.status == null ? 1 : child.status); };`,
+    `const runArgs = verdict && Array.isArray(verdict.args) ? verdict.args : args;`,
+    // package scripts run through the guard's own script shell, which puts
+    // the wrappers back first after npm puts node_modules/.bin ahead of them
+    `const runEnv = config.scriptShell ? require(${JSON.stringify(path.join(__dirname, 'spawn-env.js'))}).packageScriptEnv({ tool: config.tool, realBin: config.realBin, scriptShell: config.scriptShell }, process.env, process.cwd(), args) : process.env;`,
+    `const runReal = () => { const child = spawnSync(${binExpr}, runArgs, { cwd: process.cwd(), stdio: 'inherit', env: runEnv }); const ok = !child.error && child.status === 0; if (verdict && verdict.consume) yesLock.consume(config.stateDir, config.missionId, config.seal, verdict.consume, { ok, claims: verdict.claims }); if (child.error) { process.stderr.write(child.error.message + '\\n'); process.exit(1); } process.exit(child.status == null ? 1 : child.status); };`,
   ];
 }
 
@@ -257,8 +265,8 @@ function resolveTool(name, root, pathValue) {
   return found.status === 0 && bin && path.isAbsolute(bin) ? bin : null;
 }
 
-function yesLockWrapper({ tool, realBin, missionId, seal, stateDir }) {
-  const config = { tool, realBin, missionId, seal, stateDir };
+function yesLockWrapper({ tool, realBin, missionId, seal, stateDir, scriptShell = null }) {
+  const config = { tool, realBin, missionId, seal, stateDir, scriptShell };
   return [
     '#!/usr/bin/env node',
     "'use strict';",
@@ -292,7 +300,7 @@ function prepareMissionGitGuard({
     throw new Error('mission git guard could not resolve git');
   }
 
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-mission-git-'));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), GUARD_DIR_PREFIX));
   const wrapper = path.join(dir, 'git');
   const modulePath = __filename;
   const config = { root: path.resolve(root), tags: normalizedTags(tags), gitBin, missionId: locked ? missionId : null, seal, stateDir };
@@ -317,11 +325,20 @@ function prepareMissionGitGuard({
     '',
   ].join('\n');
   fs.writeFileSync(wrapper, source, { encoding: 'utf8', mode: 0o755 });
+  // Which mission this guard belongs to, so a member woken by a handoff from
+  // inside this run shows its yes cards on this job.
+  fs.writeFileSync(path.join(dir, GUARD_MISSION_FILE), JSON.stringify({ mission_id: missionId || null }), 'utf8');
   if (locked) {
+    // npm, yarn, and pnpm run package scripts with this shell, so a script's
+    // own npm or git is the wrapper even when the project ships one in
+    // node_modules/.bin; it then runs the shell the project configured
+    const scriptShell = path.join(dir, 'script-shell');
+    fs.writeFileSync(scriptShell, require('./spawn-env').scriptShellSource(dir), { encoding: 'utf8', mode: 0o755 });
     for (const tool of YES_LOCK_TOOLS) {
       const realBin = resolveTool(tool, root, pathValue);
       if (!realBin) continue;
-      fs.writeFileSync(path.join(dir, tool), yesLockWrapper({ tool, realBin, missionId, seal, stateDir }), { encoding: 'utf8', mode: 0o755 });
+      const pkg = tool === 'npm' || tool === 'yarn' || tool === 'pnpm';
+      fs.writeFileSync(path.join(dir, tool), yesLockWrapper({ tool, realBin, missionId, seal, stateDir, scriptShell: pkg ? scriptShell : null }), { encoding: 'utf8', mode: 0o755 });
     }
   }
 
@@ -334,7 +351,22 @@ function prepareMissionGitGuard({
   };
 }
 
+// The mission whose guard is on this PATH (the run that is calling), or
+// null. Used only to show a handed-off run's yes cards on that job.
+function guardMissionOnPath(pathValue = process.env.PATH || '') {
+  for (const dir of String(pathValue).split(path.delimiter)) {
+    if (!path.basename(dir).startsWith(GUARD_DIR_PREFIX)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(dir, GUARD_MISSION_FILE), 'utf8'));
+      if (data && data.mission_id) return String(data.mission_id);
+    } catch {}
+  }
+  return null;
+}
+
 module.exports = {
+  GUARD_DIR_PREFIX,
+  guardMissionOnPath,
   defaultGit,
   matchProtectedMissionDiff,
   unreadableMissionGuard,

package/lib/review-integrity.js

@@ -25,10 +25,6 @@ function normalizeActor(value) {
     .replace(/^-+|-+$/g, '');
 }
 
-function envActor() {
-  return normalizeActor(process.env.ATRIS_AGENT_ID || process.env.USER || '');
-}
-
 // Builder identity, oldest signal wins: explicit stamp, then who claimed it,
 // then whoever sent the first proof.
 function taskBuilder(task) {

package/lib/spawn-env.js

@@ -2,17 +2,106 @@
 
 const path = require('path');
 
+// The mission guard (lib/mission-protected-lane.js) puts a folder of
+// wrappers for git, npm, gh, and atris first on a job's PATH. Anything that
+// adds a folder ahead of it, or starts a login shell that rebuilds PATH from
+// the profile, must put that folder back first, or a git or npm inside it
+// skips the wrappers and the job's yes-lock.
+const GUARD_DIR_PREFIX = 'atris-mission-git-';
+
+function guardDirs(pathValue) {
+  return String(pathValue || '').split(path.delimiter).filter(dir => dir && path.basename(dir).startsWith(GUARD_DIR_PREFIX));
+}
+
+// The PATH with any guard folder moved back to the front.
+function guardFirst(pathValue) {
+  const guards = guardDirs(pathValue);
+  if (!guards.length) return String(pathValue || '');
+  const rest = String(pathValue || '').split(path.delimiter).filter(dir => !guards.includes(dir));
+  return [...guards, ...rest].join(path.delimiter);
+}
+
+// A first line for a shell script that puts the guard folder back first
+// after the profile has run. Empty outside a guarded job.
+function shellGuardLine(env = process.env) {
+  const guards = guardDirs(env.PATH);
+  if (!guards.length) return '';
+  return `export PATH=${guards.map(d => `'${d.replace(/'/g, `'\\''`)}'`).join(':')}:"$PATH"\n`;
+}
+
 // Autonomously launched runtimes (cron, launchd, pulse ticks) carry a minimal
 // PATH without node's directory, so any shell command that may invoke
 // `node ...` fails only in the one environment nobody is watching. Three
 // subsystems hit this on 2026-07-07 alone (experiment applies, atris2 relayed
 // ops, always-on mission verifiers). Prepend the directory of the node that
-// runs this CLI before spawning shell commands from autonomous paths.
+// runs this CLI before spawning shell commands from autonomous paths, behind
+// a guard folder if there is one.
 function envWithNodeDir(base = process.env) {
   const nodeDir = path.dirname(process.execPath);
   const basePath = String(base.PATH || '');
   if (basePath.split(path.delimiter).includes(nodeDir)) return base;
-  return { ...base, PATH: `${nodeDir}${path.delimiter}${basePath}` };
+  return { ...base, PATH: guardFirst(`${nodeDir}${path.delimiter}${basePath}`) };
+}
+
+// The guard's script shell for npm, yarn, and pnpm. It puts the wrappers
+// first, then runs the shell the project or user configured
+// (ATRIS_SCRIPT_SHELL), or /bin/sh when none is. For a POSIX shell it also
+// puts them first inside the command, since a shell like zsh can rebuild
+// PATH as it starts.
+function scriptShellSource(dir) {
+  const q = `'${String(dir).replace(/'/g, `'\\''`)}'`;
+  return [
+    '#!/bin/sh',
+    `G=${q}`,
+    'PATH="$G:$PATH"; export PATH',
+    'shell="${ATRIS_SCRIPT_SHELL:-/bin/sh}"',
+    'if [ "$1" = "-c" ] && [ $# -ge 2 ]; then',
+    '  case "${shell##*/}" in',
+    '    sh|bash|zsh|dash|ksh|mksh|ash)',
+    '      cmd=$2; shift 2',
+    `      exec "$shell" -c "PATH='$G':\\"\\$PATH\\"; export PATH; $cmd" "$@" ;;`,
+    '  esac',
+    'fi',
+    'exec "$shell" "$@"',
+    '',
+  ].join('\n');
+}
+
+// The environment npm, yarn, or pnpm runs with under a guard: scripts go
+// through the guard's shell, which then runs the configured one. The tool
+// says which shell is configured (project, user, or global config, or the
+// environment), asked with the same config-file and folder options the
+// command was given; a nested call keeps what the outer one found.
+const CONFIG_FLAGS = {
+  npm: ['--userconfig', '--globalconfig', '--prefix', '-C'],
+  pnpm: ['--userconfig', '--globalconfig', '--dir', '-C'],
+  yarn: ['--use-yarnrc', '--cwd'],
+};
+
+function configFlags(tool, args = []) {
+  const names = CONFIG_FLAGS[tool] || [];
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = String(args[i]);
+    if (a === '--') break;
+    if (names.includes(a.split('=')[0]) && a.includes('=')) out.push(a);
+    else if (names.includes(a) && args[i + 1] !== undefined) { out.push(a, String(args[i + 1])); i += 1; }
+  }
+  return out;
+}
+
+function packageScriptEnv({ tool, realBin, scriptShell }, env = process.env, cwd = process.cwd(), args = []) {
+  const out = { ...env, npm_config_script_shell: scriptShell };
+  // .yarnrc beats npm_config_*, and YARN_SCRIPT_SHELL beats .yarnrc
+  if (tool === 'yarn') out.YARN_SCRIPT_SHELL = scriptShell;
+  if (tool === 'pnpm') out.npm_config_shell_emulator = 'false';
+  if (env.npm_config_script_shell === scriptShell) return out;
+  const { spawnSync } = require('child_process');
+  const res = spawnSync(realBin, [...configFlags(tool, args), 'config', 'get', 'script-shell'], { cwd, env, encoding: 'utf8', timeout: 10000 });
+  const value = res.status === 0 ? String(res.stdout || '').trim().split('\n').pop().trim() : '';
+  if (value && !/^(null|undefined)$/.test(value) && value !== scriptShell) out.ATRIS_SCRIPT_SHELL = value;
+  else delete out.ATRIS_SCRIPT_SHELL;
+  return out;
 }
 
-module.exports = { envWithNodeDir };
+module.exports = { GUARD_DIR_PREFIX, envWithNodeDir, shellGuardLine, scriptShellSource, packageScriptEnv };

package/lib/task-proof.js

@@ -154,7 +154,8 @@ function buildVerifiedProof(verifyCmd, baseProof = '', runner, options = {}) {
   const cmd = String(verifyCmd || '').trim();
   if (!cmd) return { ok: false, reason: 'verify_command_required' };
   const run = runner || require('child_process').spawnSync;
-  const result = run('bash', ['-lc', cmd], {
+  // a login shell rebuilds PATH; a mission guard's wrappers go back first
+  const result = run('bash', ['-lc', `${require('./spawn-env').shellGuardLine()}${cmd}`], {
     cwd: options.cwd || process.cwd(),
     encoding: 'utf8',
     timeout: options.timeoutMs || 120000,

package/lib/task-receipt.js

@@ -61,9 +61,10 @@ function writeTaskReceipt({ taskId, command, root = process.cwd(), runner } = {}
   const run = runner || spawnSync;
   // A login shell can put an older node first on PATH (macOS path_helper puts
   // /usr/local/bin ahead), so the check would run on a node atris does not
-  // support. Put the node running atris first, after the profile has loaded.
+  // support. Put the node running atris first, after the profile has loaded,
+  // and a mission guard's wrapper folder ahead of it (lib/spawn-env.js).
   const nodeDir = path.dirname(process.execPath).replace(/'/g, `'\\''`);
-  const script = `export PATH='${nodeDir}':"$PATH"\n${cmd}`;
+  const script = `export PATH='${nodeDir}':"$PATH"\n${require('./spawn-env').shellGuardLine()}${cmd}`;
   const timeoutMs = verifyTimeoutMs();
   const result = run('bash', ['-lc', script], {
     cwd: root,