nexus-prime 7.9.8 → 7.9.9

package/dist/agents/adapters/mcp/definitions.js

@@ -15,6 +15,7 @@ export const FIRST_CLASS_TOOLS = new Set([
     'nexus_search',
     'nexus_runtime_health',
     'nexus_run_status',
+    'nexus_user_workflow_trace',
     'kernel_run_step',
     'kernel_run_verify',
     'kernel_run_merge',
@@ -881,6 +882,18 @@ export function buildMcpToolDefinitions() {
                 required: ['runId'],
             },
         },
+        {
+            name: 'nexus_user_workflow_trace',
+            description: 'Return the local user-agent workflow trace for a run: user goal, agent actions, context, verification, failure signals, and next actions.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    runId: { type: 'string', description: 'Execution run ID' },
+                    format: { type: 'string', enum: ['text', 'json'], description: 'Response format' },
+                },
+                required: ['runId'],
+            },
+        },
         // ── Darwin Loop ──────────────────────────────────────────────────
         {
             name: 'nexus_darwin_propose',

package/dist/agents/adapters/mcp/handlers/orchestration.d.ts

@@ -10,5 +10,7 @@ type McpResult = {
         text: string;
     }>;
 };
+export declare function extractSkillSelectorsFromPrompt(prompt: string): string[];
+export declare function inferSpawnWorkersIntent(actions: unknown[]): 'plan' | 'mutate';
 export declare function handleOrchestrationGroup(toolName: string, hctx: McpHandlerCtx, request: any, args: Record<string, unknown>, ctx?: any): Promise<McpResult | undefined>;
 export {};

package/dist/agents/adapters/mcp/handlers/orchestration.js

@@ -20,6 +20,25 @@ import { getSharedTelemetry } from '../../../../engines/telemetry-remote.js';
 import { requireRuntime } from '../util/require-runtime.js';
 import { ensureCrGraphBuilt } from '../../../../engines/code-review-graph-client.js';
 import { recordFirstBootstrap } from '../../../../engines/telemetry.js';
+export function extractSkillSelectorsFromPrompt(prompt) {
+    const selectors = new Set();
+    const add = (value) => {
+        const cleaned = value?.trim().replace(/^[$@]+/, '');
+        if (cleaned && /^[a-z0-9][a-z0-9._-]{1,120}$/i.test(cleaned)) {
+            selectors.add(cleaned);
+        }
+    };
+    for (const match of prompt.matchAll(/\[[$@]?([a-z0-9][a-z0-9._-]{1,120})\]\([^)]*\/\.agents?\/skills\/[^)]*\/SKILL\.md\)/gi)) {
+        add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\/\.agents?\/skills\/([^/\s)]+)\/SKILL\.md/gi)) {
+        add(match[1]);
+    }
+    return [...selectors];
+}
+export function inferSpawnWorkersIntent(actions) {
+    return actions.length > 0 ? 'mutate' : 'plan';
+}
 export async function handleOrchestrationGroup(toolName, hctx, request, args, ctx) {
     const runtimeError = requireRuntime(hctx);
     if (runtimeError)
@@ -315,9 +334,11 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             const workers = request.params.arguments?.workers == null
                 ? undefined
                 : Number(request.params.arguments.workers);
-            const skills = Array.isArray(request.params.arguments?.skills)
+            const explicitSkills = Array.isArray(request.params.arguments?.skills)
                 ? request.params.arguments.skills.map(String)
-                : undefined;
+                : [];
+            const promptSkills = extractSkillSelectorsFromPrompt(prompt);
+            const skills = [...new Set([...explicitSkills, ...promptSkills])];
             const workflows = Array.isArray(request.params.arguments?.workflows)
                 ? request.params.arguments.workflows.map(String)
                 : undefined;
@@ -374,7 +395,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 const execution = await hctx.nexusRef.orchestrate(prompt, applyExecutionPreset({
                     files,
                     workers,
-                    skillNames: skills,
+                    skillNames: skills.length > 0 ? skills : undefined,
                     workflowSelectors: workflows,
                     hookSelectors: hooks,
                     automationSelectors: automations,
@@ -769,6 +790,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 ? String(request.params.arguments.executionPreset)
                 : undefined;
             const preset = resolveExecutionPreset(executionPreset);
+            const inferredIntent = inferSpawnWorkersIntent(actions);
             // Surface worker-plan intent on the SSE feed without persisting it as a memory.
             try {
                 nexusEventBus.emit('memory.snapshot', {
@@ -796,11 +818,18 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 backendSelectors: { memoryBackend, compressionBackend, dslCompiler },
                 backendMode,
                 optimizationProfile,
+                intent: inferredIntent,
                 executionMode: 'manual-low-level',
                 manualOverrides: ['nexus_spawn_workers'],
             }, executionPreset));
             const verifiedWorkers = execution.workerResults.filter(result => result.verified).length;
             const modifiedFiles = execution.workerResults.reduce((sum, result) => sum + result.modifiedFiles.length, 0);
+            const noDiffInspected = execution.state === 'inspected'
+                && modifiedFiles === 0
+                && !execution.workerResults.some((result) => result.diff?.trim());
+            const displayedDecision = noDiffInspected
+                ? 'no-applicable-diff'
+                : execution.finalDecision?.action ?? 'none';
             execution.activeSkills.forEach(skill => {
                 hctx.sessionDNA.recordSkill(skill.name);
                 if (skill.scope === 'global' || skill.rolloutStatus === 'promoted') {
@@ -826,7 +855,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                 `Run: ${execution.runId.padEnd(28, ' ')} State: ${execution.state.padEnd(18, ' ')}`,
                 `Workers: ${execution.workerResults.length.toString().padEnd(5, ' ')} Verified: ${verifiedWorkers.toString().padEnd(10, ' ')} Files: ${String(modifiedFiles).padEnd(12, ' ')}`,
                 `${`Preset: ${preset?.name ?? 'manual'}`.padEnd(61, ' ')}`,
-                `Decision: ${(execution.finalDecision?.action ?? 'none').padEnd(52, ' ')}`
+                `Decision: ${displayedDecision.padEnd(52, ' ')}`
             ], execution.state === 'merged' || execution.state === 'inspected' ? '32' : execution.state === 'rolled_back' ? '33' : '31');
             return {
                 content: [{
@@ -841,7 +870,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                             preset ? `Preset: ${preset.name} (${preset.id})` : null,
                             `Verified Workers: ${verifiedWorkers}`,
                             `Modified Files: ${modifiedFiles}`,
-                            `Decision: ${execution.finalDecision?.action ?? 'none'}`,
+                            `Decision: ${displayedDecision}`,
                             `Recommended Strategy: ${execution.finalDecision?.recommendedStrategy ?? 'n/a'}`,
                             `Planner: ${execution.plannerResult?.summary ?? 'n/a'}`,
                             `Crew: ${execution.plannerResult?.selectedCrew?.name ?? 'n/a'}`,

package/dist/agents/adapters/mcp/handlers/runtime.js

@@ -4,7 +4,7 @@
  * federation_status, run_status.
  * Extracted from mcp.ts (Phase 3 split).
  */
-import { formatBullets, formatJsonDetails, buildAutoMemorySummary, } from '../helpers.js';
+import { formatBullets, formatJsonDetails, truncateText, buildAutoMemorySummary, } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
 import { getSharedLicenseManager, snapshotPCU, formatPCUStatus } from '../../../../licensing/index.js';
 import { TokenAnalyticsEngine } from '../../../../engines/token-analytics.js';
@@ -13,6 +13,7 @@ import { requireRuntime } from '../util/require-runtime.js';
 import { getAsyncGate } from '../async-gate.js';
 import { getRun as getOrchRun } from '../../../../engines/orchestrator/store.js';
 import { nxlResult } from '../../../../nxl/index.js';
+import { summarizeUserWorkflowTrace } from '../../../../engines/user-workflow-trace.js';
 export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
     const runtimeError = requireRuntime(hctx);
     if (runtimeError)
@@ -226,6 +227,40 @@ export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
                     }],
             };
         }
+        case 'nexus_user_workflow_trace': {
+            const runId = String(request.params.arguments?.runId ?? '');
+            const fmt = String(request.params.arguments?.format ?? 'text');
+            const trace = await hctx.getRuntime().getUserWorkflowTrace?.(runId);
+            if (!trace) {
+                return { content: [{ type: 'text', text: `User workflow trace not found: ${runId}` }] };
+            }
+            if (fmt === 'json') {
+                return { content: [{ type: 'text', text: JSON.stringify(trace, null, 2) }] };
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            summarizeUserWorkflowTrace(trace),
+                            '',
+                            formatBullets([
+                                `Run: ${trace.runId}`,
+                                `Goal: ${truncateText(trace.goal, 120)}`,
+                                `Actions: ${trace.userJourney.actions.length ? trace.userJourney.actions.slice(0, 5).join(' | ') : 'none recorded'}`,
+                                `Files: ${trace.userJourney.selectedFiles.length ? trace.userJourney.selectedFiles.slice(0, 5).join(', ') : 'none selected'}`,
+                                `Agents: ${trace.userJourney.selectedSpecialists.length ? trace.userJourney.selectedSpecialists.slice(0, 5).join(', ') : 'none selected'}`,
+                                `Signals: ${trace.signals.length ? trace.signals.map(signal => `${signal.severity}:${signal.code}`).slice(0, 8).join(', ') : 'none'}`,
+                            ]),
+                            trace.signals.length
+                                ? `Failure signals\n${formatBullets(trace.signals.map(signal => `${signal.code}: ${signal.summary}`))}`
+                                : '',
+                            trace.nextActions.length
+                                ? `Next actions\n${formatBullets(trace.nextActions)}`
+                                : '',
+                        ].filter(Boolean).join('\n\n'),
+                    }],
+            };
+        }
         case 'nexus_run_status': {
             const runId = String(request.params.arguments?.runId ?? '');
             const fmt = String(request.params.arguments?.format ?? 'text');

package/dist/agents/adapters/mcp/helpers.js

@@ -190,7 +190,7 @@ export function isReadOnlyMcpTool(toolName) {
         'nexus_list_', 'nexus_describe_', 'nexus_runtime_health',
         'nexus_doctor', 'nexus_token_report', 'nexus_recall_memory',
         'nexus_temporal_query', 'nexus_memory_stats', 'nexus_federation_status',
-        'nexus_license_usage', 'nexus_run_status', 'nexus_selection_ledger',
+        'nexus_license_usage', 'nexus_run_status', 'nexus_user_workflow_trace', 'nexus_selection_ledger',
         'nexus_operative_journal',
     ];
     return skipPrefixes.some(p => toolName.startsWith(p));

package/dist/dashboard/routes/runtime.js

@@ -136,6 +136,15 @@ export const handleRuntimeRoutes = async (ctx, req, res, url) => {
         ctx.respondJson(res, entry ?? { error: 'run-token-telemetry-not-found', runId }, entry ? 200 : 404);
         return true;
     }
+    const userWorkflowMatch = req.method === 'GET'
+        ? /^\/api\/runs\/(.+)\/user-workflow$/.exec(url.pathname)
+        : null;
+    if (userWorkflowMatch) {
+        const runId = decodeURIComponent(userWorkflowMatch[1]);
+        const trace = await ctx.getRuntime()?.getUserWorkflowTrace?.(runId);
+        ctx.respondJson(res, trace ?? { error: 'user-workflow-trace-not-found', runId }, trace ? 200 : 404);
+        return true;
+    }
     if (req.method === 'GET' && url.pathname.startsWith('/api/runs/')) {
         const runId = decodeURIComponent(url.pathname.replace('/api/runs/', ''));
         const run = await ctx.getRuntime()?.getRun?.(runId);

package/dist/dashboard/selectors/assets-selector.js

@@ -23,11 +23,13 @@ export function serializeSpecialistsCatalog(specialists) {
 export async function buildAssetsSurface(ctx, url) {
     const state = collectDashboardBaseState(ctx, url);
     const runtimeId = state.runtime?.getRuntimeId?.() ?? 'default';
+    const patterns = ctx.getOrchestrator?.()?.listPatterns?.() ?? [];
     return {
         repoIdentity: state.snapshot?.repoIdentity ?? ctx.getSelectedRepoIdentity(url),
         usage: state.usage,
         selectionAudit: serializeSelectionAudit(state.usage),
         featureRegistry: await ctx.getCachedValue('feature-registry', 30_000, () => Promise.resolve(buildFeatureRegistry(ctx.repoRoot))),
+        patternPacks: patterns.filter((pattern) => Array.isArray(pattern.tags) && pattern.tags.includes('pattern-pack')),
         skills: state.runtime?.listSkills?.() ?? [],
         specialists: await ctx.getCachedValue(`catalog:specialists:${runtimeId}`, 15_000, () => Promise.resolve(serializeSpecialistsCatalog(state.runtime?.listSpecialists?.() ?? []))),
         crews: state.runtime?.listCrews?.() ?? [],

package/dist/dashboard/types.d.ts

@@ -235,6 +235,7 @@ export interface AssetsSurfaceDTO {
     usage: unknown;
     selectionAudit: unknown;
     featureRegistry: unknown;
+    patternPacks: unknown[];
     skills: unknown[];
     specialists: unknown[];
     crews: unknown[];

package/dist/engines/orchestrator.js

@@ -2299,7 +2299,7 @@ export class OrchestratorEngine {
             elapsedMs: Date.now() - funnelStart,
         });
         // ── Funnel Stage 2: vote ─────────────────────────────────────────────────
-        const skillSelection = this.resolveCatalogVotes('skill', task, intent, skillItems, {
+        const skillSelection = this.resolveCatalogVotes('skill', task, intent, options.skillNames?.length ? allSkillItems : skillItems, {
             explicit: options.skillNames,
             planner: planner.selectedSkills,
             knowledge: knowledgeFabric.recommendations.skills,
@@ -2308,7 +2308,7 @@ export class OrchestratorEngine {
             limit: 5,
             selector: 'name',
         });
-        const workflowSelection = this.resolveCatalogVotes('workflow', task, intent, workflowItems, {
+        const workflowSelection = this.resolveCatalogVotes('workflow', task, intent, options.workflowSelectors?.length ? allWorkflowItems : workflowItems, {
             explicit: options.workflowSelectors,
             planner: planner.selectedWorkflows,
             knowledge: knowledgeFabric.recommendations.workflows,
@@ -2333,7 +2333,7 @@ export class OrchestratorEngine {
                 authorityTier: this.getAuthorityTier('workflow'),
             })),
         ];
-        const hookSelection = this.resolveCatalogVotes('hook', task, intent, hookItems, {
+        const hookSelection = this.resolveCatalogVotes('hook', task, intent, options.hookSelectors?.length ? allHookItems : hookItems, {
             explicit: options.hookSelectors,
             planner: [],
             knowledge: knowledgeFabric.recommendations.hooks,
@@ -2341,7 +2341,7 @@ export class OrchestratorEngine {
             limit: intent.riskClass === 'high' ? 3 : 2,
             selector: 'name',
         });
-        const automationSelection = this.resolveCatalogVotes('automation', task, intent, automationItems, {
+        const automationSelection = this.resolveCatalogVotes('automation', task, intent, options.automationSelectors?.length ? allAutomationItems : automationItems, {
             explicit: options.automationSelectors,
             planner: [],
             knowledge: knowledgeFabric.recommendations.automations,
@@ -2349,7 +2349,7 @@ export class OrchestratorEngine {
             limit: intent.taskType === 'release' || this.sessionState.repeatedFailures > 0 ? 3 : 2,
             selector: 'name',
         });
-        const specialistSelection = this.resolveCatalogVotes('specialist', task, intent, specialistItems, {
+        const specialistSelection = this.resolveCatalogVotes('specialist', task, intent, options.specialistSelectors?.length ? allSpecialistItems : specialistItems, {
             explicit: options.specialistSelectors,
             planner: planner.selectedSpecialists.map((specialist) => specialist.specialistId),
             knowledge: knowledgeFabric.recommendations.specialists,
@@ -2357,7 +2357,7 @@ export class OrchestratorEngine {
             limit: 4,
             selector: 'id',
         });
-        const crewSelection = this.resolveCatalogVotes('crew', task, intent, crewItems, {
+        const crewSelection = this.resolveCatalogVotes('crew', task, intent, options.crewSelectors?.length ? allCrewItems : crewItems, {
             explicit: options.crewSelectors,
             planner: planner.selectedCrew ? [planner.selectedCrew.crewId] : [],
             knowledge: knowledgeFabric.recommendations.crews,
@@ -2509,7 +2509,19 @@ export class OrchestratorEngine {
     resolveCatalogVotes(kind, task, intent, items, input) {
         const explicit = dedupeStrings(input.explicit ?? []);
         if (explicit.length > 0) {
-            const selectedEntries = explicit.map((value) => this.toArtifactAuditEntry(kind, value, items, {
+            const resolved = explicit.map((value) => {
+                const item = items.find((entry) => entry.id === value || entry.name === value);
+                return {
+                    value,
+                    item,
+                    selectedValue: input.selector === 'id'
+                        ? (item?.id ?? value)
+                        : (item?.name ?? value),
+                };
+            });
+            const selectedEntries = resolved
+                .filter((entry) => entry.item)
+                .map((entry) => this.toArtifactAuditEntry(kind, entry.selectedValue, items, {
                 score: 1,
                 source: 'explicit',
                 confidence: 'high',
@@ -2517,7 +2529,23 @@ export class OrchestratorEngine {
                 selector: input.selector,
                 selectionPolicy: 'explicit-only',
             }));
-            return { selectedValues: explicit, selectedEntries, rejectedEntries: [] };
+            const rejectedEntries = resolved
+                .filter((entry) => !entry.item)
+                .map((entry) => this.toArtifactAuditEntry(kind, entry.value, items, {
+                score: 1,
+                source: 'explicit',
+                confidence: 'high',
+                reason: 'User provided a hard constraint, but the selector was not found in the runtime catalog.',
+                selector: input.selector,
+                selectionPolicy: 'explicit-only',
+                blockedReason: 'Explicit selector is not present in the runtime catalog.',
+                authorityTier: this.getAuthorityTier(kind),
+            }, false));
+            return {
+                selectedValues: selectedEntries.map((entry) => input.selector === 'id' ? entry.id : entry.name),
+                selectedEntries,
+                rejectedEntries,
+            };
         }
         const votes = new Map();
         const applyVote = (value, source, score, confidence, reason) => {

package/dist/engines/pattern-registry.d.ts

@@ -16,6 +16,18 @@ export interface PatternCard {
     successCount: number;
     failureCount: number;
     lastUsedAt?: number;
+    patternPack?: {
+        kind: 'flow-kit';
+        flows: string[];
+        starterFiles: Array<{
+            path: string;
+            purpose: string;
+        }>;
+        memorySeeds: string[];
+        lifecycle: string[];
+        acceptanceChecks: string[];
+        antiPatterns: string[];
+    };
 }
 export interface PatternSearchResult extends PatternCard {
     score: number;

package/dist/engines/pattern-registry.js

@@ -93,6 +93,71 @@ const BUILTIN_PATTERNS = [
         successCount: 4,
         failureCount: 0,
     },
+    {
+        patternId: 'pattern_pack_auth_signup_flow',
+        name: 'Auth and Signup Flow Pack',
+        category: 'workflow',
+        summary: 'Ground common auth, signup, onboarding, and session flows in reusable security-aware defaults without generating stale boilerplate.',
+        instructions: 'Use this pack when a task mentions auth, login, signup, registration, onboarding, sessions, passwords, magic links, OAuth, or account creation. Start from the lifecycle and acceptance checks, inspect the target framework, then generate only framework-appropriate code with tests and security review. Never paste secrets, never invent provider config, and never bypass existing auth libraries.',
+        tags: ['pattern-pack', 'auth', 'signup', 'registration', 'login', 'onboarding', 'security', 'session'],
+        stages: ['bootstrap', 'planning', 'mutation', 'verification'],
+        suggestedSkills: ['broken-authentication', 'backend-dev-guidelines', 'frontend-dev-guidelines', 'security-auditor'],
+        suggestedWorkflows: ['backend-execution-loop', 'frontend-execution-loop'],
+        suggestedHooks: ['before-verify-approval'],
+        suggestedAutomations: [],
+        suggestedCrews: ['crew_implementation'],
+        suggestedSpecialists: [
+            'specialist_engineering-engineering-backend-architect',
+            'specialist_engineering-engineering-frontend-developer',
+            'specialist_engineering-engineering-security-engineer',
+        ],
+        confidence: 0.81,
+        successCount: 0,
+        failureCount: 0,
+        patternPack: {
+            kind: 'flow-kit',
+            flows: [
+                'email/password signup',
+                'login/logout',
+                'session refresh',
+                'password reset',
+                'email verification',
+                'OAuth handoff',
+                'first-run onboarding',
+            ],
+            starterFiles: [
+                { path: 'auth/provider', purpose: 'Wrap the project auth provider or framework-native session adapter.' },
+                { path: 'auth/routes', purpose: 'Handle signup, login, logout, callback, and reset endpoints.' },
+                { path: 'auth/ui', purpose: 'Expose signup, login, reset, and verification states.' },
+                { path: 'auth/tests', purpose: 'Cover happy path, invalid credentials, session expiry, and access-control regressions.' },
+            ],
+            memorySeeds: [
+                'Auth work must reuse project-native libraries and existing session boundaries before adding new dependencies.',
+                'Signup flows need explicit abuse, rate-limit, email verification, and password-reset checks.',
+                'Never store provider secrets, reset tokens, or session material in Nexus memory.',
+            ],
+            lifecycle: [
+                'Detect framework and existing auth surface.',
+                'Select provider pattern and security constraints.',
+                'Patch smallest route, UI, and persistence surface.',
+                'Verify with unit, integration, and access-control checks.',
+                'Store only sanitized implementation decisions as memory.',
+            ],
+            acceptanceChecks: [
+                'Unauthenticated users cannot access protected routes.',
+                'Signup and login errors are explicit without leaking account existence.',
+                'Sessions expire or refresh according to project policy.',
+                'Password reset and verification tokens are one-time and scoped.',
+                'Tests cover success, failure, and privilege-boundary cases.',
+            ],
+            antiPatterns: [
+                'Rolling custom crypto.',
+                'Saving secrets or tokens into memory.',
+                'Adding auth dependencies before checking existing stack.',
+                'Generating UI-only signup without backend/session proof.',
+            ],
+        },
+    },
 ];
 export class PatternRegistry {
     statePath;

package/dist/engines/specialist-roster.js

@@ -41,25 +41,27 @@ export function getCrewTemplate(crewId) {
 export function planSpecialists(input) {
     const requestedCrews = input.requestedCrews ?? [];
     const requestedSpecialists = input.requestedSpecialists ?? [];
+    const requestedSkills = input.requestedSkills ?? [];
+    const requestedWorkflows = input.requestedWorkflows ?? [];
     const goal = input.goal;
     const matchedDomains = detectDomains(goal, [
         ...(input.files ?? []),
         ...requestedCrews,
         ...requestedSpecialists,
-        ...(input.requestedSkills ?? []),
-        ...(input.requestedWorkflows ?? []),
+        ...requestedSkills,
+        ...requestedWorkflows,
     ]);
     const taskSignals = analyzeTaskContext(goal, matchedDomains, input.files ?? []);
     const selectedCrew = selectCrew(goal, matchedDomains, requestedCrews);
     const selectedSpecialists = rankSpecialists(goal, matchedDomains, selectedCrew, requestedSpecialists, input.optimizationProfile ?? 'standard');
-    const selectedSkills = rankAssetSelectors(goal, matchedDomains, input.files ?? [], dedupeStrings([
-        ...(input.requestedSkills ?? []),
+    const selectedSkills = pinRequestedSelectors(requestedSkills, rankAssetSelectors(goal, matchedDomains, input.files ?? [], dedupeStrings([
+        ...requestedSkills,
         ...selectedSpecialists.flatMap((entry) => getSpecialist(entry.specialistId)?.recommendedSkills ?? []),
-    ]), input.optimizationProfile ?? 'standard');
-    const selectedWorkflows = rankAssetSelectors(goal, matchedDomains, input.files ?? [], dedupeStrings([
-        ...(input.requestedWorkflows ?? []),
+    ]), input.optimizationProfile ?? 'standard'));
+    const selectedWorkflows = pinRequestedSelectors(requestedWorkflows, rankAssetSelectors(goal, matchedDomains, input.files ?? [], dedupeStrings([
+        ...requestedWorkflows,
         ...selectedSpecialists.flatMap((entry) => getSpecialist(entry.specialistId)?.recommendedWorkflows ?? []),
-    ]), input.optimizationProfile ?? 'standard');
+    ]), input.optimizationProfile ?? 'standard'));
     const toolPolicy = selectToolPolicy(selectedSpecialists);
     const fallbackPlan = {
         summary: 'Fallback to current runtime domain-pack execution if specialist confidence or crew coverage is weak.',
@@ -533,6 +535,12 @@ function rankAssetSelectors(goal, matchedDomains, files, values, optimizationPro
         .slice(0, optimizationProfile === 'max' ? 6 : 4)
         .map((entry) => entry.value);
 }
+function pinRequestedSelectors(requested, ranked) {
+    return dedupeStrings([
+        ...requested,
+        ...ranked,
+    ]);
+}
 function dedupeStrings(values) {
     return [...new Set(values.filter(Boolean))];
 }

package/dist/engines/user-workflow-trace.d.ts

@@ -0,0 +1,47 @@
+export declare const USER_WORKFLOW_TRACE_FILE = "user-workflow-trace.json";
+export type UserWorkflowSpanKind = 'user_goal' | 'planning' | 'context' | 'agent_action' | 'verification' | 'decision' | 'outcome';
+export type UserWorkflowStatus = 'ok' | 'warn' | 'failed' | 'skipped';
+export interface UserWorkflowSpan {
+    id: string;
+    parentId?: string;
+    kind: UserWorkflowSpanKind;
+    label: string;
+    status: UserWorkflowStatus;
+    summary: string;
+    attributes?: Record<string, unknown>;
+}
+export interface UserWorkflowSignal {
+    code: string;
+    severity: 'info' | 'warn' | 'high';
+    summary: string;
+    evidence?: Record<string, unknown>;
+}
+export interface UserWorkflowTrace {
+    schemaVersion: 1;
+    scope: 'user-agent-workflow';
+    traceId: string;
+    runId: string;
+    generatedAt: number;
+    goal: string;
+    state: string;
+    result: string;
+    artifactsPath?: string;
+    userJourney: {
+        goal: string;
+        selectedFiles: string[];
+        selectedSkills: string[];
+        selectedWorkflows: string[];
+        selectedSpecialists: string[];
+        actions: string[];
+        verifyCommands: string[];
+    };
+    spans: UserWorkflowSpan[];
+    signals: UserWorkflowSignal[];
+    nextActions: string[];
+}
+type RunLike = Record<string, any>;
+export declare function buildUserWorkflowTrace(run: RunLike): UserWorkflowTrace;
+export declare function resolveUserWorkflowTracePath(artifactsPath: string): string;
+export declare function readUserWorkflowTrace(artifactsPath: string): Promise<UserWorkflowTrace | undefined>;
+export declare function summarizeUserWorkflowTrace(trace: UserWorkflowTrace): string;
+export {};

package/dist/engines/user-workflow-trace.js

@@ -0,0 +1,281 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export const USER_WORKFLOW_TRACE_FILE = 'user-workflow-trace.json';
+function short(value, limit = 220) {
+    const text = String(value ?? '').replace(/\s+/g, ' ').trim();
+    return text.length > limit ? `${text.slice(0, Math.max(0, limit - 1))}...` : text;
+}
+function uniqueStrings(values) {
+    return [...new Set(values.map((value) => String(value ?? '').trim()).filter(Boolean))];
+}
+function workerStatus(worker) {
+    if (worker.budgetExceeded)
+        return 'warn';
+    if (worker.verified)
+        return 'ok';
+    if (worker.outcome === 'failed')
+        return 'failed';
+    if (worker.outcome === 'partial')
+        return 'warn';
+    if (!String(worker.diff ?? '').trim() && !(worker.commandRecords ?? []).length)
+        return 'skipped';
+    return 'warn';
+}
+function verificationStatus(entry) {
+    if (entry.status === 'passed' || entry.passed === true)
+        return 'ok';
+    if (entry.status === 'skipped')
+        return 'skipped';
+    return 'failed';
+}
+function extractActions(run) {
+    const manifestActions = (run.workerManifests ?? [])
+        .flatMap((manifest) => manifest.actions ?? [])
+        .map((action) => action.command ?? action.type ?? action.name ?? action.tool ?? JSON.stringify(action));
+    const commandRecords = (run.workerResults ?? [])
+        .flatMap((worker) => worker.commandRecords ?? [])
+        .map((record) => record.command);
+    return uniqueStrings([...manifestActions, ...commandRecords]).slice(0, 30);
+}
+function extractVerifyCommands(run) {
+    const manifestCommands = (run.workerManifests ?? []).flatMap((manifest) => manifest.verifyCommands ?? []);
+    const verificationCommands = (run.verificationResults ?? [])
+        .flatMap((entry) => entry.commands ?? [])
+        .map((record) => record.command);
+    return uniqueStrings([...manifestCommands, ...verificationCommands]).slice(0, 30);
+}
+function buildSignals(run) {
+    const signals = [];
+    const workers = run.workerResults ?? [];
+    const verifications = run.verificationResults ?? [];
+    const modifiedFiles = workers.reduce((sum, worker) => sum + (worker.modifiedFiles?.length ?? 0), 0);
+    const hasDiff = workers.some((worker) => String(worker.diff ?? '').trim().length > 0);
+    const commandOnly = workers.some((worker) => (worker.commandRecords ?? []).length > 0);
+    const failedWorkers = workers.filter((worker) => workerStatus(worker) === 'failed');
+    const skippedVerifications = verifications.filter((entry) => entry.status === 'skipped');
+    const failedVerifications = verifications.filter((entry) => verificationStatus(entry) === 'failed');
+    if (String(run.state) === 'failed') {
+        signals.push({
+            code: 'workflow_failed',
+            severity: 'high',
+            summary: short(run.result || 'Agent workflow failed before a stable user outcome was produced.'),
+            evidence: { state: run.state },
+        });
+    }
+    if (workers.length === 0) {
+        signals.push({
+            code: 'no_agent_workers',
+            severity: 'warn',
+            summary: 'No worker results were recorded for this user workflow.',
+        });
+    }
+    if (failedWorkers.length > 0) {
+        signals.push({
+            code: 'agent_worker_failed',
+            severity: 'high',
+            summary: `${failedWorkers.length} worker(s) failed or returned unusable output.`,
+            evidence: { workers: failedWorkers.map((worker) => worker.workerId).slice(0, 10) },
+        });
+    }
+    if (failedVerifications.length > 0) {
+        signals.push({
+            code: 'verification_failed',
+            severity: 'high',
+            summary: `${failedVerifications.length} verification step(s) failed.`,
+            evidence: { workers: failedVerifications.map((entry) => entry.workerId).slice(0, 10) },
+        });
+    }
+    if (!hasDiff && modifiedFiles === 0 && (skippedVerifications.length > 0 || commandOnly)) {
+        signals.push({
+            code: 'no_applicable_diff',
+            severity: String(run.state) === 'failed' ? 'warn' : 'info',
+            summary: 'Agents produced no repository patch; this is expected for read-only or command-only workflows.',
+            evidence: { skippedVerifications: skippedVerifications.length, commandOnly },
+        });
+    }
+    const tokenTelemetry = run.tokenTelemetry ?? {};
+    const grossTokens = Number(tokenTelemetry.grossInputTokens ?? 0);
+    const savedTokens = Number(tokenTelemetry.savedTokens ?? 0);
+    if (grossTokens > 80_000 && savedTokens < grossTokens * 0.2) {
+        signals.push({
+            code: 'token_pressure',
+            severity: 'warn',
+            summary: 'Workflow used a large context budget with low compression savings.',
+            evidence: { grossInputTokens: grossTokens, savedTokens },
+        });
+    }
+    return signals;
+}
+function buildNextActions(trace) {
+    if (trace.signals.length === 0) {
+        return ['Use this trace as the stable replay/eval baseline for similar user workflows.'];
+    }
+    const actions = new Set();
+    for (const signal of trace.signals) {
+        if (signal.code === 'workflow_failed' || signal.code === 'agent_worker_failed') {
+            actions.add('Inspect the failed worker span, then replay with narrower files, clearer success criteria, or a better specialist.');
+        }
+        if (signal.code === 'verification_failed') {
+            actions.add('Promote the failing verification commands into a regression eval before rerunning.');
+        }
+        if (signal.code === 'no_applicable_diff') {
+            actions.add('If a patch was expected, rerun with mutate intent and explicit target files; otherwise treat this as a read-only trace.');
+        }
+        if (signal.code === 'token_pressure') {
+            actions.add('Run token optimization first and replay with a smaller context packet.');
+        }
+    }
+    return [...actions].slice(0, 5);
+}
+export function buildUserWorkflowTrace(run) {
+    const planner = run.plannerResult ?? {};
+    const selectedFiles = uniqueStrings(planner.selectedFiles ?? []);
+    const selectedSkills = uniqueStrings([
+        ...(planner.selectedSkills ?? []),
+        ...(run.activeSkills ?? []).map((skill) => skill.name),
+    ]);
+    const selectedWorkflows = uniqueStrings([
+        ...(planner.selectedWorkflows ?? []),
+        ...(run.activeWorkflows ?? []).map((workflow) => workflow.name),
+    ]);
+    const selectedSpecialists = uniqueStrings([
+        ...(planner.selectedSpecialists ?? []).map((specialist) => specialist.name ?? specialist.specialistId),
+        ...(run.workerManifests ?? []).map((manifest) => manifest.specialistName ?? manifest.specialistId),
+    ]);
+    const actions = extractActions(run);
+    const verifyCommands = extractVerifyCommands(run);
+    const spans = [
+        {
+            id: 'user-goal',
+            kind: 'user_goal',
+            label: 'User goal',
+            status: 'ok',
+            summary: short(run.goal, 320),
+            attributes: {
+                parentRunId: run.parentRunId ?? null,
+                sourceAutomationId: run.sourceAutomationId ?? null,
+            },
+        },
+        {
+            id: 'planning',
+            parentId: 'user-goal',
+            kind: 'planning',
+            label: 'Agent plan',
+            status: selectedSpecialists.length > 0 || selectedSkills.length > 0 ? 'ok' : 'warn',
+            summary: short(planner.summary ?? 'Planner selected agents, skills, workflows, and files for the user workflow.'),
+            attributes: { selectedSkills, selectedWorkflows, selectedSpecialists },
+        },
+        {
+            id: 'context',
+            parentId: 'planning',
+            kind: 'context',
+            label: 'Context packet',
+            status: selectedFiles.length > 0 ? 'ok' : 'warn',
+            summary: `${selectedFiles.length} file(s), ${selectedSkills.length} skill(s), ${selectedWorkflows.length} workflow(s) routed into the agent workflow.`,
+            attributes: {
+                selectedFiles,
+                memoryChecks: run.memoryChecks?.length ?? 0,
+                tokenTelemetry: run.tokenTelemetry ?? null,
+            },
+        },
+        ...(run.workerResults ?? []).map((worker) => ({
+            id: `worker-${worker.workerId ?? 'unknown'}`,
+            parentId: 'planning',
+            kind: 'agent_action',
+            label: `${worker.role ?? 'worker'} ${worker.workerId ?? 'unknown'}`,
+            status: workerStatus(worker),
+            summary: short(worker.summary ?? worker.learned ?? worker.outcome ?? 'Agent worker completed.'),
+            attributes: {
+                workerId: worker.workerId,
+                role: worker.role,
+                outcome: worker.outcome,
+                verified: Boolean(worker.verified),
+                modifiedFiles: worker.modifiedFiles ?? [],
+                commandCount: worker.commandRecords?.length ?? 0,
+                tokensUsed: worker.tokensUsed ?? null,
+            },
+        })),
+        ...(run.verificationResults ?? []).map((entry) => ({
+            id: `verification-${entry.verifierId ?? entry.workerId ?? 'unknown'}`,
+            parentId: `worker-${entry.workerId ?? 'unknown'}`,
+            kind: 'verification',
+            label: `Verification for ${entry.workerId ?? 'worker'}`,
+            status: verificationStatus(entry),
+            summary: short(entry.summary ?? 'Verification completed.'),
+            attributes: {
+                workerId: entry.workerId,
+                verifierId: entry.verifierId,
+                commandCount: entry.commands?.length ?? 0,
+                skippedReason: entry.skippedReason ?? null,
+            },
+        })),
+        {
+            id: 'decision',
+            parentId: 'planning',
+            kind: 'decision',
+            label: 'Merge decision',
+            status: run.finalDecision?.action === 'apply' ? 'ok' : run.finalDecision?.action ? 'warn' : 'skipped',
+            summary: short(run.finalDecision?.recommendedStrategy ?? run.finalDecision?.action ?? 'No merge decision recorded.'),
+            attributes: {
+                action: run.finalDecision?.action ?? null,
+                winner: run.finalDecision?.winner?.workerId ?? null,
+            },
+        },
+        {
+            id: 'outcome',
+            parentId: 'decision',
+            kind: 'outcome',
+            label: 'User workflow outcome',
+            status: String(run.state) === 'failed' ? 'failed' : 'ok',
+            summary: short(run.result ?? ''),
+            attributes: {
+                state: run.state,
+                promotions: run.promotionDecisions?.length ?? 0,
+                continuationChildren: run.continuationChildren?.length ?? 0,
+            },
+        },
+    ];
+    const signals = buildSignals(run);
+    const trace = {
+        schemaVersion: 1,
+        scope: 'user-agent-workflow',
+        traceId: `uwt_${run.runId}`,
+        runId: String(run.runId ?? ''),
+        generatedAt: Date.now(),
+        goal: String(run.goal ?? ''),
+        state: String(run.state ?? ''),
+        result: String(run.result ?? ''),
+        artifactsPath: run.artifactsPath,
+        userJourney: {
+            goal: String(run.goal ?? ''),
+            selectedFiles,
+            selectedSkills,
+            selectedWorkflows,
+            selectedSpecialists,
+            actions,
+            verifyCommands,
+        },
+        spans,
+        signals,
+        nextActions: [],
+    };
+    trace.nextActions = buildNextActions(trace);
+    return trace;
+}
+export function resolveUserWorkflowTracePath(artifactsPath) {
+    return path.join(artifactsPath, USER_WORKFLOW_TRACE_FILE);
+}
+export async function readUserWorkflowTrace(artifactsPath) {
+    try {
+        const raw = await fs.readFile(resolveUserWorkflowTracePath(artifactsPath), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function summarizeUserWorkflowTrace(trace) {
+    const high = trace.signals.filter((signal) => signal.severity === 'high').length;
+    const warns = trace.signals.filter((signal) => signal.severity === 'warn').length;
+    return `${trace.state.toUpperCase()} user workflow · ${trace.spans.length} span(s) · ${high} high signal(s), ${warns} warning(s)`;
+}

package/dist/phantom/runtime.d.ts

@@ -14,6 +14,7 @@ import { type ContinuationProposal, type FallbackPlan, type OptimizationProfile,
 import { type TaskPlannerState } from '../engines/task-planner.js';
 import { type RuntimeArtifactSelectionAudit, type RuntimeArtifactOutcomeSnapshot, type RuntimeCatalogHealthSnapshot, type RuntimeClientInstructionStatus, type RuntimeMemoryHealthSnapshot, type RuntimeMemoryReconciliationSummary, type RuntimeMemoryScopeUsageSnapshot, type RuntimeRagUsageSummary, type RuntimeRegistrySnapshot, type RuntimeOrchestrationSnapshot, type RuntimePrimaryClientSnapshot, type RuntimeSourceAwareTokenBudgetSnapshot, type RuntimeTaskGraphSnapshot, type RuntimeTokenRunSnapshot, type RuntimeTokenSummarySnapshot, type RuntimeWorkerPlanSnapshot } from '../engines/runtime-registry.js';
 import { type ExecutionLedger, type InstructionPacket, type OrchestrationExecutionMode } from '../engines/instruction-gateway.js';
+import { type UserWorkflowTrace } from '../engines/user-workflow-trace.js';
 import type { KnowledgeFabricBundle, KnowledgeFabricSnapshot } from '../engines/knowledge-fabric.js';
 import type { BootstrapManifestStatus } from '../engines/client-bootstrap.js';
 import { type WorktreeHealthSnapshot } from '../engines/worktree-health.js';
@@ -282,6 +283,7 @@ export interface ExecutionRun {
     memoryScopeUsage?: RuntimeMemoryScopeUsageSnapshot;
     memoryReconciliationSummary?: RuntimeMemoryReconciliationSummary;
     autoGhostPass?: GhostReport;
+    userWorkflowTrace?: UserWorkflowTrace;
 }
 export interface SubAgentRuntimeOptions {
     repoRoot?: string;
@@ -328,6 +330,8 @@ export declare class SubAgentRuntime {
     runNXL(goal: string, rawScript?: string, useCase?: string): Promise<ExecutionRun>;
     listRuns(limit?: number): ExecutionRun[];
     getRun(runId: string): Promise<ExecutionRun | undefined>;
+    getUserWorkflowTrace(runId: string): Promise<UserWorkflowTrace | undefined>;
+    private persistUserWorkflowTrace;
     getRuntimeId(): string;
     getUsageSnapshot(): RuntimeRegistrySnapshot;
     getInstructionPacket(): InstructionPacket | undefined;

package/dist/phantom/runtime.js

@@ -19,6 +19,7 @@ import { planTask } from '../engines/task-planner.js';
 import { nexusEventBus } from '../engines/event-bus.js';
 import { RuntimeRegistry, createEmptyUsageState, createEmptyTokenSummary, } from '../engines/runtime-registry.js';
 import { InstructionGateway, createExecutionLedger, markExecutionLedgerStep, renderInstructionPacketMarkdown, } from '../engines/instruction-gateway.js';
+import { buildUserWorkflowTrace, readUserWorkflowTrace, USER_WORKFLOW_TRACE_FILE, } from '../engines/user-workflow-trace.js';
 import { resolveWorkspaceContext } from '../engines/workspace-resolver.js';
 import { WorktreeDoctorError, } from '../engines/worktree-health.js';
 // ─── Sub-module imports ────────────────────────────────────────────────────────
@@ -363,6 +364,7 @@ export class SubAgentRuntime {
             });
             run.executionLedger = task.executionLedger;
             this.syncExecutionMetadata(run);
+            this.persistUserWorkflowTrace(run, recorder);
             recorder.writeJson('run.json', run);
             return run;
         }
@@ -554,6 +556,7 @@ export class SubAgentRuntime {
             run.state = 'failed';
             run.result = 'Hooks blocked execution before mutation.';
             this.attachLatestRun(runId, task.goal, run.state);
+            this.persistUserWorkflowTrace(run, recorder);
             recorder.writeJson('run.json', run);
             return run;
         }
@@ -815,6 +818,7 @@ export class SubAgentRuntime {
         recorder.writeJson('planner-state.json', run.plannerState);
         recorder.writeJson('planner-result.json', run.plannerResult);
         recorder.writeJson('manifests.json', run.workerManifests);
+        this.persistUserWorkflowTrace(run, recorder);
         recorder.writeJson('run.json', run);
         // Persist run-level token telemetry to the global ledger so nexus_token_report
         // and dashboard analytics can aggregate lifetime savings across sessions.
@@ -883,6 +887,25 @@ export class SubAgentRuntime {
             return undefined;
         }
     }
+    async getUserWorkflowTrace(runId) {
+        const run = await this.getRun(runId);
+        if (!run)
+            return undefined;
+        return (await readUserWorkflowTrace(run.artifactsPath)) ?? buildUserWorkflowTrace(run);
+    }
+    persistUserWorkflowTrace(run, recorder) {
+        try {
+            const trace = buildUserWorkflowTrace(run);
+            run.userWorkflowTrace = trace;
+            if (recorder) {
+                recorder.writeJson(USER_WORKFLOW_TRACE_FILE, trace);
+            }
+            return trace;
+        }
+        catch {
+            return undefined;
+        }
+    }
     getRuntimeId() {
         return this.runtimeId;
     }
@@ -2247,10 +2270,17 @@ export class SubAgentRuntime {
                     summary: `Operational workflow completed with command evidence only (${records.length} command binding(s) passed); no repository patch was required.`,
                 };
             }
+            if (task.intent === 'inspect' || task.intent === 'plan') {
+                return {
+                    applied: false,
+                    rolledBack: false,
+                    summary: 'Read-only worker swarm completed without a repository patch; no applicable diff was expected.',
+                };
+            }
             return {
                 applied: false,
                 rolledBack: false,
-                summary: `Execution finished with ${decision.action} but no applicable diff was produced.`,
+                summary: 'Worker swarm completed without a repository patch; no applicable diff was produced.',
             };
         }
         if (!consensusPolicy.approveRunLevelChange(decision.winner ? [decision.winner.workerId] : ['merge-oracle'])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-prime",
-  "version": "7.9.8",
+  "version": "7.9.9",
   "description": "Local-first MCP control plane for coding agents with bootstrap-orchestrate execution, memory fabric, token budgeting, and worktree-backed swarms",
   "type": "module",
   "main": "dist/index.js",