@aiwg/cli 2026.10.9 → 2026.10.11

package/dist/src/cli/handlers/models.js

@@ -1,3 +1,8 @@
+import { MODELS_HELP } from './models-help.js';
+import { updateJson } from '../../models/config-writer.js';
+import { atomicConfigWrite as atomicWrite } from '../../config/worker-write.js';
+import { handleWorkerAdoptionArgs } from '../../config/worker-adoption-cli.js';
+import { resolveParallelism } from '../../config/aiwg-config.js';
 /**
  * Safe model-policy audit, resolution, and mutation commands.
  * @implements #1804
@@ -8,7 +13,7 @@ import { isDeepStrictEqual } from 'node:util';
 import path from 'node:path';
 import { glob } from 'glob';
 import { load as loadYaml } from 'js-yaml';
-import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, assertWorkerRoleEffort, } from '../../models/provider-policy.js';
+import { compileModelPolicy, validateCanonicalModelPolicy, loadProviderModelCapabilities, WorkerPolicyError, assertWorkerRoleEffort, } from '../../models/provider-policy.js';
 import { resolveGrokBuildRoleModel } from '../../models/grok-build-models.js';
 import { readAiwgConfig, emptyConfig } from '../../config/aiwg-config.js';
 import { ConfigLoader } from '../../models/config-loader.js';
@@ -34,22 +39,21 @@ export async function loadWorkerInputs(ctx) {
     const models = await loader.load(config.parallelism);
     const catalog = await effectiveCatalog(ctx, ctx.cwd, false, parseArgs(['resolve']));
     const registry = loadProviderModelCapabilities();
-    // Let the resolver explain the dispatch gate before requiring host qualification (#3070).
     if (!config.parallelism?.worker_dispatch) {
         return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
                 registry, installations: {} }, drivers: {} };
     }
     // Explain missing policy before a recorded approval's digest check can
     // mask it. The host owner first preserves its missing-installation errors.
-    const parallelism = config.parallelism;
+    const parallelism = resolveParallelism(config.parallelism, config.providers[0]);
     const precheckPolicy = () => {
         if (!ctx.args.some(arg => arg === '--role' || arg.startsWith('--role=')))
             return;
         const request = parseWorkerCommandArgs(ctx.args.slice(1));
         const members = Object.entries(parallelism.groups ?? {})
             .filter(([id]) => !request.group || request.group === id)
-            .flatMap(([, group]) => group.members).filter(member => member.enabled !== false
-            && parallelism.clis?.[member.cli]?.enabled !== false && member.roles.includes(request.role));
+            .flatMap(([, group]) => group.members ?? []).filter(member => member.enabled !== false
+            && parallelism.clis?.[member.cli]?.enabled !== false && member.roles.includes((models.defaults.workerSelection?.roleGuidance?.[request.role]?.baseRole ?? request.role)));
         const requiresExplicit = members.length > 0 && members.every(member => {
             // Health metadata can identify the provider before an operator has
             // qualified its dispatch adapter. It grants no dispatch authority.
@@ -269,35 +273,6 @@ function print(value, json) {
     else
         console.log(JSON.stringify(value, null, 2));
 }
-async function atomicWrite(file, content) {
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    const temporary = `${file}.tmp-${process.pid}`;
-    let mode = 0o600;
-    try {
-        mode = (await fs.stat(file)).mode;
-    }
-    catch { /* new file */ }
-    await fs.writeFile(temporary, content, { encoding: 'utf8', mode });
-    await fs.rename(temporary, file);
-}
-async function updateJson(file, mutate, dryRun) {
-    let value = {};
-    try {
-        value = JSON.parse(await fs.readFile(file, 'utf8'));
-    }
-    catch (error) {
-        if (error?.code !== 'ENOENT')
-            throw error;
-    }
-    mutate(value);
-    const validation = validateUserProjectModelConfig(value);
-    if (!validation.valid)
-        throw new Error(validation.diagnostics.map(item => item.message).join('; '));
-    const content = `${JSON.stringify(value, null, 2)}\n`;
-    if (!dryRun)
-        await atomicWrite(file, content);
-    return { file, beforeWrite: value, dryRun };
-}
 async function effectiveCatalog(ctx, target, allowNetwork, parsed, provider) {
     const { collectProviderInventory } = await import('../../providers/provider-inventory.js');
     const { resolveDynamicModelCatalog } = await import('../../models/model-discovery.js');
@@ -350,53 +325,6 @@ function replaceFrontmatter(raw, item, tier) {
     }
     return `---\n${frontmatter}\n---\n${match[2]}`;
 }
-const MODELS_HELP = `Usage: aiwg models <subcommand> [options]
-
-Subcommands:
-  list                         List discovered agent and skill model policies
-  audit                        Compile selected policies and report diagnostics
-  resolve                      Resolve artifact policies, or a direct worker invocation
-  validate                     Validate selected artifact policies (not worker configuration)
-  sources                      Show the effective model catalog without network refresh
-  refresh                      Refresh model discovery (may access the network)
-  set-default <TIER>           Write defaults.tier to models.json
-  set --tier <TIER>            Update selected agent/skill frontmatter; requires a selector or --all
-  migrate                      Add canonical role/tier hints to legacy skills
-
-Artifact selectors and options:
-  --agent <name>  --skill <name>  --glob <pattern>  --role <role>
-  --tier <tier>  --framework <name>  --all
-  --provider <provider>         Provider for artifact compilation (default: claude)
-  --model <id>                  Explicit Grok Build model for artifact resolve
-  --target <directory>         Artifact/project root (default: current directory)
-  --scope project|user         set-default destination (default: project)
-  --dry-run                    Preview mutations without writing
-  --json                       Emit JSON
-  --drift                      Include catalog drift for sources/refresh
-  --url <url>                  Remote catalog URL for refresh
-  --help, -h                   Show this reference
-  TIER: economy | standard | premium | max-quality
-
-Direct worker resolution (plans an invocation; does not launch it):
-  aiwg models resolve --role <role> --task <class> --group <group>
-    --brief <file> --workdir <tree> --final-output <file>
-    [--transport shell|mcp] [--format json|shell] [--authorize-premium]
-  --role                       efficiency | coding | reasoning
-  --task                       Task class from defaults.workerSelection.taskClasses
-                               Built-ins: inventory, implementation, architecture, review
-  --group                      Group from parallelism.groups and the role's guidance
-  --brief                      Absolute path to the task brief
-  --workdir                    Absolute path to the worker tree
-  --final-output               Absolute path for the final result
-  --transport                  Must match group execution transport (default: shell)
-  --format                     JSON plan or POSIX shell command (default: json)
-  --json                       Alias for --format json
-  --authorize-premium          Authorize premium for this resolution only
-                               Agents require explicit human confirmation of escalation
-
-Worker groups live in .aiwg/aiwg.config; role guidance lives in project-root models.json.
-Configure both, then run aiwg doctor --probe-workers --qualify.
-See docs/getting-started/worker-dispatch.md for a complete example.`;
 async function execute(ctx, services = { load: loadWorkerInputs }) {
     if (ctx.args.length === 0 || ctx.args[0] === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
         print(MODELS_HELP, false);
@@ -406,6 +334,8 @@ async function execute(ctx, services = { load: loadWorkerInputs }) {
     if (ctx.args[0] === 'resolve' && ctx.args.slice(1).some(arg => /^--(?:task|group|brief|workdir|final-output|transport|format|authorize-premium)(?:=|$)/.test(arg))) {
         return resolveDirect(ctx, services);
     }
+    if (await handleWorkerAdoptionArgs(ctx.args, ctx.cwd, 'models', ctx.signal, ctx.dryRun))
+        return { exitCode: 0 };
     const parsed = parseArgs(ctx.args);
     if (parsed.subcommand === 'resolve') {
         const supported = new Set(['agent', 'skill', 'glob', 'role', 'tier', 'framework', 'all', 'target', 'provider', 'model', 'json', 'help', 'dry-run']);

package/dist/src/cli/handlers/sessions.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { providerScopeWarnings } from '../../sessions/coverage-preflight.js';
-import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, GROKBOT_ADAPTER_VERSION, GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, GrokbotSessionAdapter, GROK_BUILD_ADAPTER_VERSION, GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS, GrokBuildSessionAdapter, grokBuildList, grokBuildSearch, grokBuildExport, grokHeadlessSessionIdFromFile, MUSE_ADAPTER_VERSION, MuseSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, createSessionAdapterRegistry, coveragePreflight, expectedSessionProviders, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, embedAttachmentsInFullV1Shard, recoverEmbeddedAttachments, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
+import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, GROKBOT_ADAPTER_VERSION, GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, GrokbotSessionAdapter, GROK_BUILD_ADAPTER_VERSION, GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS, GrokBuildSessionAdapter, grokBuildList, grokBuildSearch, grokBuildExport, grokHeadlessSessionIdFromFile, MUSE_ADAPTER_VERSION, MuseSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, countUniqueSessionsAcrossCatalogs, defaultDiscoveryManifestPath, defaultHostCatalogPath, HOST_CATALOG_WORKSPACE_ID, indexIdentitiesBySessionId, manifestNeedsHostCatalog, mergeCrossCatalogRows, mergeSessionLists, resolveHostReferences, summarizeSessionAnalyticsFacts, discoverWorkspaceHistories, createSessionAdapterRegistry, coveragePreflight, expectedSessionProviders, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, embedAttachmentsInFullV1Shard, recoverEmbeddedAttachments, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
 import { resolveImportExclusions } from '../../sessions/import-exclusions.js';
 import { resolveImportLimits } from '../../sessions/import-limits.js';
 import { classifyGrokbotBlobName } from '../../sessions/adapters/grokbot-locator.js';
@@ -227,18 +227,35 @@ async function executeCommand(ctx, args) {
                     limit,
                     cursor,
                 });
+                // Account-scoped sessions live once in the host catalog; the
+                // workspace holds references (#3232). Read through them on the
+                // opening page so the workspace lists its referenced sessions.
+                // Cursor pages continue the local snapshot. Totals dedupe legacy
+                // copied rows against references, counting each session once.
+                const hostView = cursor
+                    ? null
+                    : readHostReferencedSessions(repository, { provider, tag: args.values.get('--tag') });
+                const items = hostView && hostView.sessions.length > 0
+                    ? mergeSessionLists(result.items, hostView.sessions).slice(0, limit)
+                    : result.items;
+                const total = hostView && hostView.references.length > 0
+                    ? countUniqueSessionsAcrossCatalogs([{
+                            identities: repository.listSessionIdentities(workspaceId),
+                            references: hostView.resolvedReferences,
+                        }])
+                    : result.total;
                 const coverage = {
                     ...repository.getCoverage(workspaceId),
                     catalogScope: catalogScope(ctx, args, repository, workspaceId),
                 };
                 const response = {
-                    items: result.items,
+                    items,
                     page: {
                         limit,
                         cursor: cursor ?? null,
                         nextCursor: result.nextCursor,
                         snapshotRowid: result.snapshotRowid,
-                        total: result.total,
+                        total,
                     },
                     coverage,
                 };
@@ -314,10 +331,15 @@ async function executeCommand(ctx, args) {
                 const session = matches[0];
                 if (!session)
                     throw new CliError('SESSION_NOT_FOUND', `session not found: ${id}${scope.hint ? `; ${scope.hint}` : ''}`, EXIT.unavailable, { catalogScope: scope });
+                // Image references resolve against the blob store: available blobs
+                // report their reference, missing ones an explicit unavailable
+                // state. Bytes stay out of the response; fetch by digest (#3265).
+                const events = repository.listEvents(session.sessionId, session.workspaceId)
+                    .map((event) => ({ ...event, images: repository.resolveEventImages(event) }));
                 return ok(command, {
                     session,
                     tags: repository.listTags(session.sessionId, session.workspaceId),
-                    events: repository.listEvents(session.sessionId, session.workspaceId),
+                    events,
                     catalogScope: catalogScope(ctx, args, repository, session.workspaceId),
                 });
             }
@@ -326,7 +348,8 @@ async function executeCommand(ctx, args) {
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const providerInput = args.values.get('--provider');
                 const provider = providerInput ? assertSessionProviderId(providerInput) : undefined;
-                const result = repository.search({
+                const limit = boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit');
+                const searchOptions = {
                     query,
                     workspaceId,
                     providers: provider ? [provider] : undefined,
@@ -341,13 +364,24 @@ async function executeCommand(ctx, args) {
                     sensitivity: args.values.get('--sensitivity'),
                     extractionState: args.values.get('--extraction-state'),
                     controlEvents: controlEventMode(args.values.get('--control-events')),
-                    limit: boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit'),
+                    limit,
                     cursor: args.values.get('--cursor'),
-                });
+                };
+                const result = repository.search(searchOptions);
+                // Read through host references on the opening page so workspace
+                // search finds referenced account-scoped sessions. Each session
+                // counts once: host hits for sessions already present locally
+                // (legacy copied rows) are dropped by provider + native session.
+                const hostRead = searchOptions.cursor
+                    ? null
+                    : searchHostReferencedSessions(repository, searchOptions, provider);
+                const items = hostRead && hostRead.hits.length > 0
+                    ? mergeCrossCatalogRows(result.items, hostRead.hits, indexIdentitiesBySessionId(repository.listSessionIdentities(workspaceId)), indexIdentitiesBySessionId(hostRead.hostIdentities), (hit) => [hit.provider, hit.eventId].join(' ')).slice(0, limit)
+                    : result.items;
                 return ok(command, {
-                    items: result.items,
+                    items,
                     catalogScope: catalogScope(ctx, args, repository, workspaceId),
-                    page: { limit: boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit'),
+                    page: { limit,
                         nextCursor: result.nextCursor },
                 });
             }
@@ -355,14 +389,22 @@ async function executeCommand(ctx, args) {
                 const view = requiredPositional(args, 0, 'analytics view');
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const query = analyticsQuery(args, workspaceId);
+                // Host references resolve to facts stored under the host catalog;
+                // each session counts once by provider + native session id. Without
+                // references the single-catalog path below is unchanged.
+                const mergedFacts = readWorkspaceAnalyticsFacts(repository, query);
                 if (view === 'summary') {
                     return ok(command, {
                         view,
-                        summary: repository.analyticsSummary(query),
+                        summary: mergedFacts
+                            ? summarizeSessionAnalyticsFacts(mergedFacts, workspaceId)
+                            : repository.analyticsSummary(query),
                     });
                 }
                 const categories = analyticsCategories(view);
-                const items = repository.listAnalyticsFacts({ ...query, categories });
+                const items = mergedFacts
+                    ? mergedFacts.filter((fact) => categories.includes(fact.category))
+                    : repository.listAnalyticsFacts({ ...query, categories });
                 return ok(command, {
                     analyticsVersion: '1.0.0',
                     view,
@@ -1075,7 +1117,10 @@ async function exportBuild(ctx, args, repository, command) {
         ...output,
         bytesEmbedded: includeBytes && outputBytesByRegistrationId.has(output.registrationId),
     }));
-    const index = buildSessionAiwgFortemiIndexExport(plan.workspaceId, sessions, eventsBySessionId, outputs, catalogTagsBySessionId);
+    const index = buildSessionAiwgFortemiIndexExport(plan.workspaceId, sessions, eventsBySessionId, outputs, catalogTagsBySessionId, 
+    // Resolve image references against the live catalog: available blobs
+    // export as references, missing ones as explicit unavailable (#3265).
+    (event) => repository.resolveEventImages(event));
     // aiwgFortemiIndexToKnowledgeShardWithReport targets the declared
     // full-v1/2.0.0 archive contract and validates losslessness -- unlike the
     // plain aiwgFortemiIndexToKnowledgeShard (core-v1), which silently embeds
@@ -1355,18 +1400,33 @@ async function importDiscovered(ctx, args) {
             ...(carryPath ? { carryForward: redactSourceLocator(carryPath) } : {}),
         });
     }
-    const lease = await acquireImportLease(databasePath(ctx, args), sha256(['discovered-import', manifest.manifestId, manifest.workspaceId].join('\0')), {
-        waitMs: boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms'),
-    });
+    const waitMs = boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms');
+    const lease = await acquireImportLease(databasePath(ctx, args), sha256(['discovered-import', manifest.manifestId, manifest.workspaceId].join('\0')), { waitMs });
+    let hostLease;
     try {
         const previous = carryPath ? new SessionRepository(carryPath, { readonly: true }) : undefined;
         let repository;
+        let hostRepository;
         try {
             repository = openRepository(ctx, args);
+            // Account-scoped providers (Grok Bot) import once into the host
+            // catalog; the workspace catalog records a reference (#3232). The
+            // host catalog is only opened when the manifest actually holds an
+            // account-scoped source.
+            const hostCatalogPath = defaultHostCatalogPath();
+            if (manifestNeedsHostCatalog(manifest.sources)) {
+                mkdirSync(dirname(hostCatalogPath), { recursive: true, mode: 0o700 });
+                // The workspace lease does not cover the shared host catalog; serialize
+                // host writers the same way the hourly refresh does.
+                hostLease = await acquireImportLease(hostCatalogPath, `host-import-${process.pid}`, { waitMs });
+                hostRepository = new SessionRepository(hostCatalogPath);
+            }
             const interruptedRuns = repository.interruptRunningBatchImports();
             const receipt = await importDiscoveryManifest({
                 manifest,
                 repository,
+                hostRepository,
+                hostCatalogPath,
                 carryForward: previous,
                 limits,
                 exclude,
@@ -1388,10 +1448,12 @@ async function importDiscovered(ctx, args) {
         }
         finally {
             repository?.close();
+            hostRepository?.close();
             previous?.close();
         }
     }
     finally {
+        await hostLease?.release();
         await lease.release();
     }
 }
@@ -1718,6 +1780,127 @@ function catalogScope(ctx, args, repository, workspaceId) {
             : null,
     };
 }
+/**
+ * Host-catalog read-through for account-scoped sessions (#3232). The
+ * workspace catalog holds references instead of copies; each reference
+ * records its host catalog path. Every referenced catalog opens read-only
+ * and closes before returning. Unreadable catalogs contribute nothing, so
+ * local rows still list when the host catalog is missing.
+ */
+function eachReferencedHostCatalog(repository, provider, read) {
+    const references = repository.listHostSessionReferences()
+        .filter((reference) => !provider || reference.provider === provider);
+    if (references.length === 0)
+        return [];
+    const byCatalog = new Map();
+    for (const reference of references) {
+        const group = byCatalog.get(reference.hostCatalog);
+        if (group)
+            group.push(reference);
+        else
+            byCatalog.set(reference.hostCatalog, [reference]);
+    }
+    const reads = [];
+    for (const [catalogPath, group] of byCatalog) {
+        let host;
+        try {
+            host = new SessionRepository(catalogPath, { readonly: true });
+        }
+        catch {
+            continue;
+        }
+        try {
+            reads.push({ references: group, value: read(host, group) });
+        }
+        finally {
+            host.close();
+        }
+    }
+    return reads;
+}
+function readHostReferencedSessions(repository, filters) {
+    const reads = eachReferencedHostCatalog(repository, filters.provider, (host, group) => {
+        const page = host.listSessions({
+            provider: filters.provider,
+            workspaceId: HOST_CATALOG_WORKSPACE_ID,
+            limit: group.length,
+        });
+        const sessions = resolveHostReferences(group, page.items)
+            .filter((session) => !filters.tag || host.listTags(session.sessionId).includes(filters.tag));
+        const resolvedSourceIds = new Set(sessions.map((session) => session.sourceId));
+        return {
+            sessions,
+            resolvedReferences: group.filter((reference) => resolvedSourceIds.has(reference.sourceId)),
+        };
+    });
+    return {
+        references: reads.flatMap((read) => read.references),
+        resolvedReferences: reads.flatMap((read) => read.value.resolvedReferences),
+        sessions: reads.flatMap((read) => read.value.sessions),
+    };
+}
+function searchHostReferencedSessions(repository, searchOptions, provider) {
+    const reads = eachReferencedHostCatalog(repository, provider, (host) => {
+        const result = host.search({
+            ...searchOptions,
+            workspaceId: HOST_CATALOG_WORKSPACE_ID,
+            cursor: undefined,
+        });
+        return {
+            hits: result.items,
+            hostIdentities: host.listSessionIdentities(HOST_CATALOG_WORKSPACE_ID),
+        };
+    });
+    return {
+        hits: reads.flatMap((read) => read.value.hits),
+        hostIdentities: reads.flatMap((read) => read.value.hostIdentities),
+    };
+}
+function readHostReferencedAnalyticsFacts(repository, query) {
+    // query.sessionId is a workspace-local internal id; host rows carry host
+    // stable ids, so resolve it to a provider + native session key first.
+    let sessionKey = null;
+    if (query.sessionId) {
+        const session = repository.getSession(query.sessionId, query.workspaceId);
+        if (!session)
+            return { facts: [], hostIdentities: [] };
+        sessionKey = `${session.provider} ${session.nativeSessionId}`;
+    }
+    const reads = eachReferencedHostCatalog(repository, query.provider, (host, group) => {
+        const wanted = new Set(group.map((reference) => `${reference.provider} ${reference.nativeSessionId}`));
+        const identities = host.listSessionIdentities(HOST_CATALOG_WORKSPACE_ID);
+        const hostSessionIds = new Set(identities
+            .filter((identity) => wanted.has(`${identity.provider} ${identity.nativeSessionId}`))
+            .map((identity) => identity.sessionId));
+        const { sessionId: _localSessionId, ...hostQuery } = query;
+        const facts = host.listAnalyticsFacts({ ...hostQuery, workspaceId: HOST_CATALOG_WORKSPACE_ID })
+            .filter((fact) => hostSessionIds.has(fact.sessionId)
+            && (!sessionKey || `${fact.provider} ${hostSessionKey(fact.sessionId, identities)}` === sessionKey));
+        return { facts, identities };
+    });
+    return {
+        facts: reads.flatMap((read) => read.value.facts),
+        hostIdentities: reads.flatMap((read) => read.value.identities),
+    };
+}
+function hostSessionKey(sessionId, identities) {
+    return identities.find((identity) => identity.sessionId === sessionId)?.nativeSessionId ?? null;
+}
+/**
+ * Workspace analytics facts with host references resolved. Returns null
+ * when the workspace holds no references so callers keep the exact
+ * single-catalog query path (SQL limit/filter semantics unchanged).
+ */
+function readWorkspaceAnalyticsFacts(repository, query) {
+    const references = repository.listHostSessionReferences()
+        .filter((reference) => !query.provider || reference.provider === query.provider);
+    if (references.length === 0)
+        return null;
+    const hostRead = readHostReferencedAnalyticsFacts(repository, query);
+    if (hostRead.facts.length === 0)
+        return null;
+    return mergeCrossCatalogRows(repository.listAnalyticsFacts(query), hostRead.facts, indexIdentitiesBySessionId(repository.listSessionIdentities(query.workspaceId)), indexIdentitiesBySessionId(hostRead.hostIdentities), (fact) => `${fact.provider} ${fact.factId}`);
+}
 async function configuredImportLimits(ctx, args, workspace) {
     const selectedWorkspace = workspace ?? (args.values.has('--workspace')
         ? resolve(ctx.cwd, args.values.get('--workspace')) : ctx.cwd);

package/dist/src/cli/handlers/use-addon-profile.js

@@ -0,0 +1,72 @@
+// Select and persist an optional bundled addon memory profile.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as ui from '../ui.js';
+export async function selectAddonProfile(options) {
+    const { addonSource, framework, target, args, dryRunAddon, bulkIntent, signal } = options;
+    try {
+        const profileManifestPath = path.join(addonSource, 'manifest.json');
+        const profileManifestContent = await fs.readFile(profileManifestPath, 'utf-8');
+        const profileManifest = JSON.parse(profileManifestContent);
+        const topology = profileManifest.memory?.topology;
+        const templates = profileManifest.templates;
+        if (topology && templates && templates.length > 1) {
+            const profileIdx = args.findIndex(a => a === '--profile');
+            let selectedProfile;
+            if (profileIdx >= 0 && args[profileIdx + 1]) {
+                // Explicit --profile flag
+                selectedProfile = args[profileIdx + 1];
+                const templateFile = templates.find((t) => t.replace('.md', '') === selectedProfile || t === selectedProfile);
+                if (!templateFile) {
+                    ui.warn(`Unknown profile "${selectedProfile}". Available: ${templates.map((t) => t.replace('.md', '')).join(', ')}`);
+                    selectedProfile = undefined;
+                }
+            }
+            else if (bulkIntent || !process.stdin.isTTY) {
+                // Bulk/automation or non-TTY: silently pick 'generic' default.
+                // The profile picker is annoying during `aiwg use all`.
+                selectedProfile = 'generic';
+            }
+            else if (process.stdin.isTTY) {
+                // Interactive profile selection via the shared `listSelect` helper
+                // (POC for spike #926). One call renders the option list, handles
+                // number-or-name matching, threads `signal` for Ctrl-C
+                // cancellation, and resolves to the fallback on timeout or empty
+                // input. The hand-rolled parse-and-branch that used to live here
+                // is now a one-liner.
+                const { createPromptInterface, listSelect } = await import('../prompt-utils.js');
+                ui.blank();
+                ui.header('  Select a topology profile:');
+                const templateNames = templates.map((t) => t.replace('.md', ''));
+                const options = templateNames.map((name) => ({
+                    label: name === 'generic' ? `${name} (default)` : name,
+                    value: name,
+                }));
+                const rl = createPromptInterface();
+                try {
+                    selectedProfile = await listSelect(rl, '  Enter number or name [generic]: ', options, 'generic', signal);
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            // Write profile config to project namespace
+            if (selectedProfile && !dryRunAddon) {
+                const namespace = topology.namespace || `.aiwg/${framework}`;
+                const configDir = path.join(target, namespace);
+                await fs.mkdir(configDir, { recursive: true });
+                const profileConfig = {
+                    profile: selectedProfile,
+                    pageTemplate: `templates/${selectedProfile}.md`,
+                    selectedAt: new Date().toISOString(),
+                };
+                await fs.writeFile(path.join(configDir, 'config.json'), JSON.stringify(profileConfig, null, 2) + '\n');
+                ui.success(`Profile "${selectedProfile}" selected → ${namespace}/config.json`);
+            }
+        }
+    }
+    catch {
+        // Profile selection is optional — don't fail deployment
+    }
+}
+//# sourceMappingURL=use-addon-profile.js.map