@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

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

@@ -1,3 +1,10 @@
+// PR-CLI-SERVER-VERSION-HANDSHAKE (#225). The interceptor stamps the
+// outbound X-Pugi-Cli-Version header, inspects the inbound recommended/
+// server-version headers, and throws PugiCliUpgradeRequiredError on a
+// 426 server response. The top-level catch in `runtime/cli.ts` /
+// `index.ts` renders the upgrade message and exits 1.
+import { assertNotUpgradeRequired, injectClientVersionHeader, inspectVersionResponse, } from '../transport/version-interceptor.js';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
 /**
  * Anvil-backed engine loop client.
  *
@@ -54,23 +61,77 @@ export class AnvilEngineLoopClient {
             options.signal.addEventListener('abort', onAbort);
         const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
         try {
+            // PR-CLI-SERVER-VERSION-HANDSHAKE (#225). Stamp the outbound
+            // X-Pugi-Cli-Version header so the admin-api middleware can
+            // decide whether to honour, soft-warn, or 426 this request.
+            const outboundHeaders = injectClientVersionHeader({
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.config.apiKey}`,
+                'user-agent': 'pugi-cli/0.0.1',
+            }, PUGI_CLI_VERSION);
             const res = await fetch(url, {
                 method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${this.config.apiKey}`,
-                    'user-agent': 'pugi-cli/0.0.1',
-                },
+                headers: outboundHeaders,
                 body: JSON.stringify({
                     personaSlug: options.personaSlug,
                     messages,
                     tools,
                     maxTokens: options.maxTokens,
                     temperature: options.temperature,
+                    // β1 (audit E2): the admin-api `EngineRequestDto` accepts
+                    // these optional fields (see `pugi-engine.controller.ts:230`
+                    // EngineRequestDto schema). Before this fix the CLI dropped
+                    // them, which forced the controller to fall back to legacy
+                    // per-persona resolution + emit `command="(none)"` in its
+                    // structured logs. `undefined` keys are stripped by
+                    // `JSON.stringify` so the payload stays clean for fixture
+                    // clients that exact-match the body shape.
+                    command: options.command,
+                    // β1a r1: `tag` is `EngineDispatchTag` object shape now —
+                    // `JSON.stringify` serialises it as `{tag, priority?,
+                    // budget_hint?}` matching `EngineDispatchTagDto`. Previously
+                    // this was a bare string and the server's `IsIn` validator
+                    // rejected every payload with HTTP 400.
+                    tag: options.tag,
+                    model: options.model,
                 }),
                 signal: controller.signal,
             });
             const text = await res.text();
+            // PR-CLI-SERVER-VERSION-HANDSHAKE: cache server-recommended +
+            // server-version headers so UpdateBanner / `pugi doctor` can
+            // surface them, then short-circuit on 426 by throwing
+            // PugiCliUpgradeRequiredError. The throw bubbles to the
+            // top-level catch in index.ts which renders the upgrade banner.
+            // The getter shim handles both real `Response` (`.headers.get`)
+            // and minimal fixture/stub responses (`.headers?.[name]`) so
+            // existing transport tests that mock `fetch` with `{status, text}`
+            // don't need to grow a Headers polyfill just to keep passing.
+            //
+            // Cache poison guard: skip the inspect step on 426. A hostile
+            // upstream (proxy with a compromised cert pin, or a transient MITM
+            // on a coffee-shop network) could otherwise forge an
+            // `X-Pugi-Cli-Upgrade-Recommended` header alongside a 426 status
+            // and poison `cachedServerRecommendation` for the rest of the REPL
+            // session — `UpdateBanner` would then surface attacker-chosen
+            // version strings to the operator. The 426 body still carries the
+            // legitimate `recommendedVersion` field, which assertNotUpgrade-
+            // Required parses + throws with, so the operator-facing banner
+            // remains accurate via the error path.
+            if (res.status !== 426) {
+                inspectVersionResponse((name) => {
+                    const h = res.headers;
+                    if (h && typeof h.get === 'function') {
+                        return h.get(name);
+                    }
+                    if (h && typeof h === 'object') {
+                        const lowered = h[name.toLowerCase()];
+                        return lowered ?? null;
+                    }
+                    return null;
+                });
+            }
+            assertNotUpgradeRequired(res.status, text, PUGI_CLI_VERSION);
             if (res.status === 200) {
                 try {
                     const json = JSON.parse(text);
@@ -119,6 +180,55 @@ export class AnvilEngineLoopClient {
                 };
             }
             if (res.status === 401 || res.status === 403) {
+                // 403 has two distinct causes:
+                //   1. genuinely invalid / expired token (auth_missing) — the
+                //      old default.
+                //   2. tenant authenticated successfully but the privacy mode
+                //      (strict / balanced policy) refused upstream LLM dispatch.
+                //      The admin-api returns
+                //      `{ code: 'privacy_strict_upstream_blocked', mode, model,
+                //         message: '...switch via pugi config set privacy=...' }`.
+                //      Reported as `auth_missing` the user runs `pugi login`
+                //      again, which does nothing — the actual fix is a privacy-
+                //      mode change. Parse the body and route accordingly.
+                // (2026-05-27 P0.3 — dogfood surfaced this on /api/pugi/engine
+                // for a strict-mode tenant; see memory feedback_no_fake_dispatch_promises
+                // for the broader "misleading error" pattern.)
+                try {
+                    const parsed = text ? JSON.parse(text) : null;
+                    // 2026-05-27 dogfood cycle 2: distinct error code for the
+                    // infra-side "PII scrubber down" case. Previously the engine
+                    // server returned `privacy_strict_upstream_blocked` here even
+                    // when the tenant was on BALANCED (the scrubber crash forced
+                    // a fail-closed). Operators chased the wrong fix ("switch
+                    // privacy") for hours. Server now emits
+                    // `pii_scrubber_unavailable` — surface a distinct remediation
+                    // that points at the infra side, not the operator's privacy
+                    // posture.
+                    if (parsed?.code === 'pii_scrubber_unavailable') {
+                        return {
+                            stop: 'error',
+                            code: 'privacy_blocked',
+                            message: parsed.message ?? 'PII scrubber unavailable; privacy filter refused dispatch.',
+                            remediation: 'Infra-side issue (not your tenant privacy mode). Wait for ops to restore ' +
+                                'the PiiScrubberService, OR temporarily switch your tenant to permissive via ' +
+                                '`pugi config set privacy=permissive`.',
+                        };
+                    }
+                    if (parsed?.code === 'privacy_strict_upstream_blocked' || parsed?.code === 'privacy_blocked') {
+                        return {
+                            stop: 'error',
+                            code: 'privacy_blocked',
+                            message: parsed.message ?? 'Tenant privacy mode forbids upstream LLM dispatch.',
+                            remediation: 'pugi config set privacy=balanced — OR configure a self-hosted Anvil model.',
+                        };
+                    }
+                }
+                catch {
+                    // Body not JSON — fall through to the generic auth_missing
+                    // branch below; the 200-char text echo on `failed` will at
+                    // least give the operator the raw response to triage.
+                }
                 return {
                     stop: 'error',
                     code: 'auth_missing',

package/dist/core/engine/auto-compact.js

@@ -0,0 +1,179 @@
+/**
+ * Crude token-count heuristic mirroring `runEngineLoop`'s fallback
+ * accounting (transcript char count / 4). The CLI does not have access
+ * to a real tokenizer pre-flight — the runtime returns `usage.totalTokens`
+ * only on the server response, which is too late for our pre-turn gate.
+ * char/4 is in the right order of magnitude for English/TS and matches
+ * what the loop's own fallback uses on `tokensUsed === 0` upstream.
+ */
+export function estimateTranscriptTokens(messages) {
+    let chars = 0;
+    for (const m of messages) {
+        chars += m.content.length;
+        const calls = m.toolCalls ?? [];
+        for (const c of calls) {
+            chars += c.name.length + c.arguments.length;
+        }
+    }
+    return Math.ceil(chars / 4);
+}
+const FILE_TOOL_NAMES = new Set([
+    'read',
+    'write',
+    'edit',
+    'multi_edit',
+    'multiEdit',
+]);
+/**
+ * Walk the dropped slice and pull out tool-call metadata. We parse the
+ * `arguments` JSON best-effort — a bad parse is harmless here because
+ * the executor surfaced the canonical error to the model already; the
+ * gist just under-counts that one call.
+ */
+export function summarizeDroppedTurns(dropped) {
+    let toolCalls = 0;
+    let bashCalls = 0;
+    const files = new Set();
+    for (const m of dropped) {
+        if (m.role === 'assistant') {
+            const calls = m.toolCalls ?? [];
+            toolCalls += calls.length;
+            for (const c of calls) {
+                if (c.name === 'bash') {
+                    bashCalls += 1;
+                    continue;
+                }
+                if (FILE_TOOL_NAMES.has(c.name)) {
+                    const p = extractPath(c.arguments);
+                    if (p)
+                        files.add(p);
+                }
+            }
+        }
+    }
+    return {
+        toolCalls,
+        fileCount: files.size,
+        bashCalls,
+        messagesDropped: dropped.length,
+    };
+}
+function extractPath(rawArgs) {
+    if (!rawArgs)
+        return null;
+    try {
+        const parsed = JSON.parse(rawArgs);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const obj = parsed;
+            const path = obj['path'] ?? obj['filePath'];
+            if (typeof path === 'string' && path.length > 0)
+                return path;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Format the deterministic gist string spliced into the synthetic
+ * system message. Stable shape so spec assertions and operator
+ * logs do not drift turn-over-turn.
+ */
+export function renderAutoCompactSentinel(stats) {
+    return (`[auto-compact] Earlier turns ` +
+        `(${stats.toolCalls} tool calls, ${stats.fileCount} files read, ${stats.bashCalls} bash commands) ` +
+        `summarized to free transcript headroom. ` +
+        `Recent turns and the original task remain in context; ` +
+        `re-read any earlier file by name if you need its contents again.`);
+}
+/**
+ * Minimum transcript length (in messages) before compact is allowed.
+ * We always retain `system + user` (the first 2) + the last 2 turns,
+ * so anything <= 4 messages has nothing in the middle to drop.
+ * Compacting на 4-message transcript would either be a no-op or
+ * accidentally drop the user's original task.
+ */
+export const MIN_COMPACT_TRANSCRIPT_LENGTH = 5;
+/**
+ * Pure gate. Returns `compact` when ALL of:
+ *   - `config.enabled` is true
+ *   - estimated transcript tokens >= `thresholdRatio * maxTokens`
+ *   - transcript length >= 5 (need history to drop)
+ */
+export function evaluateAutoCompactDecision(input) {
+    const usedTokens = estimateTranscriptTokens(input.transcript);
+    if (!input.config.enabled) {
+        return { kind: 'skip', reason: 'disabled', usedTokens };
+    }
+    if (input.transcript.length < MIN_COMPACT_TRANSCRIPT_LENGTH) {
+        return { kind: 'skip', reason: 'transcript-too-short', usedTokens };
+    }
+    const thresholdTokens = Math.floor(input.config.thresholdRatio * input.maxTokens);
+    if (usedTokens < thresholdTokens) {
+        return { kind: 'skip', reason: 'below-threshold', usedTokens };
+    }
+    return { kind: 'compact', usedTokens, thresholdTokens };
+}
+/**
+ * Rewrite the transcript: keep the first two messages (system + user
+ * task), drop the middle (assistant + tool turns), insert a synthetic
+ * system sentinel summarizing what was dropped, then re-append the
+ * last 2 messages so the model has the most-recent tool result + its
+ * own last reply in full fidelity.
+ *
+ * Precondition: caller has already checked the decision is `compact`
+ * (length >= MIN_COMPACT_TRANSCRIPT_LENGTH). The function still guards
+ * with a defensive identity-return on shorter transcripts so a careless
+ * caller cannot corrupt the prefix.
+ */
+export function compactTranscript(transcript) {
+    const preUsedTokens = estimateTranscriptTokens(transcript);
+    if (transcript.length < MIN_COMPACT_TRANSCRIPT_LENGTH) {
+        return {
+            transcript: transcript.slice(),
+            droppedCount: 0,
+            gist: '',
+            stats: { toolCalls: 0, fileCount: 0, bashCalls: 0, messagesDropped: 0 },
+            preUsedTokens,
+            postUsedTokens: preUsedTokens,
+        };
+    }
+    // Always retain: index 0 (system) + index 1 (original user task) +
+    // last 2 messages. The middle slice is what gets summarised.
+    const head = transcript.slice(0, 2);
+    const tail = transcript.slice(-2);
+    const middle = transcript.slice(2, -2);
+    const stats = summarizeDroppedTurns(middle);
+    const gist = renderAutoCompactSentinel(stats);
+    const sentinelMessage = {
+        role: 'system',
+        content: gist,
+    };
+    const next = [...head, sentinelMessage, ...tail];
+    const postUsedTokens = estimateTranscriptTokens(next);
+    return {
+        transcript: next,
+        droppedCount: middle.length,
+        gist,
+        stats,
+        preUsedTokens,
+        postUsedTokens,
+    };
+}
+/**
+ * Convenience composer used by `runEngineLoop`: evaluate → compact in
+ * one shot. Returns `null` when the decision was `skip` so the loop
+ * driver can branch cheaply без destructuring two layers of records.
+ */
+export function maybeCompact(transcript, maxTokens, config) {
+    const decision = evaluateAutoCompactDecision({
+        transcript,
+        maxTokens,
+        config,
+    });
+    if (decision.kind === 'skip')
+        return null;
+    return compactTranscript(transcript);
+}
+//# sourceMappingURL=auto-compact.js.map

package/dist/core/engine/budgets.js

@@ -0,0 +1,155 @@
+/**
+ * Auto-compact (mid-loop transcript summarization) default trip point as
+ * a fraction of the per-command `maxTokens` envelope. CEO P1 #14 (CC
+ * parity): when transcript char-count tokens cross 75% of the budget,
+ * the engine loop drops the middle turns and inserts a deterministic
+ * `[auto-compact]` sentinel so the loop can continue без the model
+ * tripping the `budget_exhausted` terminal status mid-build.
+ *
+ * Empirically — `pugi code "big refactor"` hits the 80k cap on turn 4-5
+ * and refuses to finish; `pugi fix` does the same at 50k. Auto-compact
+ * keeps the recent N turns + a one-line gist of the dropped tool calls
+ * so the model retains the most recent state without paying for the
+ * full prefix.
+ *
+ * Operators can opt out / retune via `.pugi/settings.json`:
+ *
+ *   {
+ *     "autoCompact": { "enabled": true, "thresholdRatio": 0.75 }
+ *   }
+ *
+ * Bad values fall back silently to the default — the engine loop never
+ * crashes on a malformed settings field (mirrors `resolveBudget`).
+ */
+export const AUTO_COMPACT_THRESHOLD_RATIO = 0.75;
+export const DEFAULT_AUTO_COMPACT_CONFIG = {
+    enabled: true,
+    thresholdRatio: AUTO_COMPACT_THRESHOLD_RATIO,
+};
+/**
+ * Pull the auto-compact override from `.pugi/settings.json`. Uses the
+ * same defensive-cast pattern as `readSettingsBudget` so an unknown
+ * field shape silently falls back к defaults (the gate is a comfort
+ * feature; a malformed settings line must not break the engine loop).
+ *
+ * Returns the merged config — caller never sees `undefined`.
+ */
+export function resolveAutoCompactConfig(settings) {
+    if (!settings)
+        return DEFAULT_AUTO_COMPACT_CONFIG;
+    const root = settings.autoCompact;
+    if (!root || typeof root !== 'object' || Array.isArray(root)) {
+        return DEFAULT_AUTO_COMPACT_CONFIG;
+    }
+    const r = root;
+    const enabledRaw = r['enabled'];
+    const thresholdRaw = r['thresholdRatio'];
+    const enabled = typeof enabledRaw === 'boolean'
+        ? enabledRaw
+        : DEFAULT_AUTO_COMPACT_CONFIG.enabled;
+    let thresholdRatio = DEFAULT_AUTO_COMPACT_CONFIG.thresholdRatio;
+    if (typeof thresholdRaw === 'number' && Number.isFinite(thresholdRaw)) {
+        if (thresholdRaw > 0 && thresholdRaw <= 1) {
+            thresholdRatio = thresholdRaw;
+        }
+    }
+    return { enabled, thresholdRatio };
+}
+/**
+ * β1 defaults. Source of truth for the per-command budget envelope.
+ * The runtime is allowed to look these up directly (no need to round
+ * trip through settings.json when no override is in play).
+ *
+ * 2026-05-28 bump (post-Wave-7 hooks-v2 + 6-perm-modes + auto-classifier
+ * added ~12K tokens of system-prompt + tools-schema overhead per turn):
+ * `code` 30k → 80k и `fix` 30k → 50k so a single-file refactor on a
+ * 1000-line source file no longer exhausts the budget on turn 2.
+ * Empirical: smoke `pugi code "сделай snake.html"` on beta.37 burned
+ * 36k/30k after 2 tool calls; beta.36 same task closed in 8k. The Wave-7
+ * additions are good (Claude Code parity), but the budget cap did not move with
+ * them. Claude Code's `code` default is ~80k; matching that restores headroom.
+ */
+export const beta1DefaultBudgets = {
+    fix: { maxTokens: 50_000, maxToolCalls: 20 },
+    code: { maxTokens: 80_000, maxToolCalls: 20 },
+    build: { maxTokens: 200_000, maxToolCalls: 30 },
+    plan: { maxTokens: 200_000, maxToolCalls: 8 },
+    explain: { maxTokens: 40_000, maxToolCalls: 10 },
+    review_triple: { maxTokens: 100_000, maxToolCalls: 10 },
+};
+/**
+ * Hard upper bounds. Anything above this is treated as user error
+ * (likely a typo or misplaced decimal) and rejected by
+ * `assertBudgetWithinTier`. Stops a careless settings.json edit from
+ * silently authorising a 100M-token run.
+ */
+export const HARD_MAX_TOKENS = 5_000_000;
+export const HARD_MAX_TOOL_CALLS = 500;
+/**
+ * Compute the effective budget for a given command, applying:
+ *   1. β1 defaults
+ *   2. settings.json `budgets.<command>` partial overrides
+ *   3. task-level override (caller-provided, e.g. CLI `--max-tokens`)
+ *
+ * Throws `BudgetConfigError` when the resolved budget exceeds the
+ * HARD_MAX_* caps so misconfigured settings.json fails fast.
+ */
+export function resolveBudget(command, settings, override) {
+    const base = beta1DefaultBudgets[command];
+    const settingsBudget = readSettingsBudget(settings, command);
+    const resolved = {
+        maxTokens: override?.maxTokens ??
+            settingsBudget?.maxTokens ??
+            base.maxTokens,
+        maxToolCalls: override?.maxToolCalls ??
+            settingsBudget?.maxToolCalls ??
+            base.maxToolCalls,
+    };
+    assertBudgetWithinTier(command, resolved);
+    return resolved;
+}
+export class BudgetConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BudgetConfigError';
+    }
+}
+export function assertBudgetWithinTier(command, budget) {
+    if (!Number.isFinite(budget.maxTokens) || budget.maxTokens <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens must be a positive number, got ${budget.maxTokens}`);
+    }
+    if (!Number.isFinite(budget.maxToolCalls) || budget.maxToolCalls <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls must be a positive number, got ${budget.maxToolCalls}`);
+    }
+    if (budget.maxTokens > HARD_MAX_TOKENS) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens=${budget.maxTokens} exceeds hard cap ${HARD_MAX_TOKENS}`);
+    }
+    if (budget.maxToolCalls > HARD_MAX_TOOL_CALLS) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls=${budget.maxToolCalls} exceeds hard cap ${HARD_MAX_TOOL_CALLS}`);
+    }
+}
+/**
+ * Pull a settings.json budget override for the given command, with
+ * defensive typing. `PugiSettings` does not yet declare `budgets`
+ * formally (β1 is the first sprint to land it) so we cast via unknown
+ * and validate each field at the boundary.
+ */
+function readSettingsBudget(settings, command) {
+    if (!settings)
+        return undefined;
+    const root = settings.budgets;
+    if (!root || typeof root !== 'object' || Array.isArray(root))
+        return undefined;
+    const map = root;
+    const entry = map[command];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return undefined;
+    const e = entry;
+    const out = {};
+    if (typeof e['maxTokens'] === 'number')
+        out.maxTokens = e['maxTokens'];
+    if (typeof e['maxToolCalls'] === 'number')
+        out.maxToolCalls = e['maxToolCalls'];
+    return out;
+}
+//# sourceMappingURL=budgets.js.map

package/dist/core/engine/context-prefix.js

@@ -0,0 +1,155 @@
+/** Hard cap on the rendered `<context>` block, bytes. */
+export const CONTEXT_PREFIX_MAX_BYTES = 5 * 1024;
+/** Hard cap on working-set entries surfaced in the prefix. */
+export const CONTEXT_PREFIX_MAX_WORKING_SET = 50;
+/** Hard cap on per-dir markdown files surfaced inline. */
+export const CONTEXT_PREFIX_MAX_MARKDOWN = 3;
+/** Per-markdown-file inline excerpt cap, bytes. Keeps any one file from dominating. */
+export const CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES = 1024;
+/**
+ * Build the `<context>` block. Always returns a result — when there
+ * is nothing to surface (no cwd hint, no working set, no per-dir
+ * files), returns `{ block: '', bytes: 0, truncated: false, counts: ... }`
+ * so the caller can short-circuit the splice cleanly.
+ *
+ * Determinism: same input always produces byte-identical output. The
+ * working-set order comes from the caller's summary; we preserve it
+ * verbatim. Per-dir files are sorted by `distanceFromCwd` ascending
+ * (closest first) so two equal `TraversedMarkdown` arrays produce
+ * identical blocks.
+ */
+export function buildContextPrefix(input) {
+    const lines = [];
+    let bytes = 0;
+    let truncated = false;
+    // Walk a write-then-measure loop so we never overflow the byte cap.
+    // Each push checks budget; when full, set `truncated = true` and
+    // stop. The opener / closer tags always fit (small) — we reserve
+    // their byte cost up-front from the budget.
+    const opener = '<context>';
+    const closer = '</context>';
+    const reservedTagBytes = Buffer.byteLength(opener, 'utf8') + 1 + Buffer.byteLength(closer, 'utf8') + 1;
+    let budget = CONTEXT_PREFIX_MAX_BYTES - reservedTagBytes;
+    if (budget < 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: input.workingSet?.length ?? 0,
+                markdownIncluded: 0,
+                markdownTotal: input.traversedMarkdown?.length ?? 0,
+            },
+        };
+    }
+    const pushLine = (line) => {
+        const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // newline
+        if (lineBytes > budget) {
+            truncated = true;
+            return false;
+        }
+        lines.push(line);
+        budget -= lineBytes;
+        bytes += lineBytes;
+        return true;
+    };
+    // cwd — always cheap, always first.
+    pushLine(`cwd: ${input.cwdRelative || '.'}`);
+    // intent hint, if provided.
+    if (input.intentHint) {
+        pushLine(`intent: ${input.intentHint}`);
+    }
+    // Working set — render `open-files:` only when there is at least one entry.
+    const wsTotal = input.workingSet?.length ?? 0;
+    let wsIncluded = 0;
+    if (wsTotal > 0 && input.workingSet) {
+        const wsCap = Math.min(CONTEXT_PREFIX_MAX_WORKING_SET, wsTotal);
+        pushLine('open-files:');
+        for (let i = 0; i < wsCap; i += 1) {
+            const entry = input.workingSet[i];
+            if (!entry)
+                continue;
+            const ok = pushLine(`  - ${entry.absPath}`);
+            if (!ok)
+                break;
+            wsIncluded += 1;
+        }
+        if (wsTotal > wsCap) {
+            pushLine(`  ... (+${wsTotal - wsCap} more)`);
+            truncated = truncated || true;
+        }
+    }
+    // Per-dir markdown — closest-first, max 3, each capped to 1 KB excerpt.
+    const mdTotal = input.traversedMarkdown?.length ?? 0;
+    let mdIncluded = 0;
+    if (mdTotal > 0 && input.traversedMarkdown) {
+        const sorted = [...input.traversedMarkdown].sort((a, b) => a.distanceFromCwd - b.distanceFromCwd);
+        const top = sorted.slice(0, CONTEXT_PREFIX_MAX_MARKDOWN);
+        if (top.length > 0) {
+            pushLine('per-dir-conventions:');
+            for (const md of top) {
+                // Header line names the source file for traceability.
+                const header = `  [${md.resolvedPath}]`;
+                if (!pushLine(header))
+                    break;
+                // Excerpt: cap to 1 KB, single-line collapse (replace newlines
+                // with " | " so the YAML-ish block stays parseable by humans).
+                const excerpt = excerpt1KB(md.content);
+                // Indent two spaces so it nests under the file header.
+                const indented = excerpt.split('\n').map((l) => `    ${l}`).join('\n');
+                if (!pushLine(indented))
+                    break;
+                mdIncluded += 1;
+            }
+            if (mdTotal > top.length) {
+                pushLine(`  ... (+${mdTotal - top.length} more files; closest-3 shown)`);
+                truncated = truncated || true;
+            }
+        }
+    }
+    if (lines.length === 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: wsTotal,
+                markdownIncluded: 0,
+                markdownTotal: mdTotal,
+            },
+        };
+    }
+    const block = [opener, ...lines, closer].join('\n');
+    const totalBytes = Buffer.byteLength(block, 'utf8');
+    return {
+        block,
+        bytes: totalBytes,
+        truncated,
+        counts: {
+            workingSetIncluded: wsIncluded,
+            workingSetTotal: wsTotal,
+            markdownIncluded: mdIncluded,
+            markdownTotal: mdTotal,
+        },
+    };
+}
+/**
+ * Splice a built context block onto the front of a user message.
+ * Empty block → message returned verbatim (no leading blank line, no
+ * empty `<context>` tag).
+ */
+export function spliceContextPrefix(block, userMessage) {
+    if (block.length === 0)
+        return userMessage;
+    return `${block}\n\n${userMessage}`;
+}
+function excerpt1KB(content) {
+    const capped = content.length <= CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES
+        ? content
+        : content.slice(0, CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES);
+    // Trim trailing newlines so the YAML-ish render stays tight.
+    return capped.replace(/\s+$/g, '');
+}
+//# sourceMappingURL=context-prefix.js.map