@pugi/cli 0.1.0-beta.88 → 0.1.0-beta.89

package/dist/core/repl/session.js

@@ -2019,7 +2019,7 @@ export class ReplSession {
         // Surface the operator's choice as a transcript row so the
         // conversation reads linearly. The label of the chosen option
         // (or the literal custom input) is more readable than the bare
-        // value - Codex CLI's "you chose: Vercel" pattern.
+        // value - peer CLI's "you chose: Vercel" pattern.
         const humanLabel = humanLabelForVerdict(tag, sanitisedVerdict);
         this.appendOperatorLine(humanLabel);
         // Local-origin modals (operator typed `/ask`) never need an
@@ -4105,7 +4105,7 @@ export function colorizeQuotaRow(row, pct) {
  * string and emit a synthesised `ToolCallEntry`. Returns null when no
  * known tool pattern matches.
  *
- * The grammar mirrors the way the upstream tool, Codex CLI, and Gemini CLI
+ * The grammar mirrors the way the upstream tool, peer CLI, and Gemini CLI
  * display tool calls in their tool stream panes:
  *
  *  Read(path)
@@ -4293,7 +4293,7 @@ function encodePlanReviewVerdictLocal(result) {
 }
 /**
  * Compose the human-readable transcript line that records the
- * operator's ask verdict. Mirrors Codex CLI's "you chose: <label>"
+ * operator's ask verdict. Mirrors peer CLI's "you chose: <label>"
  * pattern so the conversation reads linearly.
  */
 function humanLabelForVerdict(tag, verdict) {

package/dist/core/repl/slash-commands.js

@@ -4,7 +4,7 @@
  * The REPL input box surfaces a palette of slash commands the operator
  * can run from inside a persistent session. The wave-2 expansion (CEO
  *) grows the surface from 6 to 20 commands so the `/help`
- * overlay matches the breadth the upstream tool / Codex CLI operators expect.
+ * overlay matches the breadth the upstream tool / peer CLI operators expect.
  *
  * The registry is pure: each `parseSlashCommand` call returns a
  * `SlashCommandResult` describing what the REPL session should do next.

package/dist/core/settings.js

@@ -177,6 +177,32 @@ const pugiSettingsSchema = z.object({
         tier: z.enum(['1m', 'standard']).optional(),
     })
         .optional(),
+    // PUGI-487 - `pugi --worktree` flag governance.
+    //
+    // Two knobs control the user-facing --worktree flag introduced for
+    // parity with parallel-agent isolation patterns in other coding
+    // CLIs:
+    //
+    //  - `baseRef`: which ref the new worktree branches FROM.
+    //    `'fresh'` (default) resolves origin/<default-branch> so each
+    //    parallel session starts from a clean trunk.
+    //    `'head'` carries the operator's current local HEAD (including
+    //    unpushed work) into the new tree.
+    //
+    //  - `cleanupPeriodDays`: integer days. The daily sweep removes
+    //    user-facing worktrees older than N days that have no
+    //    uncommitted, untracked, or unpushed state. Default 7 mirrors
+    //    a one-work-week window. Set to 0 to disable auto-cleanup.
+    //
+    // Both knobs are optional - the consumers (`bootstrapWorktree`,
+    // `runUserWorktreeCleanup`) carry their own defaults so a missing
+    // section produces standard behaviour.
+    worktree: z
+        .object({
+        baseRef: z.enum(['fresh', 'head']).optional(),
+        cleanupPeriodDays: z.number().int().min(0).max(365).optional(),
+    })
+        .optional(),
 });
 /**
  * #20 — the upstream tool drop-in compat ingest.

package/dist/core/worktree/include-parser.js

@@ -0,0 +1,249 @@
+/**
+ * `.worktreeinclude` parser - PUGI-487.
+ *
+ * The `.worktreeinclude` file lives at the repository root and carries
+ * gitignore-syntax patterns. Files that:
+ *
+ *   1. Match at least one pattern in `.worktreeinclude`, AND
+ *   2. Are git-ignored (untracked-and-ignored OR explicitly ignored),
+ *
+ * get COPIED into a fresh `pugi --worktree <name>` tree right after
+ * `git worktree add` finishes. Tracked files are NEVER copied because
+ * git already brings them along on its own, and double-writing would
+ * corrupt the worktree index.
+ *
+ * Why a separate include file instead of `.gitignore` negation
+ * patterns?
+ *
+ *  - The common case is "I have an untracked `.env` with API keys that
+ *    every parallel session needs". Listing it in `.gitignore` with
+ *    a negation would force-add it to the repo, defeating the point.
+ *  - Operators want a single-file, copy-pasteable manifest of WHAT
+ *    leaves the main tree, not a derived view across `.gitignore`
+ *    semantics.
+ *
+ * Pattern grammar (subset of gitignore):
+ *
+ *  - Lines starting with `#` are comments. Blank lines are skipped.
+ *  - Trailing `/` means directory-only and applies recursively to
+ *    every file under the directory.
+ *  - Leading `!` is a negation pattern that REMOVES matches from
+ *    prior includes. Multiple negations are processed in order.
+ *  - `*` matches any character except `/`.
+ *  - `**` matches any number of path segments.
+ *  - `?` matches a single non-`/` character.
+ *  - Patterns with NO `/` match anywhere in the tree (e.g. `.env`
+ *    matches both `./.env` and `./apps/foo/.env`).
+ *  - Patterns starting with `/` are anchored to the repository root.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, sep, posix } from 'node:path';
+/** Default file name. */
+export const WORKTREE_INCLUDE_FILENAME = '.worktreeinclude';
+/**
+ * Parse the textual contents of a `.worktreeinclude` file into a rule
+ * list. Pure function - does not touch the filesystem. Exposed for
+ * spec coverage and the cleanup/dry-run path.
+ */
+export function parseWorktreeIncludeText(text, source = WORKTREE_INCLUDE_FILENAME) {
+    const rules = [];
+    const lines = text.split(/\r?\n/);
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#'))
+            continue;
+        let body = line;
+        let negate = false;
+        if (body.startsWith('!')) {
+            negate = true;
+            body = body.slice(1);
+        }
+        if (body.length === 0)
+            continue;
+        let directoryOnly = false;
+        if (body.endsWith('/')) {
+            directoryOnly = true;
+            body = body.slice(0, -1);
+        }
+        let anchored = false;
+        if (body.startsWith('/')) {
+            anchored = true;
+            body = body.slice(1);
+        }
+        else if (body.includes('/')) {
+            // a non-leading slash also anchors per gitignore semantics
+            anchored = true;
+        }
+        if (body.length === 0)
+            continue;
+        rules.push({
+            raw: line,
+            pattern: body,
+            negate,
+            directoryOnly,
+            anchored,
+        });
+    }
+    return { rules, source };
+}
+/**
+ * Load + parse `.worktreeinclude` from a repository root. Returns an
+ * empty rule set when the file is absent or unreadable - a missing
+ * include file is the normal case (no extras to copy).
+ */
+export function loadWorktreeInclude(repoRoot) {
+    const path = resolve(repoRoot, WORKTREE_INCLUDE_FILENAME);
+    if (!existsSync(path)) {
+        return { rules: [], source: path };
+    }
+    try {
+        const text = readFileSync(path, 'utf8');
+        return parseWorktreeIncludeText(text, path);
+    }
+    catch {
+        return { rules: [], source: path };
+    }
+}
+const REGEX_ESCAPE = /[.+^${}()|[\]\\]/;
+/**
+ * Convert a gitignore-style glob pattern into a regex source string.
+ * Subset implementation: covers `*`, `**`, `?`, and escapes the rest.
+ *
+ * Uses index-based scanning so `**` is detected and consumed before a
+ * single `*` substitution could eat the doubled form.
+ */
+function globToRegexSource(pattern) {
+    let out = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern.charAt(i);
+        if (ch === '*') {
+            if (pattern.charAt(i + 1) === '*') {
+                out += '.*';
+                i += 1;
+                continue;
+            }
+            out += '[^/]*';
+            continue;
+        }
+        if (ch === '?') {
+            out += '[^/]';
+            continue;
+        }
+        if (REGEX_ESCAPE.test(ch)) {
+            out += '\\' + ch;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Decide whether `relPath` (a forward-slash, no-leading-slash path
+ * relative to the repo root) is matched by the given rule list. The
+ * last matching rule wins so a negation after an include drops the
+ * entry and an include after a negation re-adds it.
+ */
+export function matchesWorktreeInclude(relPath, rules, isDirectory = false) {
+    const normalized = relPath.replace(/\\+/g, '/');
+    let matched = false;
+    for (const rule of rules) {
+        if (rule.directoryOnly && !isDirectory) {
+            // directory-only rule still matches files UNDER the dir (handled
+            // below). Falls through to the file-match attempt.
+        }
+        const source = buildRegex(rule);
+        const re = new RegExp('^' + source + '$');
+        if (re.test(normalized)) {
+            matched = !rule.negate;
+            continue;
+        }
+        if (rule.directoryOnly) {
+            const reUnder = new RegExp('^' + source + '/.*$');
+            if (reUnder.test(normalized)) {
+                matched = !rule.negate;
+            }
+        }
+    }
+    return matched;
+}
+function buildRegex(rule) {
+    const body = globToRegexSource(rule.pattern);
+    if (rule.anchored) {
+        return body;
+    }
+    // Unanchored pattern matches anywhere in the tree. Allow a
+    // segment-aligned match by accepting either start-of-string or a
+    // `/` boundary before the pattern body.
+    return '(?:.*/)?' + body;
+}
+/**
+ * Walk `repoRoot` and return every git-ignored file path that matches
+ * the include rules. Tracked files are excluded because they ride
+ * along with git automatically.
+ *
+ * Implementation note: rather than re-implement gitignore evaluation
+ * the default lister shells out to
+ * `git ls-files --others --ignored --exclude-standard` to get the
+ * authoritative ignored-untracked list. Tracked files never appear in
+ * that output, so the result is exactly the safe-to-copy candidate
+ * pool.
+ */
+export function collectWorktreeIncludeFiles(repoRoot, rules, options = {}) {
+    if (rules.length === 0)
+        return [];
+    const lister = options.listIgnored ?? defaultListIgnored;
+    const stat = options.isDirectory ?? defaultIsDirectory;
+    const candidates = lister(resolve(repoRoot));
+    const out = [];
+    for (const candidate of candidates) {
+        const rel = candidate.replace(/\\+/g, '/').replace(/^\.\//, '');
+        if (rel.length === 0)
+            continue;
+        if (rel.startsWith('.pugi/') || rel.startsWith('.claude/')) {
+            // Never copy Pugi or .claude state into the worktree. Those
+            // dirs are owned by the runtime and the include file should
+            // not be able to leak audit logs or stale session state.
+            continue;
+        }
+        const absPath = resolve(repoRoot, rel);
+        const isDir = stat(absPath);
+        if (matchesWorktreeInclude(rel, rules, isDir)) {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+function defaultListIgnored(repoRoot) {
+    // `-z` emits NUL-separated paths, the only safe form when filenames
+    // may contain spaces or newlines.
+    const result = spawnSync('git', ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'], {
+        cwd: repoRoot,
+        encoding: 'buffer',
+        shell: false,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status !== 0 || !result.stdout)
+        return [];
+    const text = result.stdout.toString('utf8');
+    return text.split('\u0000').filter((s) => s.length > 0);
+}
+function defaultIsDirectory(absPath) {
+    try {
+        return statSync(absPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Cross-platform path-join in posix form (for matching semantics). */
+export function joinRel(parent, child) {
+    return posix.join(parent.replace(/\\+/g, '/'), child);
+}
+/** Re-export the system separator so consumers do not have to import it. */
+export const PATH_SEP = sep;
+//# sourceMappingURL=include-parser.js.map

package/dist/runtime/cli.js

@@ -1596,9 +1596,75 @@ export async function runCli(argv) {
     // because the welcome banner is the authoritative surface — a stray
     // stderr line above the alt-screen flicker would race against the
     // banner paint on slow terminals.
+    // PUGI-487 - `pugi --worktree [<name>]` dispatch. When the flag is
+    // present on a bare invocation we create an isolated git worktree at
+    // `.claude/worktrees/<name>/` and chdir into it BEFORE the REPL mounts.
+    // The flag is mutually exclusive with `--print` and `--headless`
+    // (already short-circuited above) and with `--bare` (which disables
+    // every project-discovery surface the worktree relies on). We refuse
+    // those combinations with a clear error rather than silently dropping
+    // the flag.
+    if (typeof flags.worktree === 'string' && isBareInvocation) {
+        if (flags.bare) {
+            process.stderr.write('--worktree cannot be combined with --bare; bare mode disables project discovery.\n');
+            process.exitCode = 2;
+            return;
+        }
+        const { bootstrapWorktree } = await import('./worktree-bootstrap.js');
+        // PUGI-487 codex P2: honour `worktree.baseRef` from .pugi/settings.json
+        // so an operator who set `head` (carry unpushed local work into the
+        // new tree) actually gets that behaviour. The schema is optional;
+        // `loadSettings` never throws so a bad/missing file degrades to the
+        // default `fresh` branching.
+        let configuredBaseRef;
+        try {
+            const { loadSettings } = await import('../core/settings.js');
+            const settings = loadSettings(process.cwd());
+            configuredBaseRef = settings.worktree?.baseRef;
+        }
+        catch {
+            // best-effort: a malformed settings file falls back to the
+            // bootstrap's own default rather than aborting the worktree.
+        }
+        const envelope = await bootstrapWorktree({
+            repoRoot: process.cwd(),
+            nameArg: flags.worktree.length === 0 ? undefined : flags.worktree,
+            ...(configuredBaseRef ? { baseRef: configuredBaseRef } : {}),
+        });
+        if (!envelope.ok) {
+            if (flags.json) {
+                process.stdout.write(JSON.stringify(envelope) + '\n');
+            }
+            else {
+                process.stderr.write(`pugi --worktree failed: ${envelope.message ?? envelope.reason ?? 'unknown error'}\n`);
+            }
+            process.exitCode = envelope.reason === 'untrusted_workspace' ? 3 : 1;
+            return;
+        }
+        // chdir into the new tree so the REPL boot below treats it as the
+        // workspace root. The flag does not change the rest of the bare-
+        // invocation flow except for the cwd.
+        try {
+            process.chdir(envelope.directory);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`failed to enter worktree ${envelope.directory}: ${message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (flags.json) {
+            process.stdout.write(JSON.stringify(envelope) + '\n');
+        }
+        else {
+            process.stderr.write(`pugi --worktree ${envelope.name} -> ${envelope.directory} (branch ${envelope.branch}, copied ${envelope.copiedFiles.length} include file(s))\n`);
+        }
+        // Fall through to the bare-REPL branch below so the REPL mounts
+        // inside the freshly-checked-out worktree.
+    }
     // Bare `pugi` on a TTY enters the REPL-by-default agentic session
     // (Sprint , ). The REPL is the customer-facing surface
-    // that brings Pugi to parity with the upstream tool / Codex CLI. When the
+    // that brings Pugi to parity with the upstream tool / peer CLI. When the
     // operator has no credentials yet, we fall back to the splash
     // so the install-time `pugi` surface still shows the wordmark +
     // quick-start hints. Non-TTY (CI, pipes, `--no-tty`) also falls
@@ -2134,6 +2200,25 @@ function parseArgs(argv) {
         else if (arg.startsWith('--filter=')) {
             flags.smokeFilter = arg.slice('--filter='.length);
         }
+        else if (arg === '--worktree') {
+            // PUGI-487 - user-facing parallel-isolation flag. Consumes
+            // the next token as the name unless it starts with `--`
+            // (treat as missing => auto-generate). The empty string is
+            // the sentinel for "flag present without value".
+            const next = argv[index + 1];
+            if (typeof next === 'string' && next.length > 0 && !next.startsWith('--')) {
+                flags.worktree = next;
+                index += 1;
+            }
+            else {
+                flags.worktree = '';
+            }
+        }
+        else if (arg.startsWith('--worktree=')) {
+            // PUGI-487 - `--worktree=<name>` form. Empty value also
+            // triggers the auto-name path.
+            flags.worktree = arg.slice('--worktree='.length);
+        }
         else {
             args.push(arg);
         }
@@ -5864,7 +5949,7 @@ function parseProviderFlag(args) {
  * `--json` / `--no-tty` / CI markers were not supplied. We only
  * prompt or render Ink surfaces when a human is plausibly watching
  * the screen. The multi-condition gate matches the upstream tool, gh CLI,
- * Codex CLI, and the npm CLI conventions.
+ * peer CLI, and the npm CLI conventions.
  */
 function isInteractive(flags) {
     if (flags.json)
@@ -6023,7 +6108,7 @@ async function login(args, flags, _session) {
  * Render the interactive Ink picker shown when `pugi login` runs on
  * a TTY with no token args. Returns the chosen provider, or `null`
  * when the user dismisses the picker via Esc / q. Mirrors the
- * the upstream tool / Codex CLI auth picker UX.
+ * the upstream tool / peer CLI auth picker UX.
  *
  * The Ink import is dynamic so a non-interactive `pugi <anything>`
  * never pays the React+Ink module-load cost. ESM dynamic-import is
@@ -7154,21 +7239,36 @@ function notImplemented(command) {
 }
 function ensurePugiGitIgnore(cwd, created, skipped) {
     const gitignorePath = resolve(cwd, '.gitignore');
-    const marker = '.pugi/';
+    // PUGI-487 - also ensure `.claude/worktrees/` is git-ignored so the
+    // user-facing `pugi --worktree` flag does not surface its created
+    // trees as untracked status noise.
+    const markers = ['.pugi/', '.claude/worktrees/'];
     if (!existsSync(gitignorePath)) {
-        writeFileSync(gitignorePath, `${marker}\n`, { encoding: 'utf8', mode: 0o600 });
+        writeFileSync(gitignorePath, `${markers.join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
         created.push(gitignorePath);
         return;
     }
     const current = readFileSync(gitignorePath, 'utf8');
     const lines = current.split('\n').map((line) => line.trim());
-    if (lines.includes(marker) || lines.includes('/.pugi/') || lines.includes('.pugi')) {
+    const equivalents = {
+        '.pugi/': ['.pugi/', '/.pugi/', '.pugi'],
+        '.claude/worktrees/': ['.claude/worktrees/', '/.claude/worktrees/', '.claude/worktrees'],
+    };
+    const toAppend = [];
+    for (const marker of markers) {
+        const eq = equivalents[marker] ?? [marker];
+        const present = eq.some((variant) => lines.includes(variant));
+        if (!present)
+            toAppend.push(marker);
+    }
+    if (toAppend.length === 0) {
         skipped.push(gitignorePath);
         return;
     }
-    const next = current.endsWith('\n') ? `${current}${marker}\n` : `${current}\n${marker}\n`;
+    const trailing = current.endsWith('\n') ? '' : '\n';
+    const next = `${current}${trailing}${toAppend.join('\n')}\n`;
     writeFileSync(gitignorePath, next, { encoding: 'utf8' });
-    created.push(`${gitignorePath} (+${marker})`);
+    created.push(`${gitignorePath} (+${toAppend.join(', ')})`);
 }
 /**
  * Compute the workspace label surfaced in the REPL header bar

package/dist/runtime/commands/agents.js

@@ -94,7 +94,7 @@ async function runAgentsList(args, ctx) {
         return;
     }
     if (verdicts.length === 0) {
-        ctx.writeOutput({ command: 'agents.list', agents: [] }, 'No agents installed. Try `pugi agents install gh:anthropics/claude-code-agents/code-reviewer.md@main`.');
+        ctx.writeOutput({ command: 'agents.list', agents: [] }, 'No agents installed. Try `pugi agents install gh:example-org/coding-agents/code-reviewer.md@main`.');
         return;
     }
     const lines = ['Installed agents:'];

package/dist/runtime/commands/hooks.js

@@ -101,6 +101,9 @@ function runList(ctx, flags) {
         SubagentStop: [],
         PreCompact: [],
         Notification: [],
+        // PUGI-487 - worktree lifecycle events.
+        WorktreeCreate: [],
+        WorktreeRemove: [],
     };
     for (const event of ALL_HOOK_EVENTS_V2) {
         perEvent[event] = config.list(event).map((entry) => ({

package/dist/runtime/commands/review-consensus.js

@@ -1,7 +1,7 @@
 /**
  * `pugi review --consensus` — customer-facing triple-review .
  *
- * The differentiator: the upstream tool ships single-Claude review, Codex CLI
+ * The differentiator: the upstream tool ships single-Claude review, peer CLI
  * ships single-GPT review, Gemini CLI ships single-Gemini review. Pugi
  * ships a 3-model consensus gate as a first-class command so customers
  * get the same production-readiness signal we use internally - without the

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.88');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.89');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.