devlyn-cli 4.3.28 → 4.3.29

package/README.md

@@ -43,17 +43,17 @@ Without prompts, `npx devlyn-cli -y` installs `.agents/skills/` plus every targe
 
 ## How It Works — Principles and Loops
 
-The Devlyn defaults carry the North Star, seven principles (no workaround, no overengineering, no guesswork, worldclass, best practice, optimized, production ready) and three discipline rules, plus short pointers to the skills. Each session gets them from the release, through the Devlyn app or `devlyn run`, so projects hold no copy and a new release reaches every project at once. A clone without either gets no Devlyn defaults. Agents do the work directly under them; for work that splits into tasks, ideate designs a loop and drains it:
+The Devlyn defaults carry the North Star, seven principles (no workaround, no overengineering, no guesswork, worldclass, best practice, optimized, production ready) and three discipline rules, plus short pointers to the skills. Each session gets them from the release, through the Devlyn app or `devlyn run`, so projects hold no copy and a new release reaches every project at once. A session started any other way, as with a plain `npx devlyn-cli` install, gets the skills but not the defaults; ideate still reads its installed copy for the loops it plans and drains. Agents do the work directly under them; for work that splits into tasks, ideate designs a loop and drains it:
 
 ```
-intent  →  direct work under the installed principles, or an ideate loop  →  ship
+intent  →  direct work under the Devlyn defaults, or an ideate loop  →  ship
 ```
 
-Non-Claude agents (Codex / omp / Pi / Grok): the default choice installs the skills for them. In Codex / omp / Pi, use `$devlyn-ideate`; in Grok, use `/devlyn-ideate`, the same slash-command form as Claude Code. A drain from Pi or Grok needs [a pinned executor](#executor--devlyn-engines).
+Non-Claude agents (Codex / omp / Pi / Grok): the default choice installs the skills for them. In Codex / omp / Pi, use `$devlyn-ideate`; in Grok, use `/devlyn-ideate`, the same slash-command form as Claude Code. A drain from any CLI other than Claude Code or Codex needs [a pinned executor](#executor--devlyn-engines).
 
 ### Terminal sessions — `devlyn run`
 
-`devlyn run claude`, `devlyn run codex` or `devlyn run omp` starts the engine in this terminal with the same principles and skills the Devlyn app delivers, from the selected release. Arguments after the engine name go to the engine. See [docs/harness-run.md](docs/harness-run.md).
+`devlyn run claude`, `devlyn run codex` or `devlyn run omp` starts the engine in this terminal on macOS or Linux (not Windows) with the same principles and skills the Devlyn app delivers, from the selected release. While the harness is on for the project, only engine arguments known not to change the session's freshness, directory or planned settings pass through, and any other stops the launch; with it off, every argument passes. See [docs/harness-run.md](docs/harness-run.md).
 
 ### Plan and drain loops — `/devlyn-ideate`
 
@@ -66,7 +66,7 @@ Give ideate an intent or a document. It writes a loop package — a meta-prompt
 | `/devlyn-ideate status` | Pending, active, accepted and failed counts; the next runnable task; delivery and recovery blockers. |
 | `/devlyn-ideate drain` | Runs the queue serially and hands-free. |
 
-A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under the Devlyn defaults and your project's CLAUDE.md/AGENTS.md. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so a task's worktree holds only what is committed there. A task would run without installed CLAUDE.md/AGENTS.md that exist only in this checkout, so add stops while they differ from HEAD, and drain waits while they differ from the task's start commit. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command brings the result into your branch, stopping if your files cannot be preserved.
+A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; a CLI other than Claude Code or Codex needs a pin) under the Devlyn defaults and your project's CLAUDE.md/AGENTS.md. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so a task's worktree holds only what is committed there. A task would run without CLAUDE.md/AGENTS.md changes that exist only in this checkout, so add stops while they differ from HEAD, and drain waits while they differ from the task's start commit. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command brings the result into your branch, stopping if your files cannot be preserved.
 
 ### Delivery
 
@@ -86,9 +86,9 @@ for allocation, acceptance, writer cessation and recovery.
 
 ### Executor — `/devlyn-engines`
 
-The orchestrator is the CLI you opened (Claude Code, Codex, omp, Pi or Grok); the contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the loop's file artifacts carry over if you switch. The executor does the implementation work, direct or drained: the engine pinned in machine-local `.devlyn/engines.json`, else the CLI you opened. Pi and Grok have no executor adapter, so a drain from them needs `devlyn-engines executor <claude|codex|omp>`.
+The orchestrator is the CLI you opened (Claude Code, Codex, omp, Pi or Grok); the contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the loop's file artifacts carry over if you switch. The executor does the implementation work, direct or drained: the engine pinned in machine-local `.devlyn/engines.json`, else the CLI you opened. Only Claude and Codex can execute, so a drain from any other CLI needs `devlyn-engines executor <claude|codex>`.
 
-`/devlyn-engines` with no arguments shows the executor and the engines detected on this machine; `executor <name>` pins one and `clear` removes the pin. A pin is a promise: an unavailable pinned engine stops dispatch with `BLOCKED:<engine>-unavailable`, and a name with no executor-eligible `_shared/adapters/<name>.md` stops with `BLOCKED:invalid-engine-config`. Adapters ship with devlyn-cli releases; a reinstall replaces `_shared`.
+`/devlyn-engines` with no arguments shows the executor and the engines detected on this machine; `executor <name>` pins one and `clear` removes the pin. A pin is a promise: an unavailable pinned engine stops dispatch with `BLOCKED:<engine>-unavailable`, and a name with no executor-eligible `_shared/adapters/<name>.adapter.md` stops with `BLOCKED:invalid-engine-config`. Adapters ship with devlyn-cli releases; a reinstall replaces `_shared`.
 
 Unattended children disable owner-desktop and account drivers: every monitored
 Codex child and every `claude` drain executor (including `.exe`/`.cmd`/`.bat`)
@@ -171,11 +171,11 @@ Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4
 
 | Old command | Now use |
 |---|---|
-| `/devlyn:auto-resolve`, `/devlyn:preflight`, `/devlyn:evaluate`, `/devlyn:review`, `/devlyn:team-resolve`, `/devlyn:team-review`, `/devlyn:clean`, `/devlyn:update-docs`, `/devlyn:browser-validate`, `/devlyn:implement-ui` | Folded into resolve, now retired — work directly under the installed principles |
+| `/devlyn:auto-resolve`, `/devlyn:preflight`, `/devlyn:evaluate`, `/devlyn:review`, `/devlyn:team-resolve`, `/devlyn:team-review`, `/devlyn:clean`, `/devlyn:update-docs`, `/devlyn:browser-validate`, `/devlyn:implement-ui` | Folded into resolve, now retired — work directly under the Devlyn defaults |
 | `/devlyn:product-spec`, `/devlyn:feature-spec`, `/devlyn:recommend-features`, `/devlyn:discover-product` | `/devlyn-ideate` |
 | `/devlyn:design-system` | Removed 2026-05-14 — no replacement |
 | `/devlyn:ideate`, `/devlyn:engines`, `devlyn:pencil-pull`, `devlyn:pencil-push`, `devlyn:reap` (3.x and earlier) | `/devlyn-ideate`, `/devlyn-engines`, `devlyn-pencil-pull`, `devlyn-pencil-push`, `devlyn-reap` (4.0.0) |
-| `/devlyn:resolve` (3.x and earlier), `/devlyn-resolve` (4.0.0–4.1.0) | Retired — work directly under the installed principles; `/devlyn-ideate` plans and drains multi-task work |
+| `/devlyn:resolve` (3.x and earlier), `/devlyn-resolve` (4.0.0–4.1.0) | Retired — work directly under the Devlyn defaults; `/devlyn-ideate` plans and drains multi-task work |
 | `/devlyn:queue` (3.x and earlier), `/devlyn-queue` (4.0.0–4.1.0) | `/devlyn-ideate add`, `status` and `drain` |
 | `/devlyn-ideate --quick`, `--from-spec`, `--project` (4.1.0 and earlier) | `/devlyn-ideate plan`; `--autonomous` replaces `--quick` |
 | `/devlyn:team-design-ui`, `/devlyn:design-ui` (3.x and earlier), `/devlyn-design-ui` (4.0.0–4.1.0) | Retired — no replacement |
@@ -257,7 +257,7 @@ Windows completion preserves the workspace, owned refs and recovery receipt when
 
 ## Contributing
 
-- **Add a skill** — add it to `optional-skills/` and `OPTIONAL_ADDONS` in [`bin/devlyn.js`](bin/devlyn.js); the core skills are fixed by `DEVLYN_CORE_SKILLS` (lint Checks 5a and 6)
+- **Add a skill** — add it to `optional-skills/` and `OPTIONAL_ADDONS` in [`bin/devlyn.js`](bin/devlyn.js); the core skills are fixed by `DEVLYN_CORE_SKILLS` (lint Check 5a)
 - **Suggest a pack** — PR to the pack list
 
 ## Supercharge it — pair devlyn with persistent agent memory

package/bin/devlyn.js

@@ -358,7 +358,7 @@ function refreshRenamedSkills(skillsDir, installedSkills) {
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
     if (found.length > 0 && optional.has(newName) && canRefreshRenamed(skillsDir, newName)) {
-      installOptionalSkillInto(skillsDir, newName, installedSkills);
+      installSkillInto(OPTIONAL_SKILLS_SOURCE, skillsDir, newName, installedSkills);
       refreshed.push(newName);
     } else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) {
       refreshPreStandardCopy(skillsDir, newName);
@@ -610,21 +610,22 @@ function installLocalSkill(skillName, roots, installedSkills = new Map()) {
   }
   log(`\n🛠️  Installing ${skillName}...`, 'cyan');
   for (const root of roots) {
-    installOptionalSkillInto(root, skillName, installedSkills);
+    installSkillInto(OPTIONAL_SKILLS_SOURCE, root, skillName, installedSkills);
     writeInstallMarker(root, [skillName], readInstallManifest(root));
   }
   return true;
 }
 
-// One optional skill into one skill-loader directory, replacing any older copy of it. A
-// copy under its name before the 4.0.0 rename goes only once the new one is complete.
-function installOptionalSkillInto(target, skillName, installedSkills) {
+// One skill from `source` into one skill-loader directory. The copy is staged and checked first, so
+// a failed copy leaves any older copy of it in place for a plain rerun. A copy under its name
+// before the 4.0.0 rename goes only once the new one is complete.
+function installSkillInto(source, target, skillName, installedSkills) {
   const dest = path.join(target, skillName);
   const stage = fs.mkdtempSync(path.join(target, '.devlyn-skill-'));
   const stagedSkill = path.join(stage, skillName);
   try {
-    const files = copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), stagedSkill, stage);
-    assertCompleteSkillInstall(OPTIONAL_SKILLS_SOURCE, stage, [skillName]);
+    const files = copyRecursive(path.join(source, skillName), stagedSkill, stage);
+    assertCompleteSkillInstall(source, stage, [skillName]);
     fs.rmSync(dest, { recursive: true, force: true });
     fs.renameSync(stagedSkill, dest);
     installedSkills.set(dest, files.map((file) => path.join(dest, path.relative(stagedSkill, file))));
@@ -692,12 +693,7 @@ function installCoreSkills(skillsDir, installedSkills = new Map()) {
   const previous = readInstallManifest(skillsDir);
   clearInstallMarker(skillsDir);
   for (const skillName of DEVLYN_CORE_SKILLS) {
-    const src = path.join(sourceSkillsDir, skillName);
-    const dest = path.join(skillsDir, skillName);
-    if (!fs.existsSync(src)) continue;
-    // Full replace: copyRecursive is an overlay, so stale files would otherwise persist.
-    fs.rmSync(dest, { recursive: true, force: true });
-    installedSkills.set(dest, copyRecursive(src, dest, skillsDir));
+    if (fs.existsSync(path.join(sourceSkillsDir, skillName))) installSkillInto(sourceSkillsDir, skillsDir, skillName, installedSkills);
   }
   assertCompleteSkillInstall(sourceSkillsDir, skillsDir, DEVLYN_CORE_SKILLS);
   const refreshed = refreshRenamedSkills(skillsDir, installedSkills);
@@ -773,14 +769,14 @@ function installClaudeCore(installedSkills = new Map()) {
     + '.claude/ is unchanged; fix the file and rerun the same install command.');
   const settingsStat = fs.lstatSync(settingsPath, { throwIfNoEntry: false });
   if (settingsStat && !settingsStat.isFile()) throw unmergeable('not a regular file');
-  let settings = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      // Claude Code accepts a leading byte order mark.
-      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, ''));
-    } catch (error) {
-      throw unmergeable(error.message);
-    }
+  let text = '{}\n'; // A missing file starts as an empty object.
+  let settings;
+  try {
+    // Claude Code accepts a leading byte order mark; bytes that are not UTF-8 could not be written back as they are.
+    if (settingsStat) text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(settingsPath));
+    settings = JSON.parse(text.replace(/^\uFEFF/, ''));
+  } catch (error) {
+    throw unmergeable(error.message);
   }
   if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
     throw unmergeable('root must be a JSON object');
@@ -789,31 +785,24 @@ function installClaudeCore(installedSkills = new Map()) {
       && (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env))) {
     throw unmergeable('env must be a JSON object');
   }
+  // The env edit finds the first env while JSON.parse keeps the last, so a repeated env has no single place to edit.
+  if (parseTree(text.replace(/^\uFEFF/, ' ')).children.filter((property) => property.children[0].value === 'env').length > 1) {
+    throw unmergeable('env appears more than once');
+  }
   installCoreSkills(skillsDir, installedSkills);
   updateProjectGitignore('.claude/skills/.devlyn-install.json');
 
   // One-hour foreground Bash calls and one-hour prompt caching serve a drain host that waits in the foreground.
-  let settingsChanged = false;
-  if (!Object.prototype.hasOwnProperty.call(settings, 'env')) {
-    settings.env = {};
-    settingsChanged = true;
-  }
-  if (!Object.prototype.hasOwnProperty.call(settings.env, 'ENABLE_PROMPT_CACHING_1H')) {
-    settings.env.ENABLE_PROMPT_CACHING_1H = 'true';
-    settingsChanged = true;
-  }
-  if (!Object.prototype.hasOwnProperty.call(settings.env, 'BASH_MAX_TIMEOUT_MS')) {
-    settings.env.BASH_MAX_TIMEOUT_MS = '3600000';
-    settingsChanged = true;
-  }
-  settingsChanged = cleanRetiredSettings(settings) || settingsChanged;
-  if (settingsChanged) {
-    replaceFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  const env = settings.env || {};
+  const missing = Object.entries({ ENABLE_PROMPT_CACHING_1H: 'true', BASH_MAX_TIMEOUT_MS: '3600000' })
+    .filter(([key]) => !Object.prototype.hasOwnProperty.call(env, key));
+  if (missing.length) {
+    replaceFile(settingsPath, insertSettingsEnv(text, missing));
     log('  → settings.json', 'dim');
   }
   // Their ownership cannot be established, so the other retired settings stay; name the ones present.
   const retired = [
-    ...RETIRED_ENV.filter((key) => Object.prototype.hasOwnProperty.call(settings.env, key)),
+    ...RETIRED_ENV.filter((key) => Object.prototype.hasOwnProperty.call(env, key)),
     ...RETIRED_PERMISSIONS.filter((rule) => Array.isArray(settings.permissions?.allow) && settings.permissions.allow.includes(rule)),
   ];
   if (retired.length > 0) {
@@ -833,7 +822,40 @@ function replaceFile(file, text) {
   }
 }
 
-function cleanRetiredSettings(settings, hookScripts = []) {
+// Adds the env entries as new text laid out like the members they join, so every existing byte stays: the byte
+// order mark, line endings, indentation, escapes and numbers beyond double precision. jsonc-parser's
+// formattingOptions would lay them out too, but by reformatting the neighbouring lines.
+function insertSettingsEnv(text, entries) {
+  const tree = () => parseTree(text.replace(/^\uFEFF/, ' '));
+  // The whitespace an object puts after its opening brace, before a later member and before its closing brace,
+  // and around its colons.
+  const layout = (object) => {
+    const first = object.children[0], last = object.children.at(-1), [key, value] = last.children;
+    const before = text.slice(0, last.offset);
+    return { open: text.slice(object.offset + 1, first.offset), lead: before.slice(before.trimEnd().length),
+      close: text.slice(last.offset + last.length, object.offset + object.length - 1),
+      colon: text.slice(key.offset + key.length, value.offset) };
+  };
+  const insert = (object, members, { open, lead, close }) => {
+    const last = object.children.at(-1);
+    text = applyEdits(text, [last
+      ? { offset: last.offset + last.length, length: 0, content: members.map((member) => `,${lead}${member}`).join('') }
+      : { offset: object.offset + 1, length: 0, content: open + members.join(`,${lead}`) + (object.length === 2 ? close : '') }]);
+  };
+  const root = tree();
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const outer = root.children.length ? layout(root) : { open: `${eol}  `, lead: `${eol}  `, close: eol, colon: ': ' };
+  // A new or empty env is one level deeper: the root's indentation once more.
+  const unit = outer.lead.includes('\n') ? outer.lead.slice(outer.lead.lastIndexOf('\n') + 1) : '';
+  if (!findNodeAtLocation(root, ['env'])) insert(root, [`"env"${outer.colon}{}`], outer);
+  const env = findNodeAtLocation(tree(), ['env']);
+  const inner = env.children.length ? layout(env)
+    : { open: outer.open + unit, lead: outer.lead + unit, close: outer.close + unit, colon: outer.colon };
+  insert(env, entries.map(([key, value]) => `${JSON.stringify(key)}${inner.colon}${JSON.stringify(value)}`), inner);
+  return text;
+}
+
+function cleanRetiredSettings(settings, hookScripts) {
   let changed = cleanJarvisSettings(settings, hookScripts);
   // Remove exactly the retired Stop hook command, and its entry only when nothing else is left in it.
   const retiredHook = (hook) => hook?.type === 'command' && hook.command === RETIRED_STOP_HOOK;
@@ -930,8 +952,8 @@ function cleanupSettingsText(text, settings, scripts) {
     const end = !previous && next ? next.offset : node.offset + node.length;
     text = applyEdits(text, [{ offset, length: end - offset, content: '' }]);
   }
-  const after = JSON.parse(text.replace(/^\uFEFF/, '')); // Refuse an invalid edit before changing any bytes.
-  return Object.keys(after).length === 0 ? null : text;
+  JSON.parse(text.replace(/^\uFEFF/, '')); // Refuse an invalid edit before changing any bytes.
+  return text;
 }
 
 // Shared user roots need one writer from ownership checks through the last addon write.
@@ -1034,7 +1056,9 @@ function install(targets, global, optionalNames = [], plan, afterInstall = () =>
     for (const name of optionalNames) installLocalSkill(name, roots, installedSkills);
     afterInstall();
     log(`\n✅ devlyn ${PKG.version} installed`, 'green');
-    log('The Devlyn app gives every session the principles; in a terminal, start with: npx devlyn-cli run <claude|codex|omp>');
+    // `devlyn run` does not start on native Windows.
+    log(process.platform === 'win32' ? 'The Devlyn app gives every session the principles.'
+      : 'The Devlyn app gives every session the principles; in a terminal, start with: npx devlyn-cli run <claude|codex|omp>');
     noticeGlobalDrift(roots);
     cleanupScope(global ? os.homedir() : projectDir(), global);
     if (!global) noticeIgnoredInstallFiles(installedSkills);
@@ -1139,15 +1163,14 @@ function cleanupScope(base, global) {
   }
   const settingsFile = path.join(base, '.claude', 'settings.json');
   attempt(settingsFile, () => {
-    if (!realParents(settingsFile) || !fs.lstatSync(settingsFile, { throwIfNoEntry: false })?.isFile()) return;
-    let settings;
-    try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8').replace(/^\uFEFF/, '')); }
-    catch (error) { if (error instanceof SyntaxError) return; throw error; }
-    if (settings && typeof settings === 'object' && cleanRetiredSettings(settings)) {
-      found = true;
-      replaceFile(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-      log('  ✕ .claude/settings.json retired entries (removed)', 'dim');
-    }
+    const { safe, settings, text } = cleanupReadSettings(base);
+    if (!safe || text === undefined) return;
+    const after = cleanupSettingsText(text, settings, []);
+    if (after === text) return;
+    found = true;
+    // Even an emptied file stays: only the reviewed cleanup, which records it first, deletes it.
+    replaceFile(settingsFile, after);
+    log('  ✕ .claude/settings.json retired entries (removed)', 'dim');
   });
   // CLAUDE.md and AGENTS.md stay as they are here: only a reviewed cleanup changes them.
   const instructions = global ? [] : ['GEMINI.md', '.cursorrules', '.windsurfrules', '.github/copilot-instructions.md'];
@@ -1972,17 +1995,18 @@ function cleanupScopes(inputs, current, includedHooks = new Set(), baseViews = n
   return scopes;
 }
 
-function cleanupPlan(inputs) {
+// A checkout-only plan is a count of the checkout as it stands: no fetch, base snapshot or checkout update.
+function cleanupPlan(inputs, checkoutOnly = false) {
   const current = cleanupCurrentFingerprints();
-  const baseViews = new Map();
+  const baseViews = checkoutOnly ? null : new Map();
   try {
     // The review covers the bytes delivery acts on, including scopes sharing a repository.
     const scopes = cleanupScopes(inputs, current, new Set(), baseViews);
-    const plan = { schemaVersion: 1, version: PKG.version, inputs, scopes };
+    const plan = { schemaVersion: 1, version: PKG.version, ...(checkoutOnly && { checkoutOnly }), inputs, scopes };
     return { ...plan, digest: cleanupDigest(plan) };
   } finally {
     const errors = [];
-    for (const view of baseViews.values()) {
+    for (const view of baseViews?.values() || []) {
       if (!view.snapshot) continue;
       try { cleanupRemoveSnapshot(view.root, view.snapshot); } catch (error) { errors.push(error); }
     }
@@ -2032,8 +2056,9 @@ function cleanupApplyItem(item) {
     const { safe, settings, text } = cleanupReadSettings(item.base);
     if (!safe || text === undefined) return cleanupReason('stale-plan');
     const after = cleanupSettingsText(text, settings, item.hookScripts);
-    if (after === null) fs.unlinkSync(item.path);
-    else if (after !== text) replaceFile(item.path, after);
+    if (after === text) return null;
+    if (Object.keys(JSON.parse(after.replace(/^\uFEFF/, ''))).length === 0) fs.unlinkSync(item.path);
+    else replaceFile(item.path, after);
     return null;
   }
   return cleanupReason('unknown-item');
@@ -2428,21 +2453,30 @@ function cleanupCommand(args) {
   const { options, fail } = require('./release');
   const opts = options(args, {
     plan: { type: 'boolean' }, apply: { type: 'boolean' }, machine: { type: 'boolean' }, events: { type: 'boolean' },
+    'checkout-only': { type: 'boolean' },
     project: { type: 'string', multiple: true }, 'account-home': { type: 'string', multiple: true },
     'plan-file': { type: 'string' }, digest: { type: 'string' }, include: { type: 'string', multiple: true },
   });
   if (opts.plan === opts.apply) fail('invalid-arguments', { argument: 'exactly one of --plan or --apply' }, 2);
   if (opts.plan && opts.include) fail('invalid-arguments', { argument: '--include requires --apply' }, 2);
+  if (opts.apply && opts['checkout-only']) fail('invalid-arguments', { argument: '--checkout-only requires --plan' }, 2);
   for (const dir of [...(opts.project || []), ...(opts['account-home'] || [])]) {
     if (!path.isAbsolute(dir)) fail('invalid-arguments', { argument: 'absolute paths required' }, 2);
   }
   // The installer's progress lines would corrupt this command's JSON on stdout.
   console.log = (...parts) => process.stderr.write(`${parts.join(' ')}\n`);
   if (opts.plan) {
-    return cleanupPlan({ machine: Boolean(opts.machine), projects: opts.project || [], accountHomes: opts['account-home'] || [] });
+    // Every process a passive count starts inherits this, so no Git process, the queue inspection's
+    // included, fetches missing objects or takes optional locks. Git before 2.45 ignores
+    // GIT_NO_LAZY_FETCH; every Git refuses all transports under GIT_ALLOW_PROTOCOL=none.
+    if (opts['checkout-only']) Object.assign(process.env, { GIT_NO_LAZY_FETCH: '1', GIT_ALLOW_PROTOCOL: 'none', GIT_OPTIONAL_LOCKS: '0' });
+    return cleanupPlan({ machine: Boolean(opts.machine), projects: opts.project || [], accountHomes: opts['account-home'] || [] },
+      Boolean(opts['checkout-only']));
   }
   if (!opts['plan-file'] || !opts.digest) fail('invalid-arguments', { argument: '--plan-file and --digest' }, 2);
   const plan = JSON.parse(fs.readFileSync(opts['plan-file'], 'utf8'));
+  // A checkout-only plan never reviewed the base that delivery acts on.
+  if (plan?.checkoutOnly !== undefined) fail('checkout-only-plan', {}, 2);
   const inputs = plan?.inputs;
   if (plan?.schemaVersion !== 1 || plan.digest !== opts.digest || cleanupDigest(plan) !== plan.digest
       || typeof inputs?.machine !== 'boolean' || !Array.isArray(inputs.projects) || !Array.isArray(inputs.accountHomes)

package/bin/engines.js

@@ -1,7 +1,8 @@
-// Engine IDs from devlyn-os-v1/packages/contracts/src/engines.ts, in inventory order.
-// CLI binary names (for example agy) are not engine IDs.
+// Engine IDs in the order of devlyn-os-v1/packages/contracts/src/engines.ts. An ID joins only once its
+// channels are confirmed on the real CLI, with that examined version as its floor below; the planner
+// refuses every other ID. CLI binary names (for example agy) are not engine IDs.
 const ENGINE_IDS = Object.freeze([
-  'claude', 'codex', 'grok', 'omp', 'antigravity', 'cursor', 'opencode', 'kimi', 'copilot', 'qwen',
+  'claude', 'codex', 'grok', 'omp', 'antigravity', 'cursor', 'opencode', 'kimi', 'copilot', 'qwen', 'pi',
 ]);
 
 // The versions each channel was examined on. Any newer release, a new major included, is taken as
@@ -20,6 +21,7 @@ const ENGINE_CAPABILITIES = Object.freeze({
   kimi: { minimum: '2.3.0', executor: false },
   copilot: { minimum: '1.0.98', executor: false },
   qwen: { minimum: '0.26.0', executor: false },
+  pi: { minimum: '1.4.0', executor: false },
 });
 
 function readableVersion(engine, version) {