@claude-flow/cli 3.25.5 → 3.26.0

package/dist/src/funnel/local-signals.js

@@ -0,0 +1,68 @@
+/**
+ * Local, synchronous, $0 structural signals shared by the statusline
+ * (commands/hooks.ts's statuslineCommand) and the advisor-tip refresh
+ * (funnel/advisor-tip.ts, ADR-316) — a single source of truth so the two
+ * call sites can never silently drift on what "security status" or "swarm
+ * status" means. Every function here is cheap, bounded, and never throws —
+ * matching the statusline's own "never allowed to break the render"
+ * discipline.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+export function getSecurityStatus(cwd = process.cwd()) {
+    const scanResultsPath = path.join(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(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 };
+}
+export 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 };
+}
+/** Count of uncommitted-changed files (git status --short line count). */
+export function getGitUncommittedCount() {
+    try {
+        const out = execSync('git status --porcelain 2>/dev/null', { encoding: 'utf-8', timeout: 3000 });
+        const lines = out.split('\n').filter((l) => l.trim().length > 0);
+        return lines.length;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=local-signals.js.map

package/dist/src/funnel/message-transport.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Remote message transport — best-effort fetch of the ADR-311 message
+ * feed, cached locally, validated through the ADR-301 content pipeline
+ * BEFORE any message is displayed.
+ *
+ * Design discipline:
+ *   1. **Never blocks the render.** The statusline reads only the local
+ *      cache. This module refreshes the cache in the background; a fresh
+ *      install shows the in-code fallback pool until the first refresh
+ *      lands (usually seconds after CLI startup).
+ *   2. **Content pipeline stays authoritative.** Every message the server
+ *      returns is validated by `isValidMessage()` from `messages.ts` —
+ *      same schema, same host allowlist, same control-char strip, same
+ *      80-column cap. A tampered or accidentally-broken remote feed can
+ *      pollute nothing.
+ *   3. **Fail silent.** Any network/parse/validation failure leaves the
+ *      previously-cached (or in-code) pool intact.
+ *   4. **Bounded cache size.** ≤ 128 KiB and ≤ 200 messages — matches
+ *      ADR-309's bounded-local-queue discipline.
+ *   5. **Kill switch.** `RUFLO_FUNNEL_MESSAGES=0` (or `RUFLO_FUNNEL=0`)
+ *      disables the fetcher entirely.
+ *   6. **Signature-verification hook.** Reserved for a future ADR-311
+ *      amendment; currently the transport-layer TLS + host allowlist is
+ *      the trust boundary. All content is treated as untrusted regardless.
+ */
+import type { FunnelMessage } from './types.js';
+/** Endpoint the client hits — overridable for staging / self-hosted. */
+export declare const DEFAULT_MESSAGES_ENDPOINT: string;
+/**
+ * Best-effort refresh of the cache. Safe to call at any point in the
+ * CLI lifecycle — returns a summary; never throws; never blocks longer
+ * than FETCH_TIMEOUT_MS + write time.
+ */
+export declare function refreshRemoteMessages(opts?: {
+    endpoint?: string;
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    refreshed: boolean;
+    skipped?: string;
+    accepted?: number;
+    rejected?: number;
+    status?: number;
+}>;
+/**
+ * Read the cached remote pool. Returns [] when the cache is empty or
+ * stale enough to distrust — callers should merge with the in-code
+ * fallback pool.
+ */
+export declare function getRemoteMessages(): FunnelMessage[];
+//# sourceMappingURL=message-transport.d.ts.map

package/dist/src/funnel/message-transport.js

@@ -0,0 +1,149 @@
+/**
+ * Remote message transport — best-effort fetch of the ADR-311 message
+ * feed, cached locally, validated through the ADR-301 content pipeline
+ * BEFORE any message is displayed.
+ *
+ * Design discipline:
+ *   1. **Never blocks the render.** The statusline reads only the local
+ *      cache. This module refreshes the cache in the background; a fresh
+ *      install shows the in-code fallback pool until the first refresh
+ *      lands (usually seconds after CLI startup).
+ *   2. **Content pipeline stays authoritative.** Every message the server
+ *      returns is validated by `isValidMessage()` from `messages.ts` —
+ *      same schema, same host allowlist, same control-char strip, same
+ *      80-column cap. A tampered or accidentally-broken remote feed can
+ *      pollute nothing.
+ *   3. **Fail silent.** Any network/parse/validation failure leaves the
+ *      previously-cached (or in-code) pool intact.
+ *   4. **Bounded cache size.** ≤ 128 KiB and ≤ 200 messages — matches
+ *      ADR-309's bounded-local-queue discipline.
+ *   5. **Kill switch.** `RUFLO_FUNNEL_MESSAGES=0` (or `RUFLO_FUNNEL=0`)
+ *      disables the fetcher entirely.
+ *   6. **Signature-verification hook.** Reserved for a future ADR-311
+ *      amendment; currently the transport-layer TLS + host allowlist is
+ *      the trust boundary. All content is treated as untrusted regardless.
+ */
+import * as https from 'https';
+import { URL as NodeUrl } from 'url';
+import { isValidMessage } from './messages.js';
+import { readStateJson, writeStateJson } from './state.js';
+const CACHE_FILE = 'funnel-messages-cache.json';
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h — matches server Cache-Control
+const CACHE_MAX_BYTES = 128 * 1024;
+const CACHE_MAX_MESSAGES = 200;
+const FETCH_TIMEOUT_MS = 4_000;
+/** Endpoint the client hits — overridable for staging / self-hosted. */
+export const DEFAULT_MESSAGES_ENDPOINT = process.env.RUFLO_FUNNEL_MESSAGES_ENDPOINT ?? 'https://funnel.ruv.io/v1/messages';
+function readCache() {
+    const raw = readStateJson(CACHE_FILE);
+    if (!raw || !Array.isArray(raw.messages))
+        return { fresh: false, messages: [] };
+    const age = Date.now() - (raw._ts ?? 0);
+    return { fresh: age < CACHE_TTL_MS, messages: raw.messages };
+}
+function writeCache(messages) {
+    // Bound the cache before persisting — messages come from an untrusted
+    // source, so we cap size regardless of server behavior.
+    let trimmed = messages.slice(0, CACHE_MAX_MESSAGES);
+    let body = JSON.stringify({ _ts: Date.now(), messages: trimmed });
+    while (Buffer.byteLength(body, 'utf-8') > CACHE_MAX_BYTES && trimmed.length > 0) {
+        trimmed = trimmed.slice(0, trimmed.length - 1);
+        body = JSON.stringify({ _ts: Date.now(), messages: trimmed });
+    }
+    writeStateJson(CACHE_FILE, { _ts: Date.now(), messages: trimmed });
+}
+function httpsGet(url) {
+    return new Promise((resolve) => {
+        let target;
+        try {
+            target = new NodeUrl(url);
+        }
+        catch {
+            resolve({ status: 0, body: 'bad-url' });
+            return;
+        }
+        if (target.protocol !== 'https:') {
+            resolve({ status: 0, body: 'non-https' });
+            return;
+        }
+        const req = https.request({
+            hostname: target.hostname,
+            port: target.port || 443,
+            path: target.pathname + target.search,
+            method: 'GET',
+            headers: {
+                'User-Agent': 'ruflo-funnel/messages',
+                'Accept': 'application/json',
+            },
+        }, (res) => {
+            let chunks = '';
+            res.setEncoding('utf-8');
+            res.on('data', (chunk) => { chunks += chunk; });
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, body: chunks }));
+        });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve({ status: 0, body: 'timeout' });
+        });
+        req.on('error', () => resolve({ status: 0, body: 'error' }));
+        req.end();
+    });
+}
+function killSwitched(env = process.env) {
+    const kill = (v) => v !== undefined && /^(0|false|off|no)$/i.test(v.trim());
+    return kill(env.RUFLO_FUNNEL_MESSAGES) || kill(env.RUFLO_FUNNEL);
+}
+/**
+ * Best-effort refresh of the cache. Safe to call at any point in the
+ * CLI lifecycle — returns a summary; never throws; never blocks longer
+ * than FETCH_TIMEOUT_MS + write time.
+ */
+export async function refreshRemoteMessages(opts) {
+    const env = opts?.env ?? process.env;
+    if (killSwitched(env))
+        return { refreshed: false, skipped: 'kill-switch' };
+    const cache = readCache();
+    if (!opts?.force && cache.fresh)
+        return { refreshed: false, skipped: 'fresh-cache' };
+    const endpoint = opts?.endpoint ?? DEFAULT_MESSAGES_ENDPOINT;
+    const res = await httpsGet(endpoint);
+    if (res.status !== 200)
+        return { refreshed: false, skipped: `http-${res.status}`, status: res.status };
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        return { refreshed: false, skipped: 'json-parse-error' };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return { refreshed: false, skipped: 'not-object' };
+    const raw = parsed.messages;
+    if (!Array.isArray(raw))
+        return { refreshed: false, skipped: 'no-messages-field' };
+    // Every message goes through the SAME pipeline the in-code pool uses.
+    // This is where trust boundary enforcement actually lives.
+    const now = new Date();
+    const accepted = [];
+    let rejected = 0;
+    for (const candidate of raw) {
+        if (isValidMessage(candidate, now)) {
+            accepted.push(candidate);
+        }
+        else {
+            rejected += 1;
+        }
+    }
+    writeCache(accepted);
+    return { refreshed: true, accepted: accepted.length, rejected, status: res.status };
+}
+/**
+ * Read the cached remote pool. Returns [] when the cache is empty or
+ * stale enough to distrust — callers should merge with the in-code
+ * fallback pool.
+ */
+export function getRemoteMessages() {
+    const cache = readCache();
+    return cache.messages;
+}
+//# sourceMappingURL=message-transport.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * Funnel message registry and content pipeline — ADR-301 signed content
+ * boundaries.
+ *
+ * Messages are inert data. Regardless of how a message reached this process
+ * (in-package today; the signed helper channel later), the renderer treats
+ * it as untrusted and enforces, before display:
+ *   - schema validation (invalid → dropped, never repaired)
+ *   - length bound (≤ 80 display columns → over-length dropped)
+ *   - URL host allowlist (exact hosts, in code — lookalikes/IPs dropped)
+ *   - expiry
+ *   - zero terminal control sequences (any control char, ANSI/OSC/DCS
+ *     escape, or bidi override → dropped, not stripped-and-shown)
+ *
+ * There is no eval path and no styling in the payload: color comes only
+ * from the renderer's own fixed styles.
+ */
+import type { FunnelMessage } from './types.js';
+export declare const MAX_MESSAGE_COLUMNS = 80;
+export declare function containsForbiddenSequences(text: string): boolean;
+/** Approximate terminal display width: wide CJK/emoji count 2. */
+export declare function displayWidth(text: string): number;
+export declare function isAllowedUrl(url: string): boolean;
+/**
+ * Full validation gate. Returns true only when every ADR-301 content
+ * boundary passes. Failures are silent drops by design — a bad message
+ * must never produce a visible error in the statusline.
+ */
+export declare function isValidMessage(msg: unknown, now?: Date): msg is FunnelMessage;
+/**
+ * Local promo/message content: INTENTIONALLY EMPTY (ADR-311 amendment).
+ *
+ * All rotation content (educational tips, promotional messages, and the
+ * disclosure notice) is served exclusively from the remote message feed
+ * (GET /v1/messages -> message-transport.ts -> Firestore). Zero message
+ * text or URLs ship in the CLI package.
+ *
+ * Fail-closed by design: if the remote feed is unreachable (network down,
+ * cert issue, server outage) and no prior successful fetch has populated
+ * the local cache, the rotation has nothing to show and the promo row
+ * simply does not render that cycle. There is no local content to fall
+ * back to -- this is a deliberate choice, not an oversight.
+ */
+export declare const MESSAGES: FunnelMessage[];
+/** Messages that survive every content boundary right now. */
+export declare function eligibleMessages(now?: Date): FunnelMessage[];
+/**
+ * Merge the remote (cached) message pool with the in-code fallback pool.
+ * The remote pool is authoritative when populated; the in-code pool
+ * covers cold starts and API-down periods. Deduplication is by `id` —
+ * remote wins over in-code for a given id so admins can override without
+ * a client release.
+ */
+export declare function eligibleMessagesFromPools(inCodePool: readonly FunnelMessage[], remotePool: readonly FunnelMessage[], now?: Date): FunnelMessage[];
+//# sourceMappingURL=messages.d.ts.map

package/dist/src/funnel/messages.js

@@ -0,0 +1,160 @@
+/**
+ * Funnel message registry and content pipeline — ADR-301 signed content
+ * boundaries.
+ *
+ * Messages are inert data. Regardless of how a message reached this process
+ * (in-package today; the signed helper channel later), the renderer treats
+ * it as untrusted and enforces, before display:
+ *   - schema validation (invalid → dropped, never repaired)
+ *   - length bound (≤ 80 display columns → over-length dropped)
+ *   - URL host allowlist (exact hosts, in code — lookalikes/IPs dropped)
+ *   - expiry
+ *   - zero terminal control sequences (any control char, ANSI/OSC/DCS
+ *     escape, or bidi override → dropped, not stripped-and-shown)
+ *
+ * There is no eval path and no styling in the payload: color comes only
+ * from the renderer's own fixed styles.
+ */
+export const MAX_MESSAGE_COLUMNS = 80;
+/**
+ * Exact-host allowlist (ADR-301). Ships in code, never in the payload.
+ * github.com is allowed only under /ruvnet/.
+ */
+const ALLOWED_URL_HOSTS = new Set([
+    'cognitum.one', 'www.cognitum.one', 'docs.cognitum.one',
+    // agentics.org — the rUv-authored OSS foundation. Distinct sponsor from
+    // cognitum.one; carries its own promotional messages in the rotation.
+    'agentics.org', 'www.agentics.org',
+]);
+const GITHUB_HOST = 'github.com';
+const GITHUB_PATH_PREFIX = '/ruvnet/';
+/**
+ * C0/C1 controls (incl. ESC, so every ANSI/OSC/DCS sequence trips this),
+ * DEL, and Unicode bidirectional overrides/isolates.
+ */
+// eslint-disable-next-line no-control-regex
+const FORBIDDEN_CHARS = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+export function containsForbiddenSequences(text) {
+    return FORBIDDEN_CHARS.test(text);
+}
+/** Approximate terminal display width: wide CJK/emoji count 2. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (cp === 0xfe0f || cp === 0x200d)
+            continue; // variation selector / ZWJ
+        const wide = (cp >= 0x1100 && cp <= 0x115f) ||
+            (cp >= 0x2e80 && cp <= 0xa4cf) ||
+            (cp >= 0xac00 && cp <= 0xd7a3) ||
+            (cp >= 0xf900 && cp <= 0xfaff) ||
+            (cp >= 0xff00 && cp <= 0xff60) ||
+            (cp >= 0x1f000 && cp <= 0x1faff) ||
+            (cp >= 0x20000 && cp <= 0x3fffd);
+        width += wide ? 2 : 1;
+    }
+    return width;
+}
+export function isAllowedUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'https:')
+        return false;
+    if (ALLOWED_URL_HOSTS.has(parsed.hostname))
+        return true;
+    if (parsed.hostname === GITHUB_HOST && parsed.pathname.startsWith(GITHUB_PATH_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * Full validation gate. Returns true only when every ADR-301 content
+ * boundary passes. Failures are silent drops by design — a bad message
+ * must never produce a visible error in the statusline.
+ */
+export function isValidMessage(msg, now = new Date()) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const m = msg;
+    if (m.schemaVersion !== 1)
+        return false;
+    if (typeof m.id !== 'string' || m.id.length === 0 || m.id.length > 64)
+        return false;
+    if (m.class !== 'educational' && m.class !== 'promotional' && m.class !== 'disclosure')
+        return false;
+    if (typeof m.text !== 'string' || m.text.length === 0)
+        return false;
+    if (containsForbiddenSequences(m.text))
+        return false;
+    if (displayWidth(m.text) > MAX_MESSAGE_COLUMNS)
+        return false;
+    // Disclosure messages MUST carry the exact ADR-301 manage-instruction tail
+    // — losing that on a truncated/malformed remote message is an invariant
+    // violation, not a cosmetic issue. Never repaired; dropped instead.
+    if (m.class === 'disclosure' && !m.text.includes(' · manage: ruflo settings'))
+        return false;
+    if (m.url !== undefined) {
+        if (typeof m.url !== 'string' || !isAllowedUrl(m.url))
+            return false;
+    }
+    if (m.expiresAt !== undefined) {
+        if (typeof m.expiresAt !== 'string')
+            return false;
+        const exp = Date.parse(m.expiresAt);
+        if (Number.isNaN(exp) || exp <= now.getTime())
+            return false;
+    }
+    return true;
+}
+/**
+ * Local promo/message content: INTENTIONALLY EMPTY (ADR-311 amendment).
+ *
+ * All rotation content (educational tips, promotional messages, and the
+ * disclosure notice) is served exclusively from the remote message feed
+ * (GET /v1/messages -> message-transport.ts -> Firestore). Zero message
+ * text or URLs ship in the CLI package.
+ *
+ * Fail-closed by design: if the remote feed is unreachable (network down,
+ * cert issue, server outage) and no prior successful fetch has populated
+ * the local cache, the rotation has nothing to show and the promo row
+ * simply does not render that cycle. There is no local content to fall
+ * back to -- this is a deliberate choice, not an oversight.
+ */
+export const MESSAGES = [];
+/** Messages that survive every content boundary right now. */
+export function eligibleMessages(now = new Date()) {
+    return MESSAGES.filter((m) => isValidMessage(m, now));
+}
+/**
+ * Merge the remote (cached) message pool with the in-code fallback pool.
+ * The remote pool is authoritative when populated; the in-code pool
+ * covers cold starts and API-down periods. Deduplication is by `id` —
+ * remote wins over in-code for a given id so admins can override without
+ * a client release.
+ */
+export function eligibleMessagesFromPools(inCodePool, remotePool, now = new Date()) {
+    const seen = new Set();
+    const out = [];
+    for (const m of remotePool) {
+        if (!isValidMessage(m, now))
+            continue;
+        if (seen.has(m.id))
+            continue;
+        seen.add(m.id);
+        out.push(m);
+    }
+    for (const m of inCodePool) {
+        if (!isValidMessage(m, now))
+            continue;
+        if (seen.has(m.id))
+            continue;
+        seen.add(m.id);
+        out.push(m);
+    }
+    return out;
+}
+//# sourceMappingURL=messages.js.map

package/dist/src/funnel/power-saver-notifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Power-saver notifier — ADR-314 §A out-of-band signal path.
+ *
+ * Structural mirror of rate-limit-notifier.ts, same self-reported/manual
+ * constraint (ADR-312's detection gap applies unchanged — ruflo cannot read
+ * "your account is at 20%" any more than it can read "you are rate
+ * limited"). Deliberately a SEPARATE flag from rate-limited: "running low,
+ * want to proactively conserve" (still have capacity) and "blocked" (zero
+ * capacity left) are different urgencies — conflating them would mean
+ * power-saver mode never fires until you're already blocked (too late to
+ * have conserved anything).
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/quota-status.json = { low: bool, since: ISO, cleared: ISO|null, lastToggleAt: ISO|null }
+ *
+ * Same 6h TTL rationale as rate-limit-notifier.ts, and the same ADR-314 §D1
+ * toggle cooldown (10 min) — a self-reported flag with zero server-side
+ * verification needs at least this much client-side friction against
+ * casual always-on gaming.
+ */
+export declare const QUOTA_STATUS_FILE = "quota-status.json";
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export declare const QUOTA_LOW_TTL_MS: number;
+export interface QuotaLowStatus {
+    low: boolean;
+    since: string | null;
+    cleared: string | null;
+    lastToggleAt: string | null;
+}
+/** Read the current power-saver status. Never throws. Applies the TTL. */
+export declare function readQuotaLowStatus(now?: Date): QuotaLowStatus;
+/**
+ * Mark quota as running low — idempotent, cooldown-gated (ADR-314 §D1).
+ * Returns false when the cooldown blocks the flip (not yet applied).
+ */
+export declare function markQuotaLow(now?: Date): boolean;
+/** Clear power-saver status. Cooldown-gated the same way as the mark direction. */
+export declare function clearQuotaLowStatus(now?: Date): boolean;
+/**
+ * User-facing single-line summary — plain text, no ANSI. Returns null when
+ * not flagged low (no surface).
+ */
+export declare function quotaLowNotice(now?: Date): string | null;
+//# sourceMappingURL=power-saver-notifier.d.ts.map

package/dist/src/funnel/power-saver-notifier.js

@@ -0,0 +1,92 @@
+/**
+ * Power-saver notifier — ADR-314 §A out-of-band signal path.
+ *
+ * Structural mirror of rate-limit-notifier.ts, same self-reported/manual
+ * constraint (ADR-312's detection gap applies unchanged — ruflo cannot read
+ * "your account is at 20%" any more than it can read "you are rate
+ * limited"). Deliberately a SEPARATE flag from rate-limited: "running low,
+ * want to proactively conserve" (still have capacity) and "blocked" (zero
+ * capacity left) are different urgencies — conflating them would mean
+ * power-saver mode never fires until you're already blocked (too late to
+ * have conserved anything).
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/quota-status.json = { low: bool, since: ISO, cleared: ISO|null, lastToggleAt: ISO|null }
+ *
+ * Same 6h TTL rationale as rate-limit-notifier.ts, and the same ADR-314 §D1
+ * toggle cooldown (10 min) — a self-reported flag with zero server-side
+ * verification needs at least this much client-side friction against
+ * casual always-on gaming.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { cooldownActive } from './toggle-cooldown.js';
+export const QUOTA_STATUS_FILE = 'quota-status.json';
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export const QUOTA_LOW_TTL_MS = 6 * 60 * 60 * 1000;
+/** Read the current power-saver status. Never throws. Applies the TTL. */
+export function readQuotaLowStatus(now = new Date()) {
+    const raw = readStateJson(QUOTA_STATUS_FILE);
+    const status = {
+        low: raw?.low ?? false,
+        since: raw?.since ?? null,
+        cleared: raw?.cleared ?? null,
+        lastToggleAt: raw?.lastToggleAt ?? null,
+    };
+    if (status.low && status.since) {
+        const since = Date.parse(status.since);
+        if (!Number.isNaN(since) && now.getTime() - since >= QUOTA_LOW_TTL_MS) {
+            return { low: false, since: status.since, cleared: now.toISOString(), lastToggleAt: status.lastToggleAt };
+        }
+    }
+    return status;
+}
+/**
+ * Mark quota as running low — idempotent, cooldown-gated (ADR-314 §D1).
+ * Returns false when the cooldown blocks the flip (not yet applied).
+ */
+export function markQuotaLow(now = new Date()) {
+    const current = readQuotaLowStatus(now);
+    if (current.low && current.since)
+        return true; // already flagged, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(QUOTA_STATUS_FILE, {
+        low: true,
+        since: current.since ?? now.toISOString(),
+        cleared: null,
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/** Clear power-saver status. Cooldown-gated the same way as the mark direction. */
+export function clearQuotaLowStatus(now = new Date()) {
+    const current = readQuotaLowStatus(now);
+    if (!current.low)
+        return true; // already clear, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(QUOTA_STATUS_FILE, {
+        low: false,
+        since: current.since,
+        cleared: now.toISOString(),
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * User-facing single-line summary — plain text, no ANSI. Returns null when
+ * not flagged low (no surface).
+ */
+export function quotaLowNotice(now = new Date()) {
+    const status = readQuotaLowStatus(now);
+    if (!status.low)
+        return null;
+    const since = status.since ? Date.parse(status.since) : NaN;
+    if (Number.isNaN(since)) {
+        return 'Power saver mode active · manage: ruflo proxy power-saver-disable';
+    }
+    const ageMin = Math.max(0, Math.round((now.getTime() - since) / (60 * 1000)));
+    const when = ageMin < 1 ? 'just now' : ageMin < 60 ? `${ageMin}m ago` : `${Math.round(ageMin / 60)}h ago`;
+    return `Power saver mode active (${when}) · manage: ruflo proxy power-saver-disable`;
+}
+//# sourceMappingURL=power-saver-notifier.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Control precedence resolver — ADR-305 (normative).
+ *
+ *   1. RUFLO_FUNNEL=0            (environment)
+ *   2. Enterprise managed policy
+ *   3. User config (funnel.enabled — user-level and project-level)
+ *   4. Package default
+ *   5. Remote signed policy      (only when the freshness feed is enabled)
+ *
+ * A lower-precedence source must never re-enable a higher-precedence
+ * disable — implemented as a strict AND chain: every source can veto,
+ * none can override a veto above it.
+ */
+import type { FunnelEnabledDecision } from './types.js';
+export declare function resolveFunnelEnabled(cwd?: string, env?: NodeJS.ProcessEnv): FunnelEnabledDecision;
+//# sourceMappingURL=precedence.d.ts.map