create-agent-rig 0.4.0 → 0.6.0

package/packages/cli/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { settingsForInstalledHooks } from '../lib/init-settings.js';
+import { mapConcurrent } from '../lib/copy-tree.js';
 import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
 import { substituteContent } from '../lib/substitute.js';
 import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
@@ -8,7 +9,11 @@ import { packageVersion } from '../lib/version.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class InitError extends Error {
 }
+/** What `--force` answers with now that `upgrade` owns the case it stood in for. */
+export const FORCE_DEPRECATED = 'deprecated — init --force replaced only CLAUDE.md; run create-agent-rig upgrade instead';
 const SETTINGS = '.claude/settings.json';
+const CODEX_HOOKS = '.codex/hooks.json';
+const MAPS = ['CLAUDE.md', 'AGENTS.md'];
 async function loadManifest() {
     const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
     return JSON.parse(raw);
@@ -53,15 +58,15 @@ export async function initManifest() {
     const manifest = await loadManifest();
     const universal = agentOsUniversalDir();
     const override = agentOsInitDir();
-    const files = [];
-    for (const rel of [...manifest.process, 'CLAUDE.md']) {
+    const files = await mapConcurrent([...manifest.process, ...MAPS], 16, async (rel) => {
         const overridden = path.join(override, rel);
-        files.push({
+        return {
             rel,
             source: (await exists(overridden)) ? overridden : path.join(universal, rel),
-        });
-    }
+        };
+    });
     files.push({ rel: SETTINGS, source: null });
+    files.push({ rel: CODEX_HOOKS, source: null });
     return files;
 }
 /**
@@ -82,14 +87,23 @@ export async function initFileContents(repoDir, project) {
     };
     const files = await initManifest();
     const contents = new Map();
-    for (const { rel, source } of files) {
-        if (source === null)
-            continue;
-        contents.set(rel, substituteContent(await readFile(source, 'utf8'), ctx));
+    const sourceFiles = files.filter((file) => file.source !== null);
+    const rendered = await mapConcurrent(sourceFiles, 16, async ({ rel, source }) => ({
+        rel,
+        content: substituteContent(await readFile(source, 'utf8'), ctx),
+    }));
+    for (const { rel, content } of rendered) {
+        contents.set(rel, content);
     }
     const installedHooks = new Set(files.map((f) => f.rel).filter((rel) => rel.startsWith('.claude/hooks/')));
-    const shipped = JSON.parse(await readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'));
+    const [shippedSettings, shippedCodexHooks] = await Promise.all([
+        readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'),
+        readFile(path.join(agentOsUniversalDir(), CODEX_HOOKS), 'utf8'),
+    ]);
+    const shipped = JSON.parse(shippedSettings);
     contents.set(SETTINGS, `${JSON.stringify(settingsForInstalledHooks(shipped, installedHooks), null, 2)}\n`);
+    const shippedCodex = JSON.parse(shippedCodexHooks);
+    contents.set(CODEX_HOOKS, `${JSON.stringify(settingsForInstalledHooks(shippedCodex, installedHooks), null, 2)}\n`);
     return contents;
 }
 /** The process layer as a set of {@link InstalledFile}s — what `upgrade` reads. */
@@ -100,41 +114,49 @@ export async function initInstallSet(repoDir, project) {
 }
 export async function planInit(repoDir) {
     const files = (await initManifest()).map((f) => f.rel);
-    const conflicts = [];
-    for (const rel of files) {
-        if (await exists(path.join(repoDir, rel)))
-            conflicts.push(rel);
-    }
+    const conflicts = (await mapConcurrent(files, 16, async (rel) => (await exists(path.join(repoDir, rel))) ? rel : null)).filter((rel) => rel !== null);
     return { files: files.map((p) => ({ path: p })), conflicts };
 }
 export async function initProject(repoDir, options) {
+    // Refused before anything is read or written, so a deprecated flag cannot
+    // half-install: `upgrade` covers what this stood in for, and it decides per
+    // file from the manifest instead of overriding one refusal wholesale.
+    if (options.force)
+        throw new InitError(FORCE_DEPRECATED);
     const files = (await initManifest()).map((f) => f.rel);
-    // Refuse to clobber an existing CLAUDE.md unless forced — init edits
-    // someone's working repository (brief §4, non-negotiable).
-    if (!options.force && files.includes('CLAUDE.md')) {
-        if (await exists(path.join(repoDir, 'CLAUDE.md'))) {
-            throw new InitError('This repo already has a CLAUDE.md. Refusing to overwrite it. ' +
-                'Merge the agent-os map in by hand, or re-run with --force to replace it.');
+    const previous = await readManifest(repoDir);
+    // Refuse to clobber an existing CLAUDE.md — init edits someone's working
+    // repository (brief §4, non-negotiable).
+    for (const map of MAPS) {
+        if (files.includes(map) && (await exists(path.join(repoDir, map)))) {
+            // A create rig whose CLAUDE.md was deleted is the legacy route into init.
+            // Its generated AGENTS.md must not newly close that route, but only the
+            // manifest can distinguish that file from a user's own Codex guidance.
+            if (map === 'AGENTS.md' &&
+                previous?.files[map] !== undefined &&
+                sha256(await readFile(path.join(repoDir, map), 'utf8')) === previous.files[map]) {
+                continue;
+            }
+            throw new InitError(`This repo already has an ${map}. Refusing to overwrite it. ` +
+                'Merge the agent-os map in by hand, or run create-agent-rig upgrade to refresh a rig.');
         }
     }
     const contents = await initFileContents(repoDir);
-    const written = [];
-    const skipped = [];
     const plannedCount = files.length;
-    for (const rel of files) {
+    const actions = await mapConcurrent(files, 16, async (rel) => {
         const dest = path.join(repoDir, rel);
-        const isForceableMeta = rel === 'CLAUDE.md';
-        if ((await exists(dest)) && !(isForceableMeta && options.force)) {
+        if (await exists(dest)) {
             // never overwrite a file init did not write (a user's own copy)
-            skipped.push(rel);
-            continue;
+            return { rel, verdict: 'skipped' };
         }
         if (options.dryRun)
-            continue;
+            return { rel, verdict: 'planned' };
         await mkdir(path.dirname(dest), { recursive: true });
         await writeFile(dest, contents.get(rel) ?? '');
-        written.push(rel);
-    }
+        return { rel, verdict: 'written' };
+    });
+    const written = actions.filter(({ verdict }) => verdict === 'written').map(({ rel }) => rel);
+    const skipped = actions.filter(({ verdict }) => verdict === 'skipped').map(({ rel }) => rel);
     if (!options.dryRun)
         await recordInstall(repoDir, written, contents);
     return { written, skipped, plannedCount };
@@ -147,6 +169,32 @@ export async function initProject(repoDir, options) {
  * somebody else's — claiming it here would let the next upgrade replace a
  * user's own document with the rig's. Earlier entries are preserved: a re-run
  * writes nothing and must not therefore un-remember everything.
+ *
+ * 🔴 **`kind`, `project` and `stacks` are preserved, not rewritten.** Reached
+ * inside a rig `create` produced, this used to stamp `kind: 'init'`,
+ * `stacks: []` and an empty `region` over the truth — and `planUpgrade` trusts
+ * a manifest wholesale (it never re-detects), so the next upgrade routed to the
+ * `init` install set and the stack overlays left the plan entirely: not
+ * reported as deleted, not as a conflict, simply absent. `init` describes what
+ * it wrote; it does not get to re-describe how the rig was installed.
+ *
+ * ⚠ **The limit, stated because the fix reads as wider than it is:** this
+ * preserves a manifest, so a rig without a READABLE one still gets
+ * `kind: 'init'`, no stacks and an empty region, and the advisory in `runInit`
+ * stays silent for the same reason. That is three populations, not one: a rig
+ * from before 0.4.0 never had a manifest, a deleted manifest is a documented
+ * recovery step, and one on disk that `parseManifest` voids reads as absent to
+ * `readManifest` alike. `upgrade`'s `detectInstall`
+ * recovers all three from the files on disk, so those values are not
+ * unavailable, only unavailable *here*: reaching for it would point
+ * `commands/init` at `commands/upgrade`, which already imports this module.
+ * The fallback below is the honest floor, not the best available answer.
+ *
+ * The item that asked for this also floated refusing `init` outright on a
+ * `create` manifest. It is already refused a step earlier and for a different
+ * reason — {@link initProject} throws on the existing `CLAUDE.md`. The gap that
+ * leaves is a `create` rig whose `CLAUDE.md` was deleted, and this function is
+ * what makes that case safe.
  */
 async function recordInstall(repoDir, written, contents) {
     const previous = await readManifest(repoDir);
@@ -156,9 +204,12 @@ async function recordInstall(repoDir, written, contents) {
         files[rel] = sha256(contents.get(rel) ?? '');
     const manifest = {
         version: await packageVersion(),
-        kind: 'init',
-        project: { name, scope: name, region: '' },
-        stacks: [],
+        kind: previous?.kind ?? 'init',
+        // No manifest: fall back to the directory name, which is all this module
+        // reads. See the limit above — `upgrade` can do better from the files
+        // themselves, and `init` deliberately does not reach for it.
+        project: previous?.project ?? { name, scope: name, region: '' },
+        stacks: previous?.stacks ?? [],
         files,
     };
     await writeManifest(repoDir, manifest);

package/packages/cli/dist/commands/upgrade.js

@@ -1,11 +1,12 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { initInstallSet, projectNameFor } from './init.js';
+import { hookFilesReferencedIn } from '../lib/init-settings.js';
 import { loadHashHistory, presentInEveryRelease } from '../lib/history.js';
 import { agentOsInstallSet, agentOsLayerDirs } from '../lib/install-set.js';
 import { listTree } from '../lib/copy-tree.js';
 import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
-import { resolveInside } from '../lib/safe-path.js';
+import { isSafeSubstitutionValue, resolveInside } from '../lib/safe-path.js';
 import { detokenizeContent, substituteFileName } from '../lib/substitute.js';
 import { TARGETS } from '../lib/targets.js';
 import { packageVersion } from '../lib/version.js';
@@ -13,6 +14,8 @@ import { packageVersion } from '../lib/version.js';
 export class UpgradeError extends Error {
 }
 const SETTINGS = '.claude/settings.json';
+const CODEX_HOOKS = '.codex/hooks.json';
+const WIRING_PATHS = new Set([SETTINGS, CODEX_HOOKS]);
 /** The universal layer's architecture group — installed by `create`, never by `init`. */
 const ARCHITECTURE_ONLY = [
     '.claude/rules/architecture.md',
@@ -130,6 +133,30 @@ function isReleasedVersion(history, rel, content, ctx) {
     const candidates = new Set([sha256(content), sha256(detokenizeContent(content, ctx))]);
     return known.hashes.some((hash) => candidates.has(hash));
 }
+/**
+ * Would writing `next` over `current` stop calling a hook that is still there?
+ *
+ * The one question the hash arms cannot answer. They prove the bytes belong to
+ * the rig; they do not prove the replacement wires the same hooks, and
+ * Wiring files have flavours that differ in exactly that. A hook file
+ * still on disk with nothing wired to it is the quiet failure
+ * `lib/init-settings.ts` names: the rules claim it is enforced and nothing ever
+ * calls it.
+ *
+ * Only hooks whose FILE is still present count. One the user deleted on purpose
+ * is not being silenced by this write — it was already gone.
+ */
+async function unwiresAnInstalledHook(repoDir, current, next) {
+    const nextHooks = hookFilesReferencedIn(next);
+    for (const hook of hookFilesReferencedIn(current)) {
+        if (nextHooks.has(hook))
+            continue;
+        const onDisk = resolveInside(repoDir, hook);
+        if (onDisk !== null && (await exists(onDisk)))
+            return true;
+    }
+    return false;
+}
 /**
  * What an upgrade would do, decided per file, writing nothing.
  *
@@ -146,11 +173,37 @@ export async function planUpgrade(repoDir, options = {}) {
         ? await detectInstall(repoDir)
         : { kind: manifest.kind, stacks: manifest.stacks, region: manifest.project.region };
     const kind = manifest?.kind ?? detected.kind;
-    const name = path.basename(path.resolve(repoDir));
-    // `init` slugs the directory name into something an operator can type (it
-    // ends up in the kill-switch filename); `create` validated it as an npm name
-    // at generation time, so there the basename is already the project name.
-    const bootstrapName = kind === 'init' ? projectNameFor(repoDir) : name;
+    // With no manifest to read, guess the name the rig's own files were written
+    // with — and each command wrote them differently, so the guess branches the
+    // same way:
+    //
+    // - `init` substitutes the **slug** and records the slug (`init.ts`,
+    //   `projectNameFor` in both places), so for an init rig the slug is not an
+    //   approximation, it is the value;
+    // - `create` substitutes the name it was **given**, having validated it — and
+    //   that validation accepts a trailing `-` or `.`, which `projectNameFor`
+    //   strips. So slugging a create rig renames it: `my-app.` became `my-app`,
+    //   stopped matching its own installed files, and returned four of them as
+    //   conflicts.
+    //
+    // The one case where the raw name cannot be kept is a directory the manifest
+    // reader would refuse — `My App` produced `{"name":"My App"}`, which
+    // `parseManifest` voids, so the manifest this command exists to write was
+    // written and immediately unreadable, and every later run fell back to
+    // matching against released versions. The condition is that reader's own
+    // exported predicate, not a second copy of its rule.
+    //
+    // 🔴 All three branches were bought by a defect, and two of those defects
+    // were introduced by fixing the other — the mirror is easy to miss, because
+    // each fix looks total until the other kind is tried. Change nothing here
+    // without running the three sibling cases in `upgrade.test.ts`.
+    //
+    // ⚠ It is still the *directory's* name, so a renamed or cloned rig with no
+    // manifest bootstraps the new name and its substituted files come back as
+    // conflicts — kept and reported, never overwritten. Committing the manifest
+    // is what removes the guess, and that is unchanged from 0.4.0.
+    const rawName = path.basename(path.resolve(repoDir));
+    const bootstrapName = kind === 'init' || !isSafeSubstitutionValue(rawName) ? projectNameFor(repoDir) : rawName;
     const project = manifest?.project ?? {
         name: bootstrapName,
         scope: bootstrapName,
@@ -172,6 +225,7 @@ export async function planUpgrade(repoDir, options = {}) {
     const contents = new Map();
     const nextFiles = {};
     let wiring = null;
+    const wiringByPath = new Map();
     for (const file of files) {
         const current = await readIfPresent(repoDir, file.rel);
         const recorded = manifest?.files[file.rel];
@@ -202,36 +256,63 @@ export async function planUpgrade(repoDir, options = {}) {
             }
             continue;
         }
-        if (file.rel === SETTINGS) {
-            if (current === file.content) {
-                actions.push({ rel: file.rel, verdict: 'unchanged' });
-                nextFiles[file.rel] = sha256(file.content);
-            }
-            else {
-                // Same special case `init` makes: this file is a merge target, not a
-                // payload — replacing it can unwire hooks the user added themselves.
-                wiring = file.content;
-                actions.push({
-                    rel: file.rel,
-                    verdict: 'wiring',
-                    reason: 'never replaced — merge the entries below by hand',
-                });
-                if (recorded !== undefined)
-                    nextFiles[file.rel] = recorded;
-            }
-            continue;
-        }
+        // The two limits that keep wiring files' new replaceability from
+        // disarming the rig, both measured rather than reasoned about.
+        //
+        // 1. The released-hash fallback is not enough for THIS file. Every other
+        //    file has one flavour; this one has two — `create` wires all the hooks,
+        //    `init` wires only the ones it installs — and they share a history
+        //    entry. A manifest-less rig that ran `init` is recorded `kind: 'init'`,
+        //    so matching a released hash would write the narrow wiring over the
+        //    full one. The item asks for the manifest arm and says the rest is
+        //    reported, which is also the reading with no regression behind it.
+        // 2. Even the manifest arm is not enough on its own, because `kind` is
+        //    trusted from a file that travels in pull requests. So the decision is
+        //    gated on the wiring itself: if the replacement would stop calling a
+        //    hook still sitting in `.claude/hooks/`, it is handed over. That check
+        //    does not care which flavour anything claims to be.
+        const isWiring = WIRING_PATHS.has(file.rel);
+        const wouldUnwireAnInstalledHook = isWiring && (await unwiresAnInstalledHook(repoDir, current, file.content));
+        const vouched = isWiring
+            ? recorded !== undefined && sha256(current) === recorded
+            : (recorded !== undefined && sha256(current) === recorded) ||
+                isReleasedVersion(history, file.rel, current, ctx);
         if (current === file.content) {
             actions.push({ rel: file.rel, verdict: 'unchanged' });
             nextFiles[file.rel] = sha256(file.content);
         }
-        else if (recorded !== undefined && sha256(current) === recorded) {
-            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+        else if (vouched && !wouldUnwireAnInstalledHook) {
+            actions.push({
+                rel: file.rel,
+                verdict: 'update',
+                templatePath: file.source,
+                // Every other replacement is routine; this one rewrites what calls the
+                // guards, so it says so rather than arriving as one more `~` line.
+                ...(isWiring ? { reason: 'the hook wiring, replaced — you never edited it' } : {}),
+            });
             nextFiles[file.rel] = sha256(file.content);
         }
-        else if (isReleasedVersion(history, file.rel, current, ctx)) {
-            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
-            nextFiles[file.rel] = sha256(file.content);
+        else if (isWiring) {
+            // Nothing vouches for these bytes, or replacing them would silence a hook
+            // that is still installed. Either way this is the one file whose conflict
+            // is a merge rather than a choice, so the released file is handed over.
+            wiring = file.content;
+            wiringByPath.set(file.rel, file.content);
+            actions.push({
+                rel: file.rel,
+                verdict: 'wiring',
+                // Say what was actually checked. This file no longer consults the
+                // released-hash table (see the limits above), so it cannot claim these
+                // bytes are not a release — only that the manifest does not vouch for
+                // them, which is the check that ran.
+                reason: wouldUnwireAnInstalledHook
+                    ? 'replacing it would stop calling a hook that is still installed — merge the entries below by hand'
+                    : recorded === undefined
+                        ? 'the manifest does not vouch for it — treated as yours, merge the entries below by hand'
+                        : 'edited since it was installed — merge the entries below by hand',
+            });
+            if (recorded !== undefined)
+                nextFiles[file.rel] = recorded;
         }
         else {
             actions.push({
@@ -263,6 +344,7 @@ export async function planUpgrade(repoDir, options = {}) {
         bootstrapped: manifest === null,
         actions,
         wiring,
+        wiringByPath,
         contents,
         manifest: {
             version: await packageVersion(),

package/packages/cli/dist/index.js

@@ -4,13 +4,14 @@ import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
 import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
+import { readManifest } from './lib/manifest.js';
 import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
 import { packageVersion } from './lib/version.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
-Scaffolds a new project into <dir>: agent operating system (.claude/, CLAUDE.md)
+Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
 plus a runnable code skeleton. Refuses to write into a non-empty directory.
 
 Options
@@ -22,9 +23,12 @@ Options
   --version         print the version
   -h, --help        this text
 
-Also: create-agent-rig init [--dry-run] [--force]
+Also: create-agent-rig init [--dry-run]
   Install the process layer (rules, gates, stop rules — no architecture
-  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md
+  or AGENTS.md.
+  --force is deprecated: it refuses and points at upgrade, which refreshes a
+  rig file by file. It is removed in 0.6.
 
 Also: create-agent-rig upgrade [--dry-run] [--yes]
   Bring the rig in the CURRENT repo up to this version. Replaces the files it
@@ -34,7 +38,13 @@ async function runInit(rawArgs) {
     try {
         ({ values } = parseArgs({
             args: rawArgs,
-            options: { 'dry-run': { type: 'boolean' }, force: { type: 'boolean' } },
+            // `--no-color` for the same reason it is accepted on `upgrade`: USAGE
+            // offers it without scoping it to one command.
+            options: {
+                'dry-run': { type: 'boolean' },
+                force: { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
             allowPositionals: false,
         }));
     }
@@ -44,10 +54,25 @@ async function runInit(rawArgs) {
     }
     const cwd = process.cwd();
     const dryRun = values['dry-run'] === true;
+    // `init` adopts a repo the rig knows nothing about. Run inside a rig `create`
+    // generated — reachable when its CLAUDE.md was deleted — it is the wrong
+    // command: it installs the process layer alone and never refreshes the stack
+    // overlays. Say so before anything is written, so it is visible on --dry-run
+    // too.
+    //
+    // It is a manifest read, so any rig without a READABLE manifest gets no
+    // advisory even when it came from `create` — one never written, one deleted,
+    // and one present but voided by `parseManifest` all reach here alike. The
+    // same limit `recordInstall` carries, stated in both places because either
+    // one alone reads as wider.
+    const existing = await readManifest(cwd);
     const plan = await planInit(cwd);
     process.stdout.write(`agent-rig init — process layer into ${cwd}\n\n` +
         plan.files.map((f) => `  + ${f.path}`).join('\n') +
         '\n');
+    if (existing?.kind === 'create') {
+        process.stdout.write(`\n!  This rig was created by create-agent-rig — \`init\` only fills gaps here; use \`upgrade\` to refresh.\n`);
+    }
     if (plan.conflicts.length > 0) {
         process.stdout.write(`\nAlready present (kept, not overwritten):\n` +
             plan.conflicts.map((c) => `  · ${c}`).join('\n') +
@@ -61,12 +86,15 @@ async function runInit(rawArgs) {
     process.stdout.write(`\nInstalled ${result.written.length} files` +
         (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
         '.\n');
-    // The one kept file that silently disables everything else: without this
-    // wiring the hooks sit on disk and are never called, while the rules claim
-    // they are enforced. Say so loudly, and hand over the exact entries.
-    if (result.skipped.includes('.claude/settings.json')) {
-        const wiring = (await initFileContents(cwd)).get('.claude/settings.json') ?? '';
-        process.stdout.write(`\n!  .claude/settings.json already exists — it was kept, so the rig's hooks are NOT wired.\n` +
+    // A kept harness config silently disables that harness's enforcement: the
+    // hooks sit on disk and are never called, while the rules claim they are.
+    // Say so loudly, and hand over the exact entries for each affected harness.
+    const generated = await initFileContents(cwd);
+    for (const wiringPath of ['.claude/settings.json', '.codex/hooks.json']) {
+        if (!result.skipped.includes(wiringPath))
+            continue;
+        const wiring = generated.get(wiringPath) ?? '';
+        process.stdout.write(`\n!  ${wiringPath} already exists — it was kept, so the rig's hooks are NOT wired there.\n` +
             `   Until you merge these entries into it, nothing enforces the rules:\n\n` +
             wiring.replace(/^/gm, '   ') +
             '\n');
@@ -86,7 +114,7 @@ function renderUpgradePlan(repoDir, plan) {
     const lines = [
         `agent-rig upgrade — ${plan.kind} rig in ${repoDir}`,
         plan.bootstrapped
-            ? `  no manifest here (a pre-0.4.0 rig) — matching files against released versions`
+            ? `  no readable manifest here (deleted, never written, or unparseable) — matching files against released versions`
             : `  installed by ${plan.fromVersion}`,
         `  upgrading to ${plan.toVersion}`,
         '',
@@ -100,9 +128,29 @@ function renderUpgradePlan(repoDir, plan) {
             }
         }
     }
-    const unchanged = of('unchanged').length;
+    // Every one of `UpgradeVerdict`'s six members is accounted for here.
+    // `wiring` and `deleted` each print their own line and were in none of the
+    // buckets, so a reader counted lines and was told a smaller number.
+    // (`unchanged` is counted and prints nothing — the sum is over actions, not
+    // over printed lines.) The two appear only when they occurred, so a plan
+    // without them renders exactly as it always has. Pinned by, in cli-report.test.ts,
+    // "renders a plan with no wiring action exactly as it does today".
+    // `deleted` before `wiring`, the relative order the plan prints them in.
+    // ⚠ Only their order relative to EACH OTHER matches: the plan prints
+    // `deleted` before `conflict` and the summary prints it after, so this is not
+    // a plan-ordered line. Pinned by, in cli-report.test.ts,
+    // "lists the two occasional buckets in the order the plan prints them".
+    const occasional = [
+        ['deleted', (n) => `${n} you removed (left removed)`],
+        ['wiring', (n) => `${n} wiring handed over`],
+    ];
+    const extra = occasional
+        .map(([verdict, phrase]) => [of(verdict).length, phrase])
+        .filter(([count]) => count > 0)
+        .map(([count, phrase]) => phrase(count));
     lines.push('', `  ${of('update').length} to replace, ${of('new').length} new, ` +
-        `${of('conflict').length} yours (kept), ${unchanged} already current`);
+        `${of('conflict').length} yours (kept), ` +
+        [...extra, `${of('unchanged').length} already current`].join(', '));
     return `${lines.join('\n')}\n`;
 }
 async function runUpgrade(rawArgs) {
@@ -110,7 +158,17 @@ async function runUpgrade(rawArgs) {
     try {
         ({ values } = parseArgs({
             args: rawArgs,
-            options: { 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' } },
+            // `--no-color` is advertised in USAGE without scoping it to one command, so
+            // every command accepts it. Refusing a flag the help offers costs the
+            // reader more than honouring it costs us — and honouring it is only a
+            // parse here, because the sole palette lives on the `create` path below.
+            // Pinned by, in cli-report.test.ts,
+            // "upgrade accepts --no-color and prints plain output".
+            options: {
+                'dry-run': { type: 'boolean' },
+                yes: { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
             allowPositionals: false,
         }));
     }
@@ -124,11 +182,15 @@ async function runUpgrade(rawArgs) {
     // The one thing this command will not do for you — printed with the plan,
     // because the dry run is where a reader decides whether there is work here,
     // and a report that mentions entries it never shows is not a plan.
-    if (plan.wiring !== null) {
-        process.stdout.write(`\n!  .claude/settings.json is never replaced — it is where your own hooks live.\n` +
-            `   This version wires them like this; merge in what is missing:\n\n` +
-            plan.wiring.replace(/^/gm, '   ') +
-            '\n');
+    if (plan.wiringByPath.size > 0) {
+        for (const [wiringPath, wiring] of plan.wiringByPath) {
+            process.stdout.write(`\n!  ${wiringPath} was handed over rather than replaced — the reason is\n` +
+                `   on its line above. It is hook wiring, so it is never overwritten\n` +
+                `   without proof the rig wrote those exact bytes.\n` +
+                `   This version wires it like this; merge in what is missing:\n\n` +
+                wiring.replace(/^/gm, '   ') +
+                '\n');
+        }
     }
     if (values['dry-run'] === true) {
         process.stdout.write('\nDry run — nothing written.\n');

package/packages/cli/dist/lib/copy-tree.js

@@ -25,8 +25,38 @@ function isBinary(buffer) {
 }
 export async function copyTree(srcDir, destDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
+    const files = [];
     await mkdir(destDir, { recursive: true });
-    await copyDir(srcDir, destDir, '', { ...options, ignore });
+    await collectCopyTasks(srcDir, destDir, '', { ...options, ignore }, files);
+    await mapConcurrent(files, 16, ({ srcPath, destPath, relPath }) => copyFileEntry(srcPath, destPath, relPath, { ...options, ignore }));
+}
+/** Run independent async work through a bounded pool while preserving result order. */
+export async function mapConcurrent(items, limit, worker) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new RangeError('concurrency limit must be positive');
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    let firstError;
+    const run = async () => {
+        while (!failed && next < items.length) {
+            const index = next;
+            next += 1;
+            try {
+                results[index] = await worker(items[index]);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    firstError = error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+    if (failed)
+        throw firstError;
+    return results;
 }
 /**
  * The destination-relative file paths {@link copyTree} would produce — same
@@ -62,7 +92,7 @@ export async function listTreeEntries(srcDir, options = {}) {
     await walk(srcDir, '');
     return files;
 }
-async function copyDir(srcDir, destDir, relDir, options) {
+async function collectCopyTasks(srcDir, destDir, relDir, options, files) {
     const entries = await readdir(srcDir, { withFileTypes: true });
     for (const entry of entries) {
         if (options.ignore.has(entry.name))
@@ -73,10 +103,10 @@ async function copyDir(srcDir, destDir, relDir, options) {
         const relPath = path.join(relDir, entry.name);
         if (entry.isDirectory()) {
             await mkdir(destPath, { recursive: true });
-            await copyDir(srcPath, destPath, relPath, options);
+            await collectCopyTasks(srcPath, destPath, relPath, options, files);
         }
         else if (entry.isFile()) {
-            await copyFileEntry(srcPath, destPath, relPath, options);
+            files.push({ srcPath, destPath, relPath });
         }
         // Symlinks and other special entries are intentionally not copied:
         // templates are plain trees.
@@ -87,7 +117,7 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
         await copyFile(srcPath, destPath); // copyFile preserves the mode by itself
         return;
     }
-    const buffer = await readFile(srcPath);
+    const [buffer, { mode }] = await Promise.all([readFile(srcPath), stat(srcPath)]);
     if (isBinary(buffer)) {
         await writeFile(destPath, buffer);
     }
@@ -96,6 +126,5 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
     }
     // writeFile does NOT preserve permissions — restore them (chmod ignores umask),
     // otherwise executable template files (scripts, hooks) arrive non-executable.
-    const { mode } = await stat(srcPath);
     await chmod(destPath, mode & 0o777);
 }