clementine-agent 1.1.0 → 1.1.2

package/dist/agent/execution-advisor.d.ts

@@ -24,7 +24,15 @@ export interface ReflectionEntry {
     gap: string;
     commNote: string;
 }
+export type AdvisorRulesMode = 'off' | 'shadow' | 'primary';
 export declare function getExecutionAdvice(jobName: string, job: CronJobDefinition): ExecutionAdvice;
+/**
+ * Mode-parameterized variant of getExecutionAdvice. Public so tests can
+ * exercise primary mode without mutating module-level env state.
+ */
+export declare function getExecutionAdviceWithMode(jobName: string, job: CronJobDefinition, mode: AdvisorRulesMode): ExecutionAdvice;
+/** Test-only: clear the rule-init flag so subsequent calls re-init. */
+export declare function _resetAdvisorRulesInit(): void;
 export declare function checkTurnLimitHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;
 export declare function checkReflectionQuality(reflections: ReflectionEntry[], job: CronJobDefinition, advice: ExecutionAdvice): void;
 export declare function checkTimeoutHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;

package/dist/agent/execution-advisor.js

@@ -11,8 +11,12 @@ import pino from 'pino';
 import { ADVISOR_RULES_LOADER, CRON_REFLECTIONS_DIR, ADVISOR_LOG_PATH } from '../config.js';
 import { CronRunLog } from '../gateway/heartbeat.js';
 import { evolvePrompt } from './prompt-evolver.js';
+import { loadAdvisorRules, getLoadedRules, watchUserRulesDir, } from './advisor-rules/loader.js';
+import { buildRuleContext } from './advisor-rules/context.js';
+import { applyRules } from './advisor-rules/engine.js';
 const logger = pino({ name: 'clementine.execution-advisor' });
 const shadowLogger = pino({ name: 'clementine.advisor-rules-shadow' });
+const primaryLogger = pino({ name: 'clementine.advisor-rules-primary' });
 // ── Tier caps for maxTurns ──────────────────────────────────────────
 export const TIER_MAX_TURNS = {
     1: 15,
@@ -22,8 +26,32 @@ export const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
 export const MAX_TIMEOUT_MS = 20 * 60 * 1000; // 20 minutes
 export const CIRCUIT_BREAKER_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour between retry probes
 export const DEFAULT_MAX_TURNS_FALLBACK = 5; // when job.maxTurns is unset
-// ── Core function ───────────────────────────────────────────────────
 export function getExecutionAdvice(jobName, job) {
+    return getExecutionAdviceWithMode(jobName, job, ADVISOR_RULES_LOADER);
+}
+/**
+ * Mode-parameterized variant of getExecutionAdvice. Public so tests can
+ * exercise primary mode without mutating module-level env state.
+ */
+export function getExecutionAdviceWithMode(jobName, job, mode) {
+    // Primary mode: rule engine is the source of truth. Falls through to the
+    // legacy TS path only if the loader is unavailable for some reason.
+    if (mode === 'primary') {
+        if (ensureRulesInitialized()) {
+            return computePrimaryAdvice(jobName, job);
+        }
+        primaryLogger.warn({ jobName }, 'Primary rule engine unavailable — falling back to legacy TS path');
+    }
+    const advice = computeLegacyAdvice(jobName, job);
+    // Shadow mode: run the YAML rule engine on the same job, log any divergence
+    // from the legacy TS advice. Non-throwing — never affects the returned advice.
+    if (mode === 'shadow' && ensureRulesInitialized()) {
+        runShadowComparison(jobName, job, advice);
+    }
+    return advice;
+}
+// ── Legacy TS path (kept as fallback for primary mode) ──────────────
+function computeLegacyAdvice(jobName, job) {
     const advice = {
         adjustedMaxTurns: null,
         adjustedModel: null,
@@ -101,67 +129,65 @@ export function getExecutionAdvice(jobName, job) {
     catch (err) {
         logger.warn({ err, job: jobName }, 'Execution advisor error — proceeding with defaults');
     }
-    // Shadow mode: run the YAML rule engine on the same job, log any divergence
-    // from the legacy TS advice. Non-throwing — never affects the returned advice.
-    if (ADVISOR_RULES_LOADER === 'shadow') {
-        runShadowComparison(jobName, job, advice);
-    }
     return advice;
 }
-// ── Shadow-mode comparison ──────────────────────────────────────────
-let shadowInitialized = false;
-let shadowAvailable = false;
-let shadowDeps = null;
-async function ensureShadowInitialized() {
-    if (shadowInitialized)
-        return;
-    shadowInitialized = true;
+// ── Rule-engine path ────────────────────────────────────────────────
+let rulesInitialized = false;
+let rulesAvailable = false;
+/** Sync init for the rule loader. Idempotent. Safe to call from any mode. */
+function ensureRulesInitialized() {
+    if (rulesInitialized)
+        return rulesAvailable;
+    rulesInitialized = true;
     try {
-        const [loaderMod, contextMod, engineMod] = await Promise.all([
-            import('./advisor-rules/loader.js'),
-            import('./advisor-rules/context.js'),
-            import('./advisor-rules/engine.js'),
-        ]);
-        shadowDeps = {
-            loadAdvisorRules: loaderMod.loadAdvisorRules,
-            getLoadedRules: loaderMod.getLoadedRules,
-            watchUserRulesDir: loaderMod.watchUserRulesDir,
-            buildRuleContext: contextMod.buildRuleContext,
-            applyRules: engineMod.applyRules,
-        };
-        shadowDeps.loadAdvisorRules();
-        shadowDeps.watchUserRulesDir();
-        shadowAvailable = true;
-        shadowLogger.info('Advisor rules shadow mode initialized');
+        loadAdvisorRules();
+        watchUserRulesDir();
+        rulesAvailable = true;
+        primaryLogger.info({ ruleCount: getLoadedRules().length }, 'Advisor rules initialized');
+    }
+    catch (err) {
+        primaryLogger.warn({ err }, 'Failed to initialize advisor rules — TS path will be used');
+        rulesAvailable = false;
+    }
+    return rulesAvailable;
+}
+function computePrimaryAdvice(jobName, job) {
+    try {
+        const rules = getLoadedRules();
+        const ctx = buildRuleContext(jobName, job);
+        const { advice, traces } = applyRules(rules, ctx);
+        const fired = traces.filter(t => t.fired).map(t => t.ruleId);
+        if (fired.length > 0) {
+            primaryLogger.debug({ jobName, firedRules: fired }, 'Rule engine produced advice');
+        }
+        return advice;
     }
     catch (err) {
-        shadowLogger.warn({ err }, 'Failed to initialize advisor rules shadow mode');
+        primaryLogger.warn({ err, jobName }, 'Rule engine threw — falling back to legacy TS path for this call');
+        return computeLegacyAdvice(jobName, job);
     }
 }
 function runShadowComparison(jobName, job, tsAdvice) {
-    // Fire-and-forget: kicks off async init the first time, then runs comparison
-    // synchronously on subsequent calls. Never throws.
-    ensureShadowInitialized()
-        .then(() => {
-        if (!shadowAvailable || !shadowDeps)
-            return;
-        try {
-            const rules = shadowDeps.getLoadedRules();
-            const ctx = shadowDeps.buildRuleContext(jobName, job);
-            const { advice: yamlAdvice, traces } = shadowDeps.applyRules(rules, ctx);
-            const diffs = diffAdvice(tsAdvice, yamlAdvice);
-            if (diffs.length > 0) {
-                shadowLogger.warn({ jobName, diffs, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor diverged from TS path');
-            }
-            else {
-                shadowLogger.debug({ jobName, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor matches TS path');
-            }
+    try {
+        const rules = getLoadedRules();
+        const ctx = buildRuleContext(jobName, job);
+        const { advice: yamlAdvice, traces } = applyRules(rules, ctx);
+        const diffs = diffAdvice(tsAdvice, yamlAdvice);
+        if (diffs.length > 0) {
+            shadowLogger.warn({ jobName, diffs, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor diverged from TS path');
         }
-        catch (err) {
-            shadowLogger.warn({ err, jobName }, 'Shadow advisor run failed');
+        else {
+            shadowLogger.debug({ jobName, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor matches TS path');
         }
-    })
-        .catch(() => { });
+    }
+    catch (err) {
+        shadowLogger.warn({ err, jobName }, 'Shadow advisor run failed');
+    }
+}
+/** Test-only: clear the rule-init flag so subsequent calls re-init. */
+export function _resetAdvisorRulesInit() {
+    rulesInitialized = false;
+    rulesAvailable = false;
 }
 function diffAdvice(a, b) {
     const fields = [

package/dist/cli/dashboard.js

@@ -7124,6 +7124,23 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.json({ byType: {}, totalOutcomes: 0 });
         }
     });
+    app.get('/api/advisor/status', async (_req, res) => {
+        try {
+            const { ADVISOR_RULES_LOADER } = await import('../config.js');
+            const { loadAdvisorRules } = await import('../agent/advisor-rules/loader.js');
+            const rules = loadAdvisorRules();
+            const builtinCount = rules.filter(r => r._sourcePath?.includes('/builtin/')).length;
+            res.json({
+                mode: ADVISOR_RULES_LOADER,
+                ruleCount: rules.length,
+                builtinCount,
+                userCount: rules.length - builtinCount,
+            });
+        }
+        catch (err) {
+            res.json({ mode: 'off', ruleCount: 0, builtinCount: 0, userCount: 0, error: String(err) });
+        }
+    });
     // ── Remote access API ────────────────────────────────────────────
     app.get('/api/remote-access', (_req, res) => {
         const config = loadRemoteConfig();
@@ -19927,12 +19944,34 @@ async function refreshHomeSessions() {
 // ── Execution Analytics ───────────────────
 async function refreshAdvisorAnalytics() {
   try {
-    const r = await apiFetch('/api/advisor/analytics');
+    const [statusR, r] = await Promise.all([
+      apiFetch('/api/advisor/status'),
+      apiFetch('/api/advisor/analytics'),
+    ]);
+    const status = await statusR.json();
     const data = await r.json();
     const container = document.getElementById('advisor-analytics-content');
 
     let html = '';
 
+    // Mode chip — surfaces the active rule-engine mode at a glance.
+    const modeColors = { off: 'var(--gray)', shadow: 'var(--blue)', primary: 'var(--green)' };
+    const modeColor = modeColors[status.mode] || 'var(--gray)';
+    const modeHints = {
+      off: 'Legacy TS path is the source of truth.',
+      shadow: 'Rule engine runs alongside the TS path; divergences are logged.',
+      primary: 'Rule engine is the source of truth.',
+    };
+    const modeHint = modeHints[status.mode] || '';
+    html += '<div style="display:flex;align-items:center;gap:12px;margin-bottom:16px;padding:10px 14px;background:var(--bg-elev);border-radius:8px;border-left:3px solid ' + modeColor + '">';
+    html += '<span style="font-size:11px;text-transform:uppercase;letter-spacing:0.05em;color:var(--text-dim)">Advisor mode</span>';
+    html += '<span style="font-weight:600;color:' + modeColor + '">' + esc(status.mode) + '</span>';
+    html += '<span style="font-size:12px;color:var(--text-dim)">' + esc(modeHint) + '</span>';
+    html += '<span style="margin-left:auto;font-size:11px;color:var(--text-dim)">' + status.ruleCount + ' rule' + (status.ruleCount === 1 ? '' : 's') + ' loaded';
+    if (status.userCount > 0) html += ' (' + status.userCount + ' user)';
+    html += '</span>';
+    html += '</div>';
+
     // Summary cards row
     html += '<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin-bottom:20px">';
     const stats = [

package/dist/cli/index.js

@@ -24,6 +24,7 @@ import { cmdCronList, cmdCronRun, cmdCronRunDue, cmdCronRuns, cmdCronAdd, cmdCro
 import { cmdDashboard } from './dashboard.js';
 import { cmdChat } from './chat.js';
 import { cmdIngestSeed, cmdIngestRun, cmdIngestList, cmdIngestStatus } from './ingest.js';
+import { isSensitiveEnvKey } from '../secrets/sensitivity.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // ── Path resolution ─────────────────────────────────────────────────
@@ -935,9 +936,7 @@ function cmdConfigList() {
             const match = line.match(/^([A-Z_]+)=(.+)$/);
             if (match) {
                 const [, k, v] = match;
-                const sensitiveKeys = ['TOKEN', 'SECRET', 'API_KEY', 'AUTH_TOKEN', 'SID'];
-                const isSensitive = sensitiveKeys.some((s) => k.includes(s));
-                if (isSensitive && v.length > 8) {
+                if (isSensitiveEnvKey(k) && v.length > 8) {
                     console.log(`  ${k}=${v.slice(0, 4)}${'*'.repeat(v.length - 8)}${v.slice(-4)}`);
                 }
                 else {
@@ -951,6 +950,294 @@ function cmdConfigList() {
     }
     console.log();
 }
+// ── Config show ──────────────────────────────────────────────────────
+async function cmdConfigShow(opts) {
+    const { computeEffectiveConfig } = await import('../config/effective-config.js');
+    const cfg = computeEffectiveConfig(BASE_DIR);
+    if (opts.json) {
+        console.log(JSON.stringify(cfg, null, 2));
+        return;
+    }
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const CYAN = '\x1b[0;36m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const BLUE = '\x1b[0;34m';
+    const RESET = '\x1b[0m';
+    const sourceColor = {
+        'process.env': YELLOW,
+        '.env': GREEN,
+        'clementine.json': CYAN,
+        'system': BLUE,
+        'default': DIM,
+    };
+    console.log();
+    console.log(`  ${BOLD}Data home:${RESET}        ${cfg.baseDir}`);
+    console.log(`  ${BOLD}.env present:${RESET}     ${cfg.hasEnvFile ? GREEN + 'yes' : DIM + 'no'}${RESET}`);
+    console.log(`  ${BOLD}clementine.json:${RESET}  ${cfg.hasJsonFile ? GREEN + 'present' : DIM + 'missing — defaults active'}${RESET}`);
+    console.log();
+    console.log(`  ${DIM}Sources (highest precedence first):${RESET}`);
+    console.log(`    ${YELLOW}process.env${RESET}     runtime override`);
+    console.log(`    ${GREEN}.env${RESET}            ~/.clementine/.env`);
+    console.log(`    ${CYAN}clementine.json${RESET} canonical user config`);
+    console.log(`    ${BLUE}system${RESET}          OS-derived default (e.g., timezone)`);
+    console.log(`    ${DIM}default${RESET}         compiled fallback`);
+    console.log();
+    // Group entries
+    const filtered = opts.group
+        ? cfg.entries.filter(e => e.group === opts.group)
+        : cfg.entries;
+    const byGroup = new Map();
+    for (const entry of filtered) {
+        const g = entry.group ?? 'misc';
+        if (!byGroup.has(g))
+            byGroup.set(g, []);
+        byGroup.get(g).push(entry);
+    }
+    if (filtered.length === 0) {
+        console.log(`  ${DIM}No entries${opts.group ? ` in group "${opts.group}"` : ''}.${RESET}`);
+        console.log();
+        return;
+    }
+    // Column widths
+    const keyWidth = Math.max(...filtered.map(e => e.key.length));
+    const valueWidth = Math.max(...filtered.map(e => String(e.value).length), 12);
+    const RED = '\x1b[0;31m';
+    for (const [group, entries] of byGroup) {
+        console.log(`  ${BOLD}${group}${RESET}`);
+        for (const entry of entries) {
+            const c = sourceColor[entry.source] ?? RESET;
+            const valueStr = String(entry.value);
+            const annotations = [];
+            if (entry.resolvedFrom === 'keychain')
+                annotations.push(`${BLUE}via keychain${RESET}`);
+            if (entry.unresolvedRef)
+                annotations.push(`${RED}UNRESOLVED REF — using fallback${RESET}`);
+            if (entry.shadowedBy && entry.shadowedBy.length > 0)
+                annotations.push(`${DIM}shadows: ${entry.shadowedBy.join(', ')}${RESET}`);
+            const annot = annotations.length > 0 ? ` ${DIM}(${RESET}${annotations.join(`${DIM},${RESET} `)}${DIM})${RESET}` : '';
+            console.log(`    ${entry.key.padEnd(keyWidth)}  ${valueStr.padEnd(valueWidth)}  ${c}${entry.source}${RESET}${annot}`);
+        }
+        console.log();
+    }
+}
+// ── Config doctor ────────────────────────────────────────────────────
+async function cmdConfigDoctor(opts) {
+    const { runDoctor } = await import('../config/config-doctor.js');
+    const report = runDoctor(BASE_DIR);
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(report.exitCode);
+    }
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const sevColor = { error: RED, warning: YELLOW, info: DIM };
+    const sevSymbol = { error: '✗', warning: '⚠', info: '·' };
+    console.log();
+    console.log(`  ${BOLD}Data home:${RESET}        ${report.baseDir}`);
+    console.log(`  ${BOLD}.env present:${RESET}     ${report.hasEnvFile ? GREEN + 'yes' : DIM + 'no'}${RESET}`);
+    console.log(`  ${BOLD}clementine.json:${RESET}  ${report.hasJsonFile ? GREEN + 'present' : DIM + 'missing'}${RESET}`);
+    console.log();
+    if (report.findings.length === 0) {
+        console.log(`  ${GREEN}✓ All checks passed.${RESET}`);
+        console.log();
+        process.exit(0);
+    }
+    for (const f of report.findings) {
+        const c = sevColor[f.severity];
+        const sym = sevSymbol[f.severity];
+        const keyTag = f.key ? `${BOLD}${f.key}${RESET} ${DIM}—${RESET} ` : '';
+        console.log(`  ${c}${sym}${RESET} ${keyTag}${f.message}`);
+        if (f.fix) {
+            console.log(`    ${DIM}↳${RESET} ${f.fix}`);
+        }
+    }
+    console.log();
+    const summary = [];
+    if (report.counts.error > 0)
+        summary.push(`${RED}${report.counts.error} error${report.counts.error === 1 ? '' : 's'}${RESET}`);
+    if (report.counts.warning > 0)
+        summary.push(`${YELLOW}${report.counts.warning} warning${report.counts.warning === 1 ? '' : 's'}${RESET}`);
+    if (report.counts.info > 0)
+        summary.push(`${DIM}${report.counts.info} info${RESET}`);
+    console.log(`  ${summary.join(', ')}`);
+    console.log();
+    process.exit(report.exitCode);
+}
+// ── Config migrate-to-keychain ───────────────────────────────────────
+async function cmdConfigMigrateToKeychain(opts) {
+    const { planMigration, applyMigration } = await import('../config/migrate-keychain.js');
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RED = '\x1b[0;31m';
+    const CYAN = '\x1b[0;36m';
+    const RESET = '\x1b[0m';
+    // Commander gives us either ['a', 'b'] or ['a,b'] depending on how the
+    // user passed the flag — normalize.
+    const only = opts.key
+        ? opts.key.flatMap(k => k.split(',').map(s => s.trim()).filter(Boolean))
+        : undefined;
+    const plan = planMigration(BASE_DIR, only ? { only } : {});
+    console.log();
+    console.log(`  ${BOLD}.env path:${RESET}  ${plan.envPath}`);
+    console.log();
+    if (plan.candidates.length === 0) {
+        console.log(`  ${DIM}No env entries found (.env may be empty or missing).${RESET}`);
+        console.log();
+        return;
+    }
+    // Group by status for readable output
+    const groups = {};
+    for (const c of plan.candidates) {
+        (groups[c.status] ??= []).push(c);
+    }
+    const renderGroup = (label, color, items) => {
+        if (!items || items.length === 0)
+            return;
+        console.log(`  ${color}${label}${RESET} ${DIM}(${items.length})${RESET}`);
+        for (const c of items) {
+            console.log(`    ${c.key} ${DIM}(${c.valueLength} chars)${RESET}`);
+        }
+        console.log();
+    };
+    renderGroup('Will migrate to keychain', CYAN, groups.migrated);
+    renderGroup('Already in keychain (skipped)', DIM, groups['already-keychain']);
+    renderGroup('Not credential-shaped (skipped)', DIM, groups['not-sensitive']);
+    renderGroup('Too short to be a credential (skipped)', DIM, groups['too-short']);
+    if (plan.toMigrate.length === 0) {
+        console.log(`  ${GREEN}Nothing to migrate.${RESET}`);
+        console.log();
+        return;
+    }
+    if (opts.dryRun) {
+        console.log(`  ${YELLOW}Dry run — no changes written.${RESET}`);
+        console.log(`  ${DIM}Re-run without --dry-run to apply.${RESET}`);
+        console.log();
+        return;
+    }
+    console.log(`  ${BOLD}Applying...${RESET}`);
+    let result;
+    try {
+        result = applyMigration(BASE_DIR, only ? { only } : {});
+    }
+    catch (err) {
+        console.error(`  ${RED}Failed:${RESET} ${err.message}`);
+        process.exit(1);
+    }
+    if (result.failed.length > 0) {
+        console.log(`  ${RED}Some keychain writes failed — .env was NOT modified:${RESET}`);
+        for (const f of result.failed) {
+            console.log(`    ${RED}✗${RESET} ${f.key}: ${f.error}`);
+        }
+        console.log();
+        process.exit(1);
+    }
+    for (const key of result.migrated) {
+        console.log(`    ${GREEN}✓${RESET} ${key} ${DIM}→ keychain${RESET}`);
+    }
+    console.log();
+    console.log(`  ${GREEN}Migrated ${result.migrated.length} key${result.migrated.length === 1 ? '' : 's'}.${RESET}`);
+    console.log(`  ${DIM}First daemon read of each ref will trigger a one-time keychain prompt;${RESET}`);
+    console.log(`  ${DIM}choose Always Allow to make the prompt permanent.${RESET}`);
+    console.log();
+}
+// ── Advisor commands ────────────────────────────────────────────────
+const ADVISOR_MODES = ['off', 'shadow', 'primary'];
+function readAdvisorMode() {
+    if (!existsSync(ENV_PATH))
+        return 'off';
+    const content = readFileSync(ENV_PATH, 'utf-8');
+    const match = content.match(/^CLEMENTINE_ADVISOR_RULES_LOADER=(.*)$/m);
+    if (!match)
+        return 'off';
+    const raw = match[1].trim().toLowerCase();
+    if (raw === 'shadow' || raw === 'primary')
+        return raw;
+    return 'off';
+}
+async function cmdAdvisorStatus() {
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const CYAN = '\x1b[0;36m';
+    const YELLOW = '\x1b[0;33m';
+    const GREEN = '\x1b[0;32m';
+    const RESET = '\x1b[0m';
+    const mode = readAdvisorMode();
+    const modeColor = mode === 'primary' ? GREEN : mode === 'shadow' ? CYAN : DIM;
+    console.log();
+    console.log(`  ${BOLD}Advisor mode:${RESET} ${modeColor}${mode}${RESET}`);
+    if (mode === 'off') {
+        console.log(`  ${DIM}Legacy TS path is the source of truth. Rule engine not loaded.${RESET}`);
+    }
+    else if (mode === 'shadow') {
+        console.log(`  ${DIM}Rule engine runs alongside TS path; divergences logged but TS path wins.${RESET}`);
+    }
+    else {
+        console.log(`  ${DIM}Rule engine is the source of truth; TS path used only as fallback.${RESET}`);
+    }
+    // Load the rules from disk to show the user-visible inventory.
+    try {
+        const { loadAdvisorRules } = await import('../agent/advisor-rules/loader.js');
+        const rules = loadAdvisorRules();
+        const builtinCount = rules.filter(r => r._sourcePath?.includes('/builtin/')).length;
+        const userCount = rules.length - builtinCount;
+        console.log();
+        console.log(`  ${BOLD}Loaded rules:${RESET} ${rules.length} ${DIM}(${builtinCount} builtin, ${userCount} user)${RESET}`);
+    }
+    catch (err) {
+        console.log(`  ${YELLOW}Could not load rules:${RESET} ${err.message}`);
+    }
+    console.log();
+    console.log(`  ${DIM}Switch mode: clementine advisor mode <off|shadow|primary>${RESET}`);
+    console.log(`  ${DIM}List rules:  clementine advisor rules${RESET}`);
+    console.log();
+}
+function cmdAdvisorMode(mode) {
+    const YELLOW = '\x1b[0;33m';
+    const GREEN = '\x1b[0;32m';
+    const RESET = '\x1b[0m';
+    const lower = mode.toLowerCase();
+    if (!ADVISOR_MODES.includes(lower)) {
+        console.error(`  Invalid mode "${mode}". Choose one of: ${ADVISOR_MODES.join(', ')}`);
+        process.exit(1);
+    }
+    cmdConfigSet('CLEMENTINE_ADVISOR_RULES_LOADER', lower);
+    console.log(`  ${GREEN}Advisor mode set to ${lower}.${RESET}`);
+    console.log(`  ${YELLOW}Restart the daemon for the change to take effect:${RESET} clementine restart`);
+}
+async function cmdAdvisorRules() {
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const CYAN = '\x1b[0;36m';
+    const RESET = '\x1b[0m';
+    try {
+        const { loadAdvisorRules } = await import('../agent/advisor-rules/loader.js');
+        const rules = loadAdvisorRules();
+        if (rules.length === 0) {
+            console.log('  No advisor rules loaded.');
+            return;
+        }
+        console.log();
+        console.log(`  ${BOLD}${'PRI'.padEnd(5)}${'ID'.padEnd(38)}SOURCE  DESCRIPTION${RESET}`);
+        for (const r of rules) {
+            const source = r._sourcePath?.includes('/builtin/') ? 'builtin' : 'user   ';
+            const desc = (r.description || '').slice(0, 60);
+            console.log(`  ${String(r.priority).padEnd(5)}${CYAN}${r.id.padEnd(38)}${RESET}${DIM}${source}${RESET}  ${desc}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error loading rules: ${err.message}`);
+        process.exit(1);
+    }
+}
 // ── Tools command ───────────────────────────────────────────────────
 function cmdTools() {
     const DIM = '\x1b[0;90m';
@@ -1396,6 +1683,18 @@ program
     .command('tools')
     .description('List available MCP tools, plugins, and channels')
     .action(cmdTools);
+const advisorCmd = program
+    .command('advisor')
+    .description('Inspect and configure the execution advisor')
+    .action(() => cmdAdvisorStatus());
+advisorCmd
+    .command('mode <mode>')
+    .description('Set advisor mode (off | shadow | primary) — restart required')
+    .action(cmdAdvisorMode);
+advisorCmd
+    .command('rules')
+    .description('List loaded advisor rules')
+    .action(cmdAdvisorRules);
 const dashCmd = program
     .command('dashboard')
     .description('Launch local command center')
@@ -1480,6 +1779,29 @@ configCmd
     .command('list')
     .description('List all config values')
     .action(cmdConfigList);
+configCmd
+    .command('show')
+    .description('Show effective config with provenance (env / json / default)')
+    .option('--json', 'Emit machine-readable JSON instead of a table')
+    .option('-g, --group <name>', 'Filter to a single group (e.g. budgets)')
+    .action(async (opts) => {
+    await cmdConfigShow(opts);
+});
+configCmd
+    .command('doctor')
+    .description('Validate config: stale keychain refs, type errors, missing channel deps')
+    .option('--json', 'Emit machine-readable JSON instead of a checklist')
+    .action(async (opts) => {
+    await cmdConfigDoctor(opts);
+});
+configCmd
+    .command('migrate-to-keychain')
+    .description('Move plaintext credentials in .env into the macOS keychain (in place)')
+    .option('--dry-run', 'Show what would migrate without writing anything')
+    .option('-k, --key <name...>', 'Limit to specific key(s); repeat or comma-separate for multiple')
+    .action(async (opts) => {
+    await cmdConfigMigrateToKeychain(opts);
+});
 configCmd
     .command('edit')
     .description('Open .env in your editor')

package/dist/config/clementine-json.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Clementine JSON config loader.
+ *
+ * `~/.clementine/clementine.json` is the canonical user-editable config file.
+ * Each field is optional — missing values fall through to .env, then to
+ * compiled defaults. Precedence (highest first):
+ *
+ *   1. process.env (CI/runtime overrides)
+ *   2. ~/.clementine/.env (existing user-edited config)
+ *   3. ~/.clementine/clementine.json (this file)
+ *   4. Compiled defaults
+ *
+ * The file is created on first run by the 0005 migration (kind: 'config').
+ * Loader validates with zod and falls back gracefully on malformed input —
+ * a corrupt file is logged and treated as empty.
+ *
+ * Cached by mtime so subsequent reads are O(1) absent file changes.
+ */
+import { z } from 'zod';
+export declare const clementineJsonSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ownerName: z.ZodOptional<z.ZodString>;
+    assistantName: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    models: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+        haiku: z.ZodOptional<z.ZodString>;
+        sonnet: z.ZodOptional<z.ZodString>;
+        opus: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    budgets: z.ZodOptional<z.ZodObject<{
+        heartbeat: z.ZodOptional<z.ZodNumber>;
+        cronT1: z.ZodOptional<z.ZodNumber>;
+        cronT2: z.ZodOptional<z.ZodNumber>;
+        chat: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    heartbeat: z.ZodOptional<z.ZodObject<{
+        intervalMinutes: z.ZodOptional<z.ZodNumber>;
+        activeStart: z.ZodOptional<z.ZodNumber>;
+        activeEnd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    unleashed: z.ZodOptional<z.ZodObject<{
+        phaseTurns: z.ZodOptional<z.ZodNumber>;
+        defaultMaxHours: z.ZodOptional<z.ZodNumber>;
+        maxPhases: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClementineJson = z.infer<typeof clementineJsonSchema>;
+export declare function clementineJsonPath(baseDir: string): string;
+/**
+ * Load and validate clementine.json. Returns an empty object if the file
+ * is missing, unreadable, or fails validation. Cached by mtime.
+ */
+export declare function loadClementineJson(baseDir: string): ClementineJson;
+/** Test-only: clear the loader cache. */
+export declare function _resetClementineJsonCache(): void;
+/** String resolution. */
+export declare function resolveString(envValue: string, jsonValue: string | undefined, fallback: string): string;
+/**
+ * Numeric resolution. Env values that don't parse as finite numbers
+ * fall through to JSON, then the default — mirrors optionalTokenEnv tolerance.
+ */
+export declare function resolveNumber(envValue: string, jsonValue: number | undefined, fallback: number): number;
+//# sourceMappingURL=clementine-json.d.ts.map