@claude-flow/cli 3.32.2 → 3.32.4

package/dist/src/auth/session.js

@@ -0,0 +1,32 @@
+/**
+ * Process-lifetime in-memory access-token cache (ADR-306).
+ *
+ * The access token is never written to `auth.json` or any other disk file —
+ * only the refresh token (via the OS keychain, or nowhere in session-only
+ * mode) survives a process exit. Every fresh `ruflo` invocation starts with
+ * an empty cache and re-derives an access token from the refresh token (or
+ * asks the user to log in again, in session-only mode). This is a deliberate
+ * ADR-306 usability cost, not something to "fix" by persisting the access
+ * token — see auth/types.ts's doc comment.
+ */
+const sessions = new Map();
+export function setSessionToken(profile, accessToken, expiresAtMs) {
+    sessions.set(profile, { accessToken, expiresAt: expiresAtMs });
+}
+/**
+ * Returns the cached access token when it remains valid for at least
+ * `minValidityMs`. Authenticated callers use a small refresh window so a
+ * token cannot expire while an outbound request is in flight.
+ */
+export function getSessionToken(profile, minValidityMs = 0) {
+    const entry = sessions.get(profile);
+    if (!entry)
+        return null;
+    if (Date.now() + Math.max(0, minValidityMs) >= entry.expiresAt)
+        return null;
+    return entry.accessToken;
+}
+export function clearSessionToken(profile) {
+    sessions.delete(profile);
+}
+//# sourceMappingURL=session.js.map

package/dist/src/auth/state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `auth.json` persistence — atomic tmp+rename, 0600, under ~/.ruflo (ADR-306).
+ * Reuses the exact same primitives `proxy-config.toml`'s consent mirror and
+ * every other funnel state file already use (src/funnel/state.ts).
+ */
+import type { AuthFile, ProfileAuthState } from './types.js';
+export declare const DEFAULT_PROFILE = "default";
+export declare function readAuthFile(): AuthFile;
+export declare function getProfile(name?: string): ProfileAuthState | null;
+export declare function listProfiles(): {
+    defaultProfile: string;
+    profiles: ProfileAuthState[];
+};
+/** Writes/overwrites a profile. The first profile ever written becomes the default. */
+export declare function setProfile(name: string, state: ProfileAuthState, makeDefault?: boolean): void;
+export declare function removeProfile(name: string): boolean;
+/** `auth logout --all` — forgets every profile. */
+export declare function clearAllProfiles(): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/src/auth/state.js

@@ -0,0 +1,53 @@
+/**
+ * `auth.json` persistence — atomic tmp+rename, 0600, under ~/.ruflo (ADR-306).
+ * Reuses the exact same primitives `proxy-config.toml`'s consent mirror and
+ * every other funnel state file already use (src/funnel/state.ts).
+ */
+import { readStateJson, writeStateJson, deleteStateFile } from '../funnel/state.js';
+const AUTH_FILE = 'auth.json';
+export const DEFAULT_PROFILE = 'default';
+function emptyAuthFile() {
+    return { schemaVersion: 1, defaultProfile: DEFAULT_PROFILE, profiles: {} };
+}
+export function readAuthFile() {
+    const file = readStateJson(AUTH_FILE);
+    return file ?? emptyAuthFile();
+}
+function writeAuthFile(file) {
+    writeStateJson(AUTH_FILE, file);
+}
+export function getProfile(name) {
+    const file = readAuthFile();
+    const key = name ?? file.defaultProfile;
+    return file.profiles[key] ?? null;
+}
+export function listProfiles() {
+    const file = readAuthFile();
+    return { defaultProfile: file.defaultProfile, profiles: Object.values(file.profiles) };
+}
+/** Writes/overwrites a profile. The first profile ever written becomes the default. */
+export function setProfile(name, state, makeDefault = false) {
+    const file = readAuthFile();
+    const isFirst = Object.keys(file.profiles).length === 0;
+    file.profiles[name] = state;
+    if (makeDefault || isFirst)
+        file.defaultProfile = name;
+    writeAuthFile(file);
+}
+export function removeProfile(name) {
+    const file = readAuthFile();
+    if (!(name in file.profiles))
+        return false;
+    delete file.profiles[name];
+    if (file.defaultProfile === name) {
+        const remaining = Object.keys(file.profiles);
+        file.defaultProfile = remaining[0] ?? DEFAULT_PROFILE;
+    }
+    writeAuthFile(file);
+    return true;
+}
+/** `auth logout --all` — forgets every profile. */
+export function clearAllProfiles() {
+    deleteStateFile(AUTH_FILE);
+}
+//# sourceMappingURL=state.js.map

package/dist/src/auth/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `ruflo auth` state shapes (ADR-306).
+ *
+ * `auth.json` holds identity metadata ONLY — never token material. The
+ * access token lives exclusively in a process-lifetime in-memory singleton
+ * (session.ts); the refresh token goes to the OS keychain (keychainRef set)
+ * or nowhere at all when no keychain backend is reachable (keychainRef:
+ * null — session-only mode, ADR-306's accepted usability cost, not a bug).
+ */
+export interface ProfileAuthState {
+    accountId: string;
+    scopes: string[];
+    /** ISO timestamp — the access token's own expiry, not tracked beyond this. */
+    accessTokenExpiresAt: string;
+    /** OS-keychain account identifier for this profile's refresh token, or null if session-only. */
+    keychainRef: string | null;
+    profile: string;
+    loginMethod: 'pkce' | 'device' | 'token-stdin';
+    /** ISO timestamp of the login that created/last-refreshed this profile. */
+    linkedAt: string;
+}
+export interface AuthFile {
+    schemaVersion: 1;
+    defaultProfile: string;
+    profiles: Record<string, ProfileAuthState>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/auth/types.js

@@ -0,0 +1,11 @@
+/**
+ * `ruflo auth` state shapes (ADR-306).
+ *
+ * `auth.json` holds identity metadata ONLY — never token material. The
+ * access token lives exclusively in a process-lifetime in-memory singleton
+ * (session.ts); the refresh token goes to the OS keychain (keychainRef set)
+ * or nowhere at all when no keychain backend is reachable (keychainRef:
+ * null — session-only mode, ADR-306's accepted usability cost, not a bug).
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * `ruflo auth` — Cognitum identity (ADR-306).
+ *
+ * `login` obtains OAuth tokens via the loopback PKCE flow (default,
+ * interactive desktop), the OOB manual-paste flow (`--no-browser`, or
+ * auto-detected headless environments), or `--token-stdin` (CI/enterprise
+ * automation — refuses interactively otherwise, per ADR-306). The refresh
+ * token goes to the OS keychain when reachable, or nowhere (session-only —
+ * a deliberate usability cost, not a bug) when it isn't. The access token
+ * itself is NEVER written to disk; see src/auth/session.ts.
+ */
+import type { Command } from '../types.js';
+export declare const authCommand: Command;
+export default authCommand;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/commands/auth.js

@@ -0,0 +1,244 @@
+/**
+ * `ruflo auth` — Cognitum identity (ADR-306).
+ *
+ * `login` obtains OAuth tokens via the loopback PKCE flow (default,
+ * interactive desktop), the OOB manual-paste flow (`--no-browser`, or
+ * auto-detected headless environments), or `--token-stdin` (CI/enterprise
+ * automation — refuses interactively otherwise, per ADR-306). The refresh
+ * token goes to the OS keychain when reachable, or nowhere (session-only —
+ * a deliberate usability cost, not a bug) when it isn't. The access token
+ * itself is NEVER written to disk; see src/auth/session.ts.
+ */
+import { output } from '../output.js';
+import { isCI, isInteractive, hasConsent, recordConsent, revokeConsent } from '../funnel/index.js';
+import { browserLogin, manualLogin, tokenStdinLogin, isProbablyHeadless, LoginCancelledError, LoginDeniedError, StateMismatchError, } from '../auth/client.js';
+import { loadSecurityOAuth, SecurityPackageMissingError } from '../auth/security-bridge.js';
+import { setProfile, removeProfile, listProfiles, clearAllProfiles, DEFAULT_PROFILE } from '../auth/state.js';
+import { setSessionToken, clearSessionToken } from '../auth/session.js';
+import { INITIAL_SCOPE, domainForScope } from '../auth/scopes.js';
+import { KEYCHAIN_SERVICE } from '../auth/constants.js';
+import { getValidAccessToken, NotLoggedInError, SessionOnlyExpiredError } from '../auth/client.js';
+import { removeInjectedToken } from '../proxy/token-bridge.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+async function persistLogin(profileName, tokens, method) {
+    const expiresInSec = tokens.expires_in ?? 0;
+    const expiresAtMs = Date.now() + expiresInSec * 1000;
+    setSessionToken(profileName, tokens.access_token, expiresAtMs);
+    let keychainRef = null;
+    if (tokens.refresh_token) {
+        const sec = await loadSecurityOAuth();
+        const keychain = await sec.createKeychainAdapter();
+        if (await keychain.isAvailable()) {
+            await keychain.setSecret(KEYCHAIN_SERVICE, profileName, tokens.refresh_token);
+            keychainRef = profileName;
+        }
+        // else: session-only — the refresh token is simply not persisted anywhere.
+    }
+    const state = {
+        accountId: tokens.account_email ?? 'unknown',
+        scopes: [INITIAL_SCOPE],
+        accessTokenExpiresAt: new Date(expiresAtMs).toISOString(),
+        keychainRef,
+        profile: profileName,
+        loginMethod: method,
+        linkedAt: nowIso(),
+    };
+    setProfile(profileName, state);
+    recordConsent('account', true, 'auth-login');
+    return state;
+}
+function refuseNonInteractive(hasTokenStdin) {
+    if (hasTokenStdin)
+        return null;
+    if (isInteractive() && !isCI())
+        return null;
+    // The CLI harness only acts on exitCode — it never auto-prints
+    // CommandResult.message, so this path must print for itself.
+    const message = 'ruflo auth login refuses to run interactively in a non-TTY/CI environment. ' +
+        'Use --token-stdin for automation (reads {"access_token",...} JSON from stdin).';
+    output.printError(message);
+    return { success: false, message, exitCode: 1 };
+}
+const loginCommand = {
+    name: 'login',
+    description: 'Sign in to Cognitum (PKCE browser flow, OOB manual flow, or --token-stdin)',
+    options: [
+        { name: 'profile', description: 'Named profile to store this login under', type: 'string', default: DEFAULT_PROFILE },
+        { name: 'no-browser', description: 'Force the headless OOB copy-paste flow', type: 'boolean', default: false },
+        { name: 'token-stdin', description: 'Read a pre-obtained token as JSON from stdin (CI/automation)', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const profileName = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : DEFAULT_PROFILE;
+        // Parser camelCases kebab-case flag names — read via tokenStdin/noBrowser,
+        // not ['token-stdin']/['no-browser'] (see doctor.ts's fixHandles comment).
+        const tokenStdin = Boolean(ctx.flags.tokenStdin ?? ctx.flags['token-stdin']);
+        const noBrowser = Boolean(ctx.flags.noBrowser ?? ctx.flags['no-browser']);
+        const refusal = refuseNonInteractive(tokenStdin);
+        if (refusal)
+            return refusal;
+        try {
+            const result = tokenStdin
+                ? await tokenStdinLogin()
+                : noBrowser || isProbablyHeadless()
+                    ? await manualLogin((line) => output.writeln(line))
+                    : await browserLogin((line) => output.writeln(line));
+            const state = await persistLogin(profileName, result.tokens, result.method);
+            output.printSuccess(`Logged in as ${state.accountId} (profile: ${profileName})`);
+            output.writeln(state.keychainRef
+                ? '  refresh token: stored in the OS keychain'
+                : '  refresh token: NOT stored (no keychain backend reachable) — session-only, you will need to log in again next time');
+            return { success: true, data: { profile: profileName, accountId: state.accountId } };
+        }
+        catch (e) {
+            if (e instanceof SecurityPackageMissingError || e instanceof LoginCancelledError || e instanceof LoginDeniedError || e instanceof StateMismatchError) {
+                output.printError(e.message);
+                return { success: false, message: e.message, exitCode: 1 };
+            }
+            const message = e instanceof Error ? e.message : String(e);
+            output.printError('Sign-in failed', message);
+            return { success: false, message, exitCode: 1 };
+        }
+    },
+};
+const logoutCommand = {
+    name: 'logout',
+    description: 'Sign out — clears the local session, keychain entry, and account consent',
+    options: [
+        { name: 'profile', description: 'Profile to log out of', type: 'string', default: DEFAULT_PROFILE },
+        { name: 'all', description: 'Log out of every profile', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        removeInjectedToken();
+        const all = ctx.flags.all === true;
+        const profileName = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : DEFAULT_PROFILE;
+        const { profiles } = listProfiles();
+        if (profiles.length === 0) {
+            output.writeln('Nothing to log out of — no profile is signed in.');
+            return { success: true, data: { hadSession: false } };
+        }
+        const toClear = all ? profiles : profiles.filter((p) => p.profile === profileName);
+        if (toClear.length === 0) {
+            output.writeln(`No such profile: ${profileName}`);
+            return { success: false, exitCode: 1 };
+        }
+        let sec;
+        try {
+            sec = await loadSecurityOAuth();
+        }
+        catch {
+            sec = null; // best-effort keychain cleanup — logout must still succeed locally
+        }
+        for (const p of toClear) {
+            clearSessionToken(p.profile);
+            if (p.keychainRef && sec) {
+                const keychain = await sec.createKeychainAdapter();
+                await keychain.deleteSecret(KEYCHAIN_SERVICE, p.keychainRef).catch(() => { });
+            }
+            removeProfile(p.profile);
+        }
+        if (all) {
+            clearAllProfiles();
+            revokeConsent('account', 'auth-logout');
+        }
+        else if (listProfiles().profiles.length === 0) {
+            revokeConsent('account', 'auth-logout');
+        }
+        output.printSuccess(all ? 'Logged out of all profiles.' : `Logged out of profile "${profileName}".`);
+        output.writeln('  Note: this only forgets the local copy. Cognitum does not currently expose a token ' +
+            'revocation endpoint for this flow, matching the same known limitation meta-proxy documents ' +
+            'for its own logout — revoke server-side access from the Cognitum dashboard if needed.');
+        return { success: true, data: { hadSession: true } };
+    },
+};
+const statusCommand = {
+    name: 'status',
+    description: 'Show signed-in profile(s), scopes, and expiry',
+    options: [
+        { name: 'profile', description: 'Show only this profile', type: 'string' },
+        { name: 'json', description: 'Machine-readable output', type: 'boolean', default: false },
+        {
+            name: 'check',
+            description: 'Validate credentials now; silently refresh from the OS keychain when needed',
+            type: 'boolean',
+            default: false,
+        },
+    ],
+    action: async (ctx) => {
+        const { defaultProfile, profiles } = listProfiles();
+        const filterName = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : undefined;
+        const shown = filterName ? profiles.filter((p) => p.profile === filterName) : profiles;
+        if (shown.length === 0) {
+            const message = filterName ? `No such profile: ${filterName}` : 'Not logged in. Run: ruflo auth login';
+            if (ctx.flags.json) {
+                output.printJson({ profiles: [] });
+            }
+            else {
+                output.writeln(message);
+            }
+            return { success: true, data: { profiles: [] } };
+        }
+        const withConsistency = shown.map((p) => {
+            const missingConsent = p.scopes.filter((scope) => {
+                const domain = domainForScope(scope);
+                return domain !== undefined && !hasConsent(domain);
+            });
+            return { ...p, isDefault: p.profile === defaultProfile, missingConsent };
+        });
+        const checked = await Promise.all(withConsistency.map(async (p) => {
+            if (!ctx.flags.check)
+                return { ...p, credentialStatus: 'not-checked' };
+            try {
+                await getValidAccessToken(p.profile);
+                return { ...p, credentialStatus: 'valid' };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return {
+                    ...p,
+                    credentialStatus: e instanceof NotLoggedInError || e instanceof SessionOnlyExpiredError
+                        ? 'login-required'
+                        : 'unavailable',
+                    credentialError: message,
+                };
+            }
+        }));
+        if (ctx.flags.json) {
+            output.printJson({ profiles: checked });
+            return { success: true, data: { profiles: checked } };
+        }
+        for (const p of checked) {
+            output.writeln(`Profile: ${p.profile}${p.isDefault ? ' (default)' : ''}`);
+            output.writeln(`  account: ${p.accountId}`);
+            output.writeln(`  scopes: ${p.scopes.join(', ')}`);
+            output.writeln(`  access token expires: ${p.accessTokenExpiresAt}`);
+            output.writeln(`  refresh token: ${p.keychainRef ? 'in OS keychain' : 'session-only (not persisted)'}`);
+            if (ctx.flags.check) {
+                output.writeln(`  credential check: ${p.credentialStatus}`);
+                if ('credentialError' in p && p.credentialError)
+                    output.writeln(`    ${p.credentialError}`);
+            }
+            if (p.missingConsent.length > 0) {
+                output.printError(`  scope-vs-consent mismatch: ${p.missingConsent.join(', ')} granted without a matching consent receipt`);
+            }
+            output.writeln('');
+        }
+        return { success: true, data: { profiles: checked } };
+    },
+};
+export const authCommand = {
+    name: 'auth',
+    description: 'Cognitum identity — login, logout, status (ADR-306)',
+    subcommands: [loginCommand, logoutCommand, statusCommand],
+    examples: [
+        { command: 'ruflo auth login', description: 'Sign in via the browser PKCE flow' },
+        { command: 'ruflo auth login --no-browser', description: 'Sign in via the headless OOB copy-paste flow' },
+        { command: 'ruflo auth status', description: 'Show signed-in profile(s)' },
+        { command: 'ruflo auth status --check', description: 'Validate or silently refresh credentials now' },
+        { command: 'ruflo auth logout', description: 'Sign out of the default profile' },
+    ],
+    action: statusCommand.action,
+};
+export default authCommand;
+//# sourceMappingURL=auth.js.map

package/dist/src/commands/doctor.js

@@ -978,7 +978,7 @@ async function checkFunnel() {
     }
 }
 /** Meta LLM Proxy — sponsored-downtime health (ADR-313). */
-async function checkProxy() {
+async function checkProxySponsoredConsent() {
     try {
         const { funnelStateDir, hasConsent, readRateLimitStatus, lastRecordedEvent } = await import('../funnel/index.js');
         const dir = funnelStateDir();
@@ -1019,6 +1019,208 @@ async function checkProxy() {
         };
     }
 }
+/**
+ * Binary presence + tamper check (ADR-307). Deliberately NEVER spawns the
+ * binary to probe a version — confirmed empirically (2026-07-16) that
+ * `meta-proxy` has no `--version`/`--help` flag and starts the live server
+ * as a side effect of ANY invocation, which a doctor health check must never
+ * do. Version info instead comes from install-manifest.json (written at
+ * install time) and, once running, the proxy's own `/status` endpoint via
+ * checkProxyProcess below.
+ */
+async function checkProxyBinary() {
+    const NAME = 'Meta LLM Proxy binary (ADR-307)';
+    try {
+        const { proxyBinaryPath, proxyInstallManifestPath } = await import('../proxy/paths.js');
+        const binPath = proxyBinaryPath();
+        if (!existsSync(binPath)) {
+            return { name: NAME, status: 'warn', message: 'not installed', fix: 'ruflo proxy install' };
+        }
+        const manifestPath = proxyInstallManifestPath();
+        if (!existsSync(manifestPath)) {
+            return {
+                name: NAME,
+                status: 'warn',
+                message: 'binary present but no install-manifest.json — provenance unknown (installed outside `ruflo proxy install`?)',
+                fix: 'ruflo proxy update --release <x.y.z>',
+            };
+        }
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        const liveSha = createHash('sha256').update(readFileSync(binPath)).digest('hex');
+        if (liveSha !== manifest.sha256) {
+            return {
+                name: NAME,
+                status: 'fail',
+                message: `binary sha256 does not match the recorded install manifest — possible tampering or a manual overwrite (expected ${manifest.sha256.slice(0, 12)}…, got ${liveSha.slice(0, 12)}…)`,
+                fix: 'ruflo proxy update --release <x.y.z>',
+            };
+        }
+        return { name: NAME, status: 'pass', message: `v${manifest.version}, signature-verified at install (${manifest.verifiedAt})` };
+    }
+    catch (err) {
+        return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** PID-file liveness (ADR-307) — mirrors daemon.ts's signal-0 probe pattern. */
+async function checkProxyProcess() {
+    const NAME = 'Meta LLM Proxy process (ADR-307)';
+    try {
+        const { proxyPidFilePath } = await import('../proxy/paths.js');
+        const pidPath = proxyPidFilePath();
+        if (!existsSync(pidPath)) {
+            return { name: NAME, status: 'warn', message: 'not running (no PID file)', fix: 'ruflo proxy start' };
+        }
+        const pidRaw = readFileSync(pidPath, 'utf-8').trim();
+        const pid = parseInt(pidRaw, 10);
+        if (!Number.isFinite(pid)) {
+            return { name: NAME, status: 'warn', message: `PID file is malformed: ${JSON.stringify(pidRaw)}`, fix: 'ruflo proxy stop && ruflo proxy start' };
+        }
+        try {
+            process.kill(pid, 0); // signal-0 liveness probe — throws if the process is dead
+        }
+        catch {
+            return { name: NAME, status: 'warn', message: `PID file points at ${pid}, which is not running — stale PID file`, fix: 'ruflo proxy start' };
+        }
+        // Live version-compat + data-plane info, ONLY once PID liveness already
+        // confirmed a process is running (never spawns anything — see
+        // checkProxyBinary's comment on why probing via process launch is unsafe).
+        // GET /status shape confirmed against the real v0.1.0 binary:
+        // {"version","data_plane","bind","sponsored_available","proxy_token_valid"}.
+        const { proxyConfigPath, proxyTokenPath, proxyInstallManifestPath } = await import('../proxy/paths.js');
+        const bindMatch = existsSync(proxyConfigPath())
+            ? readFileSync(proxyConfigPath(), 'utf-8').match(/^bind\s*=\s*"([^"]*)"/m)
+            : null;
+        const bind = bindMatch ? bindMatch[1] : '127.0.0.1:11435';
+        let token;
+        try {
+            token = readFileSync(proxyTokenPath(), 'utf-8').trim();
+        }
+        catch {
+            return { name: NAME, status: 'pass', message: `running (pid ${pid}); no proxy-token to query /status` };
+        }
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 2000);
+            const resp = await fetch(`http://${bind}/status`, {
+                headers: { authorization: `Bearer ${token}` },
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!resp.ok) {
+                return { name: NAME, status: 'warn', message: `running (pid ${pid}); /status returned HTTP ${resp.status}` };
+            }
+            const body = (await resp.json());
+            let versionNote = '';
+            if (existsSync(proxyInstallManifestPath())) {
+                const manifest = JSON.parse(readFileSync(proxyInstallManifestPath(), 'utf-8'));
+                if (manifest.version && body.version && manifest.version !== body.version) {
+                    return {
+                        name: NAME,
+                        status: 'warn',
+                        message: `running (pid ${pid}) reports v${body.version}, but the installed binary is v${manifest.version} — a stale process from a previous version?`,
+                        fix: 'ruflo proxy stop && ruflo proxy start',
+                    };
+                }
+                versionNote = body.version ? ` v${body.version}` : '';
+            }
+            return {
+                name: NAME,
+                status: 'pass',
+                message: `running (pid ${pid})${versionNote}; data plane: ${body.data_plane ?? 'unknown'}`,
+            };
+        }
+        catch (err) {
+            // Live process but /status unreachable (still starting up, or a
+            // network hiccup) — not a failure, PID liveness already passed.
+            return {
+                name: NAME,
+                status: 'pass',
+                message: `running (pid ${pid}); /status unreachable (${err instanceof Error ? err.message : String(err)})`,
+            };
+        }
+    }
+    catch (err) {
+        return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** Non-loopback bind exposure warning (ADR-307's mandated startup warning, surfaced in doctor too). */
+async function checkProxyBindAddress() {
+    const NAME = 'Meta LLM Proxy bind address (ADR-307)';
+    try {
+        const { proxyConfigPath, isLoopbackBind } = await import('../proxy/paths.js');
+        const cfgPath = proxyConfigPath();
+        if (!existsSync(cfgPath)) {
+            return { name: NAME, status: 'pass', message: 'no config file yet — defaults to loopback-only (127.0.0.1:11435)' };
+        }
+        const raw = readFileSync(cfgPath, 'utf-8');
+        const match = raw.match(/^bind\s*=\s*"([^"]*)"/m);
+        const bind = match ? match[1] : '127.0.0.1:11435';
+        if (!isLoopbackBind(bind)) {
+            return {
+                name: NAME,
+                status: 'warn',
+                message: `bound to non-loopback address ${bind} — this exposes the proxy to your network`,
+                fix: 'Set bind back to 127.0.0.1:<port> in proxy-config.toml unless external exposure is intended',
+            };
+        }
+        return { name: NAME, status: 'pass', message: `loopback-only (${bind})` };
+    }
+    catch (err) {
+        return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** `ruflo auth` health (ADR-306). Warn (never fail) on absence — auth is never required for core functionality. */
+async function checkAuth() {
+    const NAME = 'Cognitum identity (ADR-306)';
+    try {
+        const { listProfiles } = await import('../auth/state.js');
+        const { domainForScope } = await import('../auth/scopes.js');
+        const { hasConsent } = await import('../funnel/index.js');
+        const { profiles } = listProfiles();
+        if (profiles.length === 0) {
+            return { name: NAME, status: 'warn', message: 'not logged in', fix: 'ruflo auth login' };
+        }
+        let keychainAvailable = 'unknown';
+        try {
+            const sec = await import('@claude-flow/security');
+            keychainAvailable = await (await sec.createKeychainAdapter()).isAvailable();
+        }
+        catch {
+            keychainAvailable = 'unknown'; // security package unavailable — surfaced by checkProxyBinary's sibling concerns, not duplicated here
+        }
+        // Scope-vs-receipt consistency check (ADR-306: "fail-closed... reports").
+        // Unlike every other check in this file, a violation here is a FAIL, not
+        // a warn — a scope present without a matching consent receipt is exactly
+        // the condition ADR-306 says must never silently pass.
+        const violations = [];
+        for (const p of profiles) {
+            for (const scope of p.scopes) {
+                const domain = domainForScope(scope);
+                if (domain && !hasConsent(domain))
+                    violations.push(`${p.profile}: ${scope}`);
+            }
+        }
+        if (violations.length > 0) {
+            return {
+                name: NAME,
+                status: 'fail',
+                message: `scope granted without a matching consent receipt: ${violations.join(', ')}`,
+                fix: 'ruflo auth logout && ruflo auth login',
+            };
+        }
+        const names = profiles.map((p) => p.profile).join(', ');
+        const sessionOnly = profiles.filter((p) => !p.keychainRef).map((p) => p.profile);
+        const parts = [`profiles: ${names}`];
+        if (keychainAvailable === false)
+            parts.push('keychain backend unreachable — falling back to session-only tokens');
+        if (sessionOnly.length > 0)
+            parts.push(`session-only (no persisted refresh token): ${sessionOnly.join(', ')}`);
+        return { name: NAME, status: 'pass', message: parts.join('; ') };
+    }
+    catch (err) {
+        return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 async function checkMetaharnessIntegration() {
     // Locate plugins dir.
     //
@@ -1395,7 +1597,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, funnel, proxy, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, metaharness)',
             type: 'string'
         },
         {
@@ -1525,7 +1727,8 @@ export const doctorCommand = {
             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
+            checkProxySponsoredConsent, // ADR-313 — Meta LLM Proxy sponsored-downtime health
+            checkAuth, // ADR-306 — Cognitum identity (warn-only; never fails bare `ruflo doctor`)
         ];
         // #2677: `--component memory` now runs the whole memory-health suite,
         // not just the existence check. Values can be a single check or an
@@ -1563,7 +1766,11 @@ export const doctorCommand = {
             'metaharness': checkMetaharness, // ADR-150 — upstream package
             'metaharness-integration': checkMetaharnessIntegration, // iter 45 — ruflo-side
             'funnel': checkFunnel, // ADR-305
-            'proxy': checkProxy, // ADR-313
+            // ADR-307 — deep-dive array, same pattern as 'memory' above: the cheap
+            // sponsored-consent check first, then binary/process/bind in the order
+            // a user would actually debug them (is it installed? running? exposed?).
+            'proxy': [checkProxySponsoredConsent, checkProxyBinary, checkProxyProcess, checkProxyBindAddress],
+            'auth': checkAuth, // ADR-306
         };
         let checksToRun = allChecks;
         if (component && componentMap[component]) {

package/dist/src/commands/index.js

@@ -79,6 +79,8 @@ const commandLoaders = {
     // User-facing preferences wrapper (ADR-311 copy discipline — no "funnel" in
     // the user surface). Forwards to the funnel primitives internally.
     settings: () => import('./settings.js'),
+    // Cognitum identity — login/logout/status (ADR-306)
+    auth: () => import('./auth.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)