@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.11

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third-Party Notices
+
+`@pugi/cli` bundles default skill content from third parties on `pugi init`.
+Each entry below carries the full upstream MIT license text required for
+redistribution.
+
+## mattpocock/skills
+
+Pugi bundles the following skill bodies (ported, attribution preserved in
+each `SKILL.md` header) from https://github.com/mattpocock/skills:
+
+- `zoom-out` — `skills/engineering/zoom-out/SKILL.md`
+- `diagnose` — `skills/engineering/diagnose/SKILL.md`
+- `grill-me` — `skills/productivity/grill-me/SKILL.md`
+
+Upstream license follows verbatim.
+
+---
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/pugi-mascot.ansi

@@ -1,41 +1,16 @@
-[?25l▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+[?25l                              
+                              
+                              
+        ▄▄▄▄▄▄▄▄▄▄▄▄▄▄        
+       ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄       
+       ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄       
+         ▄▄▄▄▄▄▄▄▄▄▄▄         
+         ▄▄▄▄▄▄▄▄▄▄▄▄         
+          ▄▄▄▄▄▄▄▄▄▄▄         
+            ▄▄▄▄▄▄            
+       ▄▄▄▄   ▄▄              
+       ▄     ▄ ▄▄▄            
+               ▄              
+                              
+                              
 [?25h

package/dist/core/edits/worktree.js

@@ -0,0 +1,322 @@
+/**
+ * Worktree isolation — α7.7 Phase 1.
+ *
+ * Wraps `git worktree add` so a long agent loop (build / consensus
+ * review / multi-file refactor) can land its edits into a scratch
+ * workspace, run the validators against THAT path, and only then promote
+ * the resulting diff back to the operator's main working tree. The
+ * primary win is safety: a half-applied refactor never corrupts the
+ * operator's branch.
+ *
+ * Three operations:
+ *
+ *   - `createWorktree(branch)` — spawns `git worktree add --detach`
+ *     under `.pugi/worktrees/<uuid>` based on the supplied branch (or
+ *     HEAD when omitted). Returns the absolute path + a `cleanup()`
+ *     callback. The dir lives under `.pugi/` so the existing `.gitignore`
+ *     for that subtree applies (no accidental commits of the scratch
+ *     state to the main repo).
+ *
+ *   - `promoteWorktree(worktreePath, cwd)` — diffs the worktree against
+ *     its base commit and applies the diff to the main `cwd` via
+ *     `git apply`. Refuses if the main cwd has staged changes that
+ *     would conflict; the operator must commit or stash first.
+ *
+ *   - `dropWorktree(worktreePath)` — removes the worktree both from
+ *     git's bookkeeping (`git worktree remove --force`) and from disk.
+ *     Idempotent; a partially-removed worktree (`git` already cleaned
+ *     up but dir survived) is handled.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { resolve, sep } from 'node:path';
+import { OperatorAbortedError } from '../../tools/file-tools.js';
+import { applySecurityGate } from './security-gate.js';
+import { extractPatchPaths } from '../../tools/apply-patch.js';
+/**
+ * Create a scratch worktree under `.pugi/worktrees/<uuid>`. The path is
+ * guaranteed unique (uuid) so multiple agent loops can run in parallel
+ * without collision.
+ */
+export function createWorktree(opts) {
+    if (opts.cancellation && opts.cancellation.isAborted) {
+        return { ok: false, reason: 'operator_aborted', detail: 'createWorktree aborted' };
+    }
+    // Confirm we're inside a git repo. `git rev-parse --git-dir` is the
+    // canonical check and avoids a misleading error message later when
+    // `git worktree add` runs in a non-repo.
+    const gitDir = runGit(['rev-parse', '--git-dir'], opts.cwd);
+    if (gitDir.status !== 0) {
+        return {
+            ok: false,
+            reason: 'not_a_git_repo',
+            detail: `not a git repo: ${opts.cwd}`,
+        };
+    }
+    // Resolve base SHA. When the operator named a branch we honor it; the
+    // default is HEAD. We capture the SHA up-front so `promoteWorktree`
+    // can `git diff <baseSha>..HEAD` deterministically even if the main
+    // working tree has moved forward since.
+    const baseRef = opts.branch ?? 'HEAD';
+    const baseShaResult = runGit(['rev-parse', baseRef], opts.cwd);
+    if (baseShaResult.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `cannot resolve base ref ${baseRef}: ${baseShaResult.stderr}`,
+        };
+    }
+    const baseSha = baseShaResult.stdout.trim();
+    const worktreeRoot = resolve(opts.cwd, '.pugi', 'worktrees');
+    mkdirSync(worktreeRoot, { recursive: true });
+    const worktreePath = resolve(worktreeRoot, randomUUID());
+    // `--detach` keeps the worktree on a detached HEAD so we don't
+    // collide with branch checkouts on the main tree. The worktree is
+    // throwaway — there is no branch name to track.
+    const create = runGit(['worktree', 'add', '--detach', worktreePath, baseSha], opts.cwd);
+    if (create.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git worktree add failed: ${create.stderr}`,
+        };
+    }
+    const handle = {
+        path: worktreePath,
+        baseSha,
+        cleanup: () => {
+            const r = dropWorktree(worktreePath, opts.cwd);
+            if (!r.ok && r.reason !== 'worktree_missing') {
+                // Swallow non-fatal cleanup failures so the agent loop doesn't
+                // hard-crash on the happy path. The diagnostic still surfaces
+                // via the JSON output on the `pugi worktree drop` command.
+            }
+        },
+    };
+    return { ok: true, value: handle };
+}
+/**
+ * Diff the worktree against its base and apply the diff to the main cwd.
+ *
+ * Implementation notes:
+ *
+ *   - We run `git diff --binary <baseSha>` inside the worktree (NOT
+ *     `git diff <worktree>..HEAD` from the main tree — the worktree's
+ *     HEAD is detached at `baseSha`, so the meaningful diff is the
+ *     UNCOMMITTED changes the agent wrote into it).
+ *   - `--binary` ensures non-text files (assets, images) survive the
+ *     round-trip; without it `git apply` fails on any binary delta.
+ *   - We always run `git apply --check` first so a refusal does not
+ *     leave the main tree half-modified.
+ */
+export function promoteWorktree(opts) {
+    if (opts.cancellation && opts.cancellation.isAborted) {
+        return { ok: false, reason: 'operator_aborted', detail: 'promoteWorktree aborted' };
+    }
+    if (!existsSync(opts.worktreePath)) {
+        return {
+            ok: false,
+            reason: 'worktree_missing',
+            detail: `worktree path does not exist: ${opts.worktreePath}`,
+        };
+    }
+    // Capture the diff against the base SHA. `git diff <baseSha>`
+    // (no `--cached`) compares the WORKING TREE against the base, which
+    // covers both unstaged AND staged changes in a single invocation —
+    // anything the working tree shows is included. `--binary` ensures
+    // non-text files survive the round-trip.
+    //
+    // Note: untracked files that were NEVER staged stay invisible — git
+    // diff has no native flag to include them. The agent loop must
+    // `git add` any new file it wants promoted; the CLI surface
+    // documents this explicitly so the contract is not surprising.
+    // (Staging is enough to expose the file; the file does not need to
+    // be committed.)
+    const diffResult = runGit(['diff', '--binary', opts.baseSha], opts.worktreePath);
+    if (diffResult.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git diff failed: ${diffResult.stderr}`,
+        };
+    }
+    const diffText = diffResult.stdout;
+    if (diffText.trim().length === 0) {
+        return { ok: true, value: { filesChanged: 0 } };
+    }
+    // SECURITY GATE (R1 fix 2026-05-26, PR #413 r1) — every path mentioned
+    // in the worktree's diff goes through the same `applySecurityGate`
+    // chokepoint as the apply_patch + Layer A/B/C applicators. A staged
+    // `.env` (or `../../etc/passwd`, or a symlink into a protected target)
+    // inside the worktree must NOT slip into the operator's main tree just
+    // because the worktree itself was a sandboxed scratch dir. Without
+    // this gate, `promoteWorktree` was a clean bypass of every other edit
+    // primitive's safety net.
+    const diffPaths = extractPatchPaths(diffText);
+    const failedPaths = [];
+    for (const file of diffPaths) {
+        const gate = applySecurityGate(file, { cwd: opts.cwd, toolName: 'layer-c' });
+        if (!gate.ok) {
+            failedPaths.push(`${file}: ${gate.reason}`);
+        }
+    }
+    if (failedPaths.length > 0) {
+        return {
+            ok: false,
+            reason: 'protected_file_in_worktree',
+            detail: `worktree diff touches protected/escaping paths: ${failedPaths.join('; ')}`,
+            files: failedPaths,
+        };
+    }
+    // `git apply --check` validates the diff against the main tree first.
+    // Refuse early on conflict so the operator can resolve before we
+    // touch any file.
+    const check = runGit(['apply', '--check', '-'], opts.cwd, diffText);
+    if (check.status !== 0) {
+        return {
+            ok: false,
+            reason: 'apply_conflict',
+            detail: `git apply --check rejected: ${check.stderr}`,
+        };
+    }
+    if (opts.dryRun) {
+        return { ok: true, value: { filesChanged: countDiffFiles(diffText) } };
+    }
+    const apply = runGit(['apply', '-'], opts.cwd, diffText);
+    if (apply.status !== 0) {
+        return {
+            ok: false,
+            reason: 'apply_failed',
+            detail: `git apply failed: ${apply.stderr}`,
+        };
+    }
+    return { ok: true, value: { filesChanged: countDiffFiles(diffText) } };
+}
+/**
+ * Drop a worktree both from git's bookkeeping and from disk. Idempotent —
+ * a missing path returns `worktree_missing` which the caller can ignore
+ * on the cleanup-after-error path.
+ *
+ * Security (R1 fix 2026-05-26, PR #413 r1): we MUST validate the path is
+ * a real subdirectory of `<cwd>/.pugi/worktrees/` BEFORE running either
+ * `git worktree remove --force` or `rmSync`. Without this gate, a
+ * typo like `pugi worktree drop ../some-dir` recursively deleted an
+ * arbitrary directory: `git worktree remove` correctly failed (path not
+ * registered), but the `rmSync(worktreePath, recursive: true)` below
+ * still fired regardless.
+ *
+ * We resolve both `cwd` and `worktreePath` through `realpathSync` so a
+ * caller passing a symlink that points outside `.pugi/worktrees/` is
+ * still rejected. When the worktree path does not exist on disk at all
+ * (idempotent re-drop of an already-removed worktree), we fall back to
+ * the lexical containment check — the rejection only matters when there
+ * is a real directory to delete.
+ */
+export function dropWorktree(worktreePath, cwd) {
+    // SECURITY GATE — validate containment under `<cwd>/.pugi/worktrees/`
+    // BEFORE any destructive call. Two-tier check:
+    //   1. lexical containment using resolved (but not realpath'd) paths,
+    //      catches the operator-typo + missing-worktree cases.
+    //   2. realpath containment when the path exists, catches symlink
+    //      shenanigans.
+    const scratchRootLexical = resolve(cwd, '.pugi', 'worktrees');
+    const worktreeLexical = resolve(cwd, worktreePath);
+    const insideLexical = worktreeLexical.startsWith(scratchRootLexical + sep) &&
+        worktreeLexical !== scratchRootLexical;
+    if (!insideLexical) {
+        return {
+            ok: false,
+            reason: 'invalid_worktree_path',
+            detail: `worktree path ${worktreePath} is not under ${scratchRootLexical}`,
+        };
+    }
+    if (existsSync(worktreeLexical)) {
+        try {
+            const realScratchRoot = realpathSync(scratchRootLexical);
+            const realWorktree = realpathSync(worktreeLexical);
+            const insideReal = realWorktree.startsWith(realScratchRoot + sep) &&
+                realWorktree !== realScratchRoot;
+            if (!insideReal) {
+                return {
+                    ok: false,
+                    reason: 'invalid_worktree_path',
+                    detail: `worktree realpath ${realWorktree} escapes ${realScratchRoot}`,
+                };
+            }
+        }
+        catch (error) {
+            // realpath failed for a path that exists — surface as
+            // invalid_worktree_path so we never recurse into rmSync on an
+            // unreadable path.
+            return {
+                ok: false,
+                reason: 'invalid_worktree_path',
+                detail: `cannot realpath worktree path: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // `git worktree remove --force` cleans the metadata in `.git/worktrees`.
+    // If the worktree was created by another process and already pruned,
+    // git returns non-zero — we still try to `rmSync` the dir to leave the
+    // filesystem consistent. Path containment has already been validated
+    // above so the rmSync below is bounded to `.pugi/worktrees/`.
+    const remove = runGit(['worktree', 'remove', '--force', worktreeLexical], cwd);
+    const gitCleanFailed = remove.status !== 0;
+    if (existsSync(worktreeLexical)) {
+        try {
+            rmSync(worktreeLexical, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (gitCleanFailed) {
+                return {
+                    ok: false,
+                    reason: 'git_command_failed',
+                    detail: `git worktree remove failed AND rmSync failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+    }
+    if (gitCleanFailed && !worktreeLexical.includes(`${sep}.pugi${sep}worktrees${sep}`)) {
+        // A worktree that wasn't created by us (path is outside our naming
+        // convention) is suspicious — surface the failure so the operator
+        // can diagnose.
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git worktree remove failed: ${remove.stderr}`,
+        };
+    }
+    return { ok: true, value: undefined };
+}
+function countDiffFiles(diff) {
+    // Count `diff --git a/... b/...` headers. Cheap and unambiguous.
+    let count = 0;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git '))
+            count += 1;
+    }
+    return count;
+}
+function runGit(args, cwd, stdin) {
+    return spawnSync('git', args, {
+        cwd,
+        input: stdin,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+/**
+ * Test-only helper exporting the internal git runner so specs can stub
+ * the spawn surface when running on a CI host without a global git.
+ */
+export const __test__ = { runGit, countDiffFiles };
+/**
+ * Re-export the abort marker so the worktree CLI surface can fold the
+ * exception into a clean exit code without needing to import from the
+ * tools layer.
+ */
+export { OperatorAbortedError };
+//# sourceMappingURL=worktree.js.map

package/dist/core/engine/anvil-client.js

@@ -67,6 +67,22 @@ export class AnvilEngineLoopClient {
                     tools,
                     maxTokens: options.maxTokens,
                     temperature: options.temperature,
+                    // β1 (audit E2): the admin-api `EngineRequestDto` accepts
+                    // these optional fields (see `pugi-engine.controller.ts:230`
+                    // EngineRequestDto schema). Before this fix the CLI dropped
+                    // them, which forced the controller to fall back to legacy
+                    // per-persona resolution + emit `command="(none)"` in its
+                    // structured logs. `undefined` keys are stripped by
+                    // `JSON.stringify` so the payload stays clean for fixture
+                    // clients that exact-match the body shape.
+                    command: options.command,
+                    // β1a r1: `tag` is `EngineDispatchTag` object shape now —
+                    // `JSON.stringify` serialises it as `{tag, priority?,
+                    // budget_hint?}` matching `EngineDispatchTagDto`. Previously
+                    // this was a bare string and the server's `IsIn` validator
+                    // rejected every payload with HTTP 400.
+                    tag: options.tag,
+                    model: options.model,
                 }),
                 signal: controller.signal,
             });

package/dist/core/engine/budgets.js

@@ -0,0 +1,89 @@
+/**
+ * β1 defaults. Source of truth for the per-command budget envelope.
+ * The runtime is allowed to look these up directly (no need to round
+ * trip through settings.json when no override is in play).
+ */
+export const beta1DefaultBudgets = {
+    fix: { maxTokens: 30_000, maxToolCalls: 20 },
+    code: { maxTokens: 30_000, maxToolCalls: 20 },
+    build: { maxTokens: 200_000, maxToolCalls: 30 },
+    plan: { maxTokens: 200_000, maxToolCalls: 8 },
+    explain: { maxTokens: 20_000, maxToolCalls: 5 },
+    review_triple: { maxTokens: 100_000, maxToolCalls: 10 },
+};
+/**
+ * Hard upper bounds. Anything above this is treated as user error
+ * (likely a typo or misplaced decimal) and rejected by
+ * `assertBudgetWithinTier`. Stops a careless settings.json edit from
+ * silently authorising a 100M-token run.
+ */
+export const HARD_MAX_TOKENS = 5_000_000;
+export const HARD_MAX_TOOL_CALLS = 500;
+/**
+ * Compute the effective budget for a given command, applying:
+ *   1. β1 defaults
+ *   2. settings.json `budgets.<command>` partial overrides
+ *   3. task-level override (caller-provided, e.g. CLI `--max-tokens`)
+ *
+ * Throws `BudgetConfigError` when the resolved budget exceeds the
+ * HARD_MAX_* caps so misconfigured settings.json fails fast.
+ */
+export function resolveBudget(command, settings, override) {
+    const base = beta1DefaultBudgets[command];
+    const settingsBudget = readSettingsBudget(settings, command);
+    const resolved = {
+        maxTokens: override?.maxTokens ??
+            settingsBudget?.maxTokens ??
+            base.maxTokens,
+        maxToolCalls: override?.maxToolCalls ??
+            settingsBudget?.maxToolCalls ??
+            base.maxToolCalls,
+    };
+    assertBudgetWithinTier(command, resolved);
+    return resolved;
+}
+export class BudgetConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BudgetConfigError';
+    }
+}
+export function assertBudgetWithinTier(command, budget) {
+    if (!Number.isFinite(budget.maxTokens) || budget.maxTokens <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens must be a positive number, got ${budget.maxTokens}`);
+    }
+    if (!Number.isFinite(budget.maxToolCalls) || budget.maxToolCalls <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls must be a positive number, got ${budget.maxToolCalls}`);
+    }
+    if (budget.maxTokens > HARD_MAX_TOKENS) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens=${budget.maxTokens} exceeds hard cap ${HARD_MAX_TOKENS}`);
+    }
+    if (budget.maxToolCalls > HARD_MAX_TOOL_CALLS) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls=${budget.maxToolCalls} exceeds hard cap ${HARD_MAX_TOOL_CALLS}`);
+    }
+}
+/**
+ * Pull a settings.json budget override for the given command, with
+ * defensive typing. `PugiSettings` does not yet declare `budgets`
+ * formally (β1 is the first sprint to land it) so we cast via unknown
+ * and validate each field at the boundary.
+ */
+function readSettingsBudget(settings, command) {
+    if (!settings)
+        return undefined;
+    const root = settings.budgets;
+    if (!root || typeof root !== 'object' || Array.isArray(root))
+        return undefined;
+    const map = root;
+    const entry = map[command];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return undefined;
+    const e = entry;
+    const out = {};
+    if (typeof e['maxTokens'] === 'number')
+        out.maxTokens = e['maxTokens'];
+    if (typeof e['maxToolCalls'] === 'number')
+        out.maxToolCalls = e['maxToolCalls'];
+    return out;
+}
+//# sourceMappingURL=budgets.js.map