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

package/dist/runtime/commands/doctor.js

@@ -49,6 +49,8 @@ import { probeMcp } from '../../core/diagnostics/probes/mcp.js';
 import { probeConfig } from '../../core/diagnostics/probes/config.js';
 import { probeSession } from '../../core/diagnostics/probes/session.js';
 import { probeDenialTracking } from '../../core/diagnostics/probes/denial-tracking.js';
+import { probeBareMode } from '../../core/diagnostics/probes/bare-mode.js';
+import { probePugiMdHierarchy } from '../../core/diagnostics/probes/pugi-md.js';
 /**
  * Default API URL when no PUGI_API_URL env override is set. Mirrors
  * the constant in `core/credentials.ts` (kept local to avoid an
@@ -206,6 +208,25 @@ export function buildDefaultProbes(ctx, options = {}) {
                 ...(options.denialTracking ? { tracker: options.denialTracking } : {}),
             }),
         },
+        // Leak L22 (2026-05-27): BARE MODE row. Always present so the JSON
+        // schema stays stable; status flips to `ok` when `--bare` or
+        // `PUGI_BARE=1` is active, otherwise `skipped`.
+        {
+            name: 'BARE MODE',
+            run: async () => probeBareMode({ env: ctx.env }),
+        },
+        // Leak L32 (2026-05-27): PUGI.md HIERARCHY row. Reports how many
+        // ambient `PUGI.md` / `CLAUDE.md` files the cwd → homedir walk
+        // discovered, and the closest path. `skipped` when bare mode is
+        // active (walk disabled) or zero files found.
+        {
+            name: 'PUGI.md HIERARCHY',
+            run: async () => probePugiMdHierarchy({
+                cwd: ctx.cwd,
+                homedir: ctx.home,
+                env: ctx.env,
+            }),
+        },
     ];
     return probes;
 }

package/dist/runtime/commands/feedback.js

@@ -0,0 +1,184 @@
+/**
+ * `pugi feedback` + `/feedback` slash — Leak L21 (2026-05-27).
+ *
+ * In-CLI feedback collector. Parity with Claude Code's `/feedback`
+ * built-in. The operator never has to leave the terminal to file a
+ * bug / feature / general comment / praise. The wizard collects:
+ *
+ *   1. category   (bug / feature / general / praise)
+ *   2. rating     (1-5)
+ *   3. comment    (multi-line free text)
+ *   4. optional   redacted session context (last 5 turns)
+ *   5. confirm    (final y/n)
+ *
+ * # Module contract
+ *
+ *   - This file owns the WIRING from the CLI surface (TTY mount,
+ *     non-TTY JSON, slash dispatcher) to the queue + submitter
+ *     modules. The corpus + redactor + queue persistence live in
+ *     `core/feedback/{queue.ts,submitter.ts}`. The Ink prompt lives
+ *     in `tui/feedback-prompt.tsx`. Both have zero coupling to the
+ *     CLI dispatch surface.
+ *
+ *   - `runFeedbackCommand` is the single entry point. Both the top-
+ *     level `pugi feedback` handler в `runtime/cli.ts` AND the in-REPL
+ *     `/feedback` slash dispatcher call it. The function returns the
+ *     resolved `FeedbackRunResult` so the slash dispatcher can route
+ *     the outcome message to the REPL's system pane without re-prompting.
+ *
+ *   - Exit code is ALWAYS 0. Feedback is a brand surface — never a
+ *     gate. Failures land as result variants; the wrapper never
+ *     turns a network blip into a non-zero shell exit.
+ *
+ *   - The random-source-style test seam: the run helper accepts an
+ *     `interactive` flag that the spec sets to false, plus an injected
+ *     `draft` so unit tests can drive the submit + queue branches
+ *     without mounting Ink.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { enqueueFeedback, feedbackQueuePath, flushFeedbackQueue, } from '../../core/feedback/queue.js';
+import { feedbackSubmitUrl, redactSessionContext, submitFeedback, } from '../../core/feedback/submitter.js';
+/**
+ * Drive one feedback round. The function is async because of the
+ * submit round-trip, but everything else (queue write, redaction) is
+ * sync — no surprise concurrency.
+ */
+export async function runFeedbackCommand(ctx) {
+    if (ctx.draft == null) {
+        return { kind: 'cancelled' };
+    }
+    const envelope = {
+        category: ctx.draft.category,
+        rating: ctx.draft.rating,
+        comment: ctx.draft.comment,
+        ts: new Date().toISOString(),
+        cliVersion: ctx.cliVersion,
+        ...(ctx.tier ? { tier: ctx.tier } : {}),
+    };
+    if (ctx.draft.includeSessionContext && ctx.sessionContext) {
+        const sc = ctx.sessionContext();
+        if (sc)
+            envelope.sessionContext = sc;
+    }
+    let result;
+    try {
+        result = await ctx.submit(envelope);
+    }
+    catch (err) {
+        // Defensive: a thrown submitter (should not happen — the live
+        // submitter catches everything) is treated as transient so the
+        // envelope lands in the queue.
+        const reason = err instanceof Error ? err.message : String(err);
+        result = { kind: 'transient', reason };
+    }
+    if (result.kind === 'ok') {
+        return { kind: 'submitted', envelope, httpStatus: result.httpStatus };
+    }
+    if (result.kind === 'transient') {
+        const path = enqueueFeedback(envelope, ctx.cwd);
+        return { kind: 'queued', envelope, path, reason: result.reason };
+    }
+    // permanent — log + drop
+    return {
+        kind: 'dropped',
+        envelope,
+        reason: result.reason,
+        httpStatus: result.httpStatus,
+    };
+}
+/**
+ * Render one human-readable toast for the operator. Centralised so the
+ * top-level `pugi feedback` shell handler + the in-REPL `/feedback`
+ * slash dispatcher agree on the copy.
+ */
+export function renderFeedbackToast(result) {
+    switch (result.kind) {
+        case 'submitted':
+            return 'Feedback submitted. Thank you.';
+        case 'queued':
+            return `Feedback queued locally. Will sync on next online run. (${result.path})`;
+        case 'cancelled':
+            return 'Feedback cancelled. Nothing was sent.';
+        case 'dropped':
+            return `Feedback rejected by server (${result.httpStatus}): ${result.reason}. Not queued.`;
+        case 'noop':
+            return `No feedback collected: ${result.reason}`;
+    }
+}
+/**
+ * Background queue flush. Invoked silently on session start so any
+ * envelopes that landed during an offline run get drained when the
+ * operator next has connectivity. The function never throws — it
+ * returns the flush stats so the caller can log them at debug level.
+ */
+export async function flushFeedbackQueueSilently(cwd, config) {
+    // Short-circuit when the queue file does not exist. Avoids a
+    // pointless `fs.stat` round-trip on every cold session start.
+    if (!existsSync(feedbackQueuePath(cwd))) {
+        return { attempted: 0, succeeded: 0, failed: 0 };
+    }
+    const result = await flushFeedbackQueue(cwd, async (env) => {
+        const r = await submitFeedback(env, config);
+        if (r.kind === 'ok')
+            return true;
+        if (r.kind === 'permanent') {
+            // Permanent failures are "done" from the queue's POV — they
+            // would never resolve on retry. Drop them so the queue does
+            // not grow without bound.
+            return true;
+        }
+        return false;
+    });
+    return {
+        attempted: result.attempted,
+        succeeded: result.succeeded,
+        failed: result.failed,
+    };
+}
+/**
+ * Re-exports — the spec imports these via the command module so the
+ * dependency graph in the test stays single-rooted.
+ */
+export { feedbackQueuePath, feedbackSubmitUrl, redactSessionContext, submitFeedback, };
+/**
+ * Read the persona conversation log if present. Best-effort: returns
+ * an empty list when the file is missing or malformed. The CLI's REPL
+ * persists transcripts via the session module at a canonical relative
+ * path under `.pugi/sessions/`. The shell-level `pugi feedback` does
+ * not have access to a live session, so it tries to pick up the most
+ * recent persisted one for the `--with-context` path.
+ *
+ * Intentionally tolerant — feedback works even with no transcript.
+ */
+export function readMostRecentTranscript(cwd, options = {}) {
+    // The CLI may persist sessions in several places depending on the
+    // surface. We probe the conventional default; the spec drives the
+    // function via a fixture file instead of a live REPL.
+    const candidate = resolve(cwd, '.pugi', 'sessions', 'latest.jsonl');
+    if (!existsSync(candidate))
+        return [];
+    try {
+        const text = readFileSync(candidate, 'utf8');
+        const lines = text.split('\n').filter((l) => l.trim().length > 0);
+        const turns = [];
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                if ((obj.role === 'user' || obj.role === 'assistant' || obj.role === 'system')
+                    && typeof obj.text === 'string') {
+                    turns.push({ role: obj.role, text: obj.text });
+                }
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        const cap = options.maxTurns ?? 5;
+        return turns.slice(-cap);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/runtime/commands/onboarding.js

@@ -0,0 +1,275 @@
+/**
+ * Leak L25 (2026-05-27) — `pugi onboarding` first-run wizard runner.
+ *
+ * Six-step interactive walk that lands a new operator on a configured
+ * Pugi:
+ *
+ *   1. Welcome + auth status     — suggests `pugi login` when no creds
+ *   2. Default permission mode   — plan / ask / allow / bypass (L6)
+ *   3. Output style              — default / terse / explanatory /
+ *                                  russian-formal / casual (L18)
+ *   4. MCP server pointer        — link to `pugi mcp add` (L13)
+ *   5. Telemetry consent         — off / anonymous / community
+ *   6. Recap card + marker touch — `pugi doctor` next-step hint
+ *
+ * Two execution modes:
+ *
+ *   - **Interactive (TTY + no `--non-interactive` flag)** — mount the
+ *     Ink wizard (`tui/onboarding-wizard.tsx`) and await the
+ *     operator's verdict step by step. The wizard returns a structured
+ *     `OnboardingVerdict` describing each chosen value (or "skip"
+ *     when the operator pressed Enter on the current-value row).
+ *
+ *   - **Non-interactive (CI, pipes, `--non-interactive`, `--json`)** —
+ *     skip the Ink mount. Print the current values + the wizard tip
+ *     so a scripted caller sees the structured envelope without an
+ *     unresponsive raw-mode prompt.
+ *
+ * Idempotency:
+ *
+ *   - Re-running the wizard reads the CURRENT persisted values (L6
+ *     `getGlobalDefaultMode`, L18 `resolveOutputStyle`, this module's
+ *     telemetry-state) and surfaces them as the highlighted row, so
+ *     pressing Enter on each step is a no-op.
+ *
+ *   - The marker file (`~/.pugi/.onboarded`) is touched on every
+ *     successful completion. The marker existence is what suppresses
+ *     the first-run hint on bare `pugi`; resetting it via
+ *     `pugi onboarding --reset` re-arms the hint without nuking
+ *     persisted values.
+ *
+ * Exit codes:
+ *   0 — wizard completed (interactive OR non-interactive path)
+ *   0 — `--reset` cleared the marker
+ *   2 — conflicting flags (e.g. `--reset` + a verdict flag)
+ *
+ * Exit code 0 for non-interactive is intentional: a CI caller running
+ * `pugi onboarding --non-interactive` to dump the current state should
+ * not see a non-zero rc; failures (fs EIO, unknown flag) raise to the
+ * caller via thrown errors which `runtime/cli.ts` catches.
+ */
+import { DEFAULT_PERMISSION_MODE, PERMISSION_MODES, PERMISSION_MODE_GLOSS, getGlobalDefaultMode, setGlobalDefaultMode, } from '../../core/permissions/index.js';
+import { OUTPUT_STYLES, OUTPUT_STYLE_SLUGS, } from '../../core/output-style/presets.js';
+import { resolveOutputStyle, setUserOutputStyle, } from '../../core/output-style/state.js';
+import { clearOnboarded, isOnboarded, markOnboarded, } from '../../core/onboarding/marker.js';
+import { TELEMETRY_CHOICES, readTelemetryChoice, writeTelemetryChoice, } from '../../core/onboarding/telemetry-state.js';
+/**
+ * Entry point. Parses argv, resolves the snapshot, optionally drives
+ * the wizard, writes verdicts to the L6 / L18 / telemetry tiers,
+ * touches the marker, and emits a single structured payload via
+ * `writeOutput`.
+ */
+export async function runOnboardingCommand(args, ctx) {
+    const flags = parseFlags(args);
+    if (flags === null) {
+        const snapshot = readSnapshot(ctx);
+        ctx.writeOutput(buildPayload({
+            status: 'invalid_flags',
+            before: snapshot,
+            after: snapshot,
+            hints: [],
+            message: invalidFlagsMessage(args),
+        }), invalidFlagsMessage(args));
+        return 2;
+    }
+    if (flags.reset) {
+        const before = readSnapshot(ctx);
+        clearOnboarded(ctx.env ?? process.env);
+        const after = readSnapshot(ctx);
+        const message = 'Onboarding marker cleared. Run `pugi onboarding` to walk the wizard again.';
+        ctx.writeOutput(buildPayload({
+            status: 'reset',
+            before,
+            after,
+            hints: [],
+            message,
+        }), `${message}\n`);
+        return 0;
+    }
+    const before = readSnapshot(ctx);
+    if (!ctx.interactive || flags.nonInteractive) {
+        const text = renderSnapshotCard(before, {
+            heading: 'Pugi onboarding — current configuration',
+            footer: 'Re-run `pugi onboarding` from a real terminal to walk the wizard interactively.',
+        });
+        ctx.writeOutput(buildPayload({
+            status: 'non_interactive',
+            before,
+            after: before,
+            hints: buildHints(before),
+            message: text,
+        }), `${text}\n`);
+        return 0;
+    }
+    const verdict = await invokeWizard(ctx, before);
+    if (verdict.cancelled) {
+        const text = 'Onboarding cancelled. No changes written.';
+        ctx.writeOutput(buildPayload({
+            status: 'cancelled',
+            before,
+            after: before,
+            hints: buildHints(before),
+            message: text,
+        }), `${text}\n`);
+        return 0;
+    }
+    applyVerdict(verdict, ctx);
+    markOnboarded(ctx.env ?? process.env);
+    const after = readSnapshot(ctx);
+    const text = renderSnapshotCard(after, {
+        heading: 'Setup complete.',
+        footer: 'Run `pugi doctor` to verify your environment.',
+    });
+    ctx.writeOutput(buildPayload({
+        status: 'completed',
+        before,
+        after,
+        hints: buildHints(after),
+        message: text,
+    }), `${text}\n`);
+    return 0;
+}
+/**
+ * Pure snapshot reader. Called twice per invocation (before + after)
+ * so the payload can surface the diff a scripted caller would see.
+ */
+export function readSnapshot(ctx) {
+    const permissionMode = getGlobalDefaultMode(ctx.homeDir) ?? DEFAULT_PERMISSION_MODE;
+    const styleResolution = resolveOutputStyle({
+        workspaceRoot: ctx.workspaceRoot,
+        env: ctx.env ?? process.env,
+    });
+    const telemetry = readTelemetryChoice({ env: ctx.env ?? process.env });
+    const previouslyOnboarded = isOnboarded(ctx.env ?? process.env);
+    return {
+        authPresent: ctx.authPresent,
+        permissionMode,
+        outputStyle: styleResolution.slug,
+        outputStyleSource: styleResolution.source,
+        telemetry,
+        previouslyOnboarded,
+    };
+}
+/**
+ * Apply the wizard's verdict. Each step is independent — operator can
+ * skip individual steps (verdict.X === null) and only the non-null
+ * values write through to disk.
+ */
+function applyVerdict(verdict, ctx) {
+    if (verdict.permissionMode !== null) {
+        setGlobalDefaultMode(verdict.permissionMode, ctx.homeDir);
+    }
+    if (verdict.outputStyle !== null) {
+        setUserOutputStyle(verdict.outputStyle, {
+            workspaceRoot: ctx.workspaceRoot,
+            env: ctx.env ?? process.env,
+        });
+    }
+    if (verdict.telemetry !== null) {
+        writeTelemetryChoice(verdict.telemetry, { env: ctx.env ?? process.env });
+    }
+}
+/**
+ * Render the recap card surfaced both as the Step 6 exit screen and
+ * as the non-interactive snapshot dump.
+ */
+export function renderSnapshotCard(snapshot, opts) {
+    const styleGloss = OUTPUT_STYLES[snapshot.outputStyle].gloss;
+    const modeGloss = PERMISSION_MODE_GLOSS[snapshot.permissionMode];
+    const telemetryGloss = TELEMETRY_GLOSS[snapshot.telemetry];
+    const authLine = snapshot.authPresent
+        ? 'Signed in (run `pugi whoami` for details).'
+        : 'Not signed in. Run `pugi login` to authenticate.';
+    const lines = [
+        opts.heading,
+        '',
+        `  Auth:            ${authLine}`,
+        `  Permission mode: ${snapshot.permissionMode}  —  ${modeGloss}`,
+        `  Output style:    ${snapshot.outputStyle} (${snapshot.outputStyleSource})  —  ${styleGloss}`,
+        `  Telemetry:       ${snapshot.telemetry}  —  ${telemetryGloss}`,
+        `  MCP servers:     add via \`pugi mcp add <name> <command>\``,
+        '',
+        opts.footer,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Build the hint list — auth pointer + re-onboarding tip. Hints are
+ * structured (in the payload) so a JSON caller can dispatch on them.
+ */
+function buildHints(snapshot) {
+    const hints = [];
+    if (!snapshot.authPresent) {
+        hints.push('Run `pugi login` to sign in. Pugi works offline-first but auth unlocks the engine + sync.');
+    }
+    if (snapshot.previouslyOnboarded) {
+        hints.push('You have onboarded before — re-running the wizard is safe; Enter on any step keeps the current value.');
+    }
+    hints.push('Run `pugi doctor` to verify your environment.');
+    hints.push('Add MCP servers with `pugi mcp add` or list them via `pugi mcp list`.');
+    return Object.freeze(hints);
+}
+/**
+ * Drive the wizard. Production callers leave `ctx.promptWizard`
+ * undefined, in which case we dynamic-import the Ink wizard so the
+ * command module stays free of the React/Ink module graph on the
+ * non-interactive path. Specs inject a stub.
+ */
+async function invokeWizard(ctx, snapshot) {
+    if (ctx.promptWizard) {
+        return ctx.promptWizard(snapshot);
+    }
+    const { renderOnboardingWizard } = await import('../../tui/onboarding-wizard.js');
+    return renderOnboardingWizard({ snapshot });
+}
+/**
+ * Flag parser. Returns `null` on conflicting flags so the runner can
+ * emit `invalid_flags` + rc=2 without a thrown error.
+ */
+function parseFlags(args) {
+    let reset = false;
+    let nonInteractive = false;
+    for (const arg of args) {
+        if (arg === '--reset') {
+            reset = true;
+        }
+        else if (arg === '--non-interactive' || arg === '--no-tty') {
+            nonInteractive = true;
+        }
+        else {
+            return null;
+        }
+    }
+    // `--reset` + `--non-interactive` is redundant but not conflicting — reset wins.
+    // No other combinations are illegal at the moment.
+    return { reset, nonInteractive };
+}
+function invalidFlagsMessage(args) {
+    return [
+        `pugi onboarding: unknown flag in \`${args.join(' ')}\`.`,
+        'Usage: pugi onboarding [--reset] [--non-interactive]',
+    ].join('\n');
+}
+/**
+ * One-line gloss per telemetry choice — surfaced in the recap card.
+ * Mirrors the brand voice (no hedging, operator-grade).
+ */
+const TELEMETRY_GLOSS = Object.freeze({
+    off: 'No telemetry of any kind.',
+    anonymous: 'Counts + error categories only; no payloads.',
+    community: 'Anonymous + opt-in usage panels.',
+});
+function buildPayload(input) {
+    return {
+        command: 'onboarding',
+        status: input.status,
+        snapshotBefore: input.before,
+        snapshotAfter: input.after,
+        permissionModes: PERMISSION_MODES,
+        outputStyles: OUTPUT_STYLE_SLUGS,
+        telemetryChoices: TELEMETRY_CHOICES,
+        hints: input.hints,
+        message: input.message,
+    };
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/runtime/commands/plan.js

@@ -0,0 +1,143 @@
+/**
+ * `pugi plan` / `/plan` — Leak L7 quick mode-switch shortcut.
+ *
+ * `/plan` is the slick UX shortcut for `/permissions plan`: one keystroke
+ * (well, five) puts the gate into plan mode + surfaces a banner so the
+ * operator knows write/dispatch tools are refused. The model goes off and
+ * thinks / researches without side effects until the operator types
+ * `/plan --back` (restore previous mode) or explicitly flips with
+ * `/permissions <mode>`.
+ *
+ * The slash and CLI surfaces both go through `runPlanCommand` — same
+ * separation as `runPermissionsCommand`. The runtime is I/O free w.r.t.
+ * the engine; the optional one-shot dispatch (`/plan <prompt>`) is
+ * handled by the CLI dispatcher AFTER this helper sets the workspace
+ * mode so the existing `runEngineTask('plan')` path sees plan mode as
+ * the workspace state without needing a parallel code path.
+ *
+ * Verdicts (the helper returns one so the caller can decide what to do
+ * after the mode write — print the banner, dispatch the engine, no-op):
+ *   - `entered`        — first `/plan` from a non-plan mode. Print the
+ *                        banner. Caller may then run a one-shot prompt.
+ *   - `already-in-plan` — `/plan` while already in plan. No-op + show
+ *                        current. No banner reprint.
+ *   - `reverted`        — `/plan --back` popped the snapshot. Print a
+ *                        one-line confirmation; no banner.
+ *   - `no-previous`     — `/plan --back` without a snapshot. Print a
+ *                        clear "nothing to revert" line.
+ *   - `persisted`       — `/plan --persist` wrote the global default
+ *                        AND set workspace state to plan. Banner +
+ *                        persistence-confirmation line.
+ *
+ * `previousMode` semantics: stashed BEFORE the workspace write on
+ * `entered` / `persisted`. Cleared after a successful `reverted` so a
+ * second `--back` reports `no-previous` instead of looping back to plan.
+ */
+import { PERMISSION_MODES, PERMISSION_MODE_GLOSS, getCurrentMode, getGlobalDefaultMode, getPreviousMode, setCurrentMode, setGlobalDefaultMode, setPreviousMode, } from '../../core/permissions/index.js';
+/**
+ * Run the `/plan` flow. Side effects:
+ *
+ *   command.back = true:
+ *     - If a previousMode snapshot exists → restore it, clear snapshot,
+ *       return `reverted`.
+ *     - Otherwise → no writes, return `no-previous`.
+ *
+ *   command.back = false, current mode is plan:
+ *     - If `--persist`, write global config (no workspace re-write — it
+ *       is already plan).
+ *     - Print "already in plan" + the banner-summary line. Return
+ *       `already-in-plan`.
+ *
+ *   command.back = false, current mode is NOT plan:
+ *     - Snapshot current mode → previousPermissionMode.
+ *     - Write workspace mode = plan.
+ *     - If `--persist`, also write global config.
+ *     - Print the banner + (if persisted) the persistence line.
+ *     - Return `entered` or `persisted`.
+ *
+ * --back + --persist is a no-op for persistence (revert never writes
+ * global config) but the revert itself fires.
+ */
+export async function runPlanCommand(command, ctx) {
+    const current = effectiveMode(ctx);
+    if (command.back) {
+        const prev = getPreviousMode(ctx.workspaceRoot);
+        if (!prev) {
+            ctx.writeOutput(`No previous mode to restore. Current: ${current}. Use \`/permissions <mode>\` to switch explicitly.`);
+            return { verdict: 'no-previous', mode: current };
+        }
+        setCurrentMode(ctx.workspaceRoot, prev);
+        setPreviousMode(ctx.workspaceRoot, null);
+        ctx.writeOutput(`Switched back to '${prev}' mode. ${PERMISSION_MODE_GLOSS[prev]}`);
+        return { verdict: 'reverted', mode: prev };
+    }
+    if (current === 'plan') {
+        // Repeat /plan in plan mode is a no-op for the mode write, but
+        // --persist still honours the operator's intent to lock plan as
+        // the global default for future sessions.
+        if (command.persist) {
+            setGlobalDefaultMode('plan', ctx.homeDir);
+            ctx.writeOutput('Already in plan mode. Persisted plan as the default for future sessions (~/.pugi/config.json).');
+            return { verdict: 'persisted', mode: 'plan' };
+        }
+        ctx.writeOutput(`Already in plan mode. ${PERMISSION_MODE_GLOSS.plan} Switch back with \`/plan --back\` or \`/permissions <mode>\`.`);
+        return { verdict: 'already-in-plan', mode: 'plan' };
+    }
+    // Entering plan mode from a non-plan baseline. Stash the current mode
+    // BEFORE the write so /plan --back can pop it. We intentionally use the
+    // observed effective mode (workspace || global || default) rather than
+    // strictly the workspace value — if the operator's previous mode was
+    // sourced from the global config, `--back` should restore that observed
+    // state, not silently degrade to default.
+    setPreviousMode(ctx.workspaceRoot, current);
+    setCurrentMode(ctx.workspaceRoot, 'plan');
+    if (command.persist) {
+        setGlobalDefaultMode('plan', ctx.homeDir);
+    }
+    for (const line of renderPlanBanner()) {
+        ctx.writeOutput(line);
+    }
+    if (command.persist) {
+        ctx.writeOutput('Persisted plan as the default for future sessions (~/.pugi/config.json).');
+        return { verdict: 'persisted', mode: 'plan' };
+    }
+    return { verdict: 'entered', mode: 'plan' };
+}
+/**
+ * Render the plan-mode banner as a sequence of lines. The slash + CLI
+ * surfaces both print these line-by-line through their respective
+ * `writeOutput` sinks so the Ink REPL conversation pane and the plain
+ * stdout pipeline render identically.
+ *
+ * The box-drawing uses light-line glyphs (U+2500 family) which render in
+ * every modern terminal we target (Linux/macOS/Windows Terminal/iTerm/
+ * Ghostty/Alacritty). No emoji per brand-voice gate.
+ */
+export function renderPlanBanner() {
+    return [
+        '┌─ Plan mode active ────────────────────────────────────────┐',
+        '│ Read-only tools allowed. Write/dispatch tools blocked.    │',
+        '│ Pugi will think + research without making changes.        │',
+        '│ Switch back: /plan --back  or  /permissions <mode>        │',
+        '└───────────────────────────────────────────────────────────┘',
+    ];
+}
+/**
+ * Resolve the effective mode at the moment the helper was invoked,
+ * mirroring `resolveMode` but without taking a CLI flag (the `/plan`
+ * helper is called AFTER the top-level `--mode` flag has been applied
+ * to the workspace, so the file state is the source of truth here).
+ */
+function effectiveMode(ctx) {
+    const workspace = getCurrentMode(ctx.workspaceRoot);
+    if (workspace)
+        return workspace;
+    const global = getGlobalDefaultMode(ctx.homeDir);
+    if (global)
+        return global;
+    // Defensive: PERMISSION_MODES[1] is 'ask' (the canonical default). We
+    // index off the canonical list rather than re-import DEFAULT_PERMISSION_MODE
+    // here to keep the symbol surface narrow.
+    return PERMISSION_MODES[1] ?? 'ask';
+}
+//# sourceMappingURL=plan.js.map