create-agent-rig 0.5.0 → 0.6.1

package/templates/agent-os/universal/.claude/scripts/run-state.mjs

@@ -1,6 +1,8 @@
 /**
  * The run's own state — three of the four values `stopConditionOf` asks for and
- * nothing used to answer. The fourth, `killSwitch`, is deliberately not here:
+ * nothing used to answer, plus one value it does not ask for: the take-up
+ * snapshot `takeUps` ({@link recordTakeUp}), which is the run's fact as much as
+ * the other three. The fourth stop input, `killSwitch`, is deliberately not here:
  * it is already mechanical in `guard-bash` and scripted in preflight, and a
  * second answer to "is the brake on" is the disagreement `invariants.md`
  * forbids.
@@ -47,8 +49,8 @@
  * per run is the caller's part of the contract, and the `loop` skill states it.
  */
 
-import { readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { opendirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const STATE = 'state.json';
@@ -199,6 +201,102 @@ export const recordEscalation = (runDir) => {
   }
 };
 
+/**
+ * The take-up snapshot: the selected item's `updatedAt` marker, keyed by id, as
+ * seen at SELECT. `queue/core.mjs` › revalidationOf compares the next selection
+ * against it, so a stale take-up is reported rather than silently continued.
+ *
+ * Per run, like everything else here — a snapshot from yesterday's run is not
+ * a take-up this run made. Merged by id, so a second item does not erase the
+ * first; re-recording an id moves its baseline forward. A marker that is not a
+ * string is not recorded at all: `plan-md` has none, and writing `null` would
+ * later compare equal to `null` and read as "unchanged".
+ *
+ * No run directory → nothing written, `null` back, no throw: an attended
+ * selection has no run to snapshot into. (Like {@link recordEscalation} it
+ * refuses to throw there; unlike it, there is no count to hand back, so `null`.)
+ */
+export const recordTakeUp = (runDir, { id, updatedAt } = {}) => {
+  if (!runDir || typeof updatedAt !== 'string' || id === undefined || id === null) return null;
+  const state = readState(runDir);
+  const takeUps = typeof state.takeUps === 'object' && state.takeUps !== null ? state.takeUps : {};
+  return updateState(runDir, { takeUps: { ...takeUps, [String(id)]: updatedAt } });
+};
+
+/**
+ * The take-up an EARLIER run recorded for this item, or null (AR-138).
+ *
+ * {@link recordTakeUp} is per run on purpose, and that left a hole RX1
+ * measured: an item taken up yesterday and re-offered today compared against
+ * nothing and reported a first sight, however far its marker had moved. So
+ * when this run has no take-up for the item, SELECT asks the sibling run
+ * directories — newest first by name, which is the `YYYYMMDD-HHMMSS` the
+ * `loop` skill declares — and takes the first that recorded one. The answer
+ * names the run it came from, so the revalidation event can say whose
+ * baseline it compared against.
+ *
+ * 🔴 A sibling is a run only by NAME — `YYYYMMDD-HHMMSS`, the shape the `loop`
+ * skill declares — and so is the run asking. The first version took every
+ * sibling directory, and two measurements showed why that is wrong. On CI,
+ * with `RIG_RUN_DIR` under a shared temp root, a neighbouring test's scratch
+ * directory carrying a `state.json` was read as yesterday's run, and a first
+ * sight came back as a hold against a marker nobody had taken up. Locally,
+ * the same temp root held 454 000 entries, and every SELECT paid a 540 ms
+ * directory read for a question it could not answer. So a run declared under
+ * another naming looks at no siblings at all, and the limit is the mirror
+ * image: an earlier run declared under another naming is not seen here.
+ *
+ * Bounded and fail-soft: the runs root is walked through one directory handle
+ * and at most 10 000 entries are looked at, whatever is in there; at most 200
+ * candidate runs are read, an unreadable state is skipped rather than trusted,
+ * and the answer is `null` for no run directory, an unnamed one, or no runs
+ * root. Never this run's own state — that is {@link readState}'s answer, and
+ * the caller asks it first.
+ */
+const RUN_DIR_NAME = /^\d{8}-\d{6}$/;
+const RUNS_ROOT_ENTRY_BUDGET = 10_000;
+const RUNS_READ_CAP = 200;
+
+export const previousTakeUp = (runDir, id) => {
+  if (!runDir || id === undefined || id === null) return null;
+  const root = dirname(runDir);
+  const self = basename(runDir);
+  if (!RUN_DIR_NAME.test(self)) return null;
+  const names = [];
+  let dir;
+  try {
+    dir = opendirSync(root);
+  } catch {
+    return null;
+  }
+  try {
+    for (let seen = 0; seen < RUNS_ROOT_ENTRY_BUDGET; seen += 1) {
+      const entry = dir.readSync();
+      if (entry === null) break;
+      if (entry.isDirectory() && entry.name !== self && RUN_DIR_NAME.test(entry.name)) {
+        names.push(entry.name);
+      }
+    }
+  } catch {
+    return null;
+  } finally {
+    dir.closeSync();
+  }
+  names.sort().reverse();
+  for (const name of names.slice(0, RUNS_READ_CAP)) {
+    const candidate = join(root, name);
+    let state;
+    try {
+      state = JSON.parse(readFileSync(statePathIn(candidate), 'utf8'));
+    } catch {
+      continue;
+    }
+    const updatedAt = state?.takeUps?.[String(id)];
+    if (typeof updatedAt === 'string') return { updatedAt, runDir: candidate };
+  }
+  return null;
+};
+
 /**
  * The stop inputs, read out of a state object that anything may have written.
  *

package/templates/agent-os/universal/.claude/scripts/stop-flag.mjs

@@ -21,19 +21,26 @@ import { existsSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { delimiter, join } from 'node:path';
 
-/** Every path that arms the brake. The machine-level default is always first. */
-export const stopFlags = (env = process.env) => {
-  // BOTH homes: `homedir()` honours $HOME, which `.claude/settings.json` can set —
-  // pointing it at an empty directory disarmed the brake. `userInfo()` reads the
-  // password database and ignores the environment, so the operator's real flag is
-  // always among the paths checked.
-  const homes = new Set([homedir()]);
+/**
+ * BOTH homes, env-derived first: `$HOME` (what `.claude/settings.json` can set —
+ * pointing it at an empty directory once disarmed the brake) and the password
+ * database's, which ignores the environment, so the operator's real flag is
+ * always among the paths checked. Shared with the unattended flag (AR-51): one
+ * lookup, one place to be wrong.
+ */
+export const homesOf = (env = process.env) => {
+  const homes = new Set([env.HOME || homedir()]);
   try {
     homes.add(userInfo().homedir);
   } catch {
     // no password entry — the env-derived home is all there is
   }
-  const paths = [...homes].map((home) => join(home, '.claude', '__PROJECT_NAME__-loop-STOP'));
+  return [...homes];
+};
+
+/** Every path that arms the brake. The machine-level default is always first. */
+export const stopFlags = (env = process.env) => {
+  const paths = homesOf(env).map((home) => join(home, '.claude', '__PROJECT_NAME__-loop-STOP'));
   const extra = env.AGENT_LOOP_STOP;
   if (extra) {
     // Filtered and CAPPED before the spread, never after. Spreading an

package/templates/agent-os/universal/.claude/scripts/unattended-flag.mjs

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+// The unattended flag — how a hook learns that a loop is running, and what the
+// current item is allowed to touch (AR-51).
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
+//
+//   node .claude/scripts/unattended-flag.mjs on --root <checkout> --item AR-51 --run-dir <dir> --allow <prefix> [<prefix>…]
+//   node .claude/scripts/unattended-flag.mjs off --root <checkout>
+//   node .claude/scripts/unattended-flag.mjs off --legacy --path <reported-path>
+//
+// It is a FILE, not an environment variable: a `PreToolUse` hook is spawned by
+// the harness with the harness's own environment, never with a variable the
+// session exported — the generator's `test/template/guard-rulebook.test.ts` (absent in a generated rig) ›
+// "only a flag arms it — an exported RIG_UNATTENDED=1 with no flag changes
+// nothing" pins that side of it — and in some harnesses an `export` does not
+// even survive to the next Bash call. The kill switch (`stop-flag.mjs`) is a
+// file for the same reason,
+// and this module copies its two-home lookup. Unlike the machine-wide brake,
+// each unattended record is scoped to the canonical checkout, so concurrent
+// worktrees cannot overwrite or clear one another's authorization.
+//
+// The flag is JSON, `{ item, runDir, allow }`. `allow` is the list of
+// repo-relative prefixes the current item may write under even though they are
+// part of the rulebook — the loop writes it at claim time from the paths the
+// item names, and clears the flag when the run ends. A blanket "no rulebook
+// edits while unattended" would stall on the first queue item that touches
+// `queue/*.mjs`, which is most of this queue; the allow-list is what makes the
+// guard livable, and the guard is what makes the allow-list a decision rather
+// than a default.
+//
+// 🔴 Three answers, and the third is not the first: `{ on: false }` when no flag
+// exists — an attended session, the guard does nothing; `{ on: true, item,
+// runDir, allow }` when it reads; `{ on: true, unreadable: true, why }` when a
+// file is THERE and this module cannot read it as the shape above. A guard that
+// treated the third as the first would be disarmed by a corrupt flag, which is
+// the fail-open bypass `.claude/rules/invariants.md` names.
+//
+// 🔴 An `allow` entry may not WIDEN the rulebook: one that is a prefix of a
+// rulebook prefix — `.`, `.claude/`, `.claude/scripts/`, `CLAUDE` — would let
+// the flag disarm the guard for a whole tree while it reports itself as on, so
+// the writer refuses it and a flag carrying one is unreadable. An entry outside
+// the rulebook (`src/`) is harmless because it is never judged; a narrow entry
+// inside it (`.claude/skills/loop/`) authorizes only that subtree. Items name
+// both forms, so they are kept — › "an allow entry that widens the rulebook — a prefix of a rulebook prefix such as `.` — makes the flag unreadable".
+//
+// Bounded: the file is read up to 64 KiB, `allow` is capped at 64 entries, and
+// both limits are refusals, never silent truncation. A candidate is opened
+// nonblocking and must be a regular file — see the generator's
+// `test/template/unattended-flag.test.ts` (absent in a generated rig) ›
+// "returns promptly and fails closed when a candidate is a FIFO". An access
+// error is unreadable, not absent — › "is on-but-unreadable when access to an
+// existing flag fails at the stat boundary".
+// Cleanup preserves the same distinction: an owned legacy record that cannot
+// be inspected is an error, not evidence that nothing remains — › "exits
+// nonzero and leaves an unreadable owned legacy flag in place".
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homesOf } from './stop-flag.mjs';
+
+export const FLAG_BASENAME = '__PROJECT_NAME__-loop-UNATTENDED';
+export const MAX_FLAG_BYTES = 64 * 1024;
+export const MAX_ALLOW_ENTRIES = 64;
+
+/**
+ * The files that decide what a session may do — repo-relative prefixes. Owned
+ * here because two things read them: the guard, to judge an edit, and the
+ * writer above, to refuse an allow-list that reaches outside them.
+ */
+export const RULEBOOK_PREFIXES = Object.freeze([
+  '.agents/',
+  '.claude/.rig-manifest.json',
+  '.claude/agents/',
+  '.claude/hooks/',
+  '.claude/settings.json',
+  '.claude/queue.json',
+  // the per-checkout board selector: picks among the boards queue.json declares,
+  // so an unattended run must not be able to re-aim itself through it either
+  '.claude/queue.board',
+  '.claude/scripts/',
+  '.claude/rules/',
+  '.claude/skills/',
+  '.codex/',
+  'AGENTS.md',
+  'CLAUDE.md',
+]);
+
+/** Is this repo-relative path part of the rulebook? */
+export const isRulebookPath = (rel) =>
+  RULEBOOK_PREFIXES.some((prefix) => rel === prefix || rel.startsWith(prefix));
+
+/**
+ * Does this allow entry widen the rulebook? It is unsafe when it is an
+ * exact protected prefix deliberately unavailable as an allow root (`.agents/`,
+ * `.claude/scripts/`, `.codex/`), or when it is a proper prefix of any
+ * rulebook prefix and would therefore admit that prefix plus siblings. All
+ * protected script paths sit under `.claude/scripts/`; a narrower path such as
+ * `.claude/scripts/queue/` is an ordinary allow entry and does not widen it.
+ * `src/` also does not widen it because the guard judges nothing there.
+ */
+export const isWidening = (entry) =>
+  typeof entry !== 'string' ||
+  entry === '' ||
+  entry === '.agents/' ||
+  entry === '.claude/scripts/' ||
+  entry === '.codex/' ||
+  RULEBOOK_PREFIXES.some((prefix) => prefix !== entry && prefix.startsWith(entry));
+
+const canonicalCheckout = (env) => {
+  const declared = typeof env.CLAUDE_PROJECT_DIR === 'string' ? env.CLAUDE_PROJECT_DIR.trim() : '';
+  if (declared === '') return null;
+  try {
+    return realpathSync(declared);
+  } catch {
+    return resolve(declared);
+  }
+};
+
+const checkoutId = (env) => {
+  const canonical = canonicalCheckout(env);
+  if (canonical === null) return null;
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+};
+
+const scopedBasename = (env) => {
+  const id = checkoutId(env);
+  return id === null ? FLAG_BASENAME : FLAG_BASENAME.replace('-loop-UNATTENDED', `-${id}-loop-UNATTENDED`);
+};
+
+/** Every checkout-scoped path that arms unattended mode. The env-derived home is first. */
+export const unattendedFlags = (env = process.env) =>
+  homesOf(env).map((home) => join(home, '.claude', scopedBasename(env)));
+
+/** Legacy machine-wide candidates are never accepted as scoped authorization. */
+const legacyFlags = (env) => homesOf(env).map((home) => join(home, '.claude', FLAG_BASENAME));
+
+const isMissing = (error) => error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
+
+const readCapped = (path) => {
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+  try {
+    if (!fstatSync(fd).isFile()) {
+      const error = new Error('unattended flag is not a regular file');
+      error.code = 'EINVAL';
+      throw error;
+    }
+    const buffer = Buffer.alloc(MAX_FLAG_BYTES + 1);
+    const bytes = readSync(fd, buffer, 0, buffer.length, 0);
+    return { bytes, text: buffer.toString('utf8', 0, Math.min(bytes, MAX_FLAG_BYTES)) };
+  } finally {
+    closeSync(fd);
+  }
+};
+
+const unreadable = (path, why) => ({ on: true, unreadable: true, path, why });
+
+const inspectCandidates = (candidates) => {
+  const present = [];
+  for (const path of candidates) {
+    try {
+      present.push({ path, raw: readCapped(path) });
+    } catch (error) {
+      if (isMissing(error)) continue;
+      return {
+        present,
+        failure: unreadable(path, `cannot be read: ${error?.code ?? 'read failed'}`),
+      };
+    }
+  }
+  return { present, failure: null };
+};
+
+/** The mode the flag declares — see the header for the three answers. */
+export const readUnattended = (env = process.env) => {
+  const scoped = checkoutId(env) !== null;
+  const inspected = inspectCandidates(unattendedFlags(env));
+  if (inspected.failure) return inspected.failure;
+  const { present } = inspected;
+  let path = present[0]?.path;
+  let raw = present[0]?.raw ?? null;
+  if (scoped && present.length > 1) {
+    const first = present[0];
+    if (
+      present.some(
+        ({ raw: candidate }) =>
+          candidate.bytes !== first.raw.bytes || candidate.text !== first.raw.text,
+      )
+    ) {
+      return unreadable(first.path, 'mirrored checkout-scoped unattended flags disagree');
+    }
+    raw = first.raw;
+  }
+  if (!path && scoped) {
+    const legacy = inspectCandidates(legacyFlags(env));
+    if (legacy.failure) return legacy.failure;
+    path = legacy.present[0]?.path;
+    if (path) {
+      return unreadable(
+        path,
+        'legacy machine-wide unattended flag cannot authorize a scoped checkout; migrate or remove it explicitly',
+      );
+    }
+  }
+  if (!path) return { on: false };
+  if (raw.bytes > MAX_FLAG_BYTES) return unreadable(path, `larger than ${MAX_FLAG_BYTES} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.text);
+  } catch {
+    return unreadable(path, 'not valid JSON');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return unreadable(path, 'not a JSON object');
+  }
+  if (!Array.isArray(parsed.allow) || parsed.allow.some((entry) => typeof entry !== 'string')) {
+    return unreadable(path, '`allow` is not an array of strings');
+  }
+  if (parsed.allow.length > MAX_ALLOW_ENTRIES) {
+    return unreadable(path, `\`allow\` carries more than ${MAX_ALLOW_ENTRIES} entries`);
+  }
+  const allow = parsed.allow.map((entry) => entry.trim()).filter(Boolean);
+  const wide = allow.find(isWidening);
+  if (wide !== undefined) {
+    return unreadable(
+      path,
+      `\`allow\` entry ${JSON.stringify(wide)} widens the rulebook (it is a prefix of a rulebook prefix) — an allow-list narrows the rulebook, never widens it`,
+    );
+  }
+  return {
+    on: true,
+    item: typeof parsed.item === 'string' ? parsed.item : null,
+    runDir: typeof parsed.runDir === 'string' ? parsed.runDir : null,
+    allow,
+  };
+};
+
+/**
+ * Write the flag. Scoped records are mirrored into both trusted homes, with the
+ * password-database home first, so a caller whose HOME differs still observes
+ * the target checkout's state. An unscoped legacy-compatible write keeps the
+ * historical first-home behaviour.
+ */
+export const writeUnattended = ({ item, runDir = null, allow = [] } = {}, env = process.env) => {
+  if (typeof item !== 'string' || item.trim() === '') {
+    throw new Error('the unattended flag needs an item id — a run without an item has nothing to allow');
+  }
+  const list = (Array.isArray(allow) ? allow : []).map((entry) => String(entry).trim()).filter(Boolean);
+  if (list.length > MAX_ALLOW_ENTRIES) {
+    throw new Error(`the allow-list is capped at ${MAX_ALLOW_ENTRIES} entries`);
+  }
+  const wide = list.find(isWidening);
+  if (wide !== undefined) {
+    throw new Error(
+      `allow entry ${JSON.stringify(wide)} widens the rulebook — it is a prefix of one of ${RULEBOOK_PREFIXES.join(', ')}; ` +
+        'an allow-list narrows the rulebook, never widens it. A directory entry needs its trailing slash ' +
+        '(`.claude/hooks/`, not `.claude/hooks`).',
+    );
+  }
+  const candidates = unattendedFlags(env);
+  const targets = checkoutId(env) === null ? candidates.slice(0, 1) : [...candidates].reverse();
+  const written = [];
+  const content = `${JSON.stringify({ item: item.trim(), runDir, allow: list }, null, 2)}\n`;
+  try {
+    for (const path of targets) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+      written.push(path);
+    }
+  } catch (error) {
+    for (const path of written) {
+      try {
+        rmSync(path);
+      } catch {
+        // best-effort rollback; a surviving record keeps readers fail-closed
+      }
+    }
+    throw error;
+  }
+  return written;
+};
+
+const pathBelongsToCheckout = (candidate, checkout) => {
+  let resolved;
+  try {
+    resolved = realpathSync(candidate);
+  } catch {
+    resolved = resolve(candidate);
+  }
+  const rel = relative(checkout, resolved);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+const legacyBelongsToCheckout = (flagPath, env) => {
+  const checkout = canonicalCheckout(env);
+  if (checkout === null) return false;
+  try {
+    const raw = readCapped(flagPath);
+    if (raw.bytes > MAX_FLAG_BYTES) return false;
+    const parsed = JSON.parse(raw.text);
+    return typeof parsed?.runDir === 'string' && pathBelongsToCheckout(parsed.runDir, checkout);
+  } catch (error) {
+    if (!isMissing(error)) {
+      throw new Error(
+        `legacy unattended flag at ${flagPath} cannot be read: ${error?.code ?? error?.message ?? 'read failed'}`,
+        { cause: error },
+      );
+    }
+    return false;
+  }
+};
+
+/** Remove this checkout's flags and a provably-owned legacy record. */
+export const clearUnattended = (env = process.env) => {
+  const removed = [];
+  const failures = [];
+  const candidates = checkoutId(env) === null
+    ? unattendedFlags(env)
+    : [
+        ...unattendedFlags(env),
+        ...legacyFlags(env).filter((path) => legacyBelongsToCheckout(path, env)),
+      ];
+  for (const path of [...new Set(candidates)]) {
+    try {
+      rmSync(path);
+      removed.push(path);
+    } catch (error) {
+      if (isMissing(error)) continue;
+      failures.push(`${path}: ${error?.code ?? error?.message ?? 'remove failed'}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(`failed to remove unattended flag(s): ${failures.join('; ')}`);
+  }
+  return removed;
+};
+
+/** Explicit operator migration: remove exactly the inspected legacy record. */
+export const clearLegacyUnattended = (selectedPath) => {
+  if (typeof selectedPath !== 'string' || selectedPath.trim() === '') {
+    throw new Error('off --legacy requires --path <reported-path>');
+  }
+  const path = resolve(selectedPath);
+  if (basename(path) !== FLAG_BASENAME || basename(dirname(path)) !== '.claude') {
+    throw new Error(`refusing legacy cleanup outside .claude/${FLAG_BASENAME}`);
+  }
+  try {
+    rmSync(path);
+    return [path];
+  } catch (error) {
+    if (isMissing(error)) return [];
+    throw error;
+  }
+};
+
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const [word, ...rest] = process.argv.slice(2);
+  const valueOf = (flag) => {
+    const index = rest.indexOf(flag);
+    return index === -1 ? null : (rest[index + 1] ?? null);
+  };
+  const root = valueOf('--root');
+  const cliEnv = root && !root.startsWith('--')
+    ? { ...process.env, CLAUDE_PROJECT_DIR: root }
+    : process.env;
+  if (word === 'on') {
+    const item = valueOf('--item');
+    if (!item || item.startsWith('--')) {
+      process.stderr.write('unattended-flag on: --item <id> is required — the flag names the item whose paths are allowed\n');
+      process.exit(1);
+    }
+    const allowIndex = rest.indexOf('--allow');
+    const allow =
+      allowIndex === -1
+        ? []
+        : rest.slice(allowIndex + 1).filter((entry, i, all) => {
+            const stop = all.findIndex((e) => e.startsWith('--'));
+            return stop === -1 || i < stop;
+          });
+    let path;
+    try {
+      [path] = writeUnattended({ item, runDir: valueOf('--run-dir'), allow }, cliEnv);
+    } catch (error) {
+      process.stderr.write(`unattended-flag on: ${error?.message ?? error}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`${path}\n`);
+    process.exit(0);
+  }
+  if (word === 'off') {
+    const legacy = rest.includes('--legacy');
+    let removed;
+    try {
+      removed = legacy ? clearLegacyUnattended(valueOf('--path')) : clearUnattended(cliEnv);
+    } catch (error) {
+      process.stderr.write(`unattended-flag off: ${error?.message ?? error}\n`);
+      process.exit(1);
+    }
+    if (!legacy && root) {
+      const remaining = readUnattended(cliEnv);
+      if (remaining.on) {
+        const reason = remaining.why ?? 'an unattended flag is still armed';
+        process.stderr.write(
+          `unattended-flag off: ${reason} at ${remaining.path}. ` +
+            'Inspect that exact record; if no pre-upgrade run still uses it, remove it with `off --legacy --path <reported-path>`.\n',
+        );
+        process.exit(1);
+      }
+    }
+    process.stdout.write(removed.length === 0 ? 'no unattended flag was set\n' : `${removed.join('\n')}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`unknown word: ${word ?? '(none)'}. This CLI has two: on, off.\n`);
+  process.exit(1);
+}