@pugi/cli 0.1.0-beta.22 → 0.1.0-beta.23

package/dist/core/auth/env-provider.js

@@ -0,0 +1,238 @@
+/**
+ * `pugi login --provider env` — env-var auth path (Leak L35).
+ *
+ * Claude Code, Codex CLI, and gh CLI all ship a way to authenticate via
+ * an environment variable so CI / container / scripted contexts can
+ * skip the device flow entirely. This module backs that path:
+ *
+ *   1. Resolve the candidate token (explicit `--key` flag beats
+ *      `PUGI_API_KEY` env — same precedence as `gh auth login --token`).
+ *   2. Run a cheap local format check so an obviously malformed key
+ *      (empty, whitespace, suspiciously short) fails fast WITHOUT
+ *      shipping it to the server (no observability leak into the
+ *      Anvil access log).
+ *   3. Call `GET /api/pugi/health` with `Authorization: Bearer <key>`
+ *      so an expired / revoked / typo'd token surfaces immediately
+ *      and the credential file never lands on disk for a dead key.
+ *   4. Map response to typed outcome the CLI dispatcher can render.
+ *
+ * The module is intentionally pure — fetch + reading env are injected,
+ * the writer is a separate concern. The CLI dispatcher composes
+ * `resolveEnvCandidateToken` + `assertTokenFormat` + `validateTokenAgainstHealth`
+ * and then writes the credential via `storeApiKey` on success.
+ *
+ * Failure modes are explicit so the dispatcher can pick the user-facing
+ * remediation string without re-parsing strings:
+ *
+ *   - `missing`          → no token in env or --key, halt with hint
+ *   - `invalid-format`   → token failed local format check, halt
+ *   - `unauthorized`     → server rejected the token (401 / 403)
+ *   - `network-error`    → fetch threw (DNS, refused, TLS)
+ *   - `server-error`     → server returned 5xx (transient — operator
+ *                          may want to retry once)
+ *   - `unexpected-status`→ anything else non-2xx (treat as failure)
+ *
+ * NEVER log the raw token. Memory hits
+ * `feedback_no_claude_attribution_anywhere_hard_rule` plus the
+ * CSO bearer-leak sweep apply here. Use `maskApiKey` from
+ * `core/credentials.ts` when the dispatcher needs to surface the key
+ * to the operator.
+ */
+/**
+ * The minimum length below which we refuse to even ship the token to
+ * the server. Pugi-issued PATs are 48+ chars (`pugi_<32 base32>`), JWTs
+ * issued by the device flow are ~250 chars, legacy `sk-*` PATs we
+ * accept for compatibility are 32+. 16 is well below all three real
+ * shapes so it only catches obvious paste mistakes.
+ */
+export const MIN_TOKEN_LENGTH = 16;
+/**
+ * The set of prefixes we recognise as plausibly-real Pugi-shaped
+ * tokens. Loose by design — the real validator is the server-side
+ * health probe. We just want to catch an operator who pasted the
+ * wrong string entirely (a username, a URL, a placeholder like
+ * "<your-key>") before it reaches the network.
+ *
+ * Three-segment JWTs are also accepted via the `looksLikeJwt`
+ * predicate so device-flow tokens copied out of `~/.pugi/credentials.json`
+ * on a different machine work.
+ */
+export const RECOGNISED_TOKEN_PREFIXES = ['pugi_', 'sk_', 'sk-', 'pat_'];
+/**
+ * Returns the trimmed candidate token, or `null` when neither path
+ * produced one. Precedence: explicit flag arg beats env var (matches
+ * `gh auth login --with-token`, `aws configure set`, and `pugi config`
+ * which all prefer the most-specific operator intent over the ambient
+ * env).
+ */
+export function resolveEnvCandidateToken(input) {
+    const explicit = input.explicitKey?.trim();
+    if (explicit)
+        return explicit;
+    const env = input.env ?? process.env;
+    const fromEnv = env.PUGI_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return null;
+}
+/**
+ * Local-only format check. Returns `null` on accept, a human-readable
+ * error string on reject. Deliberately lenient — the server-side
+ * health probe is the source of truth. We only catch obvious paste
+ * mistakes (empty, whitespace-laden, too short, looks like a URL or
+ * a placeholder).
+ */
+export function assertTokenFormat(token) {
+    if (!token)
+        return 'Token is empty';
+    if (/\s/.test(token)) {
+        return 'Token contains whitespace — check for shell quoting issues or a stray newline';
+    }
+    if (token.length < MIN_TOKEN_LENGTH) {
+        return `Token too short (${token.length} chars; Pugi tokens are >= ${MIN_TOKEN_LENGTH})`;
+    }
+    if (token.startsWith('<') && token.endsWith('>')) {
+        return 'Token looks like a placeholder (`<your-key>`) — replace with the actual key';
+    }
+    if (/^https?:\/\//i.test(token)) {
+        return 'Token looks like a URL — did you mean --api-url?';
+    }
+    // Accept either a recognised prefix OR a JWT three-segment shape.
+    // Anything else still passes — the server probe will catch genuinely
+    // unknown keys. We just want to surface an obvious mistake.
+    const hasKnownPrefix = RECOGNISED_TOKEN_PREFIXES.some((p) => token.startsWith(p));
+    if (!hasKnownPrefix && !looksLikeJwt(token)) {
+        // Soft-fail: warn the operator but proceed. Returning null here
+        // would mask the case where the operator pasted something
+        // genuinely wrong but the server happens to accept it (impossible
+        // for real keys but defence-in-depth). Returning the warning
+        // string would block legacy keys. We choose to proceed — the
+        // server is the source of truth — and let the CLI dispatcher
+        // decide whether to surface a note. Tracked via a separate
+        // `warnUnknownPrefix` return on a future revision.
+        return null;
+    }
+    return null;
+}
+/**
+ * JWT three-segment check. Does NOT verify the signature — we just
+ * want to recognise the shape so device-flow tokens copied from one
+ * machine to another pass the format gate.
+ */
+export function looksLikeJwt(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return false;
+    return parts.every((p) => /^[A-Za-z0-9_-]+$/.test(p) && p.length > 0);
+}
+/**
+ * Call `GET /api/pugi/health` with the candidate token. Returns a
+ * typed outcome that the CLI dispatcher can map directly to an exit
+ * code + remediation string.
+ *
+ * Health endpoint conventions (see apps/admin-api):
+ *   - 200 → token is valid, account is active
+ *   - 401 → token unknown / malformed at the server boundary
+ *   - 403 → token recognised but the account is suspended / paused
+ *   - 5xx → server-side issue, operator can retry
+ *   - network throw → DNS, refused, TLS — operator's connectivity issue
+ *
+ * We do not parse the body — the health endpoint's contract is the
+ * status code. Any future field (latency, region, build sha) can be
+ * surfaced by a separate `pugi doctor` probe without touching the
+ * login path.
+ */
+export async function validateTokenAgainstHealth(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const now = input.now ?? Date.now;
+    const url = `${stripTrailingSlash(input.apiUrl)}/api/pugi/health`;
+    const started = now();
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (error) {
+        // DNS failure, ECONNREFUSED, TLS handshake — anything that makes
+        // fetch throw before a status code is observable. We deliberately
+        // do NOT echo the URL host in the message body if it could leak a
+        // self-hosted Anvil hostname into a public CI log; the dispatcher
+        // composes the user-facing remediation.
+        const cause = error instanceof Error ? error.message : String(error);
+        return {
+            kind: 'network-error',
+            message: `Cannot reach ${input.apiUrl}; check your connection`,
+            cause,
+        };
+    }
+    const latencyMs = now() - started;
+    const { status } = response;
+    if (status === 200) {
+        return { kind: 'ok', latencyMs };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            kind: 'unauthorized',
+            status,
+            message: status === 401
+                ? 'Token invalid or expired — run `pugi login --provider device` to get a fresh one'
+                : 'Token recognised but the account is suspended — check `pugi whoami` on a working machine or contact support',
+        };
+    }
+    if (status >= 500) {
+        return {
+            kind: 'server-error',
+            status,
+            message: `${input.apiUrl} returned ${status}; retry in a moment`,
+        };
+    }
+    return {
+        kind: 'unexpected-status',
+        status,
+        message: `Unexpected ${status} from /api/pugi/health; treat as login failure`,
+    };
+}
+export async function resolveAndValidateEnvLogin(input) {
+    const token = resolveEnvCandidateToken({
+        explicitKey: input.explicitKey,
+        env: input.env,
+    });
+    if (!token) {
+        return {
+            kind: 'missing',
+            message: 'pugi login --provider env requires a token. Export PUGI_API_KEY in the current shell or pass --key <value>.',
+        };
+    }
+    const formatError = assertTokenFormat(token);
+    if (formatError) {
+        return {
+            kind: 'invalid-format',
+            message: `pugi login --provider env: ${formatError}`,
+        };
+    }
+    if (input.skipValidate) {
+        // Used by the existing `login-variants.spec.ts` regression suite
+        // so the test plane does not require a live network. Production
+        // path always validates.
+        return { kind: 'ok', token, latencyMs: 0 };
+    }
+    const probe = await validateTokenAgainstHealth({
+        apiUrl: input.apiUrl,
+        apiKey: token,
+        fetchImpl: input.fetchImpl,
+        now: input.now,
+    });
+    if (probe.kind === 'ok') {
+        return { kind: 'ok', token, latencyMs: probe.latencyMs };
+    }
+    return probe;
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=env-provider.js.map

package/dist/core/diagnostics/probes/pugi-md.js

@@ -0,0 +1,89 @@
+/**
+ * PUGI.md hierarchy probe — Leak L32 (2026-05-27).
+ *
+ * Surfaces how many ambient `PUGI.md` / `CLAUDE.md` files were
+ * discovered by the cwd → homedir walk-up. Operators triaging "why
+ * is the model not following my project conventions" can run
+ * `pugi doctor` and immediately see whether the hierarchy walk
+ * loaded the file they expected.
+ *
+ * Status semantics:
+ *   - `skipped` when bare mode is active (the walk is deliberately
+ *     disabled). The row still renders so the JSON schema stays
+ *     stable for downstream consumers.
+ *   - `skipped` when zero files were found. This is the default
+ *     state on a clean machine and is NOT an error — most operators
+ *     do not maintain a `~/PUGI.md`.
+ *   - `ok` when one or more files were discovered. The detail names
+ *     the closest file and the total count.
+ *
+ * Side effects:
+ *   - One filesystem walk from cwd to homedir (bounded by the walker's
+ *     depth cap). Each level performs at most 2 `existsSync` calls.
+ *     Cost is single-digit ms even on cold cache; well inside the
+ *     doctor probe wall-clock budget.
+ *
+ * Wired into `buildDefaultProbes` in `runtime/commands/doctor.ts`.
+ */
+import { isBareMode } from '../../bare-mode/index.js';
+import { walkUpPugiMd } from '../../pugi-md/walk-up.js';
+export const PUGI_MD_DOCTOR_LABEL = 'PUGI.md HIERARCHY';
+/** Detail string emitted when bare mode disables the walk. */
+export const PUGI_MD_BARE_SKIP_DETAIL = 'skipped (--bare)';
+/** Detail string emitted when the walk ran but found nothing. */
+export const PUGI_MD_EMPTY_DETAIL = 'no PUGI.md / CLAUDE.md found in cwd → homedir';
+export function probePugiMdHierarchy(input = {}) {
+    const env = input.env ?? process.env;
+    if (isBareMode(env)) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_BARE_SKIP_DETAIL,
+        };
+    }
+    const cwd = input.cwd ?? process.cwd();
+    const walk = input.walkImpl ?? ((c, o) => walkUpPugiMd(c, o));
+    let files;
+    try {
+        files = walk(cwd, input.homedir !== undefined ? { homedir: input.homedir } : {});
+    }
+    catch {
+        // Defensive: walker is wrapped in per-file try/catch already, so
+        // a throw here means a programmer error (bad input). Degrade to
+        // a `warn` row rather than crashing the doctor sweep.
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'warn',
+            detail: 'walk-up failed (see logs)',
+        };
+    }
+    if (files.length === 0) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_EMPTY_DETAIL,
+        };
+    }
+    // `files` is shallow-to-deep; the first entry is the closest to cwd.
+    // Operators reading the table care most about that one — it is the
+    // file that will most directly influence model behaviour. The
+    // additional count gives a quick "is the homedir / parent picked up
+    // too?" signal without listing every path.
+    const closest = files[0];
+    // closest is guaranteed non-undefined: files.length > 0 enforced
+    // by the early return above.
+    if (!closest) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_EMPTY_DETAIL,
+        };
+    }
+    const suffix = files.length === 1 ? '' : ` (+${files.length - 1} more)`;
+    return {
+        name: PUGI_MD_DOCTOR_LABEL,
+        status: 'ok',
+        detail: `${files.length} file${files.length === 1 ? '' : 's'}: ${closest.path}${suffix}`,
+    };
+}
+//# sourceMappingURL=pugi-md.js.map

package/dist/core/engine/native-pugi.js

@@ -18,6 +18,8 @@ import { buildContextPrefix, spliceContextPrefix } from './context-prefix.js';
 import { applyIntentMarker, classifyIntent } from './intent.js';
 import { loadTraversedMarkdown } from '../context/markdown-traverse.js';
 import { isBareMode } from '../bare-mode/index.js';
+import { walkUpPugiMd } from '../pugi-md/walk-up.js';
+import { renderAmbientContext } from '../pugi-md/context-injector.js';
 // α7 L11 (2026-05-27): per-session DenialTrackingState. One instance
 // per `run()` so denials cluster by (tool, args) within the same
 // command but do NOT leak across CLI invocations.
@@ -234,6 +236,30 @@ export class NativePugiEngineAdapter {
             // accurate; the REPL session retains the launch cwd for the
             // lifetime of the session which is what the operator expects.
             const cwdForTraverse = process.cwd();
+            // Leak L32 (2026-05-27): cwd → homedir walk-up that picks up every
+            // ambient `PUGI.md` (or `CLAUDE.md` as a fallback) the operator
+            // has placed above their workspace. This is the cross-project
+            // hierarchy walk — distinct from the workspace-bounded
+            // `loadTraversedMarkdown` below which only sees files INSIDE the
+            // workspace root. Render the concatenation once at session boot
+            // and prepend to the system prompt so the model treats the
+            // operator's personal guidance as ambient context for the whole
+            // session. `--bare` (Leak L22) skips this walk entirely.
+            let ambientContextBlock = '';
+            if (!isBareMode()) {
+                try {
+                    const hierarchy = walkUpPugiMd(cwdForTraverse);
+                    ambientContextBlock = renderAmbientContext(hierarchy);
+                }
+                catch {
+                    // Pure FS surface — if it throws (programmer error in the
+                    // walker, not a per-file fs error which is already swallowed
+                    // inside) we drop ambient context for this session rather
+                    // than crashing the engine loop. Doctor probe still surfaces
+                    // the hierarchy state for operator triage.
+                    ambientContextBlock = '';
+                }
+            }
             let traverseResult;
             // Leak L22 (2026-05-27): `--bare` skips the parent-dir PUGI.md /
             // AGENTS.md / CLAUDE.md / GEMINI.md walk-up. The engine sees only
@@ -548,7 +574,14 @@ export class NativePugiEngineAdapter {
                             // pattern instead of re-issuing the same refused call.
                             denialTracking,
                         }),
-                        systemPrompt: systemPromptFor(kind),
+                        // Leak L32 (2026-05-27): ambient `PUGI.md` hierarchy block
+                        // prepended once at session boot. When the walk found
+                        // nothing OR bare mode is on, `ambientContextBlock === ''`
+                        // and the system prompt is unchanged — no leading blank
+                        // line, no empty wrapper tag.
+                        systemPrompt: ambientContextBlock
+                            ? `${ambientContextBlock}\n\n${systemPromptFor(kind)}`
+                            : systemPromptFor(kind),
                         // β5a R5+R6+P1: per-turn `<context>` prefix + intent marker
                         // applied above. Falls back to verbatim `task.prompt` when
                         // both the prefix block is empty AND the intent classifier

package/dist/core/pugi-md/context-injector.js

@@ -0,0 +1,76 @@
+/**
+ * Aggregate byte cap on the full rendered block. 96 KB = 3 files at
+ * the per-file cap, which is enough for cwd + parent + homedir while
+ * leaving plenty of prompt budget for the rest of the system prompt.
+ * Anything beyond is replaced with a truncation marker.
+ */
+export const MAX_INJECT_BYTES = 96 * 1024;
+/**
+ * Marker line emitted when the aggregate cap is hit. Visible to the
+ * model so it knows ambient context was clipped; visible to the
+ * operator via the doctor probe so they can decide whether to trim
+ * their `PUGI.md` hierarchy.
+ */
+export const TRUNCATION_MARKER = '<ambient-context-truncated reason="aggregate-cap" />';
+/**
+ * Render a HierarchyFile array into the system-prompt block. Returns
+ * `''` when `files` is empty. Each file becomes one
+ * `<ambient-context source="..." level="...">...</ambient-context>`
+ * stanza separated by a single newline.
+ *
+ * Determinism: same input always produces byte-identical output.
+ */
+export function renderAmbientContext(files) {
+    if (files.length === 0)
+        return '';
+    const stanzas = [];
+    let bytes = 0;
+    let truncated = false;
+    for (const file of files) {
+        const stanza = renderStanza(file);
+        const stanzaBytes = Buffer.byteLength(stanza, 'utf8') + 1; // newline join cost
+        if (bytes + stanzaBytes > MAX_INJECT_BYTES) {
+            truncated = true;
+            break;
+        }
+        stanzas.push(stanza);
+        bytes += stanzaBytes;
+    }
+    if (truncated)
+        stanzas.push(TRUNCATION_MARKER);
+    return stanzas.join('\n');
+}
+/**
+ * Build a single `<ambient-context>` stanza for one HierarchyFile.
+ * The `source` attribute carries the absolute path (after realpath)
+ * so the model can cite which file a piece of guidance came from
+ * when it explains its decisions to the operator.
+ */
+function renderStanza(file) {
+    const sourceAttr = escapeAttr(file.path);
+    const levelAttr = String(file.level);
+    // No trailing newline inside `content` — the join adds one between
+    // stanzas. Trimming the file's trailing whitespace keeps the tag
+    // close to the content for readability when an engineer dumps the
+    // assembled prompt for debugging.
+    const trimmed = file.content.replace(/\s+$/g, '');
+    return [
+        `<ambient-context source="${sourceAttr}" level="${levelAttr}">`,
+        trimmed,
+        `</ambient-context>`,
+    ].join('\n');
+}
+/**
+ * Escape an XML attribute value. We expect operator-controlled paths
+ * (not adversarial input) but `&`, `"` and `<` are still possible in
+ * symlinked / unicode paths so we escape them defensively. The model
+ * has been trained to read this attribute as opaque metadata.
+ */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=context-injector.js.map

package/dist/core/pugi-md/walk-up.js

@@ -0,0 +1,207 @@
+/**
+ * Leak L32 (2026-05-27) — `PUGI.md` hierarchy walk-up to `$HOME`.
+ *
+ * Claude Code walks from `cwd` upward toward the user's homedir and
+ * concatenates every `CLAUDE.md` it finds at each intermediate level
+ * (deepest overrides shallowest). Pugi parity: same walk, looking for
+ * `PUGI.md` first at each level and accepting `CLAUDE.md` as a fallback
+ * — operators often have a leftover `~/CLAUDE.md` or a parent-dir
+ * `CLAUDE.md` from a previous Claude Code session and we want their
+ * ambient guidance picked up automatically without a migration step.
+ *
+ * Why this is a separate module from `core/context/markdown-traverse.ts`:
+ *
+ *   - `markdown-traverse.ts` is the *workspace-bounded* walk (cwd → up
+ *     to but NOT including `workspaceRoot`). It guards every read by
+ *     `realpathSync` containment against the workspace root and
+ *     refuses to escape — by design, because the per-dir markdown is
+ *     part of the project's first-party context.
+ *
+ *   - This module is the *home-bounded* walk (cwd → up to `homedir()`,
+ *     OR until depth limit). It picks up the operator's personal /
+ *     global guidance that lives ABOVE the workspace root. The two
+ *     surfaces are complementary: workspace markdown encodes project
+ *     conventions; this hierarchy walk encodes operator-level taste
+ *     (preferred libraries, "always run prettier", style guides).
+ *
+ * Contract:
+ *
+ *   - Walks from `cwd` upward. At each directory checks `PUGI.md`
+ *     (preferred); when absent falls back to `CLAUDE.md`. Only ONE
+ *     file per level is loaded — preferred wins.
+ *   - Stops at `homedir()` INCLUSIVE — the file at `~/PUGI.md` or
+ *     `~/CLAUDE.md` IS loaded (Claude Code parity: a `~/CLAUDE.md`
+ *     applies to every project the operator opens).
+ *   - Hard depth cap of `MAX_WALK_DEPTH` (20) directories regardless
+ *     of how far cwd is from homedir; defense against symlinked or
+ *     malicious cwd values.
+ *   - Per-file byte cap `MAX_FILE_BYTES` (32 KB); over-cap files are
+ *     truncated, not rejected, so a runaway `PUGI.md` does not break
+ *     the prompt budget.
+ *   - Returns shallow-to-deep order (cwd FIRST, homedir LAST). The
+ *     caller is responsible for rendering precedence — Claude Code's
+ *     rule is "deeper overrides shallower", which means the LAST
+ *     entry in the rendered system prompt wins. Our order matches
+ *     that convention so the context injector can splice directly.
+ *
+ * Safety:
+ *
+ *   - No `realpath` on the directories themselves: the operator's
+ *     cwd may live under a workspace symlink (common with macOS
+ *     `/private/var/...`) and we want to honor what the operator
+ *     sees in their shell. We DO resolve the candidate file via
+ *     `realpathSync` before reading, but only to defeat
+ *     symlinks-pointing-outside-homedir attacks; an off-tree symlink
+ *     is skipped silently.
+ *   - Catch + skip every fs error per file. The walk-up surface MUST
+ *     NEVER break engine boot — missing read perms on a parent dir
+ *     is the common case (e.g. `/etc` on a corp laptop) and the
+ *     fallback is "no ambient context", not a crash.
+ *
+ * Pure module: no logging, no network, no fs writes.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/**
+ * Hard ceiling on parent-dir traversal depth. 20 is generous — even
+ * deep monorepo layouts rarely sit more than 8-10 levels below the
+ * homedir on a developer's laptop. The cap exists so a misconfigured
+ * cwd (e.g. cwd outside the user's home filesystem entirely) cannot
+ * cause a multi-second fs scan of unrelated directories.
+ */
+export const MAX_WALK_DEPTH = 20;
+/**
+ * Per-file byte cap. 32 KB matches the per-dir markdown traverse
+ * aggregate budget — generous enough for a fully written-out
+ * project / personal `PUGI.md` (~8000 words) while keeping any one
+ * file from blowing the prompt budget on its own.
+ */
+export const MAX_FILE_BYTES = 32 * 1024;
+/**
+ * Filenames consulted at each level, in lookup order. `PUGI.md` is
+ * preferred — when both files coexist in a directory the Pugi-native
+ * file wins and the Claude Code shim is ignored. This is the same
+ * precedence used by `markdown-traverse.ts` for workspace-bounded
+ * walks; keeping the two surfaces consistent removes the "why does
+ * Pugi sometimes read CLAUDE.md and sometimes PUGI.md?" foot-gun.
+ */
+export const HIERARCHY_SOURCES = ['PUGI.md', 'CLAUDE.md'];
+/**
+ * Walk from `cwd` upward, collecting ambient `PUGI.md` / `CLAUDE.md`
+ * files at each level until we reach the homedir (inclusive) or the
+ * depth cap.
+ *
+ * Returns an array ordered shallowest-first (cwd → homedir). When no
+ * files are found, returns `[]`. When `cwd` is OUTSIDE the homedir
+ * tree (e.g. the operator runs `pugi` from `/tmp`), the walk still
+ * proceeds upward but stops the moment we reach a filesystem root
+ * without ever entering the homedir — useful for ops/admin invocations
+ * where there is genuinely no personal context to load.
+ */
+export function walkUpPugiMd(cwd, opts = {}) {
+    const limit = clampLimit(opts.limit);
+    const home = opts.homedir;
+    let absCwd;
+    try {
+        absCwd = resolve(cwd);
+    }
+    catch {
+        return [];
+    }
+    const absHome = home ? resolve(home) : undefined;
+    const results = [];
+    let current = absCwd;
+    let level = 0;
+    const visited = new Set();
+    while (level <= limit) {
+        if (visited.has(current))
+            break; // pathological symlink loop guard
+        visited.add(current);
+        const found = tryLoadDirectory(current, level);
+        if (found)
+            results.push(found);
+        // Inclusive home boundary: load home if we are here, then stop.
+        if (absHome && current === absHome)
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root before homedir
+        current = parent;
+        level += 1;
+    }
+    return results;
+}
+/**
+ * Pick the first matching file in `dir`, read + cap it, and produce
+ * a HierarchyFile row. Returns `undefined` when no file in
+ * `HIERARCHY_SOURCES` exists or all reads error out (perms, symlink
+ * escape, etc.). NEVER throws — fs errors degrade to "no file at
+ * this level".
+ */
+function tryLoadDirectory(dir, level) {
+    for (const source of HIERARCHY_SOURCES) {
+        const candidate = resolve(dir, source);
+        if (!existsSync(candidate))
+            continue;
+        // Realpath the FILE to defeat symlink-points-elsewhere attacks.
+        // We do not realpath the directory itself — operators often run
+        // pugi from inside a workspace symlink and the walk should honor
+        // the path they see.
+        let realPath;
+        try {
+            realPath = realpathSync(candidate);
+        }
+        catch {
+            // Broken symlink or perms issue on the link itself. Skip this
+            // file and try the next source in the same directory.
+            continue;
+        }
+        let rawBytes;
+        try {
+            rawBytes = statSync(realPath).size;
+        }
+        catch {
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(realPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let truncated = false;
+        if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+            // Trim by character index sized to the byte cap. Mild over-trim
+            // on multi-byte boundaries is acceptable — we never under-trim
+            // (we'd exceed the cap) and the truncation is operator-visible
+            // via the `truncated` flag.
+            content = content.slice(0, MAX_FILE_BYTES);
+            truncated = true;
+        }
+        return {
+            path: realPath,
+            content,
+            level,
+            source,
+            truncated,
+            rawBytes,
+        };
+    }
+    return undefined;
+}
+/**
+ * Bound the limit to `[0, MAX_WALK_DEPTH]`. A negative or zero value
+ * still permits the cwd-level file to load (level 0 is always
+ * considered) — passing `limit: 0` means "current directory only".
+ */
+function clampLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isFinite(limit))
+        return MAX_WALK_DEPTH;
+    if (limit < 0)
+        return 0;
+    if (limit > MAX_WALK_DEPTH)
+        return MAX_WALK_DEPTH;
+    return Math.floor(limit);
+}
+//# sourceMappingURL=walk-up.js.map