@pugi/cli 0.1.0-beta.30 → 0.1.0-beta.35

package/dist/runtime/cli.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { statSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -33,6 +33,8 @@ import { runThemeCommand } from './commands/theme.js';
 import { runOnboardingCommand } from './commands/onboarding.js';
 import { runVimCommand } from './commands/vim.js';
 import { isOnboarded } from '../core/onboarding/marker.js';
+import { ensureInitialized as ensureInitializedHelper } from '../core/onboarding/ensure-initialized.js';
+import { ensureAuthenticated as ensureAuthenticatedHelper } from '../core/auth/ensure-authenticated.js';
 import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
@@ -67,6 +69,7 @@ import { runMcpCommand } from './commands/mcp.js';
 import { runPermissionsCommand } from './commands/permissions.js';
 import { runPlanCommand } from './commands/plan.js';
 import { parsePermissionMode } from '../core/permissions/index.js';
+import { protectedTargetReason } from '../core/permission.js';
 import { DECOMPOSE_PROMPT_SUFFIX, parseDecompositionFromText, writeDecomposition, } from './plan-decompose.js';
 import { FtsSyntaxError, SqliteSessionStore, resolveProjectStoreDir } from '../core/repl/store/index.js';
 import { slugForCwd } from '../core/repl/history.js';
@@ -170,6 +173,11 @@ const handlers = {
     // same handler as the in-REPL `/feedback` slash; the wrapper just
     // routes TTY vs non-TTY before mounting Ink.
     feedback: dispatchFeedback,
+    // BIG TRACK 10 Phase 1 (2026-05-27): `pugi smoke` runs the scenario
+    // corpus through `pugi --headless` and reports pass/fail per
+    // scenario. Subcommand-only — no slash counterpart per the Phase 1
+    // scope ("no new slash commands; harness is CLI subcommand only").
+    smoke: dispatchSmoke,
     sync,
     style: dispatchStyle,
     // Leak L30 (2026-05-27): `pugi theme` flips the local TUI color
@@ -482,6 +490,33 @@ async function dispatchTheme(args, flags, _session) {
     if (rc !== 0)
         process.exitCode = rc;
 }
+/**
+ * BIG TRACK 10 Phase 1 (2026-05-27) — `pugi smoke` top-level dispatcher.
+ *
+ * Loads the bundled scenario corpus (`apps/pugi-cli/test/scenarios/`),
+ * runs each scenario through `pugi --headless` via the smoke
+ * orchestrator, and surfaces the pass/fail summary. `--filter <pat>`
+ * subsets the corpus; `--scenarios-dir <path>` swaps in an external
+ * dir (handy for project-local scenarios in customer repos).
+ *
+ * Exit-code policy:
+ *   0 — every scenario passed (or filter matched nothing)
+ *   1 — at least one scenario failed (assertion, parse error, executor crash)
+ *   2 — invalid CLI args (--filter without a value, unknown flag)
+ */
+async function dispatchSmoke(args, flags, _session) {
+    const { runSmokeCommand } = await import('../commands/smoke.js');
+    const ctx = {
+        args,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    };
+    if (flags.smokeFilter !== undefined)
+        ctx.filter = flags.smokeFilter;
+    const rc = await runSmokeCommand(ctx);
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * Leak L25 (2026-05-27) — `pugi onboarding` top-level dispatcher.
  *
@@ -611,12 +646,22 @@ async function dispatchDelegate(args, flags, _session) {
  * stays single-sourced.
  */
 async function dispatchChain(args, flags, _session) {
+    const root = process.cwd();
+    // Wave 6 UX: chain reads / writes `.pugi/chains/*` so the auto-init
+    // pre-flight matches the engine commands. Auto-login resolves so a
+    // first-run `pugi chain new` from a cold cwd surfaces a login prompt
+    // instead of a silent unauthenticated error one layer deeper.
+    await runAutoInitPreflight(root, flags);
+    const auth = await runAutoAuthPreflight(flags);
+    const cachedCred = auth.status === 'ready' ? auth.credential : null;
     await runChainCommand(args, {
-        cwd: process.cwd(),
+        cwd: root,
         json: flags.json,
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
         resolveConfig: () => {
-            const credential = resolveActiveCredential();
+            // Prefer the pre-flight cached credential to avoid the second
+            // disk read (resolveActiveCredential reads ~/.pugi/credentials.json).
+            const credential = cachedCred ?? resolveActiveCredential();
             if (!credential)
                 return null;
             return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
@@ -715,6 +760,42 @@ async function dispatchPermissions(args, flags, _session) {
         return;
     }
     const mode = head ? parsePermissionMode(head) : undefined;
+    // Wave 6 cleanup (2026-05-27): no positional mode + interactive TTY
+    // → mount the Ink picker so the operator can arrow-select. Falls back
+    // to the legacy text table on non-TTY / --json / CI so scripted
+    // callers (and the deferred follow-up from PR #617) keep working.
+    // `bypass` selected from the picker still routes through
+    // `runPermissionsCommand` with `confirmBypass: true` — the picker IS
+    // the confirm gesture (arrow + Enter is the explicit acknowledge).
+    if (!mode && isInteractive(flags) && !flags.json) {
+        const { resolveLayeredMode } = await import('./commands/permissions.js');
+        const layered = resolveLayeredMode(process.cwd());
+        const { renderPermissionsPicker, PermissionsPickerCancelledError } = await import('../tui/render.js');
+        try {
+            const chosen = await renderPermissionsPicker({
+                currentMode: layered.effective,
+                sourceLabel: layered.source,
+                firstRun: layered.firstRun,
+            });
+            await runPermissionsCommand({
+                mode: chosen,
+                persist: Boolean(flags.persist),
+                // The picker selection IS the confirm gesture for `bypass`.
+                confirmBypass: chosen === 'bypass' ? true : Boolean(flags.confirm),
+            }, {
+                workspaceRoot: process.cwd(),
+                writeOutput: (text) => writeOutput(flags, { text }, text),
+            });
+            return;
+        }
+        catch (err) {
+            if (err instanceof PermissionsPickerCancelledError) {
+                writeOutput(flags, { cancelled: true }, 'Permissions picker cancelled. No change.');
+                return;
+            }
+            throw err;
+        }
+    }
     await runPermissionsCommand({
         ...(mode ? { mode } : {}),
         persist: Boolean(flags.persist),
@@ -1043,6 +1124,22 @@ export async function runCli(argv) {
         process.exitCode = exitCode;
         return;
     }
+    // BIG TRACK 10 Phase 1 (2026-05-27) — `--headless` flag. When the
+    // operator (or harness) passes `--headless` on a bare/repl
+    // invocation we route into the multi-turn line-by-line headless
+    // loop. Differs from `--print` (one-shot): headless reads stdin
+    // until close. The dispatch lives BEFORE the REPL / splash branches
+    // so the Ink TUI never mounts. Suppressed when `--print` is also
+    // set (the one-shot variant wins — explicit single-turn overrides
+    // the multi-turn loop).
+    if (flags.headless && typeof flags.print !== 'string') {
+        const { runHeadlessRepl } = await import('./headless-repl.js');
+        const exitCode = await runHeadlessRepl({
+            cwd: flags.cwd ?? process.cwd(),
+        });
+        process.exitCode = exitCode;
+        return;
+    }
     // Leak L25 (2026-05-27): first-run hint. When the operator types a
     // bare `pugi` on a real TTY AND the onboarding marker is absent, drop
     // a one-line hint on stderr BEFORE the REPL splash mounts. Stderr so
@@ -1146,6 +1243,12 @@ function parseArgs(argv) {
             ? process.env.PUGI_HIDE_TOOL_STREAM === '1'
             : true,
         noDefaults: process.env.PUGI_INIT_NO_DEFAULTS === '1',
+        // Wave 6 UX (2026-05-27): auto-init / auto-login opt-outs. Default
+        // OFF (auto-init + auto-login are on by default on an interactive
+        // TTY). PUGI_NO_AUTO_* env vars provide a per-shell escape hatch
+        // without needing к thread the flag through every invocation.
+        noInit: process.env.PUGI_NO_AUTO_INIT === '1',
+        noLogin: process.env.PUGI_NO_AUTO_LOGIN === '1',
         decompose: false,
         // β-headless: --no-tools default OFF so existing flag-free invocations
         // keep tool advertisement. Flipped only by explicit operator opt-in.
@@ -1172,6 +1275,11 @@ function parseArgs(argv) {
         // bare invocation hits the cache when mtime + size match; opt-in
         // for a cold rebuild from the source tree.
         refresh: false,
+        // BIG TRACK 10 Phase 1 — `--headless` for multi-turn programmatic
+        // drive. Default off; explicit opt-in only. The CLI ALSO honors
+        // `PUGI_HEADLESS=1` so the smoke harness can pre-set the env when
+        // a wrapper script forgets the flag.
+        headless: process.env.PUGI_HEADLESS === '1',
     };
     const args = [];
     // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
@@ -1442,6 +1550,40 @@ function parseArgs(argv) {
             flags.bare = true;
             setBareMode();
         }
+        else if (arg === '--no-init') {
+            // Wave 6 UX (2026-05-27): opt-out for the auto-init pre-flight
+            // wrapper. The flag-driven path mirrors PUGI_NO_AUTO_INIT=1 so a
+            // single invocation can override the env state and vice versa.
+            flags.noInit = true;
+        }
+        else if (arg === '--no-login') {
+            // Wave 6 UX (2026-05-27): opt-out for the auto-login pre-flight
+            // wrapper. The auth resolution still runs (env / file paths) —
+            // only the inline device-flow launch is suppressed.
+            flags.noLogin = true;
+        }
+        else if (arg === '--headless') {
+            // BIG TRACK 10 Phase 1 — line-by-line stdin → engine → JSON
+            // envelopes on stdout. Distinct from `--print` (single-shot).
+            // The dispatcher routes to `runHeadlessRepl` BEFORE the Ink
+            // REPL when this flag is set on a bare/repl invocation.
+            flags.headless = true;
+        }
+        else if (arg === '--filter') {
+            // BIG TRACK 10 Phase 1 — `pugi smoke --filter <pattern>`.
+            // Generic flag name so future commands (e.g. `pugi sessions
+            // --filter`) can reuse it without a second flag wired through
+            // parseArgs.
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--')) {
+                throw new Error('--filter requires a pattern (substring or *-glob)');
+            }
+            flags.smokeFilter = next;
+            index += 1;
+        }
+        else if (arg.startsWith('--filter=')) {
+            flags.smokeFilter = arg.slice('--filter='.length);
+        }
         else {
             args.push(arg);
         }
@@ -1646,9 +1788,9 @@ const COMMAND_HELP_BODIES = {
     accounts: [
         'pugi accounts — manage stored credentials across endpoints.',
         '',
-        '  list                    Every account + its endpoint + active flag.',
-        '  switch <label>          Re-point the active account.',
-        '  remove <label>          Delete a stored credential.',
+        '  pugi accounts list                Every account + its endpoint + active flag.',
+        '  pugi accounts switch <label>      Re-point the active account.',
+        '  pugi accounts remove <label>      Delete a stored credential.',
     ],
     jobs: [
         'pugi jobs — list, tail, or kill background dispatch jobs.',
@@ -1695,10 +1837,11 @@ const COMMAND_HELP_BODIES = {
         'engine adapter. Safe to run anywhere; no network calls.',
     ],
     'prd-check': [
-        'pugi prd-check <prd-path> | --all   — Wave 6 verified-deliverable gate.',
+        'pugi prd-check <prd-path> | --all | --session   — Wave 6 verified-deliverable gate.',
         '',
+        'DEFAULT MODE — verify acceptance criteria against committed artifacts.',
         'Reads a markdown PRD, parses the acceptance-criteria section, and',
-        'runs verifiers against committed artifacts:',
+        'runs verifiers:',
         '  file:<path>      fs.existsSync',
         '  test:<spec>      spec file exists + has ≥1 test()/it() block',
         '  doc:<path>       doc exists + has > 100 chars',
@@ -1708,6 +1851,13 @@ const COMMAND_HELP_BODIES = {
         '  --all                   Scan docs/prd/**.md instead of one file.',
         '  --json                  Emit a structured envelope to stdout.',
         '',
+        'SESSION MODE (Wave 6 final) — review the live session against the PRD.',
+        'Walks up for PRD.md or apps/<app>/PRODUCT.md, reads the last 20 turns',
+        'from .pugi/events.jsonl, and dispatches a cross-review subagent to',
+        'list which requirements are SATISFIED and which remain OUTSTANDING.',
+        '',
+        '  --session               Run the session-review mode (no <path>, no --all).',
+        '',
         'Exit codes: 0 healthy · 1 failing · 2 unparsed / arg error.',
     ],
     status: [
@@ -2329,7 +2479,16 @@ async function init(_args, flags, _session) {
                 'Default skills:',
                 ...result.defaultSkills.map((entry) => `  ${entry.name.padEnd(18)} ${entry.status}`),
             ];
-    writeOutput(flags, result, [
+    // Wave 6 BT 9 Phase 2 (2026-05-27): codegraph context-aware auto-install.
+    // After scaffold, evaluate whether the repo looks big-enough + matches a
+    // supported language. The init flow surfaces the offer copy + the docs
+    // URL; the operator decides via the interactive Yes/no prompt OR (in
+    // --json / --no-tty mode) explicitly via `pugi mcp install codegraph
+    // codegraph serve --mcp` later. We DO NOT auto-install here on the
+    // non-interactive path — silently writing к .pugi/mcp.json without a
+    // visible operator confirmation would violate the trust contract.
+    const codegraphLines = await maybeOfferCodegraphInline(result.root, flags);
+    writeOutput(flags, { ...result, codegraph: codegraphLines.envelope }, [
         'Pugi initialized',
         `Root: ${result.root}`,
         result.created.length
@@ -2339,8 +2498,78 @@ async function init(_args, flags, _session) {
             ? `Already present:\n${result.skipped.map((path) => `  ${path}`).join('\n')}`
             : 'Already present: none',
         ...defaultSkillLines,
+        ...codegraphLines.text,
     ].join('\n'));
 }
+/**
+ * Codegraph offer inline branch for `pugi init` (Wave 6 BT 9 Phase 2).
+ *
+ * Pure information surface — does NOT prompt synchronously. Returns:
+ *
+ *   - `text[]`     — lines к append к the human-facing init summary
+ *   - `envelope`   — structured JSON payload included in `--json` output
+ *                    so a CI harness can branch на the verdict без
+ *                    re-running detection.
+ *
+ * The interactive Yes/no prompt lives one layer up (the `/init` REPL
+ * slash handles it). The standalone `pugi init` is intentionally non-
+ * interactive — operators wanting a one-liner install can run
+ * `pugi mcp install codegraph codegraph serve --mcp` after seeing the
+ * hint here.
+ */
+async function maybeOfferCodegraphInline(workspaceRoot, flags) {
+    try {
+        const { evaluateOffer, emitOfferShown } = await import('../core/codegraph/offer-hook.js');
+        const verdict = evaluateOffer({ workspaceRoot });
+        if (!verdict.shouldPrompt) {
+            return {
+                text: [],
+                envelope: {
+                    status: 'skipped',
+                    reason: verdict.reason,
+                },
+            };
+        }
+        // Surface the telemetry shown-event only for surfaces that
+        // actually rendered к the operator. `--json` consumers still see
+        // the verdict в the envelope so we count those as shown too.
+        emitOfferShown(verdict.detection);
+        const noTty = flags.noTty || flags.json;
+        const lines = [
+            '',
+            'Codegraph context-aware install (Wave 6):',
+            `  ${verdict.promptCopy}`,
+            `  Docs: ${verdict.docsUrl}`,
+        ];
+        if (!noTty) {
+            lines.push('  Accept: `pugi mcp install codegraph codegraph serve --mcp && pugi mcp trust codegraph`', '  Skip:   `pugi mcp install codegraph` will not run automatically — your call.');
+        }
+        else {
+            lines.push('  Non-interactive mode — codegraph NOT auto-installed.', '  Run `pugi mcp install codegraph codegraph serve --mcp` to opt in.');
+        }
+        return {
+            text: lines,
+            envelope: {
+                status: 'offered',
+                sizeCategory: verdict.detection.sizeCategory,
+                languages: verdict.detection.languages,
+                primarySymbolCount: verdict.detection.primarySymbolCount,
+                copy: verdict.promptCopy,
+                docsUrl: verdict.docsUrl,
+            },
+        };
+    }
+    catch (error) {
+        // Defensive — codegraph offer is best-effort, must not fail init.
+        return {
+            text: [],
+            envelope: {
+                status: 'error',
+                reason: error.message,
+            },
+        };
+    }
+}
 async function idea(args, flags, session) {
     const prompt = args.join(' ').trim();
     if (!prompt) {
@@ -2481,6 +2710,7 @@ async function idea(args, flags, session) {
  */
 async function offlinePlan(args, flags, session) {
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const prompt = args.join(' ').trim();
     const latestIdea = latestArtifactDir(root);
@@ -2555,6 +2785,7 @@ async function offlinePlan(args, flags, session) {
 }
 async function offlineBuild(args, flags, session) {
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const prompt = args.join(' ').trim();
     if (!prompt) {
@@ -2652,6 +2883,7 @@ async function offlineExplain(args, flags, session) {
 }
 async function review(args, flags, session) {
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const prompt = args.join(' ').trim();
     // α6.7: customer-facing consensus review routes here. Distinct from
@@ -2798,6 +3030,7 @@ async function review(args, flags, session) {
 }
 async function sync(_args, flags, session) {
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const settings = loadSettings(root);
     const mode = flags.privacy ?? privacyModeFromSettings(settings.privacy.mode);
@@ -3550,6 +3783,7 @@ function parseDiffStats(raw) {
 }
 async function handoff(args, flags, session) {
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const reason = args[0] || 'web_continue';
     const prompt = args.slice(1).join(' ').trim() || 'continue local Pugi session';
@@ -3585,6 +3819,7 @@ async function sessions(args, flags, _session) {
         return;
     }
     const root = process.cwd();
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const rebuild = args.includes('--rebuild');
     let index = rebuild ? null : readIndex(root);
@@ -3769,6 +4004,7 @@ async function resume(args, flags, session) {
         await resumeLocalSession({ flags, arg0, wantsList });
         return;
     }
+    await runAutoInitPreflight(root, flags);
     ensureInitialized(root);
     const target = args[0];
     const artifacts = listArtifactSets(root);
@@ -3976,6 +4212,44 @@ const ENGINE_EXIT_CODES = {
 function commandLabel(kind) {
     return kind === 'build_task' ? 'build' : kind;
 }
+/**
+ * Heuristic: does the user-supplied first arg look like a file or
+ * directory path the operator wants `pugi explain` to inspect? Used to
+ * decide whether to run the pre-engine path-security gate vs treat the
+ * arg as a free-form natural-language prompt.
+ *
+ * Triggers when the arg:
+ *   - starts with `.` (`.env`, `./src/foo`, `..`)
+ *   - starts with `/` (absolute path)
+ *   - contains `/` (`apps/admin-api/src/index.ts`)
+ *   - contains no spaces AND exists on disk relative to the workspace
+ *
+ * Misses (treated as free-form prompts):
+ *   - "what does this package.json define?" (has spaces)
+ *   - "trace the auth flow" (has spaces)
+ *
+ * The pre-engine gate is a defence in depth — the bash classifier and
+ * file-tools `resolveWorkspacePath` already refuse the bad paths inside
+ * the engine, but failing fast at the CLI seam lets the operator see a
+ * crisp permission error with exit code 8 instead of the engine
+ * pretending to "explain" the protected file.
+ */
+function looksLikePath(arg) {
+    if (!arg)
+        return false;
+    if (arg.includes(' '))
+        return false;
+    if (arg.startsWith('.') || arg.startsWith('/') || arg.includes('/'))
+        return true;
+    // Last-resort check: bare-token paths that exist on disk
+    // (`README.md`, `package.json`) still benefit from the gate.
+    try {
+        return existsSync(resolve(process.cwd(), arg));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Sprint 2 Track A: wire `pugi code/explain/fix/plan/build` to the real
  * `NativePugiEngineAdapter`. Each command:
@@ -4040,11 +4314,26 @@ function runEngineTask(kind) {
     return async (args, flags, session) => {
         const label = commandLabel(kind);
         const root = process.cwd();
-        // `.pugi/` is created by `pugi init`. The engine writes the per-
-        // session events mirror under it, so we fail fast here instead of
-        // silently no-op'ing the mirror inside the adapter.
+        // Wave 6 UX (2026-05-27): auto-init pre-flight. On an interactive
+        // TTY in a workspace без `.pugi/` we prompt
+        // "Initialize a new Pugi workspace here? (Y/n)" and scaffold
+        // inline on Y. Falls back к the legacy strict-assert (throw `Run
+        // pugi init first`) in CI / `--no-init`, keeping pinned CI
+        // assertions green.
+        await runAutoInitPreflight(root, flags);
+        // Post-condition assertion — narrows for the type checker and
+        // matches the pre-Wave-6 invariant that the engine adapter
+        // expects `.pugi/` к exist before it writes the events mirror.
         ensureInitialized(root);
-        const credential = resolveActiveCredential();
+        // Wave 6 UX (2026-05-27): auto-login pre-flight. Read-only
+        // operators (`pugi explain` against a public repo) and `plan`/
+        // `build` still have legitimate offline fallbacks below, so the
+        // helper output is informational here — we capture it for the
+        // engine_unavailable branch below but never bail unconditionally
+        // on `missing`. `code` / `fix` reject offline runs explicitly,
+        // mirroring the pre-existing contract.
+        const auth = await runAutoAuthPreflight(flags);
+        const credential = auth.status === 'ready' ? auth.credential : null;
         const envConfig = loadRuntimeConfig();
         const config = credential
             ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
@@ -4093,6 +4382,73 @@ function runEngineTask(kind) {
             if (kind === 'explain')
                 return offlineExplain(args, flags, session);
         }
+        // P0 fix 2026-05-28 (Codex audit): pre-engine path validation for
+        // `pugi explain <path>`. Without this gate, when the first arg
+        // resolves to an on-disk path the engine would happily forward it
+        // to the model — which could then `bash cat .env` or `cat ../X` and
+        // sidestep the file-tools `resolveWorkspacePath`/
+        // `permissionGatedResolve` checks. The bash-classifier now refuses
+        // those reads (PROTECTED_BASENAME_PATTERNS + detectParentTraversalRead),
+        // but we ALSO fail fast at the CLI seam so:
+        //   - `pugi explain .env` exits non-zero with a permission error
+        //   - `pugi explain ..` exits non-zero with a path-escape error
+        //   - `pugi explain alias-to-env` (symlink to .env) exits non-zero
+        //     because `permissionGatedResolve` re-checks the realpath
+        // matching the offlineExplain behaviour the spec asserts.
+        if (kind === 'explain' && args.length > 0) {
+            const firstArg = args[0];
+            if (firstArg && looksLikePath(firstArg)) {
+                const targetExists = (() => {
+                    try {
+                        // First reject parent-traversal patterns OUTRIGHT — even a
+                        // path that does not currently exist must not address a
+                        // location above the workspace.
+                        const resolved = resolveWorkspacePath(root, firstArg);
+                        // For paths that exist, run the realpath-aware permission
+                        // re-check so symlink aliases to protected files refuse
+                        // the same way the file-tools gate would.
+                        const settings = loadSettings(root);
+                        const protectedReason = protectedTargetReason({ tool: 'explain', kind: 'read', target: firstArg }, root);
+                        if (protectedReason) {
+                            throw new Error(`Permission deny for explain ${firstArg}: ${protectedReason}`);
+                        }
+                        // Symlink alias re-check: resolve to realpath and re-test
+                        // the basename. Mirrors `permissionGatedResolve` in
+                        // file-tools.ts so `alias-to-env -> .env` is refused.
+                        try {
+                            const real = realpathSync.native(resolved);
+                            if (real !== resolved) {
+                                const realProtected = protectedTargetReason({ tool: 'explain', kind: 'read', target: relative(root, real) }, root);
+                                if (realProtected) {
+                                    throw new Error(`Permission deny for explain ${firstArg} (via symlink): ${realProtected}`);
+                                }
+                            }
+                        }
+                        catch (e) {
+                            const code = e.code;
+                            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                                throw e;
+                        }
+                        // Suppress unused-var warning while keeping settings load
+                        // explicit (some lint configs treat the const as dead).
+                        void settings;
+                        return true;
+                    }
+                    catch (error) {
+                        const message = error.message;
+                        writeOutput(flags, {
+                            command: label,
+                            status: 'blocked',
+                            reason: message,
+                        }, [`pugi ${label} refused: ${message}`].join('\n'));
+                        process.exitCode = ENGINE_EXIT_CODES.blocked;
+                        return false;
+                    }
+                })();
+                if (!targetExists)
+                    return;
+            }
+        }
         // Engine path prompt gate. (Offline `explain` accepts a path as
         // its first positional arg — that branch returned above before
         // we reach this gate.)
@@ -6056,11 +6412,105 @@ function ensureDir(path, created, skipped) {
     mkdirSync(path, { recursive: true });
     created.push(path);
 }
+/**
+ * Strict assertion — the workspace MUST already be initialised. Used
+ * AFTER `runAutoInitPreflight` so the surrounding engine command can
+ * narrow on the precondition. Kept synchronous because the async
+ * pre-flight (with the optional prompt + scaffold) is a separate
+ * step at command entry; this is the post-condition assertion.
+ */
 function ensureInitialized(root) {
     if (!existsSync(resolve(root, '.pugi'))) {
         throw new Error('Run pugi init first');
     }
 }
+/**
+ * Wave 6 UX (2026-05-27): async pre-flight wrapper around the
+ * `ensureInitializedHelper` from `core/onboarding/ensure-initialized.ts`.
+ * Called at command entry for every command that touches `.pugi/`.
+ *
+ *   - `.pugi/` already exists → no-op (helper short-circuits).
+ *   - Interactive TTY + missing → prompt "Initialize? (Y/n)". On Y,
+ *     scaffold inline and continue. On n, throw a clean error so the
+ *     surrounding command bails without dropping into a half-state.
+ *   - Non-interactive + missing → throw (matches the legacy
+ *     `ensureInitialized` strict assertion). The caller MUST run
+ *     `pugi init` explicitly before piping into Pugi from CI.
+ *
+ * Operator opt-out: `--no-init` (parsed into `flags.noInit`) OR
+ * `PUGI_NO_AUTO_INIT=1` forces the strict assertion даже on TTY so
+ * shells / wrappers that own init orchestration can disable us.
+ */
+async function runAutoInitPreflight(root, flags) {
+    const result = await ensureInitializedHelper({
+        cwd: root,
+        interactive: isInteractive(flags),
+        skip: flags.noInit || process.env.PUGI_NO_AUTO_INIT === '1',
+        prompt: async (question) => readSingleChoice(question),
+        scaffold: async (input) => {
+            // Forward to the real scaffolder. The helper does not import
+            // `scaffoldPugiWorkspace` directly to keep its module import-
+            // cycle free; threading it via the callback also lets the
+            // spec swap in a fake.
+            await scaffoldPugiWorkspace({ cwd: input.cwd, noDefaults: flags.noDefaults });
+        },
+    });
+    if (result.status === 'declined') {
+        if (result.reason === 'user_declined') {
+            throw new Error('Initialization declined. Run `pugi init` when ready.');
+        }
+        // non_interactive / disabled → match the legacy strict-assert
+        // message so CI scripts that grep for "Run pugi init first" keep
+        // working. The helper's structured `reason` field is still
+        // available via the spec for finer-grained branching.
+        throw new Error('Run pugi init first');
+    }
+}
+/**
+ * Wave 6 UX (2026-05-27): async pre-flight wrapper around the
+ * `ensureAuthenticatedHelper` from `core/auth/ensure-authenticated.ts`.
+ * Called at command entry for every command that authenticates against
+ * Anvil. Returns a structured envelope; the caller decides how к
+ * handle the `missing` path (engine commands fall back к offline OR
+ * raise `engine_unavailable`, write commands raise unauthenticated,
+ * read commands MAY proceed in degraded mode).
+ *
+ * The inline login launches `performDeviceFlowLogin` against the
+ * detected apiUrl. Operator opt-out via `--no-login` flag OR
+ * `PUGI_NO_AUTO_LOGIN=1` matches the auto-init equivalent.
+ */
+async function runAutoAuthPreflight(flags) {
+    return ensureAuthenticatedHelper({
+        resolve: () => resolveActiveCredential(),
+        interactive: isInteractive(flags),
+        skip: flags.noLogin || process.env.PUGI_NO_AUTO_LOGIN === '1',
+        // Headless mode (`--headless` / `--print`) cannot block on a
+        // browser-popup login. The helper refuses the inline branch when
+        // this flag is set даже on a TTY.
+        headless: Boolean(flags.headless || flags.print !== undefined),
+        login: async () => {
+            // Best-effort inline device-flow. Returns true on success
+            // (credential persisted), false on cancel. Errors propagate up
+            // and the helper converts them к `login_failed`.
+            const apiUrl = normalizeApiUrl(process.env.PUGI_API_URL ?? DEFAULT_API_URL);
+            const before = resolveActiveCredential();
+            try {
+                await performDeviceFlowLogin(apiUrl, flags, null);
+            }
+            catch {
+                return false;
+            }
+            // The device-flow handler may set process.exitCode on cancel;
+            // we reset it so the surrounding command does not inherit a
+            // 130 from the login surface даже on success. Re-resolution
+            // below is the source of truth.
+            if (process.exitCode === 130)
+                process.exitCode = 0;
+            const after = resolveActiveCredential();
+            return Boolean(after && after.apiKey !== before?.apiKey) || Boolean(after && !before);
+        },
+    });
+}
 function createArtifactDir(root, seed) {
     const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${slugify(seed)}`;
     const artifactDir = resolve(root, '.pugi', 'artifacts', id);