@panguard-ai/panguard 1.6.0 → 1.7.0

package/dist/cli/commands/up.js

@@ -3,19 +3,24 @@
  *
  * Flow: scan installed skills → warn about threats → start Guard → open dashboard
  */
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, openSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir, platform } from 'node:os';
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { Command } from 'commander';
 import { runCLI } from '@panguard-ai/panguard-guard';
 import { c, setLogLevel } from '@panguard-ai/core';
 import { ok, warn, arrow, shield, brandTagline } from '../theme.js';
 import { detectLang } from '../interactive/lang.js';
+import { ensureTelemetryConsent } from '../consent.js';
+import { installFor, toHookPlatform } from './hook.js';
+import { ensurePersistentService } from './persist.js';
+import { isFirstRun, markInitialized } from '../first-run.js';
+import { readAuthenticatedDashboardUrl, dashboardBaseUrl, } from '../dashboard-url.js';
 /** Minimal i18n for key user-facing strings */
 const t = (lang, en, zh) => (lang === 'zh-TW' ? zh : en);
 const TC_ENDPOINT = 'https://tc.panguard.ai';
-const DASHBOARD_URL = 'http://127.0.0.1:3100';
 function openBrowser(url) {
     const os = platform();
     if (os === 'win32') {
@@ -45,24 +50,113 @@ function isGuardRunning() {
     }
 }
 /**
- * Read the real rule count loaded by Guard from its TC cache.
- * Falls back to 311 (the @panguard-ai/agent-threat-rules@2.0.12 bundled count)
- * if the cache hasn't synced yet or is malformed.
+ * Whether Guard is installed as a persistent OS service (launchd/systemd). `pga up`
+ * starts a background daemon but does NOT install the service — so monitoring stops
+ * at the next reboot unless the user ran `pga guard install`. Used to keep the
+ * summary panel honest about persistence (a security tool must not overclaim it).
+ */
+function isServiceInstalled() {
+    try {
+        const os = platform();
+        if (os === 'darwin') {
+            const dir = join(homedir(), 'Library', 'LaunchAgents');
+            return existsSync(dir) && readdirSync(dir).some((f) => /panguard.*guard.*\.plist$/i.test(f));
+        }
+        if (os === 'linux') {
+            const dir = join(homedir(), '.config', 'systemd', 'user');
+            return existsSync(dir) && readdirSync(dir).some((f) => /panguard.*guard/i.test(f));
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return false;
+}
+/**
+ * Read the real rule count loaded by Guard from its TC cache, falling back to
+ * the count actually bundled with THIS install (never a hardcoded guess — the
+ * ATR rule count changes daily, so we read it from the shipped package).
  */
 function readRuleCountFromCache() {
+    // The Guard always loads the rules BUNDLED with this install; Threat Cloud
+    // sync can only ADD more on top. So the honest "active" count is at least the
+    // bundled count — never the (often smaller) TC cache figure alone, which would
+    // understate what the engine is really running and disagree with the dashboard.
+    const bundled = readBundledRuleCount();
     try {
         const cachePath = join(homedir(), '.panguard-guard', 'threat-cloud-cache.json');
         if (existsSync(cachePath)) {
             const cache = JSON.parse(readFileSync(cachePath, 'utf-8'));
             if (typeof cache.uniqueRulesCount === 'number' && cache.uniqueRulesCount > 0) {
-                return cache.uniqueRulesCount;
+                return Math.max(bundled, cache.uniqueRulesCount);
             }
         }
     }
     catch {
-        /* fallback */
+        /* fall through to the bundled count */
+    }
+    return bundled;
+}
+/**
+ * Count the detection rules actually bundled with this install by reading the
+ * shipped agent-threat-rules package (stats.json if present, else counting the
+ * rule YAML files). Returns 0 if it cannot be determined so the caller can omit
+ * the line rather than print a wrong number.
+ */
+function readBundledRuleCount() {
+    try {
+        const pkgDir = resolveBundledAtrDir();
+        if (!pkgDir)
+            return 0;
+        const statsPath = join(pkgDir, 'data', 'stats.json');
+        if (existsSync(statsPath)) {
+            const stats = JSON.parse(readFileSync(statsPath, 'utf-8'));
+            if (typeof stats.rules?.total === 'number' && stats.rules.total > 0) {
+                return stats.rules.total;
+            }
+        }
+        // Fallback: count rule YAML files on disk
+        const rulesDir = join(pkgDir, 'rules');
+        let count = 0;
+        const walk = (dir) => {
+            for (const entry of readdirSync(dir)) {
+                const full = join(dir, entry);
+                if (statSync(full).isDirectory())
+                    walk(full);
+                else if (entry.endsWith('.yaml') || entry.endsWith('.yml'))
+                    count++;
+            }
+        };
+        if (existsSync(rulesDir))
+            walk(rulesDir);
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Locate the bundled agent-threat-rules package directory by walking up the
+ * module tree (filesystem lookup, immune to the package's ESM `exports` map
+ * which blocks require.resolve of its package.json).
+ */
+function resolveBundledAtrDir() {
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 12; i++) {
+            const cand = join(dir, 'node_modules', 'agent-threat-rules');
+            if (existsSync(join(cand, 'package.json')))
+                return cand;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
     }
-    return 311;
 }
 /**
  * Read the anonymous client ID provisioned during first `pga up`.
@@ -88,6 +182,7 @@ export function upCommand() {
         .option('--no-proxy', 'Scan only — do not inject runtime protection into agent configs')
         .option('--verbose', 'Verbose output', false)
         .option('--skip-scan', 'Skip initial skill scan', false)
+        .option('--no-persist', 'Do not install the reboot-surviving service (run only until reboot)')
         .option('-y, --yes', 'Skip confirmation prompts', false)
         .action(async (opts) => {
         // Suppress JSON logs for clean output — set env var BEFORE any dynamic imports
@@ -101,9 +196,13 @@ export function upCommand() {
         console.log(`\n  ${c.sage(c.bold('PanGuard'))}  ${c.dim(t(lang, 'Your AI Security Guard', '你的 AI 安全防護'))}`);
         console.log(`  ${c.dim(brandTagline(lang))}\n`);
         console.log(`  ${c.dim('─'.repeat(50))}\n`);
-        const activatedMarker = join(homedir(), '.panguard', 'activated');
-        const isFirstRun = !existsSync(activatedMarker);
-        if (isFirstRun) {
+        // First-run detection uses a durable, telemetry-independent marker
+        // (~/.panguard/.initialized) so the welcome + interactive setup run ONCE.
+        // The old ~/.panguard/activated marker was written only by the opt-in
+        // Threat Cloud ping, so an opt-out user (the default) saw the welcome +
+        // setup on every single `pga up`.
+        const firstRun = isFirstRun();
+        if (firstRun) {
             console.log('');
             console.log(`  ${c.sage(c.bold(t(lang, 'Welcome to PanGuard AI!', '歡迎使用 PanGuard AI！')))}`);
             console.log('');
@@ -124,13 +223,45 @@ export function upCommand() {
                 process.stderr.write(`[panguard up] Setup failed: ${err instanceof Error ? err.message : String(err)}\n`);
             }
         }
-        // ── Step 1: Detect platforms + inject proxy ─────────────
+        // ── Threat Cloud policy + consent (BEFORE we scan or deploy anything) ──
+        // Discloses exactly what is shared — anonymized threat signatures + one-way
+        // hashes, never code/prompts/PII — and asks once. OPT-IN, default OFF: a
+        // bare Enter declines and nothing leaves the machine. This gates all TC
+        // upload, and is changeable anytime (pga config set telemetry true / the
+        // dashboard Settings + Threat Cloud toggle). Non-interactive (CI) stays OFF.
+        const telemetryConsented = await ensureTelemetryConsent();
+        // Whether the scan flywheel may upload to Threat Cloud. OPT-IN, default
+        // OFF: requires an affirmative consent (telemetryConsented) AND that TC
+        // upload is EXPLICITLY enabled in config (threatCloudUploadEnabled ===
+        // true). Absent/unset config => OFF (gate is `=== true`, never `!== false`).
+        // Nothing leaves the machine unless the user opted in via the first-run
+        // prompt / `pga config set telemetry true` / the dashboard toggle.
+        const tcUploadAllowed = (() => {
+            if (!telemetryConsented)
+                return false;
+            try {
+                const cfgPath = join(homedir(), '.panguard-guard', 'config.json');
+                if (existsSync(cfgPath)) {
+                    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+                    return cfg.threatCloudUploadEnabled === true;
+                }
+            }
+            catch {
+                // On any read error, fail closed — do not upload.
+                return false;
+            }
+            // No config on disk yet => not opted in => OFF.
+            return false;
+        })();
+        // ── Step 1: Detect AI platforms (we SCAN before deploying) ──
         let platformCount = 0;
         let serverCount = 0;
         let threatCount = 0;
+        // Captured during detection, used to inject AFTER the scan completes.
+        let detectedPlatforms = [];
+        let injectProxyFn = null;
         try {
             let detectPlatforms;
-            let injectProxyFn;
             try {
                 // Published package: import from /config subpath
                 const mcp = (await import('@panguard-ai/panguard-mcp/config'));
@@ -148,64 +279,19 @@ export function upCommand() {
             }
             console.log(`  ${shield()} ${c.bold(t(lang, 'Looking at your setup...', '看看你的環境...'))}\n`);
             const platforms = await detectPlatforms();
-            const detected = platforms.filter((p) => p.detected);
-            for (const p of detected) {
+            detectedPlatforms = platforms.filter((p) => p.detected);
+            for (const p of detectedPlatforms) {
                 console.log(`    ${ok()} ${c.safe(p.name)}  ${c.dim(t(lang, 'found', '已找到'))}`);
             }
-            if (detected.length === 0) {
+            if (detectedPlatforms.length === 0) {
                 console.log(`    ${c.dim(t(lang, 'No AI tools found yet.', '尚未找到 AI 工具。'))}`);
             }
-            // Build runtime protection by DEFAULT. `pga up` should stand up
-            // protection out of the box; --no-proxy opts out (scan only). In an
-            // interactive TTY we still confirm, but the prompt defaults to YES so
-            // the common path (just run `pga up`) actually protects. Non-TTY
-            // (CI / unattended) injects by default too — configs are backed up.
-            if (detected.length > 0) {
-                let shouldInject = opts.proxy !== false;
-                if (shouldInject && !opts.yes && process.stdin.isTTY) {
-                    const { createInterface } = await import('node:readline');
-                    const rl = createInterface({ input: process.stdin, output: process.stdout });
-                    const answer = await new Promise((resolve) => {
-                        rl.question(`\n  Inject runtime protection into ${detected.length} platform(s)? ` +
-                            `${c.dim('(configs backed up to *.bak)')} [Y/n] `, resolve);
-                    });
-                    rl.close();
-                    shouldInject = answer.trim().toLowerCase() !== 'n';
-                }
-                if (!shouldInject) {
-                    console.log(`\n    ${c.dim('Scan only — runtime protection not injected (--no-proxy).')}`);
-                }
-                else {
-                    console.log(`\n  ${shield()} ${c.bold('Watching your agents...')}\n`);
-                    const proxySummary = injectProxyFn(detected.map((p) => p.id));
-                    platformCount = proxySummary.totalPlatforms;
-                    serverCount = proxySummary.totalServersProxied;
-                    if (serverCount > 0) {
-                        console.log(`    ${c.safe(`${serverCount} MCP server(s)`)} proxied across ${c.sage(`${platformCount} platform(s)`)}`);
-                        console.log(`    ${c.dim('Config backed up to *.bak files')}`);
-                    }
-                    else {
-                        console.log(`    ${c.dim('All detected tools are already protected.')}`);
-                    }
-                    // Show errors if any
-                    for (const r of proxySummary.results) {
-                        if (r.error) {
-                            console.log(`    ${c.critical(`${r.platformId}: ${r.error}`)}`);
-                        }
-                    }
-                }
-            }
             console.log();
         }
         catch {
             console.log(`  ${c.dim('Platform detection skipped (install @panguard-ai/panguard-mcp for full detection).')}\n`);
         }
-        // ── Step 2: Open dashboard ──────────────────────────────
-        if (opts.dashboard) {
-            console.log(`  ${c.sage(`Opening dashboard: ${DASHBOARD_URL}`)}\n`);
-            openBrowser(DASHBOARD_URL);
-        }
-        // ── Step 3: Scan installed skills ────────────────────────
+        // ── Step 2: Scan installed skills (BEFORE deploying protection) ──
         if (!opts.skipScan) {
             console.log(`\n  ${arrow()} ${c.bold(t(lang, 'Scanning installed skills...', '掃描已安裝技能...'))}\n`);
             try {
@@ -272,8 +358,10 @@ export function upCommand() {
                                             riskScore: report.riskScore,
                                         });
                                     }
-                                    // ── Flywheel: submit scan results to TC ──
-                                    if (report.riskScore > 0) {
+                                    // ── Flywheel: submit scan results to TC (consent-gated) ──
+                                    // Never upload anything when the user has not consented or
+                                    // has opted out of Threat Cloud.
+                                    if (tcUploadAllowed && report.riskScore > 0) {
                                         submitToTC(skill.name, skillDir, report).catch(() => { });
                                     }
                                 }
@@ -335,39 +423,194 @@ export function upCommand() {
                 console.log(`  ${c.dim('Skill scan skipped (discovery unavailable).')}\n`);
             }
         }
-        // ── Activation tracking (one-time, respects telemetry opt-out) ──
-        const telemetryDisabled = (() => {
-            try {
-                const cfgPath = join(homedir(), '.panguard-guard', 'config.json');
-                if (existsSync(cfgPath)) {
-                    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-                    return cfg.telemetryEnabled === false;
-                }
+        // ── Step 3: Deploy runtime protection (AFTER the scan) ──
+        // Build runtime protection by DEFAULT. `pga up` should stand up
+        // protection out of the box; --no-proxy opts out (scan only). In an
+        // interactive TTY we confirm, but the prompt defaults to YES so the
+        // common path (just run `pga up`) actually protects. Non-TTY
+        // (CI / unattended) injects by default too — configs are backed up.
+        if (detectedPlatforms.length > 0 && injectProxyFn) {
+            let shouldInject = opts.proxy !== false;
+            if (shouldInject && !opts.yes && process.stdin.isTTY) {
+                const { createInterface } = await import('node:readline');
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const answer = await new Promise((resolve) => {
+                    rl.question(`\n  Inject runtime protection into ${detectedPlatforms.length} platform(s)? ` +
+                        `${c.dim('(configs backed up to *.bak)')} [Y/n] `, resolve);
+                });
+                rl.close();
+                shouldInject = answer.trim().toLowerCase() !== 'n';
             }
-            catch {
-                /* default to enabled */
+            if (!shouldInject) {
+                console.log(`\n    ${c.dim('Scan only — runtime protection not injected (--no-proxy).')}`);
             }
-            return false;
-        })();
-        if (!telemetryDisabled) {
+            else {
+                console.log(`\n  ${shield()} ${c.bold('Watching your agents...')}\n`);
+                const proxySummary = injectProxyFn(detectedPlatforms.map((p) => p.id));
+                platformCount = proxySummary.totalPlatforms;
+                serverCount = proxySummary.totalServersProxied;
+                if (serverCount > 0) {
+                    console.log(`    ${c.safe(`${serverCount} MCP server(s)`)} proxied across ${c.sage(`${platformCount} platform(s)`)}`);
+                    console.log(`    ${c.dim('Config backed up to *.bak files')}`);
+                }
+                else {
+                    console.log(`    ${c.dim('All detected tools are already protected.')}`);
+                }
+                for (const r of proxySummary.results) {
+                    if (r.error) {
+                        console.log(`    ${c.critical(`${r.platformId}: ${r.error}`)}`);
+                    }
+                }
+                // The MCP proxy only covers MCP tool servers. An agent's BUILT-IN
+                // tools (Bash/Edit/Write/WebFetch) bypass it — the most dangerous
+                // surface. Register the per-platform tool-call hook on EVERY detected
+                // platform that exposes one, so built-in tools are evaluated too.
+                const hookable = detectedPlatforms
+                    .map((p) => toHookPlatform(p.id))
+                    .filter((p) => p !== null);
+                if (hookable.length) {
+                    const done = [];
+                    for (const hp of hookable) {
+                        try {
+                            if (installFor(hp) !== 'error')
+                                done.push(hp);
+                        }
+                        catch {
+                            /* best-effort; pga hook install can retry */
+                        }
+                    }
+                    if (done.length) {
+                        console.log(`    ${c.safe(`Built-in tools guarded on ${done.length} platform(s)`)} ` +
+                            `${c.dim(`(${done.join(', ')} — restart the agent to activate)`)}`);
+                    }
+                }
+            }
+            console.log();
+        }
+        // ── Activation tracking (one-time, OPT-IN) ──
+        // The activation ping is non-essential collective telemetry, so it only
+        // fires when the user has EXPLICITLY opted in (threatCloudUploadEnabled
+        // === true). Default OFF: absent/unset config or any read error => no ping.
+        const telemetryDisabled = !tcUploadAllowed;
+        if (tcUploadAllowed) {
             reportActivation().catch(() => { });
         }
         // ── Summary + Start Guard ─────────────────────────────
         const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
         const guardAlreadyRunning = isGuardRunning();
+        // Persistence: on macOS install a user-level LaunchAgent (no sudo) so
+        // protection survives reboot like an antivirus. The service IS the daemon
+        // (RunAtLoad), so when we install it we do NOT also spawn an ephemeral one
+        // — two daemons would fight over the dashboard port. Linux/Windows keep
+        // the ephemeral daemon plus the honest "pga guard install" hint.
+        let persistResult = isServiceInstalled() ? 'already' : 'unsupported';
         if (!guardAlreadyRunning) {
-            // Suppress guard's own banner/status — pga up has its own summary
-            process.env['PANGUARD_QUIET_GUARD'] = '1';
-            const args = ['start'];
-            if (opts.dashboard)
-                args.push('--dashboard');
-            if (opts.verbose)
-                args.push('--verbose');
-            try {
-                await runCLI(args);
+            if (opts.persist !== false && platform() === 'darwin' && persistResult !== 'already') {
+                persistResult = ensurePersistentService();
             }
-            catch (err) {
-                process.stderr.write(`  ${c.caution('Guard start failed:')} ${err instanceof Error ? err.message : String(err)}\n`);
+            const serviceManages = persistResult === 'installed' || persistResult === 'already';
+            if (serviceManages) {
+                // launchctl starts the daemon asynchronously — wait briefly (up to
+                // ~3s for the PID file) so the summary reflects reality.
+                for (let i = 0; i < 30 && !isGuardRunning(); i++) {
+                    await new Promise((r) => setTimeout(r, 100));
+                }
+            }
+            else {
+                // Ephemeral fallback (no reboot-surviving service, e.g. --no-persist
+                // or a non-macOS host without an installed service): spawn a DETACHED
+                // background daemon so protection actually runs until reboot. Running
+                // the guard in-process (runCLI('start')) would die the moment `pga up`
+                // returns — commandStart is a foreground daemon, so it must be its own
+                // process, exactly like the launchd/systemd path. spawn + detached +
+                // unref() is what keeps it alive after this process exits.
+                // Re-launch THIS CLI entry running `guard --watch` — the exact command
+                // the launchd/systemd service runs — as a detached process. Resolving
+                // the guard package would fail here: its exports map defines only an
+                // `import` condition, so require.resolve (CJS) throws "No exports main".
+                // process.argv[1] is the running CLI entry and needs no resolution.
+                const watchArgs = ['guard', '--watch'];
+                if (opts.dashboard)
+                    watchArgs.push('--dashboard');
+                if (opts.verbose)
+                    watchArgs.push('--verbose');
+                // Resolve to an absolute path: when invoked as `node ./dist/...` the
+                // entry is relative, and a detached child must not depend on inheriting
+                // the right cwd to find it.
+                const cliEntry = process.argv[1] ? resolve(process.argv[1]) : '';
+                try {
+                    if (cliEntry && existsSync(cliEntry)) {
+                        // Send the daemon's console output to its own log (like launchd),
+                        // not /dev/null, so a failed background start is diagnosable.
+                        let outFd = 'ignore';
+                        try {
+                            const gdir = join(homedir(), '.panguard-guard');
+                            if (!existsSync(gdir))
+                                mkdirSync(gdir, { recursive: true, mode: 0o700 });
+                            outFd = openSync(join(gdir, 'panguard-guard.log'), 'a');
+                        }
+                        catch {
+                            outFd = 'ignore';
+                        }
+                        const child = spawn(process.execPath, [cliEntry, ...watchArgs], {
+                            detached: true,
+                            stdio: ['ignore', outFd, outFd],
+                            env: { ...process.env, PANGUARD_QUIET_GUARD: '1' },
+                        });
+                        child.unref();
+                        // Wait briefly for the detached daemon to come up so the summary
+                        // + authenticated-URL step below reflect a running guard.
+                        for (let i = 0; i < 30 && !isGuardRunning(); i++) {
+                            await new Promise((r) => setTimeout(r, 100));
+                        }
+                    }
+                    else {
+                        // Last-resort fallback (no resolvable CLI entry): in-process start.
+                        // Protection lasts only while this process lives — degraded, but
+                        // better than no daemon at all.
+                        process.env['PANGUARD_QUIET_GUARD'] = '1';
+                        const inProc = ['start'];
+                        if (opts.dashboard)
+                            inProc.push('--dashboard');
+                        if (opts.verbose)
+                            inProc.push('--verbose');
+                        await runCLI(inProc);
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`  ${c.caution('Guard start failed:')} ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+        }
+        // ── Resolve the AUTHENTICATED dashboard URL ──────────────────
+        // The daemon persists its launch token once the dashboard is listening.
+        // The launchd path writes the PID file before the dashboard token, so
+        // there can be a brief window where the daemon is up but the token is
+        // not yet on disk — poll up to ~2s before falling back to guidance, so
+        // we never open/print a bare URL that 401s.
+        let dashboardUrl = null;
+        if (opts.dashboard && isGuardRunning()) {
+            for (let i = 0; i < 20; i++) {
+                dashboardUrl = readAuthenticatedDashboardUrl();
+                if (dashboardUrl)
+                    break;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+        // ── Open dashboard (after Guard is up so the server is listening) ──
+        // Open + print the AUTHENTICATED URL so it works on rerun, headless, or
+        // when copied. If the token is unavailable, print guidance instead of a
+        // dead bare URL that would land on a 401 "Invalid token" page.
+        if (opts.dashboard) {
+            if (dashboardUrl) {
+                console.log(`\n  ${c.sage(`Opening dashboard: ${dashboardBaseUrl()}`)}\n`);
+                openBrowser(dashboardUrl);
+            }
+            else if (isGuardRunning()) {
+                console.log(`\n  ${c.caution(t(lang, `Dashboard is still starting. Re-run "pga up" in a moment to open it.`, `儀表板仍在啟動中。請稍後再次執行「pga up」開啟。`))}\n`);
+            }
+            else {
+                console.log(`\n  ${c.caution(t(lang, `Dashboard not available (Guard is not running). Start it with: pga up`, `儀表板無法使用（Guard 未執行）。請用以下指令啟動：pga up`))}\n`);
             }
         }
         // ── Read rule count + TC status ──────────
@@ -398,9 +641,21 @@ export function upCommand() {
         console.log(`\n  ${c.dim('\u2500'.repeat(50))}`);
         console.log(`  ${statusLabel} ${c.dim(`\u2014 ${elapsed}s`)}`);
         console.log(`  ${c.dim('\u2500'.repeat(50))}`);
+        // Honest persistence framing: say plainly whether protection survives a
+        // reboot \u2014 never imply always-on when it's only a until-reboot daemon.
+        const persisted = persistResult === 'installed' || persistResult === 'already' || isServiceInstalled();
+        if (guardRunning && persisted) {
+            console.log(`  ${c.dim(t(lang, 'Always-on: protection restarts after reboot (launchd).', '\u5e38\u99d0:\u91cd\u958b\u6a5f\u5f8c\u81ea\u52d5\u6062\u5fa9\u9632\u8b77(launchd)\u3002'))}`);
+        }
+        else if (guardRunning) {
+            console.log(`  ${c.dim(t(lang, 'Runs until reboot. For always-on monitoring: pga guard install', '\u6301\u7e8c\u5230\u91cd\u958b\u6a5f\u70ba\u6b62\u3002\u8981\u958b\u6a5f\u5f8c\u4ecd\u6301\u7e8c\u76e3\u63a7:pga guard install'))}`);
+        }
         console.log('');
         if (opts.dashboard) {
-            console.log(`  ${c.sage('Dashboard')}     ${DASHBOARD_URL}`);
+            // Print the AUTHENTICATED URL (with token) so copy-pasting it works —
+            // a bare URL 401s. Fall back to the base URL only as a last resort
+            // when the token is not yet on disk.
+            console.log(`  ${c.sage('Dashboard')}     ${dashboardUrl ?? dashboardBaseUrl()}`);
         }
         console.log(`  ${c.sage(t(lang, 'Rules', '規則'))}         ${ruleCount} ${t(lang, 'detection rules active', '條偵測規則運作中')}`);
         if (platformCount > 0) {
@@ -425,7 +680,13 @@ export function upCommand() {
         }
         // ── Next steps ─────────────────────────────────────────
         console.log(`  ${c.bold(t(lang, 'NEXT STEPS', '下一步'))}`);
-        console.log(`  ${c.dim('1.')} ${t(lang, 'Open dashboard', '開啟儀表板')}     ${c.sage(DASHBOARD_URL)}`);
+        if (dashboardUrl) {
+            console.log(`  ${c.dim('1.')} ${t(lang, 'Open dashboard', '開啟儀表板')}     ${c.sage(dashboardUrl)}`);
+        }
+        else {
+            // No live token: point at re-running `pga up` rather than a dead URL.
+            console.log(`  ${c.dim('1.')} ${t(lang, 'Open dashboard', '開啟儀表板')}     ${c.dim(t(lang, 'run "pga up" to open the dashboard', '執行「pga up」開啟儀表板'))}`);
+        }
         if (threatCount > 0) {
             console.log(`  ${c.dim('2.')} ${t(lang, 'Review threats', '檢視威脅')}     ${c.caution(`${threatCount} ${t(lang, 'flagged', '個標記')}`)} ${c.dim('\u2014 pga audit skill <name>')}`);
             console.log(`  ${c.dim('3.')} ${t(lang, 'Upgrade detection', '升級偵測')}  ${c.dim('pga guard setup-ai')}`);
@@ -436,11 +697,28 @@ export function upCommand() {
         console.log('');
         console.log(`  ${c.dim(t(lang, 'Layer 1 (regex) catches ~70% of attacks at zero cost.', 'Layer 1 (正則) 零成本攔截約 70% 攻擊。'))}`);
         console.log(`  ${c.dim(t(lang, 'Add Layer 2 (local AI) or 3 (cloud AI) for deeper detection.', '加入 Layer 2 (本地 AI) 或 Layer 3 (雲端 AI) 提升偵測深度。'))}`);
-        if (!telemetryDisabled) {
-            console.log(`  ${c.dim(t(lang, 'Telemetry: anonymous usage stats sent to tc.panguard.ai', '遙測：匿名使用統計會傳送至 tc.panguard.ai'))}`);
-            console.log(`  ${c.dim(t(lang, 'Opt out: pga config set telemetry false', '關閉：pga config set telemetry false'))}`);
+        if (tcUploadAllowed) {
+            console.log(`  ${c.dim(t(lang, 'Collective defense ON: when an attack is blocked, only the matched rule ID,', '集體防禦已開啟：擋下攻擊時，只分享命中的規則 ID、'))}`);
+            console.log(`  ${c.dim(t(lang, 'a one-way payload hash, and the source type are shared — never your prompts,', 'payload 的單向雜湊、來源類型 — 絕不含你的 prompt、'))}`);
+            console.log(`  ${c.dim(t(lang, 'code, file contents, keys, hostname, or IP. Thank you for defending the commons.', '程式碼、檔案內容、金鑰、主機名或 IP。謝謝你一起守護社群。'))}`);
+            console.log(`  ${c.dim(t(lang, 'Turn off anytime: pga config set telemetry false', '隨時可關閉：pga config set telemetry false'))}`);
+        }
+        else {
+            // OPT-IN guidance (NOT a default, NOT a nag): explain the value + the
+            // privacy guarantee + the one command, so the user can make an
+            // informed choice. Collective defense stays OFF until they opt in.
+            console.log(`  ${c.dim(t(lang, 'Collective defense is OFF — nothing leaves this machine.', '集體防禦目前關閉 — 沒有任何資料離開這台機器。'))}`);
+            console.log(`  ${c.dim(t(lang, 'Want to help? Each attack you block can become a new ATR rule that protects', '想幫忙嗎？你擋下的每次攻擊，都能變成一條保護所有人的新 ATR 規則，'))}`);
+            console.log(`  ${c.dim(t(lang, 'everyone — and you get community rules back faster. Shared: only the matched', '而你也能更快收到社群回流的規則。分享的只有命中的規則 ID、'))}`);
+            console.log(`  ${c.dim(t(lang, 'rule ID, a one-way hash, and the source type. Never your prompts, code,', 'payload 的單向雜湊、來源類型。絕不含你的 prompt、程式碼、'))}`);
+            console.log(`  ${c.dim(t(lang, 'file contents, keys, hostname, or IP. Opt in: pga config set telemetry true', '檔案內容、金鑰、主機名或 IP。開啟：pga config set telemetry true'))}`);
         }
         console.log('');
+        // The full first run completed: record the durable marker so the next
+        // `pga up` (and bare `pga`) skip the welcome + interactive setup and go
+        // straight to scan -> protect -> summary. Independent of telemetry
+        // consent, so opt-out users are no longer nagged every run.
+        markInitialized();
     });
 }
 /** Best-effort submit scan results to Threat Cloud for the flywheel */
@@ -551,7 +829,8 @@ async function reportActivation() {
     if (fe(marker))
         return;
     const { randomUUID } = await import('node:crypto');
-    const idPath = join(homedir(), '.panguard', 'client-id');
+    const idDir = join(homedir(), '.panguard');
+    const idPath = join(idDir, 'client-id');
     let clientId;
     try {
         clientId = rf(idPath, 'utf-8').trim();
@@ -559,6 +838,11 @@ async function reportActivation() {
     catch {
         clientId = randomUUID();
         try {
+            // On a true first run ~/.panguard may not exist yet; create it (0o700)
+            // before writing the client-id, otherwise the write ENOENTs and
+            // readSensorId() keeps returning null forever.
+            if (!fe(idDir))
+                md(idDir, { recursive: true, mode: 0o700 });
             wf(idPath, clientId, 'utf-8');
         }
         catch {