@claude-flow/cli 3.25.6 → 3.26.0

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1783692950735,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/catalog-manifest.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "generation": 1,
+  "generatedAt": "2026-07-13T16:09:11.080Z",
+  "gitSha": "2d42012e",
+  "catalog": {
+    "agents": 164,
+    "tools": 387,
+    "skills": 34
+  },
+  "benchmark": null
+}

package/dist/src/commands/advisor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `ruflo advisor` — Fable co-pilot advisor tip in the statusline insight
+ * ticker (ADR-316).
+ *
+ * Client-side only — unlike `proxy.ts`'s sponsored-downtime/power-saver/
+ * training-share domains, this feature has NO proxy-config.toml mirror,
+ * because it never talks to the meta-proxy Rust binary. It calls
+ * `claude -p` directly via services/fable-harness.ts (ADR-172's existing
+ * cost-disciplined harness) and caches the result for the insight ticker
+ * (funnel/insights.ts) to read synchronously.
+ */
+import type { Command } from '../types.js';
+export declare const advisorCommand: Command;
+export default advisorCommand;
+//# sourceMappingURL=advisor.d.ts.map

package/dist/src/commands/advisor.js

@@ -0,0 +1,94 @@
+/**
+ * `ruflo advisor` — Fable co-pilot advisor tip in the statusline insight
+ * ticker (ADR-316).
+ *
+ * Client-side only — unlike `proxy.ts`'s sponsored-downtime/power-saver/
+ * training-share domains, this feature has NO proxy-config.toml mirror,
+ * because it never talks to the meta-proxy Rust binary. It calls
+ * `claude -p` directly via services/fable-harness.ts (ADR-172's existing
+ * cost-disciplined harness) and caches the result for the insight ticker
+ * (funnel/insights.ts) to read synchronously.
+ */
+import { output } from '../output.js';
+import { hasConsent, recordConsent, revokeConsent } from '../funnel/consent.js';
+import { recordFunnelEvent } from '../funnel/events.js';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+import { readAdvisorTip, ADVISOR_DEFAULT_BUDGET_USD } from '../funnel/advisor-tip.js';
+const ADVISOR_DISCLOSURE = [
+    'Enabling the co-pilot advisor tip.',
+    '',
+    'At most once per day, ruflo will send a small STRUCTURAL snapshot of your',
+    'session — security scan status, swarm/agent state, git uncommitted-file',
+    'COUNT — never raw prompts, file contents, or commands — to a headless',
+    'Fable model (via `claude -p`) and cache one short, actionable tip for the',
+    'statusline insight ticker.',
+    '',
+    `This is a real, metered API call (~$${ADVISOR_DEFAULT_BUDGET_USD.toFixed(2)} budget cap per`,
+    'refresh, at most once/day). Disable anytime: ruflo advisor disable',
+].join('\n');
+const enableSub = {
+    name: 'enable',
+    description: 'Opt into the co-pilot advisor tip (ADR-316)',
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        if (hasConsent('advisor-tips')) {
+            output.writeln('Advisor tip is already enabled.');
+            return { success: true, data: { alreadyEnabled: true } };
+        }
+        output.writeln(ADVISOR_DISCLOSURE);
+        output.writeln('');
+        if (!ctx.flags.yes) {
+            output.writeln('Re-run with --yes to confirm: ruflo advisor enable --yes');
+            return { success: true, data: { confirmed: false } };
+        }
+        recordConsent('advisor-tips', true, 'advisor-enable');
+        recordFunnelEvent('advisor_tip_enabled', 'statusline', getInstalledCliVersion());
+        output.printSuccess('Advisor tip enabled.');
+        output.writeln('It refreshes at most once/day, in the background, on session-restore.');
+        output.writeln('Disable anytime: ruflo advisor disable');
+        return { success: true, data: { confirmed: true } };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Revoke advisor-tip consent and stop generating new tips',
+    action: async () => {
+        revokeConsent('advisor-tips', 'advisor-disable');
+        recordFunnelEvent('advisor_tip_disabled', 'statusline', getInstalledCliVersion());
+        output.printSuccess('Advisor tip disabled.');
+        return { success: true };
+    },
+};
+const statusSub = {
+    name: 'status',
+    description: 'Show advisor-tip consent state and the current cached tip',
+    action: async () => {
+        const consented = hasConsent('advisor-tips');
+        output.writeln(`Advisor tip consent: ${consented ? 'granted' : 'not granted'}`);
+        const tip = consented ? readAdvisorTip() : null;
+        if (tip) {
+            output.writeln(`Current tip: ${tip.headline}`);
+            if (tip.detail)
+                output.writeln(`  ${tip.detail}`);
+        }
+        else if (consented) {
+            output.writeln('No cached tip yet (refreshes at most once/day on session-restore).');
+        }
+        return { success: true, data: { consented, tip } };
+    },
+};
+export const advisorCommand = {
+    name: 'advisor',
+    description: 'Fable co-pilot advisor tip in the statusline insight ticker (ADR-316)',
+    subcommands: [enableSub, disableSub, statusSub],
+    examples: [
+        { command: 'ruflo advisor enable --yes', description: 'Opt into the co-pilot advisor tip' },
+        { command: 'ruflo advisor status', description: 'Show consent state + current cached tip' },
+        { command: 'ruflo advisor disable', description: 'Revoke consent and stop generating tips' },
+    ],
+    action: statusSub.action,
+};
+export default advisorCommand;
+//# sourceMappingURL=advisor.js.map

package/dist/src/commands/doctor.js

@@ -135,8 +135,10 @@ async function checkConfigFile() {
  * the broken commands).
  */
 async function checkStaleSettingsNpx() {
-    // Same regex pattern the executor migration uses — kept in sync.
-    const BROKEN_RE = /npx\s+(?:--?\S+\s+)*@?claude-flow\/cli@latest\s+hooks\s+(?:statusline|\S+)/;
+    // Same regex pattern the executor migration uses — kept in sync. Flag-list
+    // repetition bounded at 10 (CodeQL js/redos — unbounded `*` here is
+    // exponential-backtracking-prone on a crafted settings.json).
+    const BROKEN_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+hooks\s+(?:statusline|\S+)/;
     // Look in both project-local and home-dir settings.
     const candidates = [
         join(process.cwd(), '.claude', 'settings.json'),
@@ -711,6 +713,74 @@ async function checkVersionFreshness() {
  *   - plugins/ruflo-metaharness/skills/harness-similarity/SKILL.md
  *   - plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.md  (iter 53)
  */
+/**
+ * ADR-305 — funnel state audit. Reports the effective enabled/disabled
+ * state and, critically for enterprise audit verification, WHICH
+ * precedence source decided it (env > enterprise > user > default).
+ * Informational: both states are `pass`; only a resolver failure warns.
+ */
+async function checkFunnel() {
+    try {
+        const { resolveFunnelEnabled, getDisclosure } = await import('../funnel/index.js');
+        const decision = resolveFunnelEnabled();
+        const disclosure = getDisclosure();
+        return {
+            name: 'Funnel (ADR-305)',
+            status: 'pass',
+            message: `${decision.enabled ? 'enabled' : 'disabled'} (decided by: ${decision.decidedBy}; disclosure: ${disclosure.state})`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'Funnel (ADR-305)',
+            status: 'warn',
+            message: `state unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            fix: 'ruflo funnel status',
+        };
+    }
+}
+/** Meta LLM Proxy — sponsored-downtime health (ADR-313). */
+async function checkProxy() {
+    try {
+        const { funnelStateDir, hasConsent, readRateLimitStatus, lastRecordedEvent } = await import('../funnel/index.js');
+        const dir = funnelStateDir();
+        const installed = existsSync(join(dir, 'proxy-token'));
+        const consented = hasConsent('sponsored-downtime');
+        const rateLimited = readRateLimitStatus();
+        const lastExhausted = lastRecordedEvent('sponsor_capacity_exhausted');
+        if (!installed) {
+            return {
+                name: 'Meta LLM Proxy (ADR-313)',
+                status: 'warn',
+                message: 'not installed — no proxy-token found; sponsored-downtime capacity is unavailable',
+                fix: 'See cognitum-one/meta-proxy (private) for install instructions',
+            };
+        }
+        const parts = [
+            `sponsored consent: ${consented ? 'granted' : 'not granted'}`,
+            `rate-limit flag: ${rateLimited.limited ? `set (since ${rateLimited.since})` : 'not set'}`,
+        ];
+        if (lastExhausted)
+            parts.push(`last capacity-exhausted: ${lastExhausted}`);
+        if (rateLimited.limited && !consented) {
+            return {
+                name: 'Meta LLM Proxy (ADR-313)',
+                status: 'warn',
+                message: `${parts.join('; ')} — flagged rate-limited but sponsored capacity isn't enabled`,
+                fix: 'ruflo proxy sponsor-enable --yes',
+            };
+        }
+        return { name: 'Meta LLM Proxy (ADR-313)', status: 'pass', message: parts.join('; ') };
+    }
+    catch (err) {
+        return {
+            name: 'Meta LLM Proxy (ADR-313)',
+            status: 'warn',
+            message: `state unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            fix: 'ruflo proxy sponsor-status',
+        };
+    }
+}
 async function checkMetaharnessIntegration() {
     // Locate plugins dir.
     //
@@ -1087,7 +1157,7 @@ export const doctorCommand = {
         {
             name: 'component',
             short: 'c',
-            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, metaharness)',
             type: 'string'
         },
         {
@@ -1137,6 +1207,8 @@ export const doctorCommand = {
             checkFederationBreaker, // ADR-097 Phase 4
             checkMetaharness, // ADR-150 — MetaHarness upstream package
             checkMetaharnessIntegration, // iter 45 — ruflo-side integration layer
+            checkFunnel, // ADR-305 — effective funnel state + deciding precedence source
+            checkProxy, // ADR-313 — Meta LLM Proxy sponsored-downtime health
         ];
         const componentMap = {
             'version': checkVersionFreshness,
@@ -1161,6 +1233,8 @@ export const doctorCommand = {
             'federation': checkFederationBreaker, // ADR-097 Phase 4
             'metaharness': checkMetaharness, // ADR-150 — upstream package
             'metaharness-integration': checkMetaharnessIntegration, // iter 45 — ruflo-side
+            'funnel': checkFunnel, // ADR-305
+            'proxy': checkProxy, // ADR-313
         };
         let checksToRun = allChecks;
         if (component && componentMap[component]) {

package/dist/src/commands/funnel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
+ * (ADR-301/305/309).
+ *
+ *   funnel status    effective state and which precedence source decided it
+ *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
+ *   funnel id        print the pseudonymous funnel ID, if one exists
+ */
+import type { Command } from '../types.js';
+export declare const funnelCommand: Command;
+export default funnelCommand;
+//# sourceMappingURL=funnel.d.ts.map

package/dist/src/commands/funnel.js

@@ -0,0 +1,103 @@
+/**
+ * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
+ * (ADR-301/305/309).
+ *
+ *   funnel status    effective state and which precedence source decided it
+ *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
+ *   funnel id        print the pseudonymous funnel ID, if one exists
+ */
+import { output } from '../output.js';
+import { deleteFunnelData, funnelStateDir, getDisclosure, getFunnelId, readConsents, recordDisclosureDeclined, recordDisclosureReenabled, resolveFunnelEnabled, } from '../funnel/index.js';
+import { readStateJson, writeStateJson } from '../funnel/state.js';
+function setUserConfigEnabled(enabled) {
+    const cfg = readStateJson('funnel.json') ?? {};
+    cfg.enabled = enabled;
+    writeStateJson('funnel.json', cfg);
+}
+const statusSub = {
+    name: 'status',
+    description: 'Show effective funnel state and which source decided it',
+    options: [
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const decision = resolveFunnelEnabled();
+        const disclosure = getDisclosure();
+        const consents = readConsents();
+        const data = {
+            enabled: decision.enabled,
+            decidedBy: decision.decidedBy,
+            disclosure: disclosure.state,
+            stateDir: funnelStateDir(),
+            consents,
+        };
+        if (ctx.flags.json) {
+            output.printJson(data);
+        }
+        else {
+            output.writeln(`Funnel: ${decision.enabled ? 'enabled' : 'disabled'} (decided by: ${decision.decidedBy})`);
+            output.writeln(`Disclosure: ${disclosure.state}`);
+            output.writeln(`State dir: ${funnelStateDir()}`);
+            const domains = Object.keys(consents);
+            output.writeln(domains.length
+                ? `Consents: ${domains.map((d) => `${d}=${consents[d]?.granted ? 'granted' : 'declined'}`).join(', ')}`
+                : 'Consents: none recorded');
+        }
+        return { success: true, data };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Disable all funnel surfaces (user-level, persists across projects)',
+    action: async () => {
+        setUserConfigEnabled(false);
+        recordDisclosureDeclined();
+        deleteFunnelData(); // opt-out deletes the pseudonymous ID + local event queue
+        output.printSuccess('Funnel disabled. All promotional surfaces are off; local funnel data deleted.');
+        return { success: true };
+    },
+};
+const enableSub = {
+    name: 'enable',
+    description: 'Re-enable funnel surfaces at the user tier (env/enterprise disables still win)',
+    action: async () => {
+        setUserConfigEnabled(true);
+        recordDisclosureReenabled();
+        const decision = resolveFunnelEnabled();
+        if (decision.enabled) {
+            output.printSuccess('Funnel enabled.');
+        }
+        else {
+            // A lower-precedence source never overrides a higher-precedence disable.
+            output.printWarning(`User preference recorded, but the funnel stays disabled by a higher-precedence source: ${decision.decidedBy}`);
+        }
+        return { success: true, data: decision };
+    },
+};
+const idSub = {
+    name: 'id',
+    description: 'Print the pseudonymous funnel ID (exists only with telemetry consent)',
+    action: async () => {
+        const id = getFunnelId();
+        if (id) {
+            output.writeln(id);
+        }
+        else {
+            output.writeln('No funnel ID (telemetry consent not granted, or funnel data deleted).');
+        }
+        return { success: true, data: { id } };
+    },
+};
+export const funnelCommand = {
+    name: 'funnel',
+    description: 'Control the Cognitum lifecycle funnel surfaces (tips, enrollment, notices)',
+    subcommands: [statusSub, disableSub, enableSub, idSub],
+    examples: [
+        { command: 'ruflo funnel status', description: 'Effective state + deciding source' },
+        { command: 'ruflo funnel disable', description: 'Turn off every funnel surface' },
+    ],
+    action: statusSub.action,
+};
+export default funnelCommand;
+//# sourceMappingURL=funnel.js.map

package/dist/src/commands/hooks.js

@@ -8,6 +8,7 @@ import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { storeCommand } from './transfer-store.js';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { getSecurityStatus as sharedGetSecurityStatus, getSwarmStatus as sharedGetSwarmStatus, getGitUncommittedCount as sharedGetGitUncommittedCount, } from '../funnel/local-signals.js';
 /**
  * #1686 — `?? 0` only defaults null/undefined; NaN slips through and
  * surfaces as `"NaN"` (or earlier crashed `.toFixed`) in the metrics
@@ -3412,52 +3413,11 @@ const statuslineCommand = {
             const dddProgress = Math.min(100, Math.floor((domainsCompleted / totalDomains) * 100));
             return { domainsCompleted, totalDomains, dddProgress, patternsLearned: learning.patterns, sessionsCompleted: learning.sessions };
         }
-        // Get security status
-        function getSecurityStatus() {
-            const scanResultsPath = path.join(process.cwd(), '.claude', 'security-scans');
-            let cvesFixed = 0;
-            const totalCves = 3;
-            if (fs.existsSync(scanResultsPath)) {
-                try {
-                    const scans = fs.readdirSync(scanResultsPath).filter((f) => f.endsWith('.json'));
-                    cvesFixed = Math.min(totalCves, scans.length);
-                }
-                catch {
-                    // Ignore
-                }
-            }
-            const auditPath = path.join(process.cwd(), '.swarm', 'security');
-            if (fs.existsSync(auditPath)) {
-                try {
-                    const audits = fs.readdirSync(auditPath).filter((f) => f.includes('audit'));
-                    cvesFixed = Math.min(totalCves, Math.max(cvesFixed, audits.length));
-                }
-                catch {
-                    // Ignore
-                }
-            }
-            const status = cvesFixed >= totalCves ? 'CLEAN' : cvesFixed > 0 ? 'IN_PROGRESS' : 'PENDING';
-            return { status, cvesFixed, totalCves };
-        }
-        // Get swarm status
-        function getSwarmStatus() {
-            let activeAgents = 0;
-            let coordinationActive = false;
-            const maxAgents = 15;
-            const isWindows = process.platform === 'win32';
-            try {
-                const psCmd = isWindows
-                    ? 'tasklist /FI "IMAGENAME eq node.exe" /NH 2>NUL | find /c /v "" 2>NUL || echo 0'
-                    : 'ps aux 2>/dev/null | grep -c agentic-flow || echo "0"';
-                const ps = execSync(psCmd, { encoding: 'utf-8', timeout: 3000 });
-                activeAgents = Math.max(0, parseInt(ps.trim()) - 1);
-                coordinationActive = activeAgents > 0;
-            }
-            catch {
-                // ps/tasklist unavailable or timed out — report zero
-            }
-            return { activeAgents, maxAgents, coordinationActive };
-        }
+        // Security/swarm status — shared with the advisor-tip refresh (ADR-316)
+        // via funnel/local-signals.ts, a single source of truth so the two call
+        // sites can never silently drift on what these signals mean.
+        const getSecurityStatus = sharedGetSecurityStatus;
+        const getSwarmStatus = sharedGetSwarmStatus;
         // Get system metrics
         function getSystemMetrics() {
             let memoryMB = 0;
@@ -3554,12 +3514,30 @@ const statuslineCommand = {
         const swarm = getSwarmStatus();
         const system = getSystemMetrics();
         const user = getUserInfo();
+        const getGitUncommittedCount = sharedGetGitUncommittedCount;
+        // Funnel promo row (ADR-301). The statusline is spawned with piped stdio
+        // by an interactive host, so interactivity is asserted here; all other
+        // gates (RUFLO_FUNNEL, enterprise policy, config, CI, disclosure,
+        // rotation ratio) are enforced inside getFunnelPromo. Never allowed to
+        // break the statusline.
+        let promo = null;
+        try {
+            const { getFunnelPromo } = await import('../funnel/index.js');
+            promo = getFunnelPromo({
+                interactive: true,
+                localInsights: { security, swarm, gitUncommittedCount: getGitUncommittedCount() },
+            });
+        }
+        catch {
+            promo = null;
+        }
         const statusData = {
             user,
             v3Progress: progress,
             security,
             swarm,
             system,
+            promo,
             timestamp: new Date().toISOString()
         };
         // JSON output
@@ -4418,6 +4396,90 @@ const notifyCommand = {
         return { success: true, data: { timestamp, level, message } };
     }
 };
+// Refresh-funnel subcommand — the fix for "promo doesn't load right away".
+//
+// refreshRemoteMessages() (funnel/message-transport.ts) is fire-and-forget
+// by design so the STATUSLINE's own per-render invocation never blocks on
+// a network call. But the statusline is spawned as a short-lived subprocess
+// per render (execSync from statusline-generator.ts) — a fire-and-forget
+// promise kicked off there has no "later" to run in; the process exits
+// before the HTTPS fetch can complete, so the local message cache never
+// actually gets written and the promo row never appears (confirmed live:
+// two consecutive cold-cache statusline renders, 5s apart, both returned
+// promo:null and the cache file was never created).
+//
+// This command exists to be invoked from a LONGER-LIVED context — the
+// SessionStart hook (see hook-handler.cjs's 'session-restore' handler,
+// which spawns this detached so it isn't killed when the hook's own
+// process exits, and isn't awaited so it doesn't add to the hook's own
+// timeout budget). One real, properly-awaited refresh attempt here, once
+// per session, is what actually gives refreshRemoteMessages() a chance to
+// finish before anything needs the cache.
+const refreshFunnelCommand = {
+    name: 'refresh-funnel',
+    description: 'Best-effort background refresh of the funnel message cache (internal — see hook-handler.cjs session-restore)',
+    options: [
+        { name: 'quiet', description: 'Suppress output (used when spawned detached from a hook)', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        try {
+            const { refreshRemoteMessages } = await import('../funnel/index.js');
+            const result = await refreshRemoteMessages();
+            if (!ctx.flags.quiet) {
+                output.writeln(JSON.stringify(result));
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            // Fail silent by design (matches message-transport.ts's own "fail
+            // silent" discipline) — a broken refresh must never surface as a
+            // hook error, only ever as "no promo this session."
+            if (!ctx.flags.quiet) {
+                output.printError(`refresh-funnel failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return { success: true, data: { refreshed: false, skipped: 'error' } };
+        }
+    }
+};
+// Refresh-advisor subcommand — ADR-316's co-pilot tip. Mirrors
+// refreshFunnelCommand exactly: a properly-awaited CLI subcommand meant to
+// be spawned DETACHED from hook-handler.cjs's session-restore handler, so a
+// real (potentially multi-second, real-money) `claude -p` call gets a
+// chance to finish without ever blocking or being awaited by the hook's own
+// process. refreshAdvisorTipIfStale() itself is the safety net that makes
+// this cheap to call on every session-restore: it checks consent + a 24h
+// TTL BEFORE spending anything, so most invocations are a no-op file read.
+const refreshAdvisorCommand = {
+    name: 'refresh-advisor',
+    description: 'Best-effort background refresh of the co-pilot advisor tip (internal — see hook-handler.cjs session-restore; ADR-316)',
+    options: [
+        { name: 'quiet', description: 'Suppress output (used when spawned detached from a hook)', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        try {
+            const { refreshAdvisorTipIfStale } = await import('../funnel/advisor-tip.js');
+            const { getSecurityStatus, getSwarmStatus, getGitUncommittedCount } = await import('../funnel/local-signals.js');
+            const result = await refreshAdvisorTipIfStale({
+                security: getSecurityStatus(),
+                swarm: getSwarmStatus(),
+                gitUncommittedCount: getGitUncommittedCount(),
+            });
+            if (!ctx.flags.quiet) {
+                output.writeln(JSON.stringify(result));
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            // Fail silent by design (matches refresh-funnel's own discipline) — a
+            // broken advisor refresh must never surface as a hook error, only
+            // ever as "no tip this window."
+            if (!ctx.flags.quiet) {
+                output.printError(`refresh-advisor failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return { success: true, data: { refreshed: false, reason: 'error' } };
+        }
+    }
+};
 // Main hooks command
 export const hooksCommand = {
     name: 'hooks',
@@ -4461,6 +4523,10 @@ export const hooksCommand = {
         // Agent Teams integration
         teammateIdleCommand,
         taskCompletedCommand,
+        // Funnel background refresh — see refreshFunnelCommand's own doc comment
+        refreshFunnelCommand,
+        // Advisor co-pilot tip background refresh — ADR-316
+        refreshAdvisorCommand,
     ],
     options: [],
     examples: [

package/dist/src/commands/index.js

@@ -31,6 +31,7 @@ const commandLoaders = {
     'hive-mind': () => import('./hive-mind.js'),
     process: () => import('./process.js'),
     daemon: () => import('./daemon.js'),
+    version: () => import('./version.js'),
     // V3 Advanced Commands (less frequently used - lazy load)
     neural: () => import('./neural.js'),
     security: () => import('./security.js'),
@@ -73,6 +74,15 @@ const commandLoaders = {
     metaharness: () => import('./metaharness.js'),
     // Eject (ADR-150 Phase 2) — lift ruflo project into a renamed standalone harness
     eject: () => import('./eject.js'),
+    // Cognitum lifecycle funnel controls (ADR-301/305/309)
+    funnel: () => import('./funnel.js'),
+    // User-facing preferences wrapper (ADR-311 copy discipline — no "funnel" in
+    // the user surface). Forwards to the funnel primitives internally.
+    settings: () => import('./settings.js'),
+    // Meta LLM Proxy — sponsored downtime capacity (ADR-304/307/313)
+    proxy: () => import('./proxy.js'),
+    // Fable co-pilot advisor tip in the statusline insight ticker (ADR-316)
+    advisor: () => import('./advisor.js'),
 };
 // Cache for loaded commands
 const loadedCommands = new Map();