fraim 2.0.328 → 2.0.332

package/dist/src/cli/commands/doctor.js

@@ -16,6 +16,7 @@ const ide_config_checks_1 = require("../doctor/checks/ide-config-checks");
 const mcp_connectivity_checks_1 = require("../doctor/checks/mcp-connectivity-checks");
 const scripts_checks_1 = require("../doctor/checks/scripts-checks");
 const agent_cli_health_checks_1 = require("../doctor/checks/agent-cli-health-checks");
+const llm_auth_route_checks_1 = require("../doctor/checks/llm-auth-route-checks");
 const add_ide_1 = require("./add-ide");
 // Read version from package.json
 const getFramVersion = () => {
@@ -60,7 +61,11 @@ function getAllChecks() {
         ...(0, ide_config_checks_1.getIDEConfigChecks)(),
         ...(0, mcp_connectivity_checks_1.getMCPConnectivityChecks)(),
         ...(0, scripts_checks_1.getScriptsChecks)(),
-        ...(0, agent_cli_health_checks_1.getAgentCliHealthChecks)()
+        ...(0, agent_cli_health_checks_1.getAgentCliHealthChecks)(),
+        // Issue #1798: an ambient ANTHROPIC_* variable silently reroutes every Hub-launched
+        // agent's billing, so it belongs in the standing health check rather than only in the
+        // on-demand llm-spend-detection skill.
+        ...(0, llm_auth_route_checks_1.getLlmAuthRouteChecks)()
     ];
 }
 async function runFixMcpRepair(options, repair = add_ide_1.runAddIDE) {

package/dist/src/cli/doctor/check-runner.js

@@ -141,7 +141,8 @@ async function runChecks(checks, options, version) {
         ideConfiguration: { checks: [] },
         mcpConnectivity: { checks: [] },
         scripts: { checks: [] },
-        agentCliHealth: { checks: [] }
+        agentCliHealth: { checks: [] },
+        llmAuthRoute: { checks: [] }
     };
     let passed = 0;
     let warnings = 0;

package/dist/src/cli/doctor/checks/agent-cli-health-checks.js

@@ -13,6 +13,7 @@ exports.getAgentCliHealthChecks = getAgentCliHealthChecks;
 exports.checkAgentCliHealthByCommand = checkAgentCliHealthByCommand;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
+const redact_paths_1 = require("../redact-paths");
 const managed_agent_paths_1 = require("../../utils/managed-agent-paths");
 const machine_path_1 = require("../../utils/machine-path");
 const command_resolution_1 = require("../../mcp/command-resolution");
@@ -67,7 +68,17 @@ function probeVersion(commandPath) {
 function readPersistedUserPath() {
     return (0, machine_path_1.resolveMachinePathCached)();
 }
+// Issue #1482 (Privacy PRIV05 / GDPR Art. 5(1)(c)): the single exit point for every branch
+// below. `message` and `suggestion` are forwarded off this process — to the browser as
+// `driftWarning`/`driftSuggestion` by `POST /api/ai-hub/check-agent`, and to the Hub's server
+// log by `selfHealBrokenManagedAgents()` — and a resolved CLI path embeds the OS username.
+// Redacting here rather than at each branch that happens to build a path into its message is
+// deliberate: a branch added to `computeAgentCliHealth()` later is covered whether or not its
+// author remembers this constraint. `details` is not redacted; see `redact-paths.ts` for why.
 async function runAgentCliHealthCheck(cli) {
+    return (0, redact_paths_1.redactCheckResultPaths)(await computeAgentCliHealth(cli));
+}
+async function computeAgentCliHealth(cli) {
     // "Ambient" is this process's own raw, unmodified PATH — exactly what a
     // shell already open before a PATH fix landed still sees (issue #1285's
     // "any shell the user already has open keeps its own stale in-memory copy
@@ -110,7 +121,8 @@ async function runAgentCliHealthCheck(cli) {
         if (!recoveredVersion) {
             return {
                 status: 'error',
-                message: `${cli.label} is installed at ${recoveredPath} but failed to run (\`${cli.command} --version\` produced no output).`,
+                // Issue #1482: basename only. The full path stays in `details` for local/self-heal use.
+                message: `${cli.label} is installed (launcher \`${(0, redact_paths_1.redactPathForDisplay)(recoveredPath)}\`) but failed to run (\`${cli.command} --version\` produced no output).`,
                 suggestion: `Reinstall ${cli.label}, then run "${cli.command} --version" again to confirm it's fixed.`,
                 details: { recoveredPath },
             };
@@ -143,7 +155,8 @@ async function runAgentCliHealthCheck(cli) {
     if (brokenPath) {
         return {
             status: 'error',
-            message: `${cli.label} is installed at ${brokenPath} but failed to run (\`${cli.command} --version\` produced no output). An interrupted or partial update may have left a non-functional launcher.`,
+            // Issue #1482: basename only, same as the recovery branch above.
+            message: `${cli.label} is installed (launcher \`${(0, redact_paths_1.redactPathForDisplay)(brokenPath)}\`) but failed to run (\`${cli.command} --version\` produced no output). An interrupted or partial update may have left a non-functional launcher.`,
             suggestion: `Reinstall ${cli.label}, then run "${cli.command} --version" again to confirm it's fixed.`,
             details: { ambientPath, ambientVersion, managedPath, managedVersion },
         };

package/dist/src/cli/doctor/checks/llm-auth-route-checks.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * LLM billing-route health checks for the FRAIM doctor command.
+ *
+ * Issue #1798: a leftover `ANTHROPIC_API_KEY` silently reroutes every Hub-launched
+ * Claude Code agent onto a direct-API key the user may have already declined, and the
+ * only symptom is an opaque `Credit balance is too low` inside Hub while the same
+ * user's terminal keeps working. Nothing in FRAIM surfaced the cause, so the failure
+ * read as "Hub is broken".
+ *
+ * This is the on-demand env-var inspection from `skills/dev-ops/llm-spend-detection.md`
+ * (step 4) promoted into a standing health check, so the conflict is reported before
+ * the user hits it rather than only when they think to go looking.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAnthropicAuthRouteCheck = runAnthropicAuthRouteCheck;
+exports.getLlmAuthRouteChecks = getLlmAuthRouteChecks;
+const anthropic_auth_route_1 = require("../../../core/utils/anthropic-auth-route");
+const claude_subscription_login_1 = require("../../../core/utils/claude-subscription-login");
+const machine_path_1 = require("../../utils/machine-path");
+function unsetInstruction(variable) {
+    return process.platform === 'win32'
+        ? `Remove ${variable} from Windows Settings → Environment Variables (or run: reg delete "HKCU\\Environment" /v ${variable} /f), then restart FRAIM Hub from the tray's Restart item so it picks up the change.`
+        : `Remove the ${variable} export from your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile), then restart FRAIM Hub from the tray's Restart item so it picks up the change.`;
+}
+function formatFinding(finding, scope) {
+    return `${finding.variable} — ${finding.valueHint}; ${scope}. ${finding.effect}`;
+}
+function runAnthropicAuthRouteCheck(deps = {}) {
+    const env = deps.env ?? process.env;
+    const apiKeyResponses = deps.apiKeyResponses !== undefined ? deps.apiKeyResponses : (0, anthropic_auth_route_1.readClaudeApiKeyResponses)();
+    const describeScope = deps.describeScope ?? machine_path_1.describeEnvVarScope;
+    const subscriptionFallbackAvailable = deps.subscriptionFallbackAvailable !== undefined
+        ? deps.subscriptionFallbackAvailable
+        : (0, claude_subscription_login_1.hasUsableSubscriptionLogin)();
+    const { findings, hasConflict } = (0, anthropic_auth_route_1.assessAnthropicAuthRoute)({ env, apiKeyResponses, subscriptionFallbackAvailable });
+    if (findings.length === 0) {
+        return {
+            status: 'passed',
+            message: 'No ambient Anthropic auth variable is overriding the Claude Code billing route.',
+        };
+    }
+    const details = {};
+    for (const finding of findings) {
+        details[finding.variable] = formatFinding(finding, describeScope(finding.variable, env));
+    }
+    return verdictFor(findings, hasConflict, details);
+}
+/**
+ * Three outcomes, each with its own advice.
+ *
+ * A key the user already declined, with a subscription to fall back to, is the reported
+ * defect: an error, fixed by removing the variable. The same key with nothing to fall
+ * back to gets the opposite advice — removing it would leave the machine with no
+ * credential at all, so the fix is to settle which route the user wants. Anything else is
+ * a warning: it may be exactly what a direct-API user intends, and doctor has no basis to
+ * call that wrong.
+ */
+function verdictFor(findings, hasConflict, details) {
+    const primary = findings.find((finding) => finding.severity === 'conflict') ?? findings[0];
+    const names = findings.map((finding) => finding.variable).join(', ');
+    if (hasConflict) {
+        return {
+            status: 'error',
+            message: `${primary.variable} overrides the claude.ai subscription login you already chose, so FRAIM Hub agents bill it instead and typically fail with "Credit balance is too low". Your interactive terminal is unaffected, which is why this looks like a Hub fault.`,
+            suggestion: unsetInstruction(primary.variable),
+            details,
+        };
+    }
+    const stranded = findings.some((finding) => finding.variable === 'ANTHROPIC_API_KEY' && finding.decision === 'rejected');
+    if (stranded) {
+        return {
+            status: 'warning',
+            message: 'ANTHROPIC_API_KEY is a key you declined in an interactive Claude Code session, but it is the only credential on this machine — there is no signed-in claude.ai subscription to fall back to. FRAIM leaves it in place rather than leaving you with nothing to authenticate with, so Hub and your terminal both use it.',
+            suggestion: 'Decide which route you want: run "claude" and sign in with /login to use your subscription, or accept the key at the prompt to keep using direct-API billing. Until then this variable stays in effect.',
+            details,
+        };
+    }
+    return {
+        status: 'warning',
+        message: `${names} ${findings.length === 1 ? 'is' : 'are'} set and take${findings.length === 1 ? 's' : ''} precedence over a claude.ai subscription login for every headless launch, including every FRAIM Hub agent. This is correct if you intend direct-API billing; if you do not, it is the cause of any "Credit balance is too low" or "Not logged in" failure you see only inside Hub.`,
+        suggestion: `Confirm you meant to set ${names}. ${unsetInstruction(primary.variable)}`,
+        details,
+    };
+}
+function getLlmAuthRouteChecks(deps = {}) {
+    return [
+        {
+            name: `Anthropic billing route (${anthropic_auth_route_1.ANTHROPIC_DIRECT_AUTH_VARIABLES.join(', ')})`,
+            category: 'llmAuthRoute',
+            critical: false,
+            run: async () => runAnthropicAuthRouteCheck(deps),
+        },
+    ];
+}

package/dist/src/cli/doctor/redact-paths.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Path redaction for doctor check results that leave this machine.
+ *
+ * Issue #1482 (Privacy PRIV05, GDPR Art. 5(1)(c) data minimization), found during #1256's
+ * `implement-security-review`: a resolved agent-CLI path embeds the OS username on every
+ * mainstream platform (`/Users/camille/.local/bin/claude`,
+ * `C:\Users\sidma\AppData\Roaming\npm\claude.cmd`). `POST /api/ai-hub/check-agent`
+ * (`src/ai-hub/server.ts`) forwards a failing check's `message` and `suggestion` to the browser
+ * verbatim as `driftWarning` / `driftSuggestion`, and `selfHealBrokenManagedAgents()` writes
+ * `message` into the Hub's server log. The basename carries all the diagnostic value those
+ * messages need, so the prefix is dropped.
+ *
+ * Scope of the redaction, deliberately:
+ * - `message` / `suggestion`: redacted. These cross a process boundary.
+ * - `details`: left raw. It is never forwarded to any client — its only readers are
+ *   `selfHealBrokenManagedAgents()` (which reads `details.managedPath` to decide whether to
+ *   auto-reinstall a broken FRAIM-managed CLI) and `fraim doctor`'s own `--verbose` / `--json`
+ *   output, which prints the operator their own paths in their own terminal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactPathForDisplay = redactPathForDisplay;
+exports.redactPathsInText = redactPathsInText;
+exports.redactCheckResultPaths = redactCheckResultPaths;
+/**
+ * Matches an absolute filesystem path: POSIX (`/a/b`), tilde-rooted (`~/a/b`), Windows
+ * drive-rooted (`C:\a\b` or `C:/a/b`), and UNC (`\\server\share`).
+ *
+ * The lookbehind keeps it off text that only looks path-shaped: a URL's `//` is preceded by
+ * `:`, `and/or` is preceded by a letter, and a relative `./bin/x` is preceded by `.`. The body
+ * stops at whitespace and quoting so trailing prose or a quoted command survives — except that
+ * a space is consumed when a path separator still follows before the next space, which is what
+ * keeps `C:\Users\John Smith\bin\claude.cmd` from redacting to `John` and leaving the surname
+ * behind. That lookahead cannot cross whitespace, so ordinary prose after a path (`... but
+ * failed to run`) still terminates the match.
+ */
+const ABSOLUTE_PATH_PATTERN = /(?<![A-Za-z0-9_.:\\/~-])(?:[A-Za-z]:[\\/]|\\\\|~?\/)(?:[^\s"'`<>|]|[ \t](?=[^\s"'`<>|]*[\\/]))*/g;
+/** Trailing sentence punctuation is part of the surrounding prose, not part of the path. */
+const TRAILING_PUNCTUATION = /[.,;:!?)\]}]+$/;
+/**
+ * The basename of a resolved path, with no directory prefix and therefore no username.
+ *
+ * Platform-independent on purpose: `path.basename()` does not treat `\` as a separator on
+ * POSIX, so a Windows path read from a config or a cross-platform fixture would come through
+ * whole. This repo's primary dev machine is win32 and its checks also run on macOS/Linux, so
+ * both separators are always honoured.
+ */
+function redactPathForDisplay(filePath) {
+    const trimmed = filePath.replace(/[\\/]+$/, '');
+    const lastSeparator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    return lastSeparator === -1 ? trimmed : trimmed.slice(lastSeparator + 1);
+}
+/** Replaces every absolute filesystem path in `text` with its basename. */
+function redactPathsInText(text) {
+    return text.replace(ABSOLUTE_PATH_PATTERN, (match) => {
+        const trailing = TRAILING_PUNCTUATION.exec(match)?.[0] ?? '';
+        const candidate = trailing ? match.slice(0, -trailing.length) : match;
+        // A bare drive root (`C:\`) or a lone `/` has no basename to keep; leave it as written.
+        const afterRoot = candidate.replace(/^[A-Za-z]:/, '');
+        if (!/[\\/].+/.test(afterRoot))
+            return match;
+        return redactPathForDisplay(candidate) + trailing;
+    });
+}
+/**
+ * Sanitizes the two fields that leave this machine, leaving `details` untouched.
+ *
+ * Applied at the single exit point of `runAgentCliHealthCheck()` rather than at each branch
+ * that happens to build a path into its message, so a branch added later is covered whether or
+ * not its author remembers this constraint — the failure mode issue #1482 was filed about.
+ */
+function redactCheckResultPaths(result) {
+    const message = redactPathsInText(result.message);
+    const suggestion = result.suggestion === undefined ? undefined : redactPathsInText(result.suggestion);
+    if (message === result.message && suggestion === result.suggestion)
+        return result;
+    return { ...result, message, ...(suggestion === undefined ? {} : { suggestion }) };
+}

package/dist/src/cli/doctor/reporters/console-reporter.js

@@ -17,7 +17,8 @@ const CATEGORY_NAMES = {
     ideConfiguration: 'IDE Configuration',
     mcpConnectivity: 'MCP Server Connectivity',
     scripts: 'Scripts',
-    agentCliHealth: 'Agent CLI Health'
+    agentCliHealth: 'Agent CLI Health',
+    llmAuthRoute: 'LLM Billing Route'
 };
 function getStatusIcon(status) {
     switch (status) {

package/dist/src/cli/setup/ide-detector.js

@@ -56,7 +56,7 @@ const isMacAppRunning = (appName) => {
     // "app not installed" via a temp HOME set this to keep results deterministic.
     if (process.env.FRAIM_DETECT_DISABLE_PROCESS_CHECK === '1')
         return false;
-    const result = (0, child_process_1.spawnSync)('pgrep', ['-f', `${appName}.app/Contents`], { encoding: 'utf8', timeout: 1500 });
+    const result = (0, child_process_1.spawnSync)('pgrep', ['-f', `${appName}.app/Contents`], { encoding: 'utf8', windowsHide: true, timeout: 1500 });
     return result.status === 0 && Boolean((result.stdout || '').trim());
 };
 const hasAppEvidence = (appName) => {
@@ -82,8 +82,8 @@ const availableByVersionProbe = (command) => {
     const recoveredPath = (0, managed_agent_paths_1.buildRecoveredAgentPath)(process.env.PATH ?? process.env.Path);
     const env = { ...process.env, PATH: recoveredPath, Path: recoveredPath };
     const result = process.platform === 'win32'
-        ? (0, child_process_1.spawnSync)('cmd.exe', ['/d', '/s', '/c', `${command} --version`], { encoding: 'utf8', timeout: 1500, env })
-        : (0, child_process_1.spawnSync)(command, ['--version'], { encoding: 'utf8', timeout: 1500, env });
+        ? (0, child_process_1.spawnSync)('cmd.exe', ['/d', '/s', '/c', `${command} --version`], { encoding: 'utf8', windowsHide: true, timeout: 1500, env })
+        : (0, child_process_1.spawnSync)(command, ['--version'], { encoding: 'utf8', windowsHide: true, timeout: 1500, env });
     return result.status === 0 && !result.error && (0, managed_agent_paths_1.versionFromProbeOutput)(result.stdout, result.stderr) !== null;
 };
 const detectClaude = () => {
@@ -180,7 +180,7 @@ exports.CODEX_DESKTOP_DOWNLOAD_URL = 'https://chatgpt.com/download/';
 const detectCodexDesktopMac = () => {
     if (process.env.FRAIM_DETECT_DISABLE_PROCESS_CHECK === '1')
         return false;
-    const result = (0, child_process_1.spawnSync)('mdfind', [`kMDItemCFBundleIdentifier == '${exports.CODEX_DESKTOP_BUNDLE_ID}'`], { encoding: 'utf8', timeout: 2000 });
+    const result = (0, child_process_1.spawnSync)('mdfind', [`kMDItemCFBundleIdentifier == '${exports.CODEX_DESKTOP_BUNDLE_ID}'`], { encoding: 'utf8', windowsHide: true, timeout: 2000 });
     return result.status === 0 && Boolean((result.stdout || '').trim());
 };
 const detectCodexDesktopWindows = () => {
@@ -192,7 +192,7 @@ const detectCodexDesktopWindows = () => {
     // publisher-assigned identifier, distinct from the mutable Start-menu
     // display name) is queried by a name pattern as the best-available proxy.
     const psCmd = `(Get-AppxPackage | Where-Object { $_.Name -like '*ChatGPT*' } | Select-Object -First 1).PackageFamilyName`;
-    const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8', timeout: 3000 });
+    const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8', windowsHide: true, timeout: 3000 });
     return result.status === 0 && Boolean((result.stdout || '').trim());
 };
 const detectCodexDesktopOverride = () => {

package/dist/src/cli/utils/machine-path.js

@@ -9,8 +9,12 @@ exports.composeMachinePath = composeMachinePath;
 exports.resolveMachinePathCached = resolveMachinePathCached;
 exports.clearMachinePathCache = clearMachinePathCache;
 exports.setMachinePathResolver = setMachinePathResolver;
+exports.readWindowsEnvVarScopes = readWindowsEnvVarScopes;
+exports.setWindowsEnvScopeResolver = setWindowsEnvScopeResolver;
+exports.describeEnvVarScope = describeEnvVarScope;
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const env_var_names_1 = require("../../core/utils/env-var-names");
 // ─── Issue #1748: Windows machine-PATH recovery ─────────────────────────────
 //
 // A Windows process inherits its environment at creation and never observes later
@@ -49,12 +53,14 @@ const MACHINE_PATH_CACHE_TTL_MS = 60_000;
 let machinePathResolverOverride = null;
 let cachedMachinePath;
 let cachedMachinePathAtMs = 0;
-// The two registry values Windows itself composes a process PATH from, in the order it
-// composes them: Machine first, then User.
-const WINDOWS_PATH_REGISTRY_KEYS = [
-    [String.raw `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`, 'Path'],
-    [String.raw `HKCU\Environment`, 'Path'],
+// The two registry hives Windows itself composes a process environment from, in the
+// order it composes them: Machine first, then User.
+const WINDOWS_ENVIRONMENT_REGISTRY_KEYS = [
+    ['Machine', String.raw `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`],
+    ['User', String.raw `HKCU\Environment`],
 ];
+const WINDOWS_PATH_REGISTRY_KEYS = WINDOWS_ENVIRONMENT_REGISTRY_KEYS
+    .map(([, key]) => [key, 'Path']);
 // Resolve reg.exe by absolute path rather than letting the OS search PATH for it. This
 // module's whole purpose is to stop a PATH entry from deciding which binary FRAIM runs,
 // so invoking its own helper by bare name through that same untrusted PATH would undercut
@@ -163,3 +169,65 @@ function setMachinePathResolver(resolver) {
     machinePathResolverOverride = resolver;
     clearMachinePathCache();
 }
+let windowsEnvScopeResolverOverride = null;
+function defaultReadWindowsEnvVarScopes(name) {
+    if (process.platform !== 'win32')
+        return [];
+    // Same isolation rule as defaultResolveMachinePath: a sandboxed test run must not
+    // read this machine's real registry environment, or whatever happens to be set on
+    // the build agent would leak into a fixture's expectations.
+    if (process.env.FRAIM_TEST_SANDBOX === '1')
+        return [];
+    const scopes = [];
+    for (const [scope, key] of WINDOWS_ENVIRONMENT_REGISTRY_KEYS) {
+        const result = (0, child_process_1.spawnSync)(resolveRegExePath(), ['query', key, '/v', name], {
+            encoding: 'utf8',
+            timeout: MACHINE_PATH_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        if (result.status !== 0 || result.error)
+            continue;
+        // A value name that does not exist makes `reg query` exit non-zero, so reaching
+        // here already means a hit; parsing confirms the line is a real string value and
+        // not, say, a subkey listing.
+        if (parseRegQueryPathValue(result.stdout || '') !== null)
+            scopes.push(scope);
+    }
+    return scopes;
+}
+/**
+ * The persisted Windows scopes an environment variable is set in, nearest-to-the-OS
+ * first (Machine, then User). Empty on non-Windows, and empty for a variable that only
+ * exists in the current process's inherited environment.
+ */
+function readWindowsEnvVarScopes(name) {
+    if (windowsEnvScopeResolverOverride)
+        return windowsEnvScopeResolverOverride(name);
+    try {
+        return defaultReadWindowsEnvVarScopes(name);
+    }
+    catch {
+        return [];
+    }
+}
+function setWindowsEnvScopeResolver(resolver) {
+    windowsEnvScopeResolverOverride = resolver;
+}
+/**
+ * Where a variable currently in `env` actually lives, phrased for a user who has to go
+ * and remove it.
+ */
+function describeEnvVarScope(name, env = process.env) {
+    // Not `env[name]`: a caller may pass an ordinary copy of the environment, where a
+    // Windows variable the user typed in another casing would read as absent.
+    if ((0, env_var_names_1.lookupEnvVar)(env, name) === undefined)
+        return 'not set';
+    if (process.platform !== 'win32') {
+        return 'set in this process (exported by your shell profile or the app that launched FRAIM)';
+    }
+    const scopes = readWindowsEnvVarScopes(name);
+    if (scopes.length === 0) {
+        return 'set in this process only (not persisted in the Windows registry — it came from the shell that launched FRAIM)';
+    }
+    return `persisted in the Windows ${scopes.join(' and ')} environment`;
+}

package/dist/src/cli/utils/managed-agent-paths.js

@@ -192,6 +192,7 @@ function resolveNpmGlobalBinDirs(basePath, env) {
         ? ['/d', '/s', '/c', 'npm', 'prefix', '-g']
         : ['prefix', '-g'];
     const result = (0, child_process_1.spawnSync)(executable, args, {
+        windowsHide: true,
         encoding: 'utf8',
         timeout: 5000,
         env: childEnv,

package/dist/src/core/utils/anthropic-auth-route.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_API_KEY_DECISION_TAIL_LENGTH = exports.ANTHROPIC_DIRECT_AUTH_VARIABLES = void 0;
+exports.claudeApiKeyDecisionTail = claudeApiKeyDecisionTail;
+exports.claudeConfigFilePath = claudeConfigFilePath;
+exports.parseClaudeApiKeyResponses = parseClaudeApiKeyResponses;
+exports.readClaudeApiKeyResponses = readClaudeApiKeyResponses;
+exports.readClaudeApiKeyResponsesCached = readClaudeApiKeyResponsesCached;
+exports.clearClaudeApiKeyResponsesCache = clearClaudeApiKeyResponsesCache;
+exports.classifyAmbientApiKey = classifyAmbientApiKey;
+exports.assessAnthropicAuthRoute = assessAnthropicAuthRoute;
+exports.anthropicEnvToUnsetForRecordedRoute = anthropicEnvToUnsetForRecordedRoute;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const env_var_names_1 = require("./env-var-names");
+// ─── Issue #1798: ambient Anthropic auth env vars vs. the user's intended route ───
+//
+// Claude Code resolves its credentials differently depending on how it was started,
+// and the two paths disagree:
+//
+//   Interactive TUI  — an `ANTHROPIC_API_KEY` found in the environment produces a
+//                      one-time "use this API key?" prompt. The answer is persisted
+//                      in `~/.claude.json` under `customApiKeyResponses`, and a
+//                      rejected key is thereafter ignored in favour of the
+//                      claude.ai subscription OAuth login.
+//   Headless (`-p`)  — there is nobody to prompt, and the stored answer is never
+//                      consulted. The environment variable wins unconditionally.
+//
+// FRAIM Hub spawns agents headlessly, merging `process.env` into the child, so a
+// stray `ANTHROPIC_API_KEY` left over from unrelated testing silently reroutes every
+// Hub job onto a direct-API key the user already declined — while their own terminal
+// keeps working. The observable symptom is an opaque `Credit balance is too low`.
+//
+// Verified live on the reporter's machine (issue #1798, and re-confirmed while
+// implementing it) against a real subscription login, same config home for all runs:
+//
+//   ANTHROPIC_API_KEY   (recorded as rejected) → exit 1, "Credit balance is too low"
+//   ANTHROPIC_AUTH_TOKEN (bogus value)         → exit 1, "Not logged in · Please run /login"
+//   ANTHROPIC_BASE_URL   (unroutable value)    → exit 1, "API Error: Connection refused"
+//   none of the above                          → exit 0, normal reply
+//
+// So all three override a working subscription login, but only `ANTHROPIC_API_KEY`
+// has a recorded user decision to read back. That asymmetry is why this module
+// reports on all three and authorises removing only the first — see
+// `anthropicEnvToUnsetForRecordedRoute`.
+/** The env vars confirmed above to take precedence over a claude.ai subscription login. */
+exports.ANTHROPIC_DIRECT_AUTH_VARIABLES = [
+    'ANTHROPIC_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_BASE_URL',
+];
+/**
+ * Claude Code keys a recorded accept/reject decision by the LAST 20 CHARACTERS of the
+ * key, not by the whole key or a hash of it. Confirmed against real data on the
+ * reporting machine: a 108-character `sk-ant-api03-…` key whose final 20 characters
+ * appear verbatim as the single entry in `customApiKeyResponses.rejected`.
+ */
+exports.CLAUDE_API_KEY_DECISION_TAIL_LENGTH = 20;
+/** The decision key Claude Code stores for an API key. Empty for a value too short to key on. */
+function claudeApiKeyDecisionTail(apiKey) {
+    const value = String(apiKey || '');
+    return value.length >= exports.CLAUDE_API_KEY_DECISION_TAIL_LENGTH
+        ? value.slice(-exports.CLAUDE_API_KEY_DECISION_TAIL_LENGTH)
+        : '';
+}
+/**
+ * A printable stand-in for a credential. Six characters is enough for a user to tell
+ * which of their keys this is while leaving the value unusable — deliberately shorter
+ * than the 20-character decision tail, which is itself key material and must not be
+ * echoed to a console or a log.
+ */
+const CREDENTIAL_HINT_CHARS = 6;
+function credentialHint(value) {
+    const trimmed = String(value || '');
+    if (trimmed.length <= CREDENTIAL_HINT_CHARS)
+        return `set (${trimmed.length} chars)`;
+    return `set (${trimmed.length} chars, ending …${trimmed.slice(-CREDENTIAL_HINT_CHARS)})`;
+}
+function normalizeResponseList(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+/**
+ * The file Claude Code persists interactive answers in. The home-directory location is
+ * the confirmed one; no other location is guessed at, because a miss here degrades to
+ * "no recorded decision", which is the safe answer everywhere this module is used.
+ */
+function claudeConfigFilePath(homeDir = os_1.default.homedir()) {
+    return path_1.default.join(homeDir, '.claude.json');
+}
+function parseClaudeApiKeyResponses(fileContents) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fileContents);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const responses = parsed.customApiKeyResponses;
+    if (!responses || typeof responses !== 'object')
+        return null;
+    return {
+        approved: normalizeResponseList(responses.approved),
+        rejected: normalizeResponseList(responses.rejected),
+    };
+}
+function readClaudeApiKeyResponses(homeDir = os_1.default.homedir()) {
+    try {
+        return parseClaudeApiKeyResponses(fs_1.default.readFileSync(claudeConfigFilePath(homeDir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// `~/.claude.json` is ~120KB on a well-used machine and is re-read on every agent
+// launch, so the read is memoized. It expires rather than living for the process
+// lifetime because the user can answer the interactive prompt in a terminal at any
+// moment, and a Hub instance runs for days — the same reasoning as the machine-PATH
+// cache in src/cli/utils/machine-path.ts.
+const CLAUDE_API_KEY_RESPONSES_CACHE_TTL_MS = 60_000;
+let cachedResponses;
+let cachedResponsesAtMs = 0;
+function readClaudeApiKeyResponsesCached(nowMs = Date.now()) {
+    if (cachedResponses !== undefined && nowMs - cachedResponsesAtMs < CLAUDE_API_KEY_RESPONSES_CACHE_TTL_MS) {
+        return cachedResponses;
+    }
+    cachedResponses = readClaudeApiKeyResponses();
+    cachedResponsesAtMs = nowMs;
+    return cachedResponses;
+}
+function clearClaudeApiKeyResponsesCache() {
+    cachedResponses = undefined;
+    cachedResponsesAtMs = 0;
+}
+function classifyAmbientApiKey(apiKey, responses) {
+    const tail = claudeApiKeyDecisionTail(apiKey || '');
+    if (!tail || !responses)
+        return 'unprompted';
+    if (responses.rejected.includes(tail))
+        return 'rejected';
+    if (responses.approved.includes(tail))
+        return 'approved';
+    return 'unprompted';
+}
+function isSet(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+const EFFECT_REJECTED_WITH_FALLBACK = 'You already declined this key in an interactive Claude Code session, so your terminal uses your claude.ai '
+    + 'subscription. Headless launches (which is how FRAIM Hub starts agents) never read that answer, so Hub bills this '
+    + 'key instead — typically failing with "Credit balance is too low".';
+const EFFECT_REJECTED_NO_FALLBACK = 'You declined this key in an interactive Claude Code session, but it is the only credential on this machine — there '
+    + 'is no signed-in claude.ai subscription to fall back to. FRAIM leaves it in place rather than leaving you with '
+    + 'nothing to authenticate with. Run "claude" and sign in with /login if you meant to use your subscription, or '
+    + 'accept the key at the prompt if you meant to use it.';
+const EFFECT_UNPROMPTED = 'This key takes precedence over your claude.ai subscription login for every headless launch, including every FRAIM '
+    + 'Hub agent. If it is exhausted or belongs to a different account, Hub jobs fail with "Credit balance is too low" '
+    + 'while your terminal keeps working.';
+/**
+ * The finding for an ambient `ANTHROPIC_API_KEY`, or null when there is nothing to say.
+ *
+ * An approved key produces no finding at all: the user was asked, said yes, and chose
+ * direct-API billing. A rejected key with nothing to fall back to is reported but is not
+ * a conflict FRAIM can resolve — it is the only credential on the machine, so it is left
+ * in place rather than errored on and removed.
+ */
+function apiKeyFindingFor(apiKey, responses, subscriptionFallbackAvailable) {
+    if (!isSet(apiKey))
+        return null;
+    const decision = classifyAmbientApiKey(apiKey, responses);
+    if (decision === 'approved')
+        return null;
+    const stranded = decision === 'rejected' && !subscriptionFallbackAvailable;
+    return {
+        variable: 'ANTHROPIC_API_KEY',
+        severity: decision === 'rejected' && !stranded ? 'conflict' : 'unreviewed',
+        decision,
+        valueHint: credentialHint(apiKey),
+        effect: stranded
+            ? EFFECT_REJECTED_NO_FALLBACK
+            : decision === 'rejected' ? EFFECT_REJECTED_WITH_FALLBACK : EFFECT_UNPROMPTED,
+    };
+}
+/**
+ * Describe every ambient variable that would reroute a Hub-launched Claude Code agent
+ * away from the route the user's recorded state says they intend.
+ *
+ * An `approved` key produces no finding at all: the user was asked, said yes, and
+ * direct-API billing is what they chose.
+ */
+function assessAnthropicAuthRoute(input) {
+    const { env, apiKeyResponses, platform = process.platform, subscriptionFallbackAvailable = true } = input;
+    const findings = [];
+    const apiKey = (0, env_var_names_1.lookupEnvVar)(env, 'ANTHROPIC_API_KEY', platform);
+    const apiKeyFinding = apiKeyFindingFor(apiKey, apiKeyResponses, subscriptionFallbackAvailable);
+    if (apiKeyFinding)
+        findings.push(apiKeyFinding);
+    const authToken = (0, env_var_names_1.lookupEnvVar)(env, 'ANTHROPIC_AUTH_TOKEN', platform);
+    if (isSet(authToken)) {
+        findings.push({
+            variable: 'ANTHROPIC_AUTH_TOKEN',
+            severity: 'unreviewed',
+            valueHint: credentialHint(authToken),
+            effect: 'This token takes precedence over your claude.ai subscription login. If it is not a valid credential, Hub agents fail with "Not logged in · Please run /login". Claude Code records no accept/reject answer for this variable, so nothing can tell FRAIM whether you meant to set it.',
+        });
+    }
+    const baseUrl = (0, env_var_names_1.lookupEnvVar)(env, 'ANTHROPIC_BASE_URL', platform);
+    if (isSet(baseUrl)) {
+        findings.push({
+            variable: 'ANTHROPIC_BASE_URL',
+            severity: 'unreviewed',
+            // Not a credential: showing it in full is what makes the finding actionable.
+            valueHint: baseUrl,
+            effect: 'This sends every Hub agent request to that address instead of the Anthropic API. If it points at a proxy that is no longer running, Hub agents fail with a connection error.',
+        });
+    }
+    return { findings, hasConflict: findings.some((finding) => finding.severity === 'conflict') };
+}
+/**
+ * The variables FRAIM may remove from a headless child's environment on the user's
+ * behalf, given what they have already recorded.
+ *
+ * Deliberately narrow: only an `ANTHROPIC_API_KEY` the user explicitly rejected in an
+ * interactive session qualifies. That is not a new policy — it is the answer the user
+ * already gave, applied to the launch path that never asked. Everything else is left
+ * alone and merely reported, because an unprompted key may be the user's only
+ * credential, and removing it would break a working direct-API setup to fix a problem
+ * they do not have.
+ */
+function anthropicEnvToUnsetForRecordedRoute(env, responses, platform = process.platform, subscriptionFallbackAvailable = true) {
+    const apiKey = (0, env_var_names_1.lookupEnvVar)(env, 'ANTHROPIC_API_KEY', platform);
+    if (!isSet(apiKey))
+        return [];
+    // Never remove the only credential on the machine. A user who declined this key once
+    // and later changed their mind without clearing the record still needs it to work.
+    if (!subscriptionFallbackAvailable)
+        return [];
+    return classifyAmbientApiKey(apiKey, responses) === 'rejected' ? ['ANTHROPIC_API_KEY'] : [];
+}

package/dist/src/core/utils/claude-subscription-login.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCredentialsFilePath = claudeCredentialsFilePath;
+exports.parseSubscriptionLoginPresence = parseSubscriptionLoginPresence;
+exports.hasUsableSubscriptionLogin = hasUsableSubscriptionLogin;
+exports.hasUsableSubscriptionLoginCached = hasUsableSubscriptionLoginCached;
+exports.clearSubscriptionLoginCache = clearSubscriptionLoginCache;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+// ─── Is there a subscription session to fall back to? ───────────────────────
+//
+// Removing a credential is only safe when another one remains. FRAIM sheds an ambient
+// `ANTHROPIC_API_KEY` that the user declined interactively (see anthropic-auth-route.ts),
+// but a user whose only working credential is that same declined key — they said no once
+// and later changed their mind without clearing the record — would be left with nothing
+// to authenticate with, turning a working Hub into `Not logged in · Please run /login`.
+// That is a worse outcome than the problem the removal exists to fix, so the removal is
+// gated on this answer.
+//
+// The signal is `claudeAiOauth` in `~/.claude/.credentials.json`, where Claude Code keeps
+// the subscription session. Only presence and the numeric expiry are ever read: no token
+// value is assigned to a named variable, returned, logged, or compared.
+//
+// `~/.claude.json`'s `hasAvailableSubscription` is deliberately not used. It reads `false`
+// on a machine whose subscription login demonstrably works, so it describes entitlement
+// rather than whether a session exists to fall back to.
+//
+// Its own module rather than part of anthropic-auth-route.ts because "is the user signed
+// in" is a different question from "what did the user decide about this key", and keeping
+// them apart is what lets either be reused without dragging the other along.
+function claudeCredentialsFilePath(homeDir = os_1.default.homedir()) {
+    return path_1.default.join(homeDir, '.claude', '.credentials.json');
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Whether a subscription session exists that a child process could authenticate with.
+ * Every failure mode answers `false`, because "we could not tell" and "there is no
+ * fallback" must lead to the same safe outcome: leave the user's credential alone.
+ */
+function parseSubscriptionLoginPresence(fileContents, nowMs = Date.now()) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fileContents);
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const oauth = parsed.claudeAiOauth;
+    if (!oauth || typeof oauth !== 'object')
+        return false;
+    const record = oauth;
+    // A refresh token is enough on its own: Claude Code renews an expired access token from
+    // it without any user action. Without one, the access token must still be live.
+    if (isNonEmptyString(record.refreshToken))
+        return true;
+    if (!isNonEmptyString(record.accessToken))
+        return false;
+    return typeof record.expiresAt === 'number' ? record.expiresAt > nowMs : true;
+}
+function hasUsableSubscriptionLogin(homeDir = os_1.default.homedir(), nowMs = Date.now()) {
+    try {
+        return parseSubscriptionLoginPresence(fs_1.default.readFileSync(claudeCredentialsFilePath(homeDir), 'utf8'), nowMs);
+    }
+    catch {
+        return false;
+    }
+}
+// Memoized for the same reason the sibling reads in anthropic-auth-route.ts and
+// machine-path.ts are: the user can sign in from a terminal at any moment, while a Hub
+// instance runs for days, so the answer must expire rather than live for the process.
+const SUBSCRIPTION_LOGIN_CACHE_TTL_MS = 60_000;
+let cached;
+let cachedAtMs = 0;
+function hasUsableSubscriptionLoginCached(nowMs = Date.now()) {
+    if (cached !== undefined && nowMs - cachedAtMs < SUBSCRIPTION_LOGIN_CACHE_TTL_MS)
+        return cached;
+    cached = hasUsableSubscriptionLogin(os_1.default.homedir(), nowMs);
+    cachedAtMs = nowMs;
+    return cached;
+}
+function clearSubscriptionLoginCache() {
+    cached = undefined;
+    cachedAtMs = 0;
+}

package/dist/src/core/utils/env-var-names.js

@@ -0,0 +1,64 @@
+"use strict";
+// ─── Windows environment names are case-insensitive; a copy of them is not ───
+//
+// Windows treats `anthropic_api_key` and `ANTHROPIC_API_KEY` as the same variable, and
+// Node's `process.env` reproduces that: a read through any casing finds the value.
+// `{ ...process.env }` does not — the spread produces an ordinary object keyed by
+// whatever casing the user actually typed, where a differently-cased read returns
+// undefined and a differently-cased delete silently does nothing:
+//
+//   process.env.zz_probe = 'set'
+//   process.env.ZZ_PROBE            -> 'set'       (case-insensitive)
+//   { ...process.env }.ZZ_PROBE     -> undefined   (an ordinary, case-SENSITIVE object)
+//   delete copy.ZZ_PROBE            -> 'zz_probe' still present
+//
+// Any code that builds a child environment works on exactly such a copy, so matching a
+// variable by its canonical name there needs these helpers rather than `env[name]`.
+// (`src/ai-hub/hosts.ts` already carried a narrower form of this workaround as
+// `merged.PATH ?? merged.Path`; issue #1798 generalized it after a bug bash found that
+// a lower-cased `anthropic_api_key` defeated both a detection and a removal.)
+//
+// POSIX environments are genuinely case-sensitive, where two differently-cased names
+// are two different variables, so the exact match is the correct behaviour there and
+// the platform is a parameter rather than an assumption — which also makes both
+// branches testable from either host.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupEnvVar = lookupEnvVar;
+exports.hasEnvVar = hasEnvVar;
+exports.deleteEnvVar = deleteEnvVar;
+/** The value of `name` under the platform's own name-matching rules, or undefined. */
+function lookupEnvVar(env, name, platform = process.platform) {
+    const direct = env[name];
+    if (direct !== undefined || platform !== 'win32')
+        return direct;
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === lower)
+            return env[key];
+    }
+    return undefined;
+}
+/**
+ * Whether `name` is present at all — distinct from `lookupEnvVar(...) !== undefined`,
+ * because an explicitly empty value is still an explicit value.
+ */
+function hasEnvVar(env, name, platform = process.platform) {
+    if (Object.prototype.hasOwnProperty.call(env, name))
+        return true;
+    if (platform !== 'win32')
+        return false;
+    const lower = name.toLowerCase();
+    return Object.keys(env).some((key) => key.toLowerCase() === lower);
+}
+/** Removes every casing of `name` on Windows; the exact name elsewhere. */
+function deleteEnvVar(env, name, platform = process.platform) {
+    if (platform !== 'win32') {
+        delete env[name];
+        return;
+    }
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === lower)
+            delete env[key];
+    }
+}

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -211,6 +211,55 @@ function resolvePersonalLearningFileTiers(repoBase, managerCacheBase, managerCac
     }
     return tiers;
 }
+/**
+ * Issue #754 (OWASP API10): `userId` is untrusted at the point of file-path use.
+ *
+ * Every learning file name in this module is built as `${resolvedUserId}-<type>.md`
+ * and handed to `join(base, …)`. `path.join` NORMALIZES `..` and swallows a leading
+ * separator rather than blocking either, so an unvetted userId is a traversal
+ * primitive: `join(base, '../../evil-preferences.md')` lands outside `base`, and
+ * `join(base, '/victim@corp.com-preferences.md')` lands back inside it under a
+ * DIFFERENT user's name. Before #750 the value came only from local files; since
+ * #750 the Hub feeds it from the hosted `GET /api/personas/me` response, so it now
+ * crosses a network trust boundary before reaching this construction.
+ *
+ * REJECT, NOT STRIP. Stripping the offending characters is worse than the traversal
+ * it prevents: `../../victim@corp.com` would strip to `victim@corp.com`, turning a
+ * blocked traversal into a successful impersonation of a real account whose learning
+ * files are the very assets in this directory. A rejected identity instead resolves
+ * to no candidate at all, which this module already has a defined meaning for - the
+ * #1002 R4.1 contract below: an unresolved identity yields an EMPTY personal section
+ * rather than a guess. Rejection is a filter and not a throw, because
+ * `buildLearningContextSection` runs on MCP auto-load; throwing would turn a
+ * malformed identity into a hard session-startup failure.
+ */
+function isPathSafeUserIdCandidate(candidate) {
+    // A candidate becomes a file NAME, never a path. Reject anything that can
+    // address a directory (`/`, `\`), a drive or an NTFS alternate data stream
+    // (`:`), or terminate a C string inside a syscall (NUL and the other control
+    // bytes). Hyphens, dots and `@` stay legal - real addresses carry them.
+    // eslint-disable-next-line no-control-regex
+    if (/[\\/:\u0000-\u001f]/.test(candidate))
+        return false;
+    // `..-preferences.md` is an ordinary file name, but a candidate that IS a
+    // relative-directory token is never a real identity.
+    if (candidate === '.' || candidate === '..')
+        return false;
+    // Structural backstop rather than a restatement of the check above: prove the
+    // candidate cannot leave a base directory no matter which mechanism it used, by
+    // resolving the real file name it produces against a synthetic base and requiring
+    // a direct child. This keeps holding if the character list is ever found to be
+    // incomplete on some platform.
+    //
+    // The base is a cwd-relative token resolved to absolute rather than a real
+    // directory: nothing is touched on disk, and a path-safety check must not depend
+    // on environment or configuration. `getUserFraimDirPath()` in particular throws
+    // under FRAIM_TEST_SANDBOX=1, which would turn a malformed identity into a crash -
+    // the exact outcome the reject-as-filter decision above exists to avoid.
+    const probeBase = (0, path_1.resolve)('__fraim_userid_probe__');
+    const probed = (0, path_1.resolve)((0, path_1.join)(probeBase, `${candidate}-preferences.md`));
+    return (0, path_1.dirname)(probed) === probeBase;
+}
 function buildUserIdCandidates(userId) {
     const candidates = new Set();
     const trimmed = userId.trim();
@@ -219,7 +268,7 @@ function buildUserIdCandidates(userId) {
     const atIndex = trimmed.indexOf('@');
     if (atIndex > 0)
         candidates.add(trimmed.slice(0, atIndex));
-    return Array.from(candidates);
+    return Array.from(candidates).filter(isPathSafeUserIdCandidate);
 }
 function countMatchingFilesByPrefix(dirPath, matcher) {
     if (!(0, fs_1.existsSync)(dirPath))
@@ -233,7 +282,13 @@ function countMatchingFilesByPrefix(dirPath, matcher) {
 }
 function resolveLearningUserId(workspaceRoot, userId, roots) {
     const candidates = buildUserIdCandidates(userId);
-    let bestCandidate = candidates[0] || userId;
+    // Issue #754: falling back to the raw `userId` here would route every rejected
+    // candidate straight back into `join(base, "${resolvedUserId}-<type>.md")` and
+    // undo the filter above. The empty string is the module's existing "no identity"
+    // value - `src/ai-hub/server.ts` already calls in with `userEmail || ''` - so an
+    // identity that fails the path-safety check lands on the same defined, contained
+    // behavior as an identity that was never supplied: an empty personal section.
+    let bestCandidate = candidates[0] || '';
     let bestScore = -1;
     for (const candidate of candidates) {
         const score = ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-preferences.md`)) ? 1 : 0) +
@@ -630,14 +685,25 @@ const CONTEXT_CATEGORIES = {
  * resolutions that can drift.
  */
 function resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain) {
-    // Domain axis (issue #806): session startup stays broad enough for stable
-    // preferences plus L0, while job contexts load the full global set and may
-    // append the current job's domain files below the global files.
+    // Domain axis (issue #806) plus the connect/job single-injection contract (issue
+    // #860). Session startup stays broad enough for stable preferences plus L0, while
+    // job contexts add the remaining global categories and may append the current job's
+    // domain files below the global files.
+    //
+    // `sessionCats` is the single source of truth for what `fraim_connect` already put
+    // in the agent's context. A job's GLOBAL listing subtracts it, so nothing global is
+    // listed at both injection points, and adding a category to `sessionCats` later
+    // dedups it at job time with no other edit. DOMAIN files are never subtracted:
+    // connect has no job selected and so cannot know the domain, which means a job lists
+    // the domain file for EVERY category, including the ones deduped above.
     const sessionCats = ['pref'];
     const jobL2Cats = ['mistake', 'pref', 'coach', 'validated'];
     const jobL1Cats = ['pref', 'coach', 'mistake', 'validated'];
-    const l2Cats = forJob ? jobL2Cats : sessionCats;
-    const l1Cats = forJob ? jobL1Cats : sessionCats;
+    const notAlreadyInjectedAtConnect = (cats) => cats.filter(key => !sessionCats.includes(key));
+    const l2GlobalCats = forJob ? notAlreadyInjectedAtConnect(jobL2Cats) : sessionCats;
+    const l1GlobalCats = forJob ? notAlreadyInjectedAtConnect(jobL1Cats) : sessionCats;
+    const l2DomainCats = forJob ? jobL2Cats : [];
+    const l1DomainCats = forJob ? jobL1Cats : [];
     const activeDomain = forJob && domain ? domain : null;
     let multiTier = false;
     let coachPresent = false;
@@ -645,6 +711,10 @@ function resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJo
     // so a promoted entry never hides the rest of its family. `multiTier` is true
     // when at least one family exists at more than one level, which is when the
     // collision rule needs stating.
+    // `global` and `domain` are independent so a job can drop a global category already
+    // injected at connect (#860) while still listing that category's domain file (#806).
+    // They are one named argument rather than two positional ones of the same type: a
+    // swap would compile and silently invert both contracts at once.
     const collect = (cats, tiersFor, fallbackLevel) => {
         const globalFiles = [];
         const domainFiles = [];
@@ -666,16 +736,18 @@ function resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJo
                     coachPresent = true;
             }
         };
-        for (const key of cats) {
-            const meta = CONTEXT_CATEGORIES[key];
-            push(globalFiles, key, tiersFor(meta.ft));
-            if (activeDomain)
-                push(domainFiles, key, tiersFor(meta.ft, activeDomain));
+        for (const key of cats.global) {
+            push(globalFiles, key, tiersFor(CONTEXT_CATEGORIES[key].ft));
+        }
+        if (activeDomain) {
+            for (const key of cats.domain) {
+                push(domainFiles, key, tiersFor(CONTEXT_CATEGORIES[key].ft, activeDomain));
+            }
         }
         return [...globalFiles, ...domainFiles];
     };
-    const l2 = collect(l2Cats, (ft, dom) => resolveOrgLearningFileTiers(roots.repoLearningsBase, dom ? `org-${dom}-${ft}.md` : `org-${ft}.md`), 'org');
-    const l1 = collect(l1Cats, (ft, dom) => resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, dom ? `${resolvedUserId}-${dom}-${ft}.md` : `${resolvedUserId}-${ft}.md`), 'manager');
+    const l2 = collect({ global: l2GlobalCats, domain: l2DomainCats }, (ft, dom) => resolveOrgLearningFileTiers(roots.repoLearningsBase, dom ? `org-${dom}-${ft}.md` : `org-${ft}.md`), 'org');
+    const l1 = collect({ global: l1GlobalCats, domain: l1DomainCats }, (ft, dom) => resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, dom ? `${resolvedUserId}-${dom}-${ft}.md` : `${resolvedUserId}-${ft}.md`), 'manager');
     return { l2, l1, multiTier, coachPresent };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.328",
+  "version": "2.0.332",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {