@pugi/cli 0.1.0-beta.49 → 0.1.0-beta.50

package/dist/core/consensus/diff-capture.js

@@ -128,7 +128,18 @@ function captureFromPr(cwd, pr) {
     // Fetch the PR head into a private ref so we have local objects to
     // diff against. `pull/<num>/head` is GitHub's special refspec exposed
     // to anyone with read access on the repo.
-    safeExec(cwd, 'git', ['fetch', 'origin', `pull/${pr}/head:${tempRef}`]);
+    //
+    // The leading `+` (force-update) is REQUIRED: if a prior invocation
+    // died before reaching the `finally` cleanup (SIGKILL, host crash,
+    // operator Ctrl-C inside a `try` block in a wrapping caller, hung
+    // gh CLI), the tempRef survives on disk. Without `+`, the next
+    // `fetch <pr>/head:<tempRef>` aborts with
+    //   `! [rejected] pull/N/head -> refs/pugi/consensus-pr-N (non-fast-forward)`
+    // and the entire consensus run fails for an operator who did nothing
+    // wrong. `+` semantics: replace the ref unconditionally — exactly
+    // the recovery behavior we want for a sandboxed `refs/pugi/...` slot
+    // that no human ever reads.
+    safeExec(cwd, 'git', ['fetch', 'origin', `+pull/${pr}/head:${tempRef}`]);
     try {
         // Resolve the base ref to diff against. Prefer the PR's declared
         // base; fall back to `origin/main`. We compute the merge-base so a
@@ -163,8 +174,10 @@ function captureFromPr(cwd, pr) {
             safeExec(cwd, 'git', ['update-ref', '-d', tempRef]);
         }
         catch {
-            // Swallow: a leftover ref under refs/pugi/ is harmless. The next
-            // run will overwrite it via `fetch ... :ref` anyway.
+            // Swallow: a leftover ref under refs/pugi/ is harmless. The
+            // next run force-overwrites it via `fetch +pull/<n>/head:<ref>`
+            // (note the leading `+` in the refspec above), so a stale tempRef
+            // never blocks a future invocation even if cleanup never runs.
         }
     }
 }
@@ -229,6 +242,29 @@ function captureFromRange(cwd, baseRef, commit) {
     const fullCommit = safeExec(cwd, 'git', ['rev-parse', commit]).trim();
     if (!fullCommit)
         throw new Error(`Unknown commit ref: ${commit}`);
+    // Task #63 (2026-05-27) — refresh the base ref via `git fetch` BEFORE
+    // resolving. Previously a stale local `main` (last fetched days ago)
+    // would silently produce a diff containing every commit that landed
+    // upstream after the fetch, swamping the model's review с unrelated
+    // changes. The fetch is opportunistic: failures (offline, auth) are
+    // swallowed so the existing rev-parse path stays the safety net и
+    // returns the clear "Unknown base ref" error if the stale local copy
+    // is also missing.
+    //
+    // We fetch ONLY the base ref (not all refs) so the overhead is
+    // bounded — typical PR-style review payload, base = main, one ref.
+    // `--no-tags --quiet` keeps the network footprint minimal.
+    const remoteCandidate = baseRef.includes('/') ? baseRef : `origin/${baseRef}`;
+    if (remoteCandidate.startsWith('origin/')) {
+        const bareRef = remoteCandidate.slice('origin/'.length);
+        safeExecOptional(cwd, 'git', [
+            'fetch',
+            '--no-tags',
+            '--quiet',
+            'origin',
+            bareRef,
+        ]);
+    }
     // Resolve the base: accept already-qualified refs (`origin/main`,
     // `refs/heads/foo`) and bare branch names. If the bare name isn't
     // locally resolvable, retry against `origin/<name>` — the common

package/dist/core/engine/budgets.js

@@ -17,7 +17,7 @@ export const beta1DefaultBudgets = {
     code: { maxTokens: 80_000, maxToolCalls: 20 },
     build: { maxTokens: 200_000, maxToolCalls: 30 },
     plan: { maxTokens: 200_000, maxToolCalls: 8 },
-    explain: { maxTokens: 40_000, maxToolCalls: 5 },
+    explain: { maxTokens: 40_000, maxToolCalls: 10 },
     review_triple: { maxTokens: 100_000, maxToolCalls: 10 },
 };
 /**

package/dist/core/path-security.js

@@ -1,5 +1,41 @@
-import { realpathSync } from 'node:fs';
-import { basename, relative, resolve } from 'node:path';
+/**
+ * Path-security gate for Pugi CLI file operations.
+ *
+ * The original `resolveWorkspacePath` (preserved below) is the read-path
+ * gate: it stops relative-path traversal, URL-encoded traversal, and
+ * symlink escapes at the leaf. It is kept as the existing call surface
+ * for `read` and other non-mutating tools.
+ *
+ * `assertSafeWritePath` is a stricter, write-only gate ported from
+ * KeiSeiLab/KeiSeiKit's Rust `path_guard.rs` (Apache-2.0). It adds:
+ *
+ *   1. `..` segment rejection BEFORE any filesystem touch.
+ *   2. Walk-up canonicalize: finds the deepest existing ancestor,
+ *      canonicalizes it (resolving every symlink in the existing
+ *      prefix), then reattaches the non-existent tail. This closes
+ *      the "parent's parent is a symlink" bypass that catches naive
+ *      canonicalize-the-parent implementations.
+ *   3. Leaf-symlink reject: refuse to write through a symlink even
+ *      when the file already exists. Covers dangling symlinks too.
+ *   4. Fail-CLOSED on empty allowed roots: an empty PUGI_ALLOWED_ROOTS
+ *      means "no writes anywhere" rather than "writes allowed
+ *      everywhere".
+ *   5. Containment check against canonicalized allowed roots.
+ *   6. Denylist of system, credential, and shell-init paths even
+ *      when they sit inside an allowed root (defense in depth — a
+ *      misconfigured root pointing at `$HOME` still cannot clobber
+ *      `~/.ssh/id_ed25519`).
+ *
+ * ---
+ * Portions of `assertSafeWritePath` and `canonicalizeWithWalkUp` are
+ * derived from KeiSeiLab/KeiSeiKit `kei-mcp/src/handlers/safe_tools/
+ * path_guard.rs` (Apache-2.0). See `licenses/keiseikit-LICENSE-NOTICE.md`
+ * at the repo root for attribution and the full upstream license
+ * reference.
+ */
+import { existsSync, lstatSync, realpathSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, relative, resolve, sep, } from 'node:path';
 /**
  * Resolve and validate that an inputPath stays within the workspace.
  *
@@ -60,4 +96,250 @@ function isInsideWorkspace(child, workspaceRoot) {
     const rel = relative(workspaceRoot, child);
     return Boolean(rel) && !rel.startsWith('..') && rel !== '..';
 }
+/**
+ * Apply the full KeiSei write-path guard. Returns the canonical
+ * absolute path on success, throws on rejection.
+ *
+ * Use this for any operation that mutates the filesystem (`write`,
+ * `edit`, atomic-rename targets). The error message is safe to surface
+ * to the operator — it never echoes filesystem secrets.
+ */
+export function assertSafeWritePath(inputPath, options = {}) {
+    if (typeof inputPath !== 'string' || inputPath.length === 0) {
+        throw new Error('file_path: empty');
+    }
+    if (inputPath.includes('\0')) {
+        throw new Error('file_path: null byte rejected');
+    }
+    // KeiSei step #1: reject `..` segments before any FS work. We split on
+    // both `/` and the platform separator so a Windows-style `..\foo`
+    // input cannot smuggle a traversal through on macOS test paths.
+    const decoded = decodeURIComponent(inputPath);
+    const segments = decoded.split(/[/\\]/);
+    if (segments.some((seg) => seg === '..')) {
+        throw new Error(`file_path: '..' segment not allowed in ${inputPath}`);
+    }
+    // KeiSei step #3: refuse to write through a symlink leaf. We must
+    // check the LITERAL input path (pre-canonicalize) because `realpath`
+    // unconditionally resolves symlinks — so by the time we have the
+    // canonical path the symlink fingerprint is already gone. `lstatSync`
+    // does NOT follow symlinks, which is exactly what we need.
+    const cwdRoot = options.root ?? process.cwd();
+    const literalAbsolute = isAbsolute(decoded) ? decoded : resolve(cwdRoot, decoded);
+    try {
+        const meta = lstatSync(literalAbsolute);
+        if (meta.isSymbolicLink()) {
+            throw new Error(`file_path: leaf is a symlink (refusing to follow): ${literalAbsolute}`);
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR')
+            throw error;
+        // ENOENT/ENOTDIR is fine — the leaf simply does not exist yet
+        // (write-create path). The walk-up canonicalize below handles it.
+    }
+    const canonical = canonicalizeWithWalkUp(decoded, cwdRoot);
+    // KeiSei step #4: fail-CLOSED on empty allowed roots.
+    const roots = computeAllowedRoots(options);
+    if (roots.length === 0) {
+        throw new Error("file_path: allowed_roots is empty — refusing all writes " +
+            '(set PUGI_ALLOWED_ROOTS to a non-empty value or run from a real cwd)');
+    }
+    // KeiSei step #5: containment check against canonicalized allowed
+    // roots. Each root is normalized to end in `sep` so `/tmp/wsX` does
+    // not accidentally pass containment for `/tmp/ws`.
+    const inAllowedRoot = roots.some((r) => isContainedIn(canonical, r));
+    if (!inAllowedRoot) {
+        throw new Error(`file_path: outside allowed roots ${JSON.stringify(roots)}: ${canonical}`);
+    }
+    // KeiSei step #6: denylist. Applied AFTER containment so a
+    // misconfigured root pointing at `/` or `$HOME` still cannot clobber
+    // sensitive files. We canonicalize HOME so a $HOME that lives under
+    // a symlinked prefix (macOS /var → /private/var, Linux /home →
+    // /usr/home on some FreeBSD-style mounts) still matches the
+    // canonical write target.
+    assertNotDenylisted(canonical, canonicalizeHomeDir(options.homeDir ?? homedir()));
+    return canonical;
+}
+function canonicalizeHomeDir(raw) {
+    if (!raw)
+        return raw;
+    try {
+        return realpathSync.native(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Ported from KeiSeiKit `canonicalize_with_walk_up`. Finds the deepest
+ * existing ancestor, canonicalizes it (resolving every symlink in the
+ * existing prefix), then reattaches the non-existent tail components.
+ *
+ * This closes the "parent's parent is a symlink" bypass where naive
+ * implementations canonicalize only the immediate parent.
+ */
+export function canonicalizeWithWalkUp(inputPath, cwd) {
+    const absolute = isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath);
+    let current = absolute;
+    const tail = [];
+    // Hard cap on walk-up iterations — defense against pathological
+    // inputs that somehow evade `dirname` termination.
+    const maxIterations = 4096;
+    let iterations = 0;
+    while (true) {
+        iterations += 1;
+        if (iterations > maxIterations) {
+            throw new Error(`file_path: walk-up exceeded ${maxIterations} iterations: ${absolute}`);
+        }
+        if (existsSync(current)) {
+            let canonicalExisting;
+            try {
+                canonicalExisting = realpathSync.native(current);
+            }
+            catch (error) {
+                throw new Error(`file_path: canonicalize ${current}: ${error.message}`);
+            }
+            // Reattach tail in original order (we pushed leaf-first).
+            let result = canonicalExisting;
+            for (let i = tail.length - 1; i >= 0; i -= 1) {
+                result = resolve(result, tail[i]);
+            }
+            return result;
+        }
+        const name = basename(current);
+        const parent = dirname(current);
+        if (!name || parent === current) {
+            throw new Error(`file_path: walked to root without finding existing dir: ${absolute}`);
+        }
+        tail.push(name);
+        current = parent;
+    }
+}
+function computeAllowedRoots(options) {
+    const envValue = options.allowedRootsEnv ?? process.env.PUGI_ALLOWED_ROOTS;
+    if (envValue !== undefined) {
+        return envValue
+            .split(':')
+            .filter((s) => s.length > 0)
+            .map(canonicalizeRoot)
+            .filter((s) => s !== null);
+    }
+    // No env override: implicit root is the caller-supplied cwd (defaults
+    // to `process.cwd()`).
+    const cwd = options.root ?? process.cwd();
+    const canon = canonicalizeRoot(cwd);
+    return canon ? [canon] : [];
+}
+function canonicalizeRoot(raw) {
+    if (!raw)
+        return null;
+    let canon;
+    try {
+        canon = realpathSync.native(raw);
+    }
+    catch {
+        canon = resolve(raw);
+    }
+    if (!canon)
+        return null;
+    return canon.endsWith(sep) ? canon : canon + sep;
+}
+function isContainedIn(canonicalChild, rootWithSep) {
+    const rootNoSep = rootWithSep.endsWith(sep)
+        ? rootWithSep.slice(0, -1)
+        : rootWithSep;
+    if (canonicalChild === rootNoSep)
+        return true;
+    return canonicalChild.startsWith(rootWithSep);
+}
+function assertNotDenylisted(canonical, homeDir) {
+    // System paths — match as prefix-with-separator so `/etc-fake/` is
+    // not denied while `/etc/passwd` is.
+    const systemDenyPrefixes = [
+        '/etc/',
+        '/usr/',
+        '/System/',
+        '/Library/Application Support/',
+        '/var/db/',
+        '/var/log/',
+        '/var/root/',
+        '/private/etc/',
+        '/private/usr/',
+        '/private/var/db/',
+        '/private/var/log/',
+        '/private/var/root/',
+        '/root/',
+        '/bin/',
+        '/sbin/',
+    ];
+    for (const prefix of systemDenyPrefixes) {
+        if (canonical.startsWith(prefix)) {
+            throw new Error(`file_path: denied (system dir): ${canonical}`);
+        }
+    }
+    if (!homeDir)
+        return;
+    // Credential and substrate directories.
+    const homeDirSecrets = [
+        '.ssh/',
+        '.aws/',
+        '.gnupg/',
+        '.config/gcloud/',
+        '.kube/',
+        '.docker/',
+        '.claude/',
+        '.grok/',
+        '.gemini/',
+        '.copilot/',
+        '.kimi/',
+        '.pugi/credentials/',
+    ];
+    for (const secret of homeDirSecrets) {
+        const full = joinHome(homeDir, secret);
+        if (canonical.startsWith(full)) {
+            throw new Error(`file_path: denied (secret/substrate dir): ${canonical}`);
+        }
+    }
+    // Credential files (exact match).
+    const homeFileSecrets = [
+        '.npmrc',
+        '.cargo/credentials',
+        '.cargo/credentials.toml',
+        '.docker/config.json',
+        '.netrc',
+        '.pgpass',
+    ];
+    for (const secret of homeFileSecrets) {
+        const full = joinHome(homeDir, secret);
+        if (canonical === full) {
+            throw new Error(`file_path: denied (credential file): ${canonical}`);
+        }
+    }
+    // Shell-init files (exact match).
+    const initFiles = [
+        '.zshrc',
+        '.bashrc',
+        '.profile',
+        '.bash_profile',
+        '.zprofile',
+        '.zshenv',
+        '.bash_login',
+        '.bash_logout',
+        '.inputrc',
+        '.gitconfig',
+        '.config/fish/config.fish',
+    ];
+    for (const file of initFiles) {
+        const full = joinHome(homeDir, file);
+        if (canonical === full) {
+            throw new Error(`file_path: denied (shell-init file): ${canonical}`);
+        }
+    }
+}
+function joinHome(homeDir, rest) {
+    const trimmedHome = homeDir.endsWith(sep) ? homeDir.slice(0, -1) : homeDir;
+    return `${trimmedHome}${sep}${rest}`;
+}
 //# sourceMappingURL=path-security.js.map

package/dist/core/worktree-manager/cleanup.js

@@ -0,0 +1,123 @@
+/**
+ * Stale-worktree sweep — leak L23 (Pugi α7).
+ *
+ * Pairs with `WorktreeManager` to find worktrees whose agent has either:
+ *
+ *   1. No corresponding progress JSON under `.pugi/agent-progress/` (the
+ *      writer never wrote one, OR the file was archived away), OR
+ *   2. A progress JSON whose `status` is `completed` or `failed` (the
+ *      agent finished — the worktree is no longer load-bearing).
+ *
+ * Crashed agents (status `running` with a stale lastUpdate) are NOT
+ * swept; the leak-research contract says we LEAVE worktrees of crashed
+ * agents in place for forensics. The operator can `pugi worktrees
+ * cleanup <id>` manually after the post-mortem.
+ *
+ * Implementation notes:
+ *
+ *   - The cleanup is read-then-write: list the manager state, classify
+ *     each entry, then call `manager.cleanup()` per stale id. Errors per
+ *     entry never abort the loop — they accumulate in the report.
+ *   - The progress directory we look at is the SAME `.pugi/agent-progress/`
+ *     root the writer uses (resolved via the writer's env-aware helper).
+ *   - `runStaleCleanup` is the only public entry point. The internal
+ *     classifier is exported as `classifyStale` for spec coverage.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveProgressDir } from '../agent-progress/writer.js';
+import { validateAgentProgress } from '../agent-progress/schema.js';
+import { WorktreeManager, } from './manager.js';
+/**
+ * Classify a single worktree listing against the on-disk progress JSON.
+ * Pure-ish — only reads from the progress file when one exists. Exposed
+ * for the spec; production callers go through `runStaleCleanup`.
+ */
+export function classifyStale(listing, progressDir, options = {}) {
+    const grace = options.crashedGraceMs ?? 30 * 60 * 1000;
+    const now = options.now ?? Date.now;
+    const progressPath = join(progressDir, `${listing.agentId}.json`);
+    if (!existsSync(progressPath)) {
+        return 'orphan_no_progress';
+    }
+    let raw;
+    try {
+        raw = readFileSync(progressPath, 'utf8');
+    }
+    catch {
+        // Unreadable progress file — treat as orphan so the operator can
+        // see it in the cleanup report. We never act on it silently.
+        return 'orphan_no_progress';
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return 'orphan_no_progress';
+    }
+    const validation = validateAgentProgress(parsed);
+    if (!validation.ok)
+        return 'orphan_no_progress';
+    const progress = validation.value;
+    if (progress.status === 'completed')
+        return 'stale_completed';
+    if (progress.status === 'failed')
+        return 'stale_failed';
+    // status === 'running' — check for crashed (stale lastUpdate)
+    const lastTs = Date.parse(progress.lastUpdate);
+    if (Number.isFinite(lastTs) && now() - lastTs > grace) {
+        return 'crashed_running';
+    }
+    return 'active';
+}
+/**
+ * Run a single stale-worktree sweep. Removes only `stale_completed`,
+ * `stale_failed`, and `orphan_no_progress` entries. Crashed-running
+ * entries are LEFT IN PLACE per the L23 forensics contract, but they
+ * appear in the report so the operator can act on them manually.
+ */
+export function runStaleCleanup(managerOpts, options = {}) {
+    const manager = new WorktreeManager(managerOpts);
+    const report = {
+        scanned: 0,
+        classified: [],
+        removed: [],
+        preserved: [],
+        errors: [],
+    };
+    const listResult = manager.list();
+    if (!listResult.ok) {
+        report.errors.push({ agentId: '', detail: `list failed: ${listResult.detail}` });
+        return report;
+    }
+    const progressDir = options.progressDir ?? resolveProgressDir();
+    const listings = listResult.value;
+    report.scanned = listings.length;
+    for (const entry of listings) {
+        const cls = classifyStale(entry, progressDir, options);
+        report.classified.push({ agentId: entry.agentId, path: entry.path, class: cls });
+        if (cls === 'active' || cls === 'crashed_running') {
+            report.preserved.push({ agentId: entry.agentId, reason: cls });
+            continue;
+        }
+        if (options.dryRun) {
+            // Dry-run reports the classification only — no cleanup, no remove.
+            continue;
+        }
+        const cleanup = manager.cleanup(entry.agentId);
+        if (cleanup.ok) {
+            report.removed.push(entry.path);
+        }
+        else {
+            report.errors.push({
+                agentId: entry.agentId,
+                detail: `${cleanup.reason}: ${cleanup.detail}`,
+            });
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/core/worktree-manager/manager.js

@@ -0,0 +1,303 @@
+/**
+ * WorktreeManager — leak L23 (Pugi α7).
+ *
+ * Claude Code spawns a separate git worktree per dispatched sub-agent so
+ * parallel agents never collide on the filesystem. This module is Pugi's
+ * parity surface: it binds a worktree to an `agentId` (the same kebab-case
+ * id the agent-progress JSON uses) and exposes a tiny CRUD-shaped API
+ * the dispatcher can call before/after spawning a sub-persona.
+ *
+ * Differences from the existing `core/edits/worktree.ts` primitive:
+ *
+ *   - The edits primitive keys worktrees by UUID and serves the manual
+ *     `pugi worktree create/promote/drop` operator surface (one-shot
+ *     scratch trees that get promoted back to the operator's tree).
+ *   - This manager keys worktrees by AGENT ID so the dispatcher (and any
+ *     observer like `pugi worktrees list`) can correlate a worktree
+ *     with the in-flight agent driving it.
+ *
+ * The two namespaces coexist safely because the directory shapes differ:
+ *
+ *   - manager:  `<cwd>/.pugi/worktrees/<agent-id>/`        (kebab-case)
+ *   - primitive `<cwd>/.pugi/worktrees/<uuid>/`            (dashed hex)
+ *
+ * The manager refuses to operate on a path whose basename does not match
+ * the agent-id regex `[a-zA-Z0-9_-]+` and does NOT collide with the UUID
+ * shape (`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`).
+ *
+ * Concurrency:
+ *
+ *   - `create(agentId)` is mutex'd per agent-id in process so two
+ *     concurrent dispatch hooks racing on the same id resolve to the
+ *     same handle (the second call awaits the first).
+ *   - At the filesystem level the worktree dir's existence is the lock:
+ *     if a stale dir for an agent-id survives from a previous process
+ *     `create` returns `already_exists` so the caller can decide to
+ *     reuse-or-cleanup explicitly (avoids `git worktree add` racing on
+ *     the same path which surfaces a noisy git error).
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/**
+ * Filename-safe + dispatcher-safe agent id.
+ *
+ * Mirrors the regex on `AgentProgress.agentId` so an id that can write a
+ * progress file is exactly the id this manager will accept. The UUID
+ * exclusion below makes sure a caller never accidentally collides with
+ * the existing UUID-based scratch worktrees managed by
+ * `core/edits/worktree.ts`.
+ */
+const AGENT_ID_RE = /^[a-zA-Z0-9_-]+$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Validate an agent id. Exported for spec coverage + caller pre-checks. */
+export function isValidAgentId(id) {
+    if (typeof id !== 'string' || id.length === 0 || id.length > 128)
+        return false;
+    if (!AGENT_ID_RE.test(id))
+        return false;
+    if (UUID_RE.test(id))
+        return false;
+    // Disallow `.` / `..` and the archive subdir name reserved by
+    // agent-progress cleanup so list/scan never crosses paths.
+    if (id === '.' || id === '..' || id === 'archive')
+        return false;
+    return true;
+}
+/**
+ * Build the absolute path for an agent's worktree without touching the
+ * filesystem. Exposed so the dispatcher can compute a `cwd` for the
+ * spawned child without invoking the manager (useful in dry-run paths).
+ */
+export function worktreePathFor(cwd, agentId) {
+    return resolve(cwd, '.pugi', 'worktrees', agentId);
+}
+/** Shape an agent-id + slug into the canonical branch name. */
+export function branchNameFor(agentId, slug) {
+    const clean = (slug ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 24);
+    return clean.length > 0 ? `agent/${agentId}-${clean}` : `agent/${agentId}`;
+}
+/**
+ * Class wrapping git worktree operations for a single workspace root.
+ * Stateless across instances except for the per-agent-id mutex map.
+ */
+export class WorktreeManager {
+    cwd;
+    spawnGit;
+    inFlight = new Map();
+    constructor(options) {
+        this.cwd = options.cwd;
+        this.spawnGit = options.spawnGit ?? defaultSpawnGit;
+    }
+    /**
+     * Create a worktree bound to `agentId`. Idempotent under concurrent
+     * callers: the second concurrent `create(<same id>)` awaits the first.
+     * A subsequent `create()` after a process restart on an EXISTING dir
+     * returns `already_exists` so the caller can choose to cleanup-then-
+     * recreate explicitly.
+     */
+    async create(agentId, options = {}) {
+        if (!isValidAgentId(agentId)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `agent id ${String(agentId)} does not match ${AGENT_ID_RE} or collides with UUID shape` };
+        }
+        const pending = this.inFlight.get(agentId);
+        if (pending)
+            return pending;
+        const promise = this.createUnlocked(agentId, options);
+        this.inFlight.set(agentId, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.inFlight.delete(agentId);
+        }
+    }
+    async createUnlocked(agentId, options) {
+        const gitDir = this.spawnGit(['rev-parse', '--git-dir'], this.cwd);
+        if (gitDir.status !== 0) {
+            return { ok: false, reason: 'not_a_git_repo', detail: `not a git repo: ${this.cwd}` };
+        }
+        const target = worktreePathFor(this.cwd, agentId);
+        if (existsSync(target)) {
+            return {
+                ok: false,
+                reason: 'already_exists',
+                detail: `worktree already exists at ${target}; call cleanup(${agentId}) first if reuse intended`,
+            };
+        }
+        const baseRef = options.baseRef ?? 'HEAD';
+        const baseShaResult = this.spawnGit(['rev-parse', baseRef], this.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 branch = branchNameFor(agentId, options.slug);
+        // Ensure the parent exists before git creates the leaf. git worktree
+        // add will create the leaf itself; pre-creating .pugi/worktrees/ keeps
+        // the failure mode local to git (we never have to mkdir the leaf).
+        const worktreesRoot = resolve(this.cwd, '.pugi', 'worktrees');
+        mkdirSync(worktreesRoot, { recursive: true });
+        // `-b <branch> <path> <base>` creates a NEW branch off `base`,
+        // checked out at `path`. We deliberately do NOT use `--detach` here
+        // (unlike the scratch primitive) so the branch survives across
+        // process restarts and the operator can `git push agent/<id>-<slug>`
+        // if they want to inspect the child's work outside the worktree.
+        const create = this.spawnGit(['worktree', 'add', '-b', branch, target, baseSha], this.cwd);
+        if (create.status !== 0) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `git worktree add failed: ${create.stderr || create.stdout}`,
+            };
+        }
+        return {
+            ok: true,
+            value: { agentId, path: target, branch, baseSha },
+        };
+    }
+    /**
+     * Remove the worktree bound to `agentId`. Idempotent: a missing path
+     * surfaces `worktree_missing` rather than throwing, so a double-call
+     * during dispatch teardown never crashes the parent.
+     */
+    cleanup(agentId) {
+        if (!isValidAgentId(agentId)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `agent id ${String(agentId)} is invalid` };
+        }
+        const target = worktreePathFor(this.cwd, agentId);
+        // Guard: never let cleanup touch a path that escapes the worktrees
+        // root (defensive — the worktreePathFor builder is already bounded
+        // because the agent id regex rejects '..', but containment check
+        // is cheap and gives us a second line of defense).
+        const root = resolve(this.cwd, '.pugi', 'worktrees');
+        if (!target.startsWith(root + sep)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `resolved path ${target} escapes ${root}` };
+        }
+        if (!existsSync(target)) {
+            // Best-effort prune so a metadata-only orphan goes away too.
+            this.spawnGit(['worktree', 'prune'], this.cwd);
+            return { ok: false, reason: 'worktree_missing', detail: `no worktree at ${target}` };
+        }
+        const remove = this.spawnGit(['worktree', 'remove', '--force', target], this.cwd);
+        if (remove.status !== 0) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `git worktree remove failed: ${remove.stderr || remove.stdout}`,
+            };
+        }
+        return { ok: true, value: { removed: target } };
+    }
+    /**
+     * Enumerate worktrees the manager knows about. Read-only and never
+     * touches git metadata; the optional `gitTracked` flag on each entry
+     * surfaces the cross-check against `git worktree list --porcelain`.
+     */
+    list() {
+        const root = resolve(this.cwd, '.pugi', 'worktrees');
+        if (!existsSync(root)) {
+            return { ok: true, value: [] };
+        }
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `readdir ${root} failed: ${err.message}`,
+            };
+        }
+        const tracked = this.collectGitTrackedWorktrees();
+        const out = [];
+        for (const name of entries) {
+            if (!isValidAgentId(name))
+                continue;
+            const path = resolve(root, name);
+            let isDir = false;
+            try {
+                isDir = statSync(path).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir)
+                continue;
+            const meta = tracked.get(path);
+            const branch = meta?.branch ?? branchNameFor(name);
+            const baseSha = meta?.head ?? '';
+            out.push({
+                agentId: name,
+                path,
+                branch,
+                baseSha,
+                gitTracked: meta !== undefined,
+            });
+        }
+        return { ok: true, value: out };
+    }
+    /**
+     * Parse `git worktree list --porcelain` into a `path → {branch, head}`
+     * map. Errors degrade to an empty map — `list()` still surfaces the
+     * directory entries; the caller sees `gitTracked: false` rows and can
+     * decide.
+     */
+    collectGitTrackedWorktrees() {
+        const out = new Map();
+        const list = this.spawnGit(['worktree', 'list', '--porcelain'], this.cwd);
+        if (list.status !== 0)
+            return out;
+        let currentPath = null;
+        let currentHead = '';
+        let currentBranch = '';
+        const commit = () => {
+            if (currentPath) {
+                out.set(currentPath, { branch: currentBranch, head: currentHead });
+            }
+            currentPath = null;
+            currentHead = '';
+            currentBranch = '';
+        };
+        for (const raw of list.stdout.split('\n')) {
+            const line = raw.trimEnd();
+            if (line.length === 0) {
+                commit();
+                continue;
+            }
+            if (line.startsWith('worktree ')) {
+                // New record — flush the previous one if any.
+                commit();
+                currentPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('HEAD ')) {
+                currentHead = line.slice('HEAD '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                // `branch refs/heads/agent/foo` → `agent/foo`
+                const ref = line.slice('branch '.length);
+                currentBranch = ref.replace(/^refs\/heads\//, '');
+            }
+        }
+        commit();
+        return out;
+    }
+}
+function defaultSpawnGit(args, cwd) {
+    return spawnSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    });
+}
+//# sourceMappingURL=manager.js.map

package/dist/runtime/cli.js

@@ -62,6 +62,7 @@ import { runAgentsCommand } from './commands/agents.js';
 import { runLspCommand } from './commands/lsp.js';
 import { runPatchCommand } from './commands/patch.js';
 import { runWorktreeCommand } from './commands/worktree.js';
+import { runWorktreesCommand } from './commands/worktrees.js';
 import { resolveWorkspaceLabel } from '../core/repl/workspace-context.js';
 import { runReviewConsensus } from './commands/review-consensus.js';
 import { runMcpCommand } from './commands/mcp.js';
@@ -213,6 +214,10 @@ const handlers = {
     web: dispatchWeb,
     whoami,
     worktree: dispatchWorktree,
+    // L23 (2026-05-27): `pugi worktrees <op>` (plural) — agent-bound
+    // worktree manager: `list`, `cleanup <agent-id>`, `cleanup --all-stale`.
+    // Distinct from the singular `pugi worktree` (UUID-keyed scratch).
+    worktrees: dispatchWorktrees,
 };
 /**
  * α6.3 `pugi ask "<question>"` — surface the office-hours forcing-question
@@ -1075,6 +1080,24 @@ async function dispatchWorktree(args, flags, _session) {
     if (result.exitCode !== 0)
         process.exitCode = result.exitCode;
 }
+/**
+ * L23 (2026-05-27): `pugi worktrees <op>` — agent-bound worktree
+ * manager surface. Distinct from singular `pugi worktree` which
+ * manages UUID-keyed scratch worktrees for the manual create/promote/
+ * drop flow. The plural surface keys worktrees by agent id (the same
+ * id `.pugi/agent-progress/<id>.json` uses) so an operator can
+ * correlate a worktree with the in-flight agent driving it.
+ */
+async function dispatchWorktrees(args, flags, _session) {
+    const result = await runWorktreesCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        dryRun: flags.dryRun,
+    });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
 export async function runCli(argv) {
     const { command, args, flags, isBareInvocation } = parseArgs(argv);
     // Leak L22 — print the one-line bare banner once per invocation when
@@ -1708,7 +1731,7 @@ const COMMAND_HELP_BODIES = {
     explain: [
         'pugi explain "<question>" — read-only Q&A about the workspace.',
         '',
-        'Calls the engine loop in explain mode (budget: 5 calls / 20k tokens).',
+        'Calls the engine loop in explain mode (budget: 10 calls / 40k tokens).',
         'No file writes; safe to run against unfamiliar code.',
         '',
         'Examples:',

package/dist/runtime/commands/worktrees.js

@@ -0,0 +1,155 @@
+/**
+ * `pugi worktrees <op>` — leak L23 (Pugi α7).
+ *
+ * Plural surface for the agent-bound worktree manager. Distinct from the
+ * singular `pugi worktree <op>` (α7.7 Phase 1) which manages UUID-keyed
+ * scratch worktrees for the manual `create / promote / drop` flow.
+ *
+ *   pugi worktrees list                  # show active agent worktrees
+ *   pugi worktrees cleanup <agent-id>    # remove one
+ *   pugi worktrees cleanup --all-stale   # sweep orphans + completed/failed
+ *   pugi worktrees cleanup --all-stale --dry-run
+ *
+ * Output: human-readable by default, NDJSON envelope under --json.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { runStaleCleanup } from '../../core/worktree-manager/cleanup.js';
+import { WorktreeManager } from '../../core/worktree-manager/manager.js';
+export async function runWorktreesCommand(args, opts) {
+    const [op, ...rest] = args;
+    if (!op)
+        return usage();
+    if (op === 'list') {
+        return runList(opts);
+    }
+    if (op === 'cleanup') {
+        return runCleanup(rest, opts);
+    }
+    return {
+        ok: false,
+        text: `unknown worktrees operation: ${op}. Supported: list, cleanup`,
+        exitCode: 2,
+    };
+}
+function runList(opts) {
+    const manager = new WorktreeManager({ cwd: opts.cwd });
+    const result = manager.list();
+    if (!result.ok) {
+        return {
+            ok: false,
+            text: opts.json
+                ? JSON.stringify(result, null, 2)
+                : `worktrees list failed: ${result.reason}: ${result.detail}`,
+            exitCode: 1,
+        };
+    }
+    const rows = result.value;
+    if (opts.json) {
+        return {
+            ok: true,
+            text: JSON.stringify({ worktrees: rows }, null, 2),
+            exitCode: 0,
+        };
+    }
+    if (rows.length === 0) {
+        return { ok: true, text: 'no agent worktrees', exitCode: 0 };
+    }
+    const lines = [];
+    lines.push('AGENT ID                    BRANCH                              GIT     PATH');
+    for (const row of rows) {
+        lines.push(`${pad(row.agentId, 28)}${pad(row.branch, 36)}${pad(row.gitTracked ? 'yes' : 'no', 8)}${row.path}`);
+    }
+    return { ok: true, text: lines.join('\n'), exitCode: 0 };
+}
+function runCleanup(args, opts) {
+    // --all-stale sweeps every classified stale entry. Otherwise the next
+    // positional arg is the agent id to remove.
+    const allStale = args.includes('--all-stale');
+    if (allStale) {
+        const report = runStaleCleanup({ cwd: opts.cwd }, opts.dryRun ? { dryRun: true } : {});
+        return formatStaleReport(report, opts);
+    }
+    const agentId = args.find((a) => !a.startsWith('--'));
+    if (!agentId) {
+        return {
+            ok: false,
+            text: 'Usage: pugi worktrees cleanup <agent-id> | --all-stale [--dry-run]',
+            exitCode: 2,
+        };
+    }
+    const manager = new WorktreeManager({ cwd: opts.cwd });
+    const result = manager.cleanup(agentId);
+    if (!result.ok) {
+        // Missing-worktree is idempotent: surface the structured note but
+        // return exit 0 so a double-cleanup in a teardown hook never trips
+        // CI. Every other failure mode (invalid id, git failure) stays
+        // exit 1.
+        return {
+            ok: false,
+            text: opts.json
+                ? JSON.stringify(result, null, 2)
+                : `cleanup failed: ${result.reason}: ${result.detail}`,
+            exitCode: result.reason === 'worktree_missing' ? 0 : 1,
+        };
+    }
+    return {
+        ok: true,
+        text: opts.json
+            ? JSON.stringify({ removed: result.value.removed }, null, 2)
+            : `worktree removed: ${result.value.removed}`,
+        exitCode: 0,
+    };
+}
+function formatStaleReport(report, opts) {
+    if (opts.json) {
+        return {
+            ok: report.errors.length === 0,
+            text: JSON.stringify(report, null, 2),
+            exitCode: report.errors.length === 0 ? 0 : 1,
+        };
+    }
+    const lines = [];
+    lines.push(`scanned: ${report.scanned} worktree(s)`);
+    if (report.removed.length > 0) {
+        lines.push(`removed: ${report.removed.length}`);
+        for (const r of report.removed)
+            lines.push(`  - ${r}`);
+    }
+    if (report.preserved.length > 0) {
+        lines.push(`preserved: ${report.preserved.length}`);
+        for (const p of report.preserved)
+            lines.push(`  - ${p.agentId} (${p.reason})`);
+    }
+    if (opts.dryRun) {
+        lines.push('dry-run: classifications only, nothing removed');
+        for (const c of report.classified)
+            lines.push(`  - ${c.agentId}: ${c.class}`);
+    }
+    if (report.errors.length > 0) {
+        lines.push(`errors: ${report.errors.length}`);
+        for (const e of report.errors)
+            lines.push(`  - ${e.agentId}: ${e.detail}`);
+    }
+    return {
+        ok: report.errors.length === 0,
+        text: lines.join('\n'),
+        exitCode: report.errors.length === 0 ? 0 : 1,
+    };
+}
+function usage() {
+    return {
+        ok: false,
+        text: 'Usage: pugi worktrees <op>\n' +
+            '  pugi worktrees list\n' +
+            '  pugi worktrees cleanup <agent-id>\n' +
+            '  pugi worktrees cleanup --all-stale [--dry-run]',
+        exitCode: 2,
+    };
+}
+function pad(s, n) {
+    if (s.length >= n)
+        return `${s.slice(0, n - 1)} `;
+    return s + ' '.repeat(n - s.length);
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.49');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.50');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/bash.js

@@ -27,7 +27,7 @@
  *      drops Windows shell support for M1.
  */
 import { randomUUID } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
@@ -60,6 +60,32 @@ export async function bashTool(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    // Cwd carry-over decision (also re-checked post-run).
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51, 2026-05-29).
+    // Runs BEFORE the permission gate so the boundary escape message is
+    // the one the operator/engine sees, regardless of permission policy.
+    // The leak is structural (git silently writes to an ancestor .git
+    // when the workspace lacks one), not a policy violation, so the
+    // diagnostic must surface even when the permission gate would
+    // otherwise have asked or auto-allowed.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
     // Permission gate via the new class-aware engine.
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
@@ -78,8 +104,6 @@ export async function bashTool(input, ctx) {
             timedOut: false,
         };
     }
-    // Cwd carry-over decision (also re-checked post-run).
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     // Background job branch.
     if (input.background === true) {
         return runBackground({ cmd, ctx, toolCallId, startCwd, additionalDirectories });
@@ -565,6 +589,160 @@ function readRegistryEntriesSync() {
         return [];
     }
 }
+/**
+ * Workspace-git-boundary guard (CEO P0 #51, 2026-05-29).
+ *
+ * Background: CEO live REPL surfaced a scenario where the customer
+ * workspace dir was created INSIDE another git repository (the Pugi
+ * monorepo itself). The model emitted `git init && git add . && git
+ * commit -m ...` against that workspace. The workspace had no `.git`
+ * of its own so git silently walked up to the outer repo's `.git` and
+ * committed the customer's files directly to the monorepo's main
+ * branch. Had the outer remote been FF-permissive, those files would
+ * have pushed to production. This is a customer-of-customer leak.
+ *
+ * The guard: when the agent emits a mutating git op (add / commit /
+ * push / rebase / reset / checkout) and the effective git toplevel
+ * (`git -C $cwd rev-parse --show-toplevel`) sits OUTSIDE the workspace
+ * root, block the command. The model is steered (via the persona
+ * prompt) to run `git init` first; the guard is the defensive net so
+ * a careless model emission cannot cross the boundary.
+ *
+ * Exported so the spec can exercise the predicate in isolation without
+ * having to drive the whole bash tool.
+ */
+export const GIT_BOUNDARY_BLOCK_PREFIX = 'git boundary escape:';
+/**
+ * Subcommands we treat as definitely mutating for the boundary check.
+ * We intentionally OMIT subcommands that have common read-only modes
+ * (`branch --list`, `tag --list`, `stash list`, `remote -v`) to keep
+ * the guard precise. The CEO P0 #51 leak vector is files written to
+ * an ancestor repo's working tree / refs, which the included set
+ * fully covers. The omitted subcommands can still create refs in the
+ * outer .git, but they do not move customer files into the outer
+ * repo's commit graph, so the leak severity is lower and the
+ * ergonomic cost of false positives on `--list` flags is higher.
+ */
+const MUTATING_GIT_SUBCOMMANDS = new Set([
+    'add',
+    'commit',
+    'push',
+    'rebase',
+    'reset',
+    'checkout',
+    'merge',
+    'restore',
+    'switch',
+    'cherry-pick',
+    'am',
+    'apply',
+    'clean',
+    'rm',
+    'mv',
+]);
+/**
+ * Inspect a shell command for mutating git operations. Returns the
+ * first matching subcommand (e.g. 'commit') or null when none of the
+ * components are mutating git ops.
+ *
+ * We split on `&&`, `||`, `;`, `|` so a compound like
+ * `mkdir foo && cd foo && git add .` is correctly flagged on the
+ * trailing git component.
+ */
+export function detectMutatingGitOp(cmd) {
+    const components = cmd.split(/\s*(?:&&|\|\||;|\|)\s*/);
+    for (const raw of components) {
+        const component = raw.trim();
+        if (component === '')
+            continue;
+        // Strip leading `sudo` wrapper which would otherwise hide the verb.
+        const stripped = component.replace(/^sudo\s+/, '');
+        // Match `git [<global-flags>] <subcommand> ...`. Global flags we
+        // tolerate:
+        //   - long flag: `--no-pager`, `--git-dir=.git`
+        //   - short flag with attached value: `-C <path>`, `-c <k=v>`
+        //   - bare short flag: `-P`
+        // Anything weirder falls through and the predicate returns null,
+        // which means the guard does not fire on that component — safer
+        // to err open here because the destructive classifier and the
+        // outer permission gate are independent defences.
+        const match = stripped.match(/^git(?:\s+(?:--[A-Za-z][A-Za-z0-9-]*(?:=\S+)?|-[CcP](?:\s+\S+)?|-[A-Za-z]+))*\s+([a-z][a-z0-9-]*)\b/);
+        if (!match)
+            continue;
+        const subcommand = match[1];
+        if (subcommand && MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {
+            return subcommand;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the workspace's effective git boundary. Returns:
+ *   - the absolute path of the .git toplevel that owns `cwd`
+ *   - null when no .git ancestor exists at all (standalone, no repo)
+ *
+ * Pure filesystem walk so the guard does not depend on git being on
+ * PATH. We look for either a `.git` directory or a `.git` file (the
+ * worktree case where `.git` is a pointer file).
+ */
+export function resolveGitToplevel(cwd) {
+    let dir = cwd;
+    while (true) {
+        const dotGit = join(dir, '.git');
+        if (existsSync(dotGit))
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * The actual guard. Returns null when the command is allowed; returns
+ * a block descriptor when it should be denied. The block message uses
+ * the literal prefix `git boundary escape:` so callers (and the spec)
+ * can pattern-match.
+ */
+export function enforceGitBoundary(cmd, startCwd, workspaceRoot) {
+    const subcommand = detectMutatingGitOp(cmd);
+    if (subcommand === null)
+        return null;
+    // Resolve symlinks on both sides so a /var → /private/var macOS
+    // realpath divergence does not produce a false escape.
+    const root = safeRealpath(workspaceRoot);
+    const toplevel = resolveGitToplevel(safeRealpath(startCwd));
+    const resolvedToplevel = toplevel === null ? null : safeRealpath(toplevel);
+    if (resolvedToplevel === root)
+        return null;
+    // Either no .git anywhere (standalone) OR the .git that wins is an
+    // ancestor — both are escape scenarios. Operator must run `git init`
+    // explicitly inside the workspace.
+    if (resolvedToplevel === null) {
+        return {
+            subcommand,
+            resolvedToplevel: null,
+            reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git ` +
+                `and no ancestor repository exists. Run \`git init\` in the workspace first ` +
+                `before \`git ${subcommand}\`.`,
+        };
+    }
+    return {
+        subcommand,
+        resolvedToplevel,
+        reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git; ` +
+            `outer toplevel is '${resolvedToplevel}'. Run \`git init\` in the workspace ` +
+            `first before \`git ${subcommand}\` (otherwise the operation would write to ` +
+            `the ancestor repository, not the workspace).`,
+    };
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
 function removeRegistryEntrySync(jobId) {
     const path = join(homedir(), '.pugi', 'jobs.json');
     const entries = readRegistryEntriesSync().filter((entry) => entry.id !== jobId);
@@ -592,6 +770,28 @@ export function bashToolSync(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51, 2026-05-29). Fires
+    // BEFORE the permission gate so the structural boundary diagnostic
+    // is the one the operator sees. See the async path for the full
+    // rationale.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
         additionalDirectories,
@@ -609,7 +809,6 @@ export function bashToolSync(input, ctx) {
             timedOut: false,
         };
     }
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     const timeoutMs = sanitizeTimeout(input.timeoutMs);
     const childEnv = buildChildEnv();
     const result = spawnSync('/bin/sh', ['-c', cmd], {

package/dist/tui/repl-splash-mascot.js

@@ -101,21 +101,33 @@ export function loadPugMascotAnsi() {
         //    icon, clipboard, hyperlinks, color-palette change). Drop them
         //    so a corrupted asset cannot rename the operator's terminal tab
         //    or smuggle a hyperlink into the splash region.
-        // 2. Drop CSI ? <mode> [hl] for mouse-tracking and screen-buffer
-        //    switch modes (1000, 1001, 1002, 1003, 1004, 1005, 1006, 1015,
-        //    1049, 47, 1047, 1048). These would either start swallowing
-        //    mouse input or flip the terminal into the alternate screen.
+        // 2. Drop ALL CSI ? <numbers and semicolons> [lh] (DEC private-mode
+        //    set / reset). The legitimate chafa output for a splash is
+        //    truecolor SGR (`CSI 38;2;R;G;B m`) plus cursor-positioning —
+        //    no private-mode toggle ever appears там legitimately. A
+        //    permissive deny-all pattern covers every disruptive private
+        //    mode in one regex:
+        //      - cursor visibility (25)
+        //      - alt-screen buffer  (47, 1047, 1048, 1049)
+        //      - mouse tracking     (1000, 1001, 1002, 1003, 1004, 1005, 1006, 1015)
+        //      - bracketed paste    (2004)
+        //      - focus reporting    (1004)
+        //      - multi-mode forms   (e.g. `CSI ? 47 ; 1049 h` — legal per
+        //        xterm ctlseqs but missed by the previous single-mode regex)
+        //      - any future private mode a corrupt asset might emit
+        //    Allowlisting the modes the splash needs is impossible because
+        //    the splash needs ZERO of them — chafa renders glyph-by-glyph,
+        //    not via private-mode toggles. A pure deny-all is strictly
+        //    safer than enumerating known-bad modes one-by-one.
         // 3. Drop CSI 6 n (cursor-position report). Would inject a fake
         //    CPR into the operator's stdin stream.
         // 4. Drop CSI [23]J / CSI [23]K (full screen / line clear). A
         //    chafa render uses cursor-positioning per row, not bulk
         //    erases; bulk clears would wipe whatever the operator already
         //    had on screen above the splash.
-        // The cursor-hide/show wrappers (CSI ? 25 [lh]) are handled by
-        // the same CSI-?-mode pattern as the mouse / alt-screen modes.
         const stripped = raw
             .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
-            .replace(/\x1b\[\?(?:25|47|1000|1001|1002|1003|1004|1005|1006|1015|1047|1048|1049)[lh]/g, '')
+            .replace(/\x1b\[\?[0-9;]+[lh]/g, '')
             .replace(/\x1b\[6n/g, '')
             .replace(/\x1b\[[23]?[JK]/g, '');
         if (stripped.trim().length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.49",
+  "version": "0.1.0-beta.50",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -55,7 +55,7 @@
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.49"
+    "@pugi/sdk": "0.1.0-beta.50"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",