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

package/dist/core/settings.js

@@ -165,6 +165,44 @@ const pugiSettingsSchema = z.object({
     // keeps Zod's strip-pass from swallowing it before the chain reader
     // sees it. See `hook-chains.ts` for the full schema.
     hooks: z.any().optional(),
+    // PUGI-260 — persistent default for the 1M context tier opt-in.
+    // `pugi config set context.tier 1m` writes this; per-invocation
+    // `--context-tier=...` flags override it. When omitted, the CLI
+    // sends no `contextTier` field на the wire (server treats as
+    // `standard` routing). The closed enum mirrors the CLI flag и the
+    // admin-api DTO; an unrecognised value triggers a Zod parse error
+    // at load time rather than a silent fallback.
+    context: 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/index.js

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 import { runCli } from './runtime/cli.js';
 import { PugiCliUpgradeRequiredError } from './core/transport/version-interceptor.js';
+import { installSigintGuard } from './runtime/sigint-guard.js';
+// PUGI-469 — install the top-level double-press Ctrl+C exit guard
+// BEFORE any other init. Operators reported single ^C exiting the
+// CLI; the guard requires a second press inside a 2s window (or
+// emits a clean session-end envelope on the headless path) so a
+// stray keystroke never kills the session. See the module header
+// in `runtime/sigint-guard.ts` for the full behavior spec.
+installSigintGuard();
 runCli(process.argv.slice(2)).catch((error) => {
     // PR-CLI-SERVER-VERSION-HANDSHAKE . When the admin-api returns
     // 426 Upgrade Required, the engine transport throws a typed

package/dist/runtime/cli.js

@@ -49,7 +49,7 @@ import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
 import { runRewindCommand } from './commands/rewind.js';
 import { runSessionsCommand } from './commands/sessions.js';
-// Day 4 ADR-0063: persona-memory operator surface (list / recall / write /
+// Day 4 : persona-memory operator surface (list / recall / write /
 // forget / sync). The runner is shared by `pugi memory` top-level and the
 // in-REPL `/memory` slash so the two surfaces stay single-sourced.
 import { runMemoryCommand } from './commands/memory.js';
@@ -64,7 +64,7 @@ import { runRecipeCommand } from './commands/recipe.js';
 import { installDefaultSkills } from '../core/skills/defaults.js';
 // Backlog : bundled-skills batch 1 (stuck / simplify /
 // remember). Backlog : batch 2 (batch / verify / loop /
-// skillify, Nuekkis clean-room).
+// skillify, external independent implementation).
 // Imported through the dedicated registry so future batches only append
 // to one barrel.
 import { runRememberCommand, runSimplifyCommand, runStuckCommand, runBatchCommand, runVerifyCommand, runLoopCommand, runSkillifyCommand, } from '../skills/bundled/index.js';
@@ -151,7 +151,7 @@ const handlers = {
     logout,
     lsp: dispatchLsp,
     mcp: dispatchMcp,
-    // ADR-0063 Day 4: `pugi memory list|recall|write|forget|sync`. Routes
+    //  Day 4: `pugi memory list|recall|write|forget|sync`. Routes
     // to `runMemoryCommand` (admin-api `/api/persona-memory` + offline
     // queue at `~/.pugi/memory-queue.jsonl`).
     memory: dispatchMemory,
@@ -233,7 +233,7 @@ const handlers = {
     // when no approval gate is wired. The existing `pugi memory write`
     // surface keeps its silent-enqueue behaviour for back-compat.
     remember: dispatchRemember,
-    // Backlog — bundled-skills batch 2 (Nuekkis clean-room).
+    // Backlog — bundled-skills batch 2 (external independent implementation).
     // `pugi batch` fans out a YAML recipe of independent engine tasks
     // through up to --concurrency=N subprocesses (hard cap 30 per the
     // Mac safety carve-out). Aggregates results into
@@ -447,7 +447,7 @@ async function dispatchPrivacy(args, flags, _session) {
     });
 }
 /**
- * ADR-0063 Day 4 — `pugi memory <sub>` top-level dispatcher.
+ *  Day 4 — `pugi memory <sub>` top-level dispatcher.
  *
  * Forwards to the shared `runMemoryCommand` runner. Exit codes:
  *
@@ -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 , ADR-0056). The REPL is the customer-facing surface
-    // that brings Pugi to parity with the upstream tool / Codex CLI. When the
+    // (Sprint , ). The REPL is the customer-facing surface
+    // 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
@@ -1824,7 +1890,7 @@ function parseArgs(argv) {
         }
         else if (arg === '--council') {
             // Backlog — opt-in council mode (Karpathy llm-council
-            // pattern, MIT clean-room TS port). Pairs with `--triple
+            // pattern, MIT independent implementation TS port). Pairs with `--triple
             // --commit <SHA>`; the dispatch wraps the multi-provider
             // fan-out with an anonymous peer-review stage + chairman
             // synthesis. Costs ~2× tokens; explicit opt-in only.
@@ -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);
         }
@@ -4101,7 +4186,7 @@ async function performTripleProviderReview(root, session, flags, prompt) {
         // Server-side the controller also accepts `?council=true` query
         // string + `mode: 'council'` body shorthand; the CLI sends the
         // explicit boolean for forward compatibility. Inspired by
-        // Karpathy llm-council pattern (MIT). Clean-room TS port.
+        // Karpathy llm-council pattern (MIT). independent implementation TS port.
         ...(flags.council ? { council: true } : {}),
     });
     writeFileSync(requestPath, `${JSON.stringify(requestBody, null, 2)}\n`, {
@@ -4961,6 +5046,38 @@ export function setHeadlessWriters(writers) {
     headlessStdoutWriter = writers.stdout ?? null;
     headlessStderrWriter = writers.stderr ?? null;
 }
+/**
+ * PUGI-260 — read the persisted `contextTier` default из
+ * `~/.pugi/config.json` (written by `pugi config set context.tier 1m`).
+ * Returns `undefined` when the config file is missing, the key is
+ * unset, or the value is invalid. Failures are silent — a malformed
+ * persisted config must NEVER break the per-invocation dispatch path;
+ * the flag default just falls back к "no preference" and the request
+ * goes out on the standard lane.
+ *
+ * Kept inline (rather than importing from `commands/config.ts`) so the
+ * dispatch path does not pull в the full `pugi config` command tree
+ * during a `pugi code "..."` cold start — the import graph stays narrow.
+ */
+function readPersistedContextTier() {
+    try {
+        const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+        const path = resolve(home, 'config.json');
+        if (!existsSync(path))
+            return undefined;
+        const raw = readFileSync(path, 'utf8');
+        if (raw.trim() === '')
+            return undefined;
+        const parsed = JSON.parse(raw);
+        if (parsed.contextTier === '1m' || parsed.contextTier === 'standard') {
+            return parsed.contextTier;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function runEngineTask(kind) {
     return async (args, flags, session) => {
         const label = commandLabel(kind);
@@ -5250,18 +5367,29 @@ function runEngineTask(kind) {
             // point); `allowParallelAgents=false` strips the `agent` tool from
             // the schema so quick / standard tiers cannot accidentally fan out.
             intensityProfile,
-            // Task — 1M context tier opt-in. The operator passes
+            // PUGI-260 — 1M context tier opt-in. The operator passes
             // `--context-tier=1m` to request the long-context lane. Server
-            // enforces Team-tier ($199) entitlement and rewrites the model к
-            // the `pugi-1m` alias. Lower tiers receive HTTP 402 with an
-            // upgrade-path message rendered by the dispatch error handler.
-            // `flags.contextTier` is intentionally NOT defaulted к 'standard'
-            // here — `undefined` and `'standard'` are wire-equivalent (admin-
-            // api treats both as no-op), so the wire stays clean for callers
-            // that omit the flag entirely.
-            ...(flags.contextTier !== undefined
-                ? { contextTier: flags.contextTier }
-                : {}),
+            // enforces Builder ($99) или Team ($199) entitlement и rewrites
+            // the model к the `pugi-1m` alias. Lower tiers receive HTTP 402
+            // with `reason: 'context_tier_requires_upgrade'` + the
+            // `X-Pugi-Quota-Exceeded: context_tier_requires_upgrade` response
+            // header rendered by the dispatch error handler.
+            //
+            // Resolution order:
+            //   1. `--context-tier=1m|standard` flag (per-invocation override).
+            //   2. `~/.pugi/config.json::contextTier` (persistent default,
+            //      set via `pugi config set context.tier 1m`).
+            //   3. Omitted on the wire — admin-api treats omitted == standard.
+            //
+            // `'standard'` is wire-equivalent to omitted (the gate short-
+            // circuits when `request.contextTier !== '1m'`), so the wire stays
+            // clean for callers that omit the flag entirely.
+            ...(() => {
+                const effectiveTier = flags.contextTier ?? readPersistedContextTier();
+                return effectiveTier !== undefined
+                    ? { contextTier: effectiveTier }
+                    : {};
+            })(),
         });
         const toolCallId = recordToolCall(session, `engine:${adapter.name}`, `${label}: ${prompt}`);
         const taskId = `${kind}-${Date.now()}`;
@@ -5821,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)
@@ -5980,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
@@ -7111,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
@@ -7810,7 +7953,12 @@ export const __test__ = {
     // Backlog — `parseArgs` exposed under the test namespace so the
     // council-flag spec can assert flag-to-CliFlags mapping without
     // standing up a full execFileSync harness. Inspired by Karpathy
-    // llm-council pattern (MIT). Clean-room TS port.
+    // llm-council pattern (MIT). independent implementation TS port.
     parseArgs,
+    // PUGI-260 — exposed под the test namespace so the persisted-
+    // contextTier-fallback spec can exercise the actual reader (с its
+    // env-driven $PUGI_HOME redirect) without going через the full
+    // engine-task dispatch path.
+    readPersistedContextTier,
 };
 //# sourceMappingURL=cli.js.map

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:'];