fraim 2.0.360 → 2.0.361-next.1

package/dist/registry/scripts/artifact-paths.js

@@ -46,20 +46,25 @@ function directory(root, value, field) {
         throw new Error(`Invalid artifactPaths.${field}: target is not a directory`);
     return target.replace(/\\/g, '/');
 }
-function resolveArtifactPaths(homeRoot, contentRoot) {
+function resolveArtifactPaths(homeRoot, contentRoot, configPath, configOverrides) {
     if (!node_path_1.default.isAbsolute(homeRoot) || !node_path_1.default.isAbsolute(contentRoot))
         throw new Error('Absolute owning homeRoot and contentRoot are required');
     homeRoot = node_path_1.default.resolve(homeRoot);
     contentRoot = node_path_1.default.resolve(contentRoot);
     if (!within(homeRoot, contentRoot))
         throw new Error('Personalized contentRoot escapes owning homeRoot');
-    const configPath = node_path_1.default.join(node_path_1.default.dirname(contentRoot), 'config.json');
+    const resolvedConfigPath = configPath ?? node_path_1.default.join(node_path_1.default.dirname(contentRoot), 'config.json');
     let config = {};
-    try {
-        config = (0, local_runtime_1.readJsonIfObject)(configPath, { strict: true });
+    if (configOverrides !== undefined) {
+        config = configOverrides;
     }
-    catch {
-        throw new Error(`Cannot read artifact configuration: ${configPath}`);
+    else if (node_fs_1.default.existsSync(resolvedConfigPath)) {
+        try {
+            config = (0, local_runtime_1.readJsonIfObject)(resolvedConfigPath, { strict: true });
+        }
+        catch {
+            throw new Error(`Cannot read artifact configuration: ${resolvedConfigPath}`);
+        }
     }
     const configured = config.artifactPaths === undefined ? {} : config.artifactPaths;
     // Defaults follow the configured home layout, but every value has the same root-relative basis.
@@ -90,7 +95,7 @@ function resolveArtifactPaths(homeRoot, contentRoot) {
             if (within(target, other) || within(other, target))
                 throw new Error(`Artifact directories overlap: ${field} and ${otherField}`);
         }
-    return { configPath: configPath.replace(/\\/g, '/'), evidence: outputs.evidence, raw: outputs.raw,
+    return { configPath: resolvedConfigPath.replace(/\\/g, '/'), evidence: outputs.evidence, raw: outputs.raw,
         retrospectives: outputs.retrospectives,
         archiveRaw: directory(homeRoot, values.learningArchive + '/raw', 'learningArchive'),
         archiveRetrospectives: directory(homeRoot, values.learningArchive + '/retrospectives', 'learningArchive') };

package/dist/registry/scripts/learning/outcome-assessment.js

@@ -12,7 +12,7 @@ const learning_usage_store_1 = require("../../../src/local-mcp-server/learning-u
 const owner_identity_1 = require("./owner-identity");
 const proposal_queue_1 = require("./proposal-queue");
 const completion_state_1 = require("./completion-state");
-const artifact_paths_1 = require("../artifact-paths");
+const pack_home_1 = require("../../../src/cli/utils/pack-home");
 const learning_source_record_1 = require("../learning-usage/learning-source-record");
 const corpus_audit_1 = require("./corpus-audit");
 const outcome_types_1 = require("./outcome-types");
@@ -34,7 +34,7 @@ function resolveAssessmentSources(input, homes) {
         const originalFile = (0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join((0, owner_identity_1.ownerArtifactRoot)(home), ref.relativePath));
         let file = originalFile;
         if (!node_fs_1.default.existsSync(file)) {
-            const paths = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+            const paths = (0, pack_home_1.resolvePackArtifactPaths)(home);
             const archive = (0, completion_state_1.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_1.sourcePathKey)(paths.raw) ? paths.archiveRaw
                 : (0, completion_state_1.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_1.sourcePathKey)(paths.retrospectives) ? paths.archiveRetrospectives : undefined;
             if (archive)
@@ -83,7 +83,8 @@ function verifyAssessmentSources(sources, state) {
         const originalBody = source.archived ? body.replace(/^(synthesized:)[^\r\n]*/m, '$1') : body;
         if ((0, proposal_queue_1.hashContent)(body) !== source.ref.sha256 && (0, proposal_queue_1.hashContent)(originalBody) !== source.ref.sha256)
             throw new Error('assessment-source-hash-conflict');
-        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.file, (0, owner_identity_1.ownerArtifactRoot)(source.home), source.home.contentRoot);
+        const locations = (0, pack_home_1.resolvePackArtifactPaths)(source.home);
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.file, (0, owner_identity_1.ownerArtifactRoot)(source.home), source.home.contentRoot, locations);
         if (parsed.status !== 'valid')
             throw new Error(`invalid-assessment-source: ${parsed.reason}`);
         if (parsed.record.sourceId !== source.ref.sourceId

package/dist/registry/scripts/learning/run-application.js

@@ -17,7 +17,7 @@ const proposal_queue_1 = require("./proposal-queue");
 const entry_authoring_1 = require("./entry-authoring");
 const run_publication_1 = require("./run-publication");
 const completion_state_2 = require("./completion-state");
-const artifact_paths_1 = require("../artifact-paths");
+const pack_home_1 = require("../../../src/cli/utils/pack-home");
 const learning_source_record_1 = require("../learning-usage/learning-source-record");
 const corpus_audit_1 = require("./corpus-audit");
 const { learningEntryBlocks, learningEntryMetadata } = require('./entry-format');
@@ -453,14 +453,14 @@ function sourceCompletion(run, homes, options, afterStage) {
     if (new Set(normalized.map(item => process.platform === 'win32' ? item.path.toLowerCase() : item.path)).size !== normalized.length)
         throw new Error('duplicate-analyzed-source');
     const runHome = options.resolveHome(run.owner);
-    const retrospectiveFile = (0, owner_identity_1.configuredArtifactPath)(runHome, node_path_1.default.join((0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(runHome), runHome.contentRoot).retrospectives, node_path_1.default.basename(options.retrospective.relativePath)));
+    const retrospectiveFile = (0, owner_identity_1.configuredArtifactPath)(runHome, node_path_1.default.join((0, pack_home_1.resolvePackArtifactPaths)(runHome).retrospectives, node_path_1.default.basename(options.retrospective.relativePath)));
     const allowed = (source) => {
         for (const home of homes) {
             const configured = options.resolveHome(home.owner);
             (0, owner_identity_1.assertSameOwner)(home.owner, configured.owner);
             if ((0, completion_state_2.sourcePathKey)(home.contentRoot) !== (0, completion_state_2.sourcePathKey)(configured.contentRoot) || (0, completion_state_2.sourcePathKey)(home.root) !== (0, completion_state_2.sourcePathKey)(configured.root) || (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(home)) !== (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(configured)))
                 throw new Error('analyzed-source-outside-home');
-            const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(configured), configured.contentRoot);
+            const locations = (0, pack_home_1.resolvePackArtifactPaths)(configured);
             const sourceDirectory = source.kind === 'raw' ? locations.raw : locations.retrospectives;
             const archiveDirectory = source.kind === 'raw' ? locations.archiveRaw : locations.archiveRetrospectives;
             if ((0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(source.path)) !== (0, completion_state_2.sourcePathKey)(sourceDirectory))
@@ -471,7 +471,7 @@ function sourceCompletion(run, homes, options, afterStage) {
                 const relative = node_path_1.default.relative(configured.contentRoot, directory);
                 return relative === '..' || relative.startsWith('..' + node_path_1.default.sep) || node_path_1.default.isAbsolute(relative);
             });
-            return { root: (0, owner_identity_1.ownerArtifactRoot)(configured), contentRoot: configured.contentRoot, owner: configured.owner, destination,
+            return { root: (0, owner_identity_1.ownerArtifactRoot)(configured), contentRoot: configured.contentRoot, owner: configured.owner, destination, locations,
                 layout: { contentRoot: node_path_1.default.resolve(configured.contentRoot).replace(/\\/g, '/'), sourceDirectory, archiveDirectory, ...(outsideContent ? { homeRoot: (0, owner_identity_1.ownerArtifactRoot)(configured) } : {}) } };
         }
         throw new Error('analyzed-source-outside-home');
@@ -510,7 +510,7 @@ function sourceCompletion(run, homes, options, afterStage) {
             if (!node_path_1.default.isAbsolute(ref))
                 continue;
             const isInput = homes.some(home => {
-                const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+                const locations = (0, pack_home_1.resolvePackArtifactPaths)(home);
                 return [locations.raw, locations.retrospectives].some(directory => (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(ref)) === (0, completion_state_2.sourcePathKey)(directory));
             });
             if (isInput && !normalized.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(ref) && item.sha256 === action.sourceHashes?.[ref])
@@ -536,8 +536,8 @@ function sourceCompletion(run, homes, options, afterStage) {
             && !options.deferredSources?.some(item => (0, completion_state_2.sourcePathKey)(source.path) === (0, completion_state_2.sourcePathKey)(item.path)))))
         throw new Error('completion-sources-conflict');
     const date = new Date().toISOString().slice(0, 10);
-    const validateInput = (body, source, root, contentRoot, owner, archivePath) => {
-        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, archivePath ?? source.path, root, contentRoot);
+    const validateInput = (body, source, root, contentRoot, owner, configuredPaths, archivePath) => {
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, archivePath ?? source.path, root, contentRoot, configuredPaths);
         if (parsed.status !== 'valid' || parsed.record.kind !== source.kind
             || !(0, completion_state_1.sourceAuthorAllowed)(state, parsed.record.author, owner)
             || parsed.record.state !== (archivePath ? 'archived' : 'pending')
@@ -551,13 +551,13 @@ function sourceCompletion(run, homes, options, afterStage) {
                 throw new Error(`completion-sources-conflict: ${source.path}: original plan changed`);
             return recorded;
         }
-        const { root, destination, contentRoot, owner, layout } = allowed(source);
+        const { root, destination, contentRoot, owner, layout, locations } = allowed(source);
         regular(source.path, root);
         regular(destination, root);
         const body = node_fs_1.default.readFileSync(source.path, 'utf8');
         if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
             throw new Error('analyzed-source-changed');
-        validateInput(body, source, root, contentRoot, owner);
+        validateInput(body, source, root, contentRoot, owner, locations);
         return { ...source, destination, resultHash: (0, proposal_queue_1.hashContent)(stamp(body, date)), synthesizedAt: date, layout };
     });
     const reservationsAndPlans = [...(prior ?? []), ...plans.filter(source => !prior?.some(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path)))];
@@ -637,7 +637,7 @@ function sourceCompletion(run, homes, options, afterStage) {
                 throw new Error('source-participants-conflict');
             persistRejections(false);
             for (const source of plans) {
-                const { root, destination, contentRoot, owner, layout } = allowed(source);
+                const { root, destination, contentRoot, owner, layout, locations } = allowed(source);
                 regular(source.path, root);
                 regular(destination, root);
                 if ((0, completion_state_2.sourcePathKey)(destination) !== (0, completion_state_2.sourcePathKey)(source.destination) || (source.layout && Object.keys(layout).some(key => typeof source.layout[key] !== 'string' || (0, completion_state_2.sourcePathKey)(layout[key]) !== (0, completion_state_2.sourcePathKey)(source.layout[key]))))
@@ -646,7 +646,7 @@ function sourceCompletion(run, homes, options, afterStage) {
                 if (body !== undefined) {
                     if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
                         throw new Error('analyzed-source-changed');
-                    validateInput(body, source, root, contentRoot, owner);
+                    validateInput(body, source, root, contentRoot, owner, locations);
                 }
                 if (!node_fs_1.default.existsSync(destination)) {
                     if (body === undefined)
@@ -668,12 +668,12 @@ function sourceCompletion(run, homes, options, afterStage) {
                 const archivedBody = node_fs_1.default.readFileSync(destination, 'utf8');
                 if ((0, proposal_queue_1.hashContent)(archivedBody) !== source.resultHash)
                     throw new Error('source-archive-conflict');
-                validateInput(archivedBody, source, root, contentRoot, owner, destination);
+                validateInput(archivedBody, source, root, contentRoot, owner, locations, destination);
                 afterStage?.('source-verified');
                 if (body !== undefined) {
                     const currentRunHome = options.resolveHome(run.owner);
                     (0, owner_identity_1.assertSameOwner)(run.owner, currentRunHome.owner);
-                    const currentRunPaths = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(currentRunHome), currentRunHome.contentRoot);
+                    const currentRunPaths = (0, pack_home_1.resolvePackArtifactPaths)(currentRunHome);
                     if ((0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(currentRunHome)) !== (0, completion_state_2.sourcePathKey)((0, owner_identity_1.ownerArtifactRoot)(runHome))
                         || (0, completion_state_2.sourcePathKey)(currentRunHome.contentRoot) !== (0, completion_state_2.sourcePathKey)(runHome.contentRoot)
                         || (0, completion_state_2.sourcePathKey)(node_path_1.default.join(currentRunPaths.evidence, 'sleep')) !== (0, completion_state_2.sourcePathKey)(run.completionDirectory)
@@ -736,7 +736,7 @@ function completeRun(run, summary, homes, options, afterStage) {
                 sources.push(source);
         }
         const sourceHome = (file) => homes.find(home => {
-            const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+            const locations = (0, pack_home_1.resolvePackArtifactPaths)(home);
             return [locations.raw, locations.retrospectives].some(directory => (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(file)) === (0, completion_state_2.sourcePathKey)(directory));
         });
         for (const action of actions)
@@ -774,7 +774,7 @@ function completeRun(run, summary, homes, options, afterStage) {
                     const recorded = state.processedSources?.find(item => (0, completion_state_2.sourcePathKey)(item.path) === (0, completion_state_2.sourcePathKey)(source.path));
                     if (recorded && (recorded.sha256 !== source.sha256 || recorded.kind !== source.kind))
                         throw new Error('original-source-plan-changed');
-                    const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+                    const locations = (0, pack_home_1.resolvePackArtifactPaths)(home);
                     const destination = (0, owner_identity_1.configuredArtifactPath)(home, node_path_1.default.join(source.kind === 'raw' ? locations.archiveRaw : locations.archiveRetrospectives, node_path_1.default.basename(source.path)));
                     if (reserved.includes((0, completion_state_2.sourcePathKey)(source.path)) || reserved.includes((0, completion_state_2.sourcePathKey)(destination)))
                         throw new Error('source-reserved-by-pending-run');
@@ -787,7 +787,7 @@ function completeRun(run, summary, homes, options, afterStage) {
                     const body = node_fs_1.default.readFileSync(source.path, 'utf8');
                     if ((0, proposal_queue_1.hashContent)(body) !== source.sha256)
                         throw new Error('analyzed-source-changed');
-                    const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.path, (0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot);
+                    const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, source.path, (0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot, locations);
                     if (parsed.status !== 'valid' || parsed.record.kind !== source.kind || !(0, completion_state_1.sourceAuthorAllowed)(state, parsed.record.author, home.owner) || parsed.record.state !== 'pending' || parsed.record.synthesized)
                         throw new Error('invalid-learning-source');
                     // References may use immutable identity, content-relative or home-relative path, or
@@ -835,7 +835,7 @@ function completeRun(run, summary, homes, options, afterStage) {
     const retrospective = options.retrospective;
     const retrospectiveHome = options.resolveHome(run.owner);
     (0, owner_identity_1.assertSameOwner)(run.owner, retrospectiveHome.owner);
-    const locations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+    const locations = (0, pack_home_1.resolvePackArtifactPaths)(retrospectiveHome);
     const retrospectiveDirectory = node_path_1.default.relative((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), locations.retrospectives).replace(/\\/g, '/');
     const legacyDirectory = node_path_1.default.relative(retrospectiveHome.contentRoot, locations.retrospectives).replace(/\\/g, '/');
     const expectedPaths = [retrospectiveDirectory, legacyDirectory].filter(directory => directory.split('/').every(part => part && part !== '.' && part !== '..'))
@@ -852,7 +852,7 @@ function completeRun(run, summary, homes, options, afterStage) {
     const verifyRetrospective = () => {
         // Meaning, attribution and template fidelity are reviewed by the agent.
         // This guard binds the actual document, including on interruption retries.
-        const currentLocations = (0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+        const currentLocations = (0, pack_home_1.resolvePackArtifactPaths)(retrospectiveHome);
         if ((0, completion_state_2.sourcePathKey)(node_path_1.default.join(currentLocations.evidence, 'sleep')) !== (0, completion_state_2.sourcePathKey)(run.completionDirectory)
             || (0, completion_state_2.sourcePathKey)(currentLocations.retrospectives) !== (0, completion_state_2.sourcePathKey)(node_path_1.default.dirname(retrospectiveFile)))
             throw new Error('completion-artifact-paths-changed');
@@ -862,7 +862,7 @@ function completeRun(run, summary, homes, options, afterStage) {
         const body = node_fs_1.default.readFileSync(retrospectiveFile, 'utf8');
         if (!body.trim() || (0, proposal_queue_1.hashContent)(body) !== retrospective.sha256)
             throw new Error('completion-retrospective-changed');
-        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, retrospectiveFile, (0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot);
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, retrospectiveFile, (0, owner_identity_1.ownerArtifactRoot)(retrospectiveHome), retrospectiveHome.contentRoot, currentLocations);
         if (parsed.status !== 'valid' || parsed.record.kind !== 'retrospective' || parsed.record.author !== run.reviewer || parsed.record.runId !== run.runId || parsed.record.synthesized)
             throw new Error('completion-retrospective-invalid');
     };

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

@@ -326,6 +326,7 @@ exports.syncCommand = new commander_1.Command('sync')
     .option('--skip-updates', 'Skip checking for CLI updates (legacy)')
     .option('--local', 'Sync from local development server (port derived from git branch)')
     .option('--global', 'Sync machine-level FRAIM content only (~/.fraim/), skip project maintenance')
+    .option('--automatic', 'Refresh catalogs without changing the selected MCP launcher version')
     .option('--project-root <path>', 'Explicit project root for configuration and local exclusion maintenance')
     .option('--project-adapters', 'Deprecated compatibility option (no effect; use machine-level FRAIM setup)')
     .action(exports.runSync);

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

@@ -1,22 +1,13 @@
 "use strict";
-/**
- * Agent CLI PATH/version health checks for FRAIM doctor command
- * Issue #1284/#1285: detect drift between FRAIM's own managed-PATH resolution,
- * the ambient shell PATH, and the actual npm-global install for agent CLIs
- * FRAIM installs through its managed-Node fallback.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 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 agent_command_probe_1 = require("../../utils/agent-command-probe");
 const command_resolution_1 = require("../../mcp/command-resolution");
+const operation_scope_1 = require("../../utils/operation-scope");
+const redact_paths_1 = require("../redact-paths");
+const command_resolution_2 = require("../../mcp/command-resolution");
 // CLIs with a managed-install fallback (npm install -g into FRAIM's portable
 // Node when no system install is found). Add gemini/copilot here when their
 // installManagedAgent wiring lands.
@@ -24,50 +15,6 @@ const MANAGED_CLIS = [
     { id: 'codex', label: 'Codex', command: 'codex' },
     { id: 'claude-code', label: 'Claude Code', command: 'claude' },
 ];
-// Windows cannot CreateProcess a `.cmd`/`.bat` file directly (spawnSync on a
-// resolved absolute `.cmd` path throws EINVAL) — it must go through cmd.exe,
-// matching the same wrapping `hosts.ts`'s `resolveHostInvocation()` and
-// `server.ts`'s `hubCommandVersion()` already use. Duplicated here (not
-// imported from `hosts.ts`) because `src/cli` is a pure layer that cannot
-// import the server-layer `src/ai-hub` module (`scripts/validate-purity.ts`).
-function quoteWindowsArg(value) {
-    if (value.length === 0)
-        return '""';
-    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
-}
-function escapeWindowsArg(value) {
-    return /[\s"]/u.test(value) ? quoteWindowsArg(value) : value;
-}
-function probeVersion(commandPath) {
-    try {
-        const executable = process.platform === 'win32' ? 'cmd.exe' : commandPath;
-        const args = process.platform === 'win32'
-            ? ['/d', '/s', '/c', `${escapeWindowsArg(commandPath)} --version`]
-            : ['--version'];
-        const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000, windowsHide: true });
-        if (result.status !== 0 || result.error)
-            return null;
-        // Issue #1256 (AC-D1/D2): only stdout counts as a version — see versionFromProbeOutput.
-        return (0, managed_agent_paths_1.versionFromProbeOutput)(result.stdout, result.stderr);
-    }
-    catch {
-        return null;
-    }
-}
-// The persisted Windows User PATH (what a brand-new terminal reads) can
-// disagree with this process's own inherited `process.env.PATH` (what a
-// shell already open before the fix landed still uses) — issue #1285's
-// exact "update said success but --version looked wrong" ambiguity.
-// Windows-only; there is no equivalent persisted-PATH registry on macOS/Linux.
-// Issue #1748: this used to shell out to PowerShell for HKCU Environment Path on its own,
-// a second independently-written Windows registry PATH reader. Two implementations of the
-// same read drift apart, and a parsing fix applied to one is easy to miss on the other,
-// which is the same PATH-resolution-drift bug class this check exists to report. Delegates
-// to the shared reader instead, which also covers HKLM rather than only the user hive and
-// expands REG_EXPAND_SZ references.
-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
@@ -75,132 +22,36 @@ function readPersistedUserPath() {
 // 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 runAgentCliHealthCheck(cli, options = {}) {
+    return (0, operation_scope_1.withOperation)(options, 30000, async (signal) => (0, redact_paths_1.redactCheckResultPaths)(await computeAgentCliHealth(cli, signal)));
 }
-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
-    // until restarted" applies to the process running this check too, not
-    // only the user's terminal). "Managed" strips any stale managed directory
-    // already sitting on that ambient PATH and re-appends FRAIM's current,
-    // correctly-ordered managed dirs — so it always reflects the current
-    // versioned build, independent of whatever the ambient PATH happens to
-    // still contain. Deliberately NOT `resolveManagedCommand()`: that helper
-    // is system-PATH-first for launch purposes and would silently agree with
-    // a stale ambient entry instead of surfacing the drift this check exists
-    // to catch.
-    // Issue #1748: process.env.PATH no longer carries FRAIM's managed bin dirs (the
-    // module-load mutation that put them there was the defect). Without a fallback,
-    // `ambientPath` is null whenever the only install is FRAIM-managed, and both clauses
-    // of `versionMismatch` below short-circuit on it, so this check would return
-    // "consistent" while the #1285 stale-shim drift it exists to catch went unreported.
-    // The machine PATH is what a newly opened shell resolves, which is the notion of
-    // "ambient" this check actually wants once the process is no longer self-mutating.
-    const machinePathForAmbient = (0, machine_path_1.resolveMachinePathCached)();
-    const ambientPath = (0, command_resolution_1.getSystemCommandPath)(cli.command)
-        || (machinePathForAmbient ? (0, command_resolution_1.getSystemCommandPath)(cli.command, machinePathForAmbient) : null);
-    const managedSearchPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
-    const managedPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, managedSearchPath);
-    if (!ambientPath && !managedPath) {
-        // Issue #1256 (AC-A3): before concluding the CLI is absent, try the same shared
-        // location-agnostic recovery the Hub's version probe and check-agent route use. This
-        // only changes the answer for a CLI this process's raw/managed PATH cannot see at all
-        // (e.g. doctor itself invoked from a PATH-truncated context) — it never overrides a
-        // drift verdict computed from a real ambient/managed hit above.
-        const recoveredSearchPath = (0, managed_agent_paths_1.buildRecoveredAgentPath)(process.env.PATH);
-        const recoveredPath = (0, command_resolution_1.getSystemCommandPath)(cli.command, recoveredSearchPath);
-        if (!recoveredPath) {
-            return {
-                status: 'passed',
-                message: `${cli.label} is not installed; nothing to check.`,
-            };
-        }
-        const recoveredVersion = probeVersion(recoveredPath);
-        if (!recoveredVersion) {
-            return {
-                status: 'error',
-                // 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 },
-            };
+async function computeAgentCliHealth(cli, signal) {
+    const env = await (0, agent_command_probe_1.agentProbeEnvironmentAsync)(undefined, process.env, { signal });
+    const failures = [];
+    const selected = await (0, agent_command_probe_1.selectAgentCommand)(cli.command, { env, signal, onFailure: reason => failures.push(reason) });
+    const ambientPath = (0, command_resolution_2.getSystemCommandPath)(cli.command);
+    const candidate = (0, command_resolution_1.getPortableManagedCommandPath)(cli.command);
+    const managedPath = candidate && (0, managed_agent_paths_1.isOwnedManagedAgentTarget)(candidate) ? candidate : null;
+    let repairable = false;
+    const managed = managedPath ? await (0, agent_command_probe_1.selectAgentCommand)(managedPath, { env, signal, onFailure: reason => { repairable = reason === 'exit'; } }) : null;
+    const ambient = ambientPath ? await (0, agent_command_probe_1.selectAgentCommand)(ambientPath, { env: { ...process.env }, signal }) : null;
+    const details = { repairable, launchFailure: selected ? undefined : failures.at(-1), ambientPath, ambientVersion: ambient?.version ?? null,
+        managedPath, managedVersion: managed?.version ?? null,
+        recoveredPath: selected?.target ?? (0, command_resolution_2.getSystemCommandPath)(cli.command, env.PATH), recoveredVersion: selected?.version ?? null };
+    if (!selected) {
+        if (!failures.length && !ambientPath && !managedPath && !(0, command_resolution_2.getSystemCommandPath)(cli.command, env.PATH)) {
+            return { status: 'passed', message: cli.label + ' is not installed; nothing to check.', details };
         }
-        return {
-            status: 'passed',
-            message: `${cli.label} is consistent (${recoveredVersion}).`,
-            details: { recoveredPath, recoveredVersion },
-        };
+        const explanation = (0, agent_command_probe_1.agentProbeFailureMessage)(failures.at(-1));
+        const boundary = explanation.indexOf('. ');
+        return { status: failures.at(-1) === 'timeout' || failures.at(-1) === 'cancelled' ? 'warning' : 'error',
+            message: cli.label + ': ' + explanation.slice(0, boundary + 1), suggestion: explanation.slice(boundary + 2), details };
     }
-    const ambientVersion = ambientPath ? probeVersion(ambientPath) : null;
-    const managedVersion = !managedPath
-        ? null
-        : managedPath === ambientPath
-            ? ambientVersion
-            : probeVersion(managedPath);
-    // Issue #1412: a resolved file that fails to execute at all (e.g. an
-    // interrupted update left a non-executable fallback launcher) is a harder
-    // failure than drift — `getSystemCommandPath()` only proves the file
-    // exists, not that it can run. Without this check, a single broken install
-    // with nothing else on PATH to disagree with (ambientPath === managedPath,
-    // both versions null) falls straight through the mismatch check below and
-    // reads as "consistent". Check this before computing npm-global/drift
-    // details that don't matter once the CLI can't run at all.
-    const brokenPath = ambientPath && !ambientVersion
-        ? ambientPath
-        : managedPath && !managedVersion
-            ? managedPath
-            : null;
-    if (brokenPath) {
-        return {
-            status: 'error',
-            // 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 },
-        };
+    if (ambientPath && (ambientPath !== selected.target || !ambient)) {
+        return { status: 'warning', message: cli.label + ' works in Hub (' + selected.version + '), but the current terminal resolves a different or broken launcher (' + (ambient?.version || 'unavailable') + ').',
+            suggestion: 'Open a new terminal and check the agent version.', details };
     }
-    const npmGlobalBinDirs = (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)();
-    const npmGlobalPath = npmGlobalBinDirs.length > 0
-        ? (0, command_resolution_1.getSystemCommandPath)(cli.command, npmGlobalBinDirs.join(path_1.default.delimiter))
-        : null;
-    const npmGlobalVersion = npmGlobalPath ? probeVersion(npmGlobalPath) : null;
-    // Drift means either: the ambient shell resolves a different version than
-    // the actual npm-global install, or this process's own ambient PATH
-    // resolves a *different file* than FRAIM's freshly-recomputed managed-dir
-    // resolution would — the exact "stale shim still shadows the current one"
-    // signature from #1285.
-    const versionMismatch = Boolean((ambientVersion && npmGlobalVersion && ambientVersion !== npmGlobalVersion)
-        || (ambientPath && managedPath && ambientPath !== managedPath));
-    if (!versionMismatch) {
-        return {
-            status: 'passed',
-            message: `${cli.label} is consistent (${ambientVersion || managedVersion || 'unknown version'}).`,
-            details: { ambientPath, managedPath, npmGlobalPath },
-        };
-    }
-    const persistedUserPath = readPersistedUserPath();
-    const persistedResolved = persistedUserPath ? (0, command_resolution_1.getSystemCommandPath)(cli.command, persistedUserPath) : null;
-    const persistedVersion = persistedResolved ? probeVersion(persistedResolved) : null;
-    const persistedMatchesManaged = Boolean(persistedResolved && managedPath && persistedResolved === managedPath);
-    const suggestion = persistedUserPath === null
-        ? `Restart your terminal, then run "${cli.command} --version" again to confirm.`
-        : persistedMatchesManaged
-            ? `Your saved PATH is already correct — open a new terminal window so it takes effect, then run "${cli.command} --version" again.`
-            : `Your saved PATH still resolves the old ${cli.label} build. Run "${cli.command} update" (or reinstall ${cli.label}), then open a new terminal.`;
-    return {
-        status: 'warning',
-        message: `${cli.label} PATH drift detected: ambient ${ambientVersion || 'not found'} vs managed ${managedVersion || 'not found'} vs npm-global ${npmGlobalVersion || 'not found'}.`,
-        suggestion,
-        details: {
-            ambientPath, ambientVersion,
-            managedPath, managedVersion,
-            npmGlobalPath, npmGlobalVersion,
-            persistedUserPathResolvedTo: persistedResolved,
-            persistedUserPathVersion: persistedVersion,
-        },
-    };
+    return { status: 'passed', message: cli.label + ' is consistent (' + selected.version + ').', details };
 }
 function agentCliHealthCheck(cli) {
     return {
@@ -217,12 +68,12 @@ function getAgentCliHealthChecks() {
 // manager who clicks "Check if Ready" right after `codex update` sees PATH
 // drift immediately instead of a bare pass/fail. Returns null for a CLI this
 // module does not track.
-async function checkAgentCliHealthByCommand(command) {
+async function checkAgentCliHealthByCommand(command, options = {}) {
     const cli = MANAGED_CLIS.find((entry) => entry.command === command);
     if (!cli)
         return null;
     try {
-        return await runAgentCliHealthCheck(cli);
+        return await runAgentCliHealthCheck(cli, options);
     }
     catch {
         return null;

package/dist/src/cli/learning/inventory.js

@@ -15,6 +15,7 @@ const user_config_1 = require("../utils/user-config");
 const run_record_1 = require("../../../registry/scripts/learning/run-record");
 const completion_state_1 = require("../../../registry/scripts/learning/completion-state");
 const artifact_paths_1 = require("../../../registry/scripts/artifact-paths");
+const pack_home_2 = require("../utils/pack-home");
 const local_runtime_1 = require("../../../registry/scripts/learning-usage/local-runtime");
 const learning_source_record_1 = require("../../../registry/scripts/learning-usage/learning-source-record");
 const corpus_audit_1 = require("../../../registry/scripts/learning/corpus-audit");
@@ -76,7 +77,7 @@ function discoverLearningSources(projectPath, owner, orgRunId) {
             reservationHomes.push(record);
         if (record.status !== 'unavailable') {
             try {
-                record.artifactPaths = (0, artifact_paths_1.resolveArtifactPaths)(record.root, record.contentRoot);
+                record.artifactPaths = (0, pack_home_2.resolvePackArtifactPaths)(record);
             }
             catch (error) {
                 record.status = 'unavailable';

package/dist/src/cli/learning/queue-operations.js

@@ -13,6 +13,7 @@ const node_crypto_1 = require("node:crypto");
 const runtime_1 = require("./runtime");
 const completion_state_1 = require("../../../registry/scripts/learning/completion-state");
 const artifact_paths_1 = require("../../../registry/scripts/artifact-paths");
+const pack_home_1 = require("../utils/pack-home");
 const entry_authoring_1 = require("../../../registry/scripts/learning/entry-authoring");
 const owner_identity_1 = require("../../../registry/scripts/learning/owner-identity");
 const run_record_1 = require("../../../registry/scripts/learning/run-record");
@@ -21,14 +22,14 @@ const run_publication_1 = require("../../../registry/scripts/learning/run-public
 const corpus_audit_1 = require("../../../registry/scripts/learning/corpus-audit");
 const outcome_assessment_1 = require("../../../registry/scripts/learning/outcome-assessment");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
-const pack_home_1 = require("../utils/pack-home");
+const pack_home_2 = require("../utils/pack-home");
 const user_config_1 = require("../utils/user-config");
 const local_registry_resolver_1 = require("../../core/utils/local-registry-resolver");
 function resolveQueueHome(projectPath, level) {
     return (0, owner_identity_1.resolveOwnerHome)(projectPath, level, { runtimeModule: runtime_1.runtimeModuleStatic });
 }
 function resolveReaderCorpusRoots(projectPath) {
-    const manager = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
+    const manager = (0, pack_home_2.resolvePackHome)('manager', { migrateLegacy: false });
     const portable = (0, project_fraim_paths_1.getConfiguredPortableLearningsDir)(projectPath);
     const same = (left, right) => node_path_1.default.resolve(left) === node_path_1.default.resolve(right);
     const roots = manager.synced ? [] : [node_path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', 'learnings')];
@@ -37,7 +38,7 @@ function resolveReaderCorpusRoots(projectPath) {
     return [...new Set(roots)];
 }
 function evidenceDirectory(home) {
-    const directory = node_path_1.default.join((0, artifact_paths_1.resolveArtifactPaths)((0, owner_identity_1.ownerArtifactRoot)(home), home.contentRoot).evidence, 'sleep');
+    const directory = node_path_1.default.join((0, pack_home_1.resolvePackArtifactPaths)(home).evidence, 'sleep');
     (0, owner_identity_1.configuredArtifactPath)(home, directory);
     return directory;
 }
@@ -115,8 +116,8 @@ async function runQueueCommand(argv) {
         if (input.kind === 'learning' && input.operation !== 'remove') {
             if (!input.target.entryId)
                 input.target.entryId = 'L-' + (0, node_crypto_1.randomUUID)().replace(/-/g, '').slice(0, 10);
-            const managerHome = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
-            const orgHome = (0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false });
+            const managerHome = (0, pack_home_2.resolvePackHome)('manager', { migrateLegacy: false });
+            const orgHome = (0, pack_home_2.resolvePackHome)('org', { migrateLegacy: false });
             const resolver = new local_registry_resolver_1.LocalRegistryResolver({ workspaceRoot: projectPath, managerLocalRoot: managerHome.contentRoot, managerCacheRoot: managerHome.contentRoot, orgCacheRoot: orgHome.contentRoot, remoteContentResolver: async () => { throw new Error('job-definition-unavailable'); } });
             if (input.content?.domain?.basis !== 'manager') {
                 for (const origin of input.content.trace.originatingJobs) {

package/dist/src/cli/mcp/command-resolution.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveManagedCommand = exports.getPortableManagedCommandPath = exports.getSystemCommandPath = void 0;
+exports.resolveManagedCommand = exports.getPortableManagedCommandPath = exports.getSystemCommandPath = exports.getSystemCommandCandidates = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const managed_agent_paths_1 = require("../utils/managed-agent-paths");
@@ -20,25 +20,30 @@ const getPathEntries = (basePath) => {
         .map((entry) => entry.trim())
         .filter(Boolean);
 };
-const getSystemCommandCandidates = (command, basePath) => {
+const getSystemCommandCandidates = (command, basePath, pathExt = process.env.PATHEXT) => {
     if (!command || path_1.default.isAbsolute(command)) {
         return command ? [command] : [];
     }
     const commandNames = process.platform === 'win32'
         ? command.includes('.')
             ? [command]
-            : [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`, `${command}.com`]
+            : (pathExt || '.COM;.EXE;.BAT;.CMD').split(';')
+                .filter(ext => /^\.(com|exe|bat|cmd)$/i.test(ext)).map(ext => command + ext.toLowerCase())
         : [command];
     return getPathEntries(basePath).flatMap((entry) => commandNames.map((name) => path_1.default.join(entry, name)));
 };
+exports.getSystemCommandCandidates = getSystemCommandCandidates;
 // `basePath` defaults to the current process PATH; pass an explicit PATH
 // string to resolve a command against a different candidate list (e.g. the
 // npm-global bin dirs computed by `resolveNpmGlobalBinDirs`) without mutating
 // `process.env.PATH`.
 const getSystemCommandPath = (command, basePath) => {
-    for (const candidate of getSystemCommandCandidates(command, basePath)) {
+    for (const candidate of (0, exports.getSystemCommandCandidates)(command, basePath)) {
         try {
             const stats = fs_1.default.statSync(candidate);
+            fs_1.default.accessSync(candidate, process.platform === 'win32' ? fs_1.default.constants.R_OK : fs_1.default.constants.X_OK);
+            if (process.platform === 'win32')
+                fs_1.default.closeSync(fs_1.default.openSync(candidate, 'r'));
             if (stats.isFile()) {
                 return candidate;
             }