vgxness 0.1.0

package/dist/cli/dispatcher.js

@@ -0,0 +1,2880 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { AgentRegistryService } from '../agents/agent-registry-service.js';
+import { AgentSeedService } from '../agents/agent-seed-service.js';
+import { ManagerProfileOverlayService } from '../agents/manager-profile-overlay-service.js';
+import { resolveAgentProfileModel } from '../agents/profile-model-routing.js';
+import { ManagerProfileOverlayRepository } from '../agents/repositories/manager-profile-overlays.js';
+import { getProviderRenderer } from '../agents/renderers/index.js';
+import { renderDashboard as renderStatusDashboard } from './dashboard-renderer.js';
+import { buildDashboardApprovalsReadModel, buildDashboardRunsReadModel, buildDashboardWorkflowsReadModel } from './dashboard-operational-read-models.js';
+import { dashboardKeyFromInput, loadInitialDashboardState, reduceDashboardKey, refreshDashboard, renderDashboard as renderInteractiveDashboard, resolveDashboardRenderStyle } from './interactive-dashboard.js';
+import { sanitizeDashboardError } from './dashboard-tui-read-model.js';
+import { createAgentRegistryToolHandlers } from '../harness/tools/agents.js';
+import { createMemoryToolHandlers } from '../harness/tools/memory.js';
+import { MemoryService } from '../memory/memory-service.js';
+import { planMemoryImportDryRun, validateMemoryImportPackage, writeMemoryImportObservations } from '../memory/import/index.js';
+import { openMemoryDatabase } from '../memory/sqlite/database.js';
+import { prepareMemoryDatabasePath, resolveMemoryDatabasePath } from '../memory/storage-paths.js';
+import { planOpenCodeMcpInstall } from '../mcp/client-install-opencode-contract.js';
+import { installOpenCodeMcpClient } from '../mcp/client-install-opencode.js';
+import { createMcpClientSetupPreview, isMcpClientSetupProvider } from '../mcp/client-setup-preview.js';
+import { createMcpDoctorReport } from '../mcp/doctor.js';
+import { createOpenCodeMcpVisibilityReport } from '../mcp/opencode-visibility.js';
+import { createNaturalLanguagePlan } from '../orchestrator/natural-language-planner.js';
+import { evaluatePermission, permissionCategories } from '../permissions/policy-evaluator.js';
+import { OpenCodeInjectionPreviewService } from '../providers/opencode/injection-preview.js';
+import { parseOperationRetryPolicy } from '../runs/operation-retry.js';
+import { RunSnapshotExportService } from '../runs/run-snapshot-export-service.js';
+import { RunService } from '../runs/run-service.js';
+import { ArtifactPortabilityService } from '../sdd/artifact-portability-service.js';
+import { isSddPhase, sddPhases } from '../sdd/schema.js';
+import { SddWorkflowService } from '../sdd/sdd-workflow-service.js';
+import { SetupLifecycleService } from '../setup/setup-lifecycle-service.js';
+import { rollbackConfigBackup } from '../setup/backup-rollback-service.js';
+import { createSetupPlan } from '../setup/setup-plan.js';
+import { vgxnessSetupDefaults } from '../setup/setup-defaults.js';
+import { SkillRegistryService } from '../skills/skill-registry-service.js';
+import { findWorkflowDefinition, getWorkflowDefinition, listWorkflows } from '../workflows/workflow-registry.js';
+import { CommandAllowlistAdapter, commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
+import { GuardedProviderWorkflowExecutor, operationMetadataForWorkflowExecution, SafeNonDispatchingWorkflowExecutor, workflowExecutorSafety } from '../workflows/workflow-executor.js';
+import { isWorkflowId } from '../workflows/schema.js';
+const promptBuffers = new WeakMap();
+export function dispatchCli(argv, environment) {
+    const parsed = parseArgs(argv);
+    const [area, command] = parsed.positionals;
+    if (!area || area === 'help' || area === '--help' || area === '-h')
+        return okText(visibleHelpText());
+    if (area === 'init')
+        return runSetupPlanCommand(parsed, environment);
+    if (area === 'doctor')
+        return usageFailure('doctor is available through the async CLI entrypoint; run vgxness doctor from the installed CLI.');
+    if (!command)
+        return usageFailure(`Missing command for ${area}`);
+    const commandValidation = validateCommand(area, command);
+    if (!commandValidation.ok)
+        return usageFailure(commandValidation.message);
+    if (area === 'setup')
+        return runSetupLifecycleCommand(parsed, environment);
+    if (isWorkflowId(area) && command === 'preview')
+        return runWorkflowPreviewCommand(area, parsed);
+    if (area === 'memory' && command === 'import')
+        return runMemoryImportCommand(parsed, environment);
+    const selectedDatabasePath = databasePathFor(parsed.flags, environment);
+    if (!selectedDatabasePath.ok)
+        return resultFailure(selectedDatabasePath);
+    const databasePath = selectedDatabasePath.value;
+    const opened = openCliDatabase(databasePath);
+    if (!opened.ok)
+        return resultFailure(opened);
+    try {
+        if (isWorkflowId(area) && command === 'run')
+            return runWorkflowRunCommand(area, parsed, opened.value);
+        if (isWorkflowId(area) && command === 'execute')
+            return runWorkflowExecuteCommand(area, parsed, opened.value, environment);
+        if (area === 'agents')
+            return runAgentCommand(command, parsed, opened.value, environment);
+        if (area === 'subagents')
+            return runSubagentCommand(command, parsed, opened.value, environment);
+        if (area === 'memory')
+            return runMemoryCommand(command, parsed, opened.value);
+        if (area === 'approvals')
+            return runApprovalsCommand(command, parsed, opened.value);
+        if (area === 'runs')
+            return runRunsCommand(command, parsed, opened.value, environment);
+        if (area === 'permissions')
+            return runPermissionsCommand(command, parsed, opened.value, environment);
+        if (area === 'skills')
+            return runSkillCommand(command, parsed, opened.value, environment);
+        if (area === 'sdd')
+            return runSddCommand(command, parsed, opened.value, environment);
+        if (area === 'orchestrator')
+            return runOrchestratorCommand(command, parsed, opened.value);
+        if (area === 'opencode')
+            return runOpenCodeCommand(command, parsed, opened.value, environment);
+        if (area === 'dashboard')
+            return runDashboardCommand(command, parsed, opened.value, environment, databasePath);
+        return usageFailure(`Unknown command area: ${area}`);
+    }
+    finally {
+        opened.value.close();
+    }
+}
+function runWorkflowPreviewCommand(workflow, parsed) {
+    const project = optionalStringFlag(parsed.flags, 'project') ?? 'vgxness';
+    const intent = optionalStringFlag(parsed.flags, 'intent') ?? parsed.positionals.slice(2).join(' ').trim();
+    const selected = getWorkflowDefinition(workflow);
+    return jsonResult({
+        ok: true,
+        value: {
+            workflow: selected,
+            registry: listWorkflows(),
+            ...(intent.length > 0 ? { planner: createNaturalLanguagePlan({ project, intent }) } : {}),
+            safety: {
+                executed: false,
+                callsProvider: false,
+                editsFiles: false,
+                writesProviderConfig: false,
+                recordsRuns: false,
+            },
+        },
+    });
+}
+function runWorkflowRunCommand(workflow, parsed, database) {
+    const project = optionalStringFlag(parsed.flags, 'project') ?? 'vgxness';
+    const intent = requiredFlag(parsed.flags, 'intent');
+    if (!intent.ok)
+        return resultFailure(intent);
+    const selected = getWorkflowDefinition(workflow);
+    const planner = createNaturalLanguagePlan({ project, intent: intent.value });
+    const recommended = getWorkflowDefinition(planner.workflow);
+    const phase = optionalStringFlag(parsed.flags, 'phase') ?? selected.defaultPhase;
+    if (selected.id === 'sdd' && !isSddPhase(phase))
+        return resultFailure(validationFailure(`Unknown SDD phase: ${phase}. Expected one of: ${sddPhases.join(', ')}`));
+    const providerAdapter = optionalStringFlag(parsed.flags, 'provider-adapter') ?? 'opencode';
+    const model = optionalStringFlag(parsed.flags, 'model') ?? 'openai/gpt-5.5';
+    const registry = new AgentRegistryService(database);
+    const explicitAgentId = optionalStringFlag(parsed.flags, 'agent-id');
+    const selectedAgent = resolveWorkflowRunAgent({
+        registry,
+        project,
+        intent: intent.value,
+        workflow: selected.id,
+        phase,
+        providerAdapter,
+        ...(explicitAgentId !== undefined ? { explicitAgentId } : {}),
+    });
+    if (!selectedAgent.ok)
+        return jsonResult({ ok: true, value: selectedAgent.value });
+    const service = new RunService(database);
+    const created = service.createRun({
+        project,
+        userIntent: intent.value,
+        workflow: selected.id,
+        phase,
+        selectedAgentId: selectedAgent.value.agent.id,
+        providerAdapter,
+        model,
+    });
+    if (!created.ok)
+        return resultFailure(created);
+    const executionSafety = workflowRunSafety(selected);
+    const recommendation = workflowRunRecommendation(selected, recommended, planner);
+    const checkpointState = toJsonValue({
+        kind: 'workflow-run-plan',
+        version: 1,
+        workflow: selected,
+        planner,
+        safety: executionSafety,
+        recommendation,
+        selectedAgent: selectedAgent.value.summary,
+        nextAction: workflowRunNextAction(selected, recommended, planner),
+    });
+    const checkpoint = service.appendCheckpoint({
+        runId: created.value.id,
+        label: 'workflow-run-planned',
+        state: checkpointState,
+    });
+    if (!checkpoint.ok)
+        return resultFailure(checkpoint);
+    return jsonResult({
+        ok: true,
+        value: {
+            ok: true,
+            runId: created.value.id,
+            workflow: selected,
+            phase,
+            selectedAgent: selectedAgent.value.summary,
+            planner: {
+                workflow: planner.workflow,
+                flow: planner.flow,
+                confidence: planner.confidence,
+                reason: planner.reason,
+                signals: planner.signals,
+                needsClarification: planner.needsClarification,
+            },
+            safety: executionSafety,
+            checkpointId: checkpoint.value.id,
+            recommendation,
+            nextAction: workflowRunNextAction(selected, recommended, planner),
+        },
+    });
+}
+function runWorkflowExecuteCommand(workflow, parsed, database, environment) {
+    const runId = requiredFlag(parsed.flags, 'run-id');
+    if (!runId.ok)
+        return resultFailure(runId);
+    const service = new RunService(database);
+    const details = service.getRun(runId.value);
+    if (!details.ok)
+        return resultFailure(details);
+    const selected = getWorkflowDefinition(workflow);
+    if (details.value.workflow !== selected.id) {
+        const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, 'workflow-execution-blocked', {
+            kind: 'workflow-execution-blocked',
+            version: 1,
+            runId: details.value.id,
+            requestedWorkflow: selected.id,
+            runWorkflow: details.value.workflow,
+            status: 'blocked',
+            dispatched: false,
+            reason: 'workflow-mismatch',
+            message: `Run ${details.value.id} belongs to workflow ${details.value.workflow}, not ${selected.id}.`,
+            safety: workflowExecutionSafety(false),
+        });
+        if (!checkpoint.ok)
+            return resultFailure(checkpoint);
+        return jsonResult({ ok: true, value: workflowExecutionBlockedValue(details.value.id, selected.id, 'workflow-mismatch', 'Run workflow does not match the execute command.', checkpoint) });
+    }
+    const agent = new AgentRegistryService(database).getAgent(details.value.selectedAgentId);
+    if (!agent.ok) {
+        const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, 'workflow-execution-blocked', {
+            kind: 'workflow-execution-blocked',
+            version: 1,
+            runId: details.value.id,
+            workflow: selected.id,
+            status: 'blocked',
+            dispatched: false,
+            reason: 'selected-agent-unresolved',
+            message: agent.error.message,
+            selectedAgentId: details.value.selectedAgentId,
+            safety: workflowExecutionSafety(false),
+        });
+        if (!checkpoint.ok)
+            return resultFailure(checkpoint);
+        return jsonResult({ ok: true, value: workflowExecutionBlockedValue(details.value.id, selected.id, 'selected-agent-unresolved', agent.error.message, checkpoint) });
+    }
+    const agentGate = validateWorkflowExecutionAgent(agent.value, details.value, selected);
+    if (!agentGate.ok) {
+        const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, 'workflow-execution-blocked', {
+            kind: 'workflow-execution-blocked',
+            version: 1,
+            runId: details.value.id,
+            workflow: selected.id,
+            status: 'blocked',
+            dispatched: false,
+            reason: agentGate.reason,
+            message: agentGate.message,
+            selectedAgent: workflowRunAgentSummary(agent.value, { policy: 'run-selected-agent', reasons: ['run.selectedAgentId resolved to a real registry agent'] }),
+            safety: workflowExecutionSafety(false),
+        });
+        if (!checkpoint.ok)
+            return resultFailure(checkpoint);
+        return jsonResult({ ok: true, value: workflowExecutionBlockedValue(details.value.id, selected.id, agentGate.reason, agentGate.message, checkpoint) });
+    }
+    if (parsed.flags.confirm !== true) {
+        const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, 'workflow-execution-blocked', {
+            kind: 'workflow-execution-blocked',
+            version: 1,
+            runId: details.value.id,
+            workflow: selected.id,
+            status: 'blocked',
+            dispatched: false,
+            reason: 'missing-confirmation',
+            message: 'Explicit --confirm is required before delegated workflow execution can be requested.',
+            selectedAgent: workflowRunAgentSummary(agent.value, { policy: 'run-selected-agent', reasons: ['run.selectedAgentId resolved to a real registry agent'] }),
+            safety: workflowExecutionSafety(false),
+            nextAction: `Re-run: vgxness ${selected.id} execute --run-id ${details.value.id} --confirm`,
+        });
+        if (!checkpoint.ok)
+            return resultFailure(checkpoint);
+        return jsonResult({ ok: true, value: workflowExecutionBlockedValue(details.value.id, selected.id, 'missing-confirmation', 'Explicit --confirm is required.', checkpoint) });
+    }
+    const planner = createNaturalLanguagePlan({ project: details.value.project, intent: details.value.userIntent });
+    const recommended = getWorkflowDefinition(planner.workflow);
+    const recommendation = workflowRunRecommendation(selected, recommended, planner);
+    if (recommended.id === 'sdd' && selected.id !== 'sdd' && parsed.flags['override-escalation'] !== true) {
+        const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, 'workflow-execution-blocked', {
+            kind: 'workflow-execution-blocked',
+            version: 1,
+            runId: details.value.id,
+            workflow: selected.id,
+            status: 'blocked',
+            dispatched: false,
+            reason: 'escalation-recommended',
+            message: 'Planner recommends formal SDD; delegated lightweight execution is blocked unless --override-escalation is supplied.',
+            recommendation,
+            planner,
+            selectedAgent: workflowRunAgentSummary(agent.value, { policy: 'run-selected-agent', reasons: ['run.selectedAgentId resolved to a real registry agent'] }),
+            safety: workflowExecutionSafety(false),
+            nextAction: workflowRunNextAction(selected, recommended, planner),
+        });
+        if (!checkpoint.ok)
+            return resultFailure(checkpoint);
+        return jsonResult({ ok: true, value: workflowExecutionBlockedValue(details.value.id, selected.id, 'escalation-recommended', 'Planner recommends formal SDD; supply --override-escalation only after human review.', checkpoint, recommendation) });
+    }
+    const workspaceRoot = optionalStringFlag(parsed.flags, 'workspace') ?? environment.cwd;
+    const executorMode = optionalStringFlag(parsed.flags, 'executor') ?? 'safe-non-dispatching';
+    if (executorMode !== 'safe-non-dispatching' && executorMode !== 'provider' && executorMode !== 'command')
+        return resultFailure(validationFailure(`Unknown workflow executor: ${executorMode}. Expected safe-non-dispatching, provider, or command.`));
+    const commandId = optionalStringFlag(parsed.flags, 'command');
+    if (executorMode === 'command' && commandId === undefined)
+        return resultFailure(validationFailure(`--executor command requires --command <name>. Allowlisted commands: ${commandAllowlistIds().join(', ')}`));
+    if (executorMode !== 'command' && commandId !== undefined)
+        return resultFailure(validationFailure('--command can only be used with --executor command'));
+    const commandTargets = optionalStringFlag(parsed.flags, 'command-targets')?.split(',').map((item) => item.trim()).filter((item) => item.length > 0) ?? [];
+    let commandAdapter;
+    if (executorMode === 'command') {
+        try {
+            const commandCwd = optionalStringFlag(parsed.flags, 'command-cwd');
+            commandAdapter = new CommandAllowlistAdapter({
+                commandId: commandId ?? '',
+                workspaceRoot,
+                targetPaths: commandTargets,
+                ...(commandCwd === undefined ? {} : { cwd: commandCwd }),
+            });
+        }
+        catch (error) {
+            return resultFailure(validationFailure(error instanceof Error ? error.message : 'Command allowlist adapter rejected the request.'));
+        }
+    }
+    const operation = {
+        category: executorMode === 'command' ? 'shell' : 'provider-tool',
+        operation: executorMode === 'command' ? `command-allowlist:${commandId}` : 'workflow-delegated-dispatch',
+        ...(executorMode === 'command' ? {} : { providerToolName: `${details.value.providerAdapter}:workflow-dispatch` }),
+        workspaceRoot,
+        agent: agent.value,
+        ambiguous: executorMode !== 'command',
+        input: toJsonValue({
+            runId: details.value.id,
+            project: details.value.project,
+            workflow: selected.id,
+            phase: details.value.phase,
+            userIntent: details.value.userIntent,
+            providerAdapter: details.value.providerAdapter,
+            model: details.value.model,
+            selectedAgentId: agent.value.id,
+            requestedBy: 'cli-workflow-execute',
+            ...(executorMode === 'command' ? { command: commandId, allowlistedCommand: commandAdapter?.plan.request.argv ?? [] } : {}),
+        }),
+    };
+    const preflight = service.preflightOperation({ runId: details.value.id, ...operation });
+    if (!preflight.ok)
+        return resultFailure(preflight);
+    if (preflight.value.outcome === 'approval-needed') {
+        const pending = recordWorkflowPendingApproval(service, details.value.id, operation, executorMode, preflight.value);
+        if (!pending.ok)
+            return resultFailure(pending);
+    }
+    const selectedAgentSummary = workflowRunAgentSummary(agent.value, { policy: 'run-selected-agent', reasons: ['run.selectedAgentId resolved to a real registry agent'] });
+    const executor = executorMode === 'provider' || executorMode === 'command'
+        ? new GuardedProviderWorkflowExecutor({
+            ...(commandAdapter === undefined ? {} : { adapter: commandAdapter }),
+            capabilities: {
+                sandboxEnforceable: commandAdapter !== undefined,
+                processExecutionEnforceable: commandAdapter !== undefined,
+                workspaceBoundaryEnforced: commandAdapter !== undefined,
+                providerConfigWritesBlocked: commandAdapter !== undefined,
+            },
+        })
+        : new SafeNonDispatchingWorkflowExecutor();
+    const executorResult = executor.execute({
+        run: details.value,
+        workflow: selected,
+        selectedAgent: agent.value,
+        selectedAgentSummary,
+        workspaceRoot,
+        requestedOperation: operation,
+        preflight: preflight.value,
+        ...(commandAdapter === undefined ? {} : { sandboxExecutionEvidence: commandAdapter.plan.evidence }),
+        gates: {
+            validRunId: true,
+            workflowMatchesRun: true,
+            selectedAgentReal: true,
+            selectedAgentMatchesRun: true,
+            workspaceRoot,
+            confirmed: true,
+            escalationOverride: parsed.flags['override-escalation'] === true,
+        },
+        plannerRecommendation: { planner, recommendation },
+    });
+    const checkpoint = appendWorkflowExecutionCheckpoint(service, details.value.id, executorResult.checkpointLabel, executorResult.checkpointPayload);
+    if (!checkpoint.ok)
+        return resultFailure(checkpoint);
+    return jsonResult({ ok: true, value: {
+            ok: true,
+            runId: details.value.id,
+            workflow: selected.id,
+            phase: details.value.phase,
+            status: executorResult.status,
+            dispatched: executorResult.dispatched,
+            dispatchMode: executorResult.dispatchMode,
+            executorId: executorResult.executorId,
+            executorKind: executorResult.executorKind,
+            reason: executorResult.reason,
+            message: executorResult.message,
+            selectedAgent: selectedAgentSummary,
+            preflight: {
+                outcome: preflight.value.outcome,
+                decision: preflight.value.decision,
+                audit: preflight.value.audit,
+                eligibleForFutureExecution: preflight.value.eligibleForFutureExecution,
+                safety: preflight.value.safety,
+            },
+            executorAudit: executorResult.audit,
+            checkpointId: checkpoint.value.id,
+            safety: workflowExecutionSafety(true),
+            nextAction: executorResult.nextAction,
+        } });
+}
+function recordWorkflowPendingApproval(service, runId, operation, executorMode, preflight) {
+    const approvalId = preflight.approval?.id ?? preflight.audit.approvalId;
+    return service.appendEvent({
+        runId,
+        kind: 'operation-execution',
+        title: `Workflow operation pending approval: ${operation.category} ${operation.operation}`,
+        payload: {
+            status: 'pending-approval',
+            executorName: `workflow-${executorMode}`,
+            requestedOperation: operationMetadataForWorkflowExecution(operation),
+            input: operation.input ?? null,
+            decisionEventId: preflight.permissionEvent.id,
+            approvalId: approvalId ?? null,
+            decision: preflight.decision.decision,
+            reason: preflight.decision.reason,
+            message: preflight.decision.message,
+            executorInvoked: false,
+            operationExecuted: false,
+            timestamp: new Date().toISOString(),
+        },
+        relatedType: 'approval',
+        ...(approvalId === undefined ? {} : { relatedId: approvalId }),
+    });
+}
+function resolveWorkflowRunAgent(input) {
+    if (input.explicitAgentId !== undefined) {
+        const agent = input.registry.getAgent(input.explicitAgentId);
+        if (!agent.ok) {
+            return { ok: false, value: workflowRunBlockedAgentResolution(input, `Explicit --agent-id could not be resolved: ${agent.error.message}`) };
+        }
+        return {
+            ok: true,
+            value: {
+                agent: agent.value,
+                summary: workflowRunAgentSummary(agent.value, {
+                    policy: 'explicit-agent-id',
+                    reasons: ['explicit --agent-id selected a registry agent'],
+                    fallbackReason: null,
+                }),
+            },
+        };
+    }
+    const resolution = input.registry.resolveAgents({
+        project: input.project,
+        scope: 'project',
+        mode: 'agent',
+        workflow: input.workflow,
+        phase: input.phase,
+        providerAdapter: input.providerAdapter,
+        intent: input.intent,
+        taskDescription: input.intent,
+        desiredCapabilities: [],
+    });
+    if (!resolution.ok)
+        return { ok: false, value: workflowRunBlockedAgentResolution(input, resolution.error.message) };
+    const manager = resolution.value.candidates.find((candidate) => candidate.agent.name === 'vgxness-manager');
+    const selected = manager ?? resolution.value.candidates[0];
+    if (selected === undefined) {
+        return {
+            ok: false,
+            value: workflowRunBlockedAgentResolution(input, 'No project agent matched the requested workflow, phase, provider adapter, and project scope. Seed or register vgxness-manager before running workflows.', resolution.value.skipped.map((skipped) => ({ agent: skipped.agent, reasons: skipped.reasons }))),
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            agent: selected.agent,
+            summary: workflowRunAgentSummary(selected.agent, {
+                policy: 'project-manager-preferred',
+                reasons: selected.reasons,
+                fallbackReason: manager === undefined && selected.agent.name !== 'vgxness-manager'
+                    ? 'vgxness-manager was not resolvable for this workflow/phase/provider; selected the highest-scoring project agent instead.'
+                    : null,
+                score: selected.score,
+            }),
+        },
+    };
+}
+function workflowRunAgentSummary(agent, details) {
+    return {
+        id: agent.id,
+        name: agent.name,
+        mode: agent.mode,
+        project: agent.project,
+        scope: agent.scope,
+        workflows: agent.workflows,
+        policy: details.policy,
+        reasons: details.reasons,
+        fallbackReason: details.fallbackReason ?? null,
+        ...(details.score !== undefined ? { score: details.score } : {}),
+    };
+}
+function workflowRunBlockedAgentResolution(input, reason, skipped) {
+    return {
+        ok: false,
+        status: 'blocked',
+        reason,
+        workflow: input.workflow,
+        phase: input.phase,
+        providerAdapter: input.providerAdapter,
+        selectedAgent: null,
+        safety: {
+            executed: false,
+            recordsRuns: false,
+            callsProvider: false,
+            editsFiles: false,
+            writesProviderConfig: false,
+            mutatesSddArtifacts: false,
+        },
+        nextAction: 'Register or seed a real project agent such as vgxness-manager, then retry the workflow run.',
+        ...(skipped !== undefined ? { skipped } : {}),
+    };
+}
+function workflowRunSafety(workflow) {
+    return {
+        executed: true,
+        recordsRuns: true,
+        callsProvider: false,
+        editsFiles: false,
+        writesProviderConfig: false,
+        mutability: workflow.mutability,
+        safetyProfile: workflow.safetyProfile,
+        requiresSddArtifacts: workflow.requiresSddArtifacts,
+        notes: [
+            'Safe run slice: recorded run intent and checkpoint only.',
+            'No provider tools were called, no user files were edited, no provider config was written, and no SDD artifacts were mutated.',
+        ],
+    };
+}
+function workflowRunRecommendation(selected, recommended, planner) {
+    if (selected.id === recommended.id) {
+        return {
+            status: 'aligned',
+            recommendedWorkflow: recommended.id,
+            message: `Planner agrees with explicit ${selected.id} workflow.`,
+        };
+    }
+    return {
+        status: recommended.id === 'sdd' ? 'escalation-recommended' : 'workflow-mismatch',
+        explicitWorkflow: selected.id,
+        recommendedWorkflow: recommended.id,
+        reason: planner.reason,
+        message: recommended.id === 'sdd'
+            ? `Planner recommends formal SDD instead of ${selected.id}; do not continue with mutable lightweight work until reviewed.`
+            : `Planner recommends ${recommended.id} instead of explicit ${selected.id}; review before continuing.`,
+    };
+}
+function workflowRunNextAction(selected, recommended, planner) {
+    if (recommended.id === 'sdd' && selected.id !== 'sdd') {
+        return {
+            type: 'review-escalation',
+            command: planner.suggestedChangeId === undefined ? null : `vgxness sdd next --project ${planner.project} --change ${planner.suggestedChangeId}`,
+            reason: 'Planner detected broad or risky work and recommends the formal SDD workflow before any edits.',
+        };
+    }
+    return {
+        type: selected.id === 'sdd' ? 'continue-sdd' : 'manual-continuation',
+        command: selected.id === 'sdd' && planner.suggestedChangeId !== undefined ? `vgxness sdd next --project ${planner.project} --change ${planner.suggestedChangeId}` : null,
+        reason: selected.id === 'sdd'
+            ? 'Use existing SDD commands to inspect readiness; this run command did not mutate artifacts.'
+            : 'Inspect the recorded checkpoint, then continue manually or through a future approved executor slice.',
+    };
+}
+function appendWorkflowExecutionCheckpoint(service, runId, label, state) {
+    return service.appendCheckpoint({ runId, label, state: toJsonValue(state) });
+}
+function workflowExecutionSafety(preflightRecorded) {
+    return workflowExecutorSafety(preflightRecorded);
+}
+function workflowExecutionBlockedValue(runId, workflow, reason, message, checkpoint, recommendation) {
+    return {
+        ok: false,
+        runId,
+        workflow,
+        status: 'blocked',
+        dispatched: false,
+        reason,
+        message,
+        ...(checkpoint.ok ? { checkpointId: checkpoint.value.id } : {}),
+        ...(recommendation === undefined ? {} : { recommendation }),
+        safety: workflowExecutionSafety(false),
+        nextAction: 'Resolve the blocking safety gate, then re-run the explicit execute command.',
+    };
+}
+function validateWorkflowExecutionAgent(agent, run, workflow) {
+    if (agent.mode !== 'agent')
+        return { ok: false, reason: 'selected-agent-not-primary-agent', message: `Selected registry entry ${agent.id} is ${agent.mode}; delegated workflow execution requires a primary agent.` };
+    if (agent.id !== run.selectedAgentId)
+        return { ok: false, reason: 'selected-agent-mismatch', message: 'Resolved selected agent does not match run.selectedAgentId.' };
+    if (agent.project !== run.project)
+        return { ok: false, reason: 'selected-agent-project-mismatch', message: `Selected agent belongs to project ${agent.project}, not run project ${run.project}.` };
+    if (agent.adapters[run.providerAdapter] === undefined)
+        return { ok: false, reason: 'selected-agent-provider-mismatch', message: `Selected agent has no ${run.providerAdapter} adapter.` };
+    if (!agent.workflows.includes(workflow.id) && !agent.workflows.includes(`${workflow.id}:${run.phase}`)) {
+        return { ok: false, reason: 'selected-agent-workflow-mismatch', message: `Selected agent is not registered for workflow ${workflow.id} or phase ${workflow.id}:${run.phase}.` };
+    }
+    return { ok: true };
+}
+function toJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function runSetupLifecycleCommand(parsed, environment) {
+    const [area, command] = parsed.positionals;
+    if (area === 'setup' && command === 'plan')
+        return runSetupPlanCommand(parsed, environment);
+    if (area === 'setup' && command === 'apply')
+        return usageFailure('setup apply is available through the async CLI entrypoint; run vgxness setup apply --yes from the installed CLI.');
+    if (area === 'setup' && command === 'rollback')
+        return runSetupRollbackCommand(parsed);
+    if (area === 'setup' && command !== 'status')
+        return usageFailure(command === undefined ? 'Missing command for setup' : `Unknown setup command: ${command}`);
+    const scope = scopeFlag(parsed.flags, 'scope', 'project');
+    if (!scope.ok)
+        return resultFailure(scope);
+    const project = optionalStringFlag(parsed.flags, 'project') ?? 'vgxness';
+    const selectedDatabasePath = databasePathFor(parsed.flags, environment);
+    if (!selectedDatabasePath.ok)
+        return resultFailure(selectedDatabasePath);
+    const databasePath = selectedDatabasePath.value;
+    const opened = openCliDatabase(databasePath);
+    const service = createSetupLifecycleService({ opened, databasePath, environment });
+    try {
+        return jsonResult(service.getStatus({ project, projectRoot: environment.cwd, scope: scope.value }));
+    }
+    finally {
+        if (opened.ok)
+            opened.value.close();
+    }
+}
+function runSetupPlanCommand(parsed, environment) {
+    const input = setupPlanInputFromFlags(parsed, environment);
+    if (!input.ok)
+        return resultFailure(input);
+    const plan = createSetupPlan(input.value);
+    return jsonResult(plan);
+}
+function runSetupRollbackCommand(parsed) {
+    const backupPath = optionalStringFlag(parsed.flags, 'backup');
+    if (backupPath === undefined)
+        return usageFailure('setup rollback requires --backup <path>');
+    const result = rollbackConfigBackup({ backupPath: resolve(backupPath) });
+    if (parsed.flags.json === true)
+        return jsonResult(result);
+    if (!result.ok)
+        return resultFailure(result);
+    const lines = [
+        'Rollback restored OpenCode config.',
+        `Target: ${result.value.targetPath}`,
+        `Restored from: ${result.value.backupPath}`,
+        ...(result.value.preRollbackBackupPath === undefined ? [] : [`Pre-rollback backup: ${result.value.preRollbackBackupPath}`]),
+        'Next: vgx doctor; restart OpenCode and verify the vgxness MCP server is visible.',
+    ];
+    return okText(`${lines.join('\n')}\n`);
+}
+async function runSetupApplyCommand(parsed, environment) {
+    if (parsed.flags.yes !== true)
+        return usageFailure('setup apply writes provider config and requires --yes');
+    const input = setupPlanInputFromFlags(parsed, environment);
+    if (!input.ok)
+        return resultFailure(input);
+    const plan = createSetupPlan(input.value);
+    if (!plan.ok)
+        return resultFailure(plan);
+    if (plan.value.status !== 'ready')
+        return resultFailure(validationFailure(`Setup plan is ${plan.value.status}; resolve conflicts before applying.`));
+    if (input.value.provider === 'none')
+        return jsonResult({ ok: true, value: { status: 'manual-required', message: 'Provider is none; there is no config to apply.', plan: plan.value } });
+    const result = await installOpenCodeMcpClient({
+        cwd: environment.cwd,
+        databasePath: plan.value.db.path,
+        databasePathSource: plan.value.db.source === 'global-default' || plan.value.db.source === 'environment' ? plan.value.db.source : 'flag',
+        scope: input.value.scope ?? vgxnessSetupDefaults.defaultOpenCodeScope,
+        env: environment.env,
+        confirmed: true,
+        mcpOnly: input.value.installMode === 'mcp-only',
+    });
+    return result.status === 'installed'
+        ? jsonResult({ ok: true, value: { kind: 'setup-apply-result', version: 1, status: 'installed', plan: plan.value, opencode: result, nextCommands: ['vgx doctor', 'Restart OpenCode and verify the vgxness MCP server is visible.'] } })
+        : resultFailure(validationFailure(`${result.reason}: ${result.message}`));
+}
+function setupPlanInputFromFlags(parsed, environment) {
+    const project = optionalStringFlag(parsed.flags, 'project');
+    const database = setupDatabaseFlags(parsed.flags);
+    if (!database.ok)
+        return database;
+    const provider = setupProviderFlag(parsed.flags);
+    if (!provider.ok)
+        return provider;
+    const scope = opencodeInstallScopeFlag(parsed.flags, 'scope');
+    if (!scope.ok)
+        return scope;
+    const installMode = setupInstallModeFlag(parsed.flags);
+    if (!installMode.ok)
+        return installMode;
+    return {
+        ok: true,
+        value: {
+            ...(project === undefined ? {} : { project }),
+            workspaceRoot: environment.cwd,
+            env: environment.env,
+            databaseMode: database.value.mode,
+            ...(database.value.path === undefined ? {} : { databasePath: database.value.path }),
+            provider: provider.value,
+            scope: scope.value,
+            installMode: installMode.value,
+        },
+    };
+}
+function setupDatabaseFlags(flags) {
+    const dbValue = optionalStringFlag(flags, 'db');
+    const dbPath = optionalStringFlag(flags, 'db-path');
+    if (dbValue === undefined)
+        return { ok: true, value: { mode: vgxnessSetupDefaults.defaultDatabaseMode } };
+    if (dbValue === 'global' || dbValue === 'project-local')
+        return { ok: true, value: { mode: dbValue } };
+    if (dbValue === 'custom')
+        return dbPath === undefined ? validationFailure('--db custom requires --db-path <path>') : { ok: true, value: { mode: 'custom', path: dbPath } };
+    return { ok: true, value: { mode: 'custom', path: dbValue } };
+}
+function setupProviderFlag(flags) {
+    const value = optionalStringFlag(flags, 'provider') ?? vgxnessSetupDefaults.defaultProvider;
+    return value === 'opencode' || value === 'none' ? { ok: true, value } : validationFailure('--provider must be opencode or none');
+}
+function setupInstallModeFlag(flags) {
+    const value = optionalStringFlag(flags, 'mode');
+    if (value !== undefined)
+        return value === 'mcp-only' || value === 'mcp-plus-agents' ? { ok: true, value } : validationFailure('--mode must be mcp-only or mcp-plus-agents');
+    if (flags['mcp-only'] === true || flags['no-agents'] === true)
+        return { ok: true, value: 'mcp-only' };
+    return { ok: true, value: vgxnessSetupDefaults.defaultInstallMode };
+}
+function runDoctorAliasCommand(parsed, environment) {
+    return runMcpDoctorCommand({ ...parsed, positionals: ['mcp', 'doctor', ...parsed.positionals.slice(1)] }, environment);
+}
+function createSetupLifecycleService(input) {
+    return new SetupLifecycleService({
+        store: () => input.opened.ok ? { ok: true, value: { path: input.databasePath } } : input.opened,
+        mcp: (setupInput) => {
+            const visibility = createOpenCodeMcpVisibilityReport({ cwd: input.environment.cwd, projectRoot: setupInput.projectRoot });
+            const preview = createMcpClientSetupPreview({ provider: 'opencode', databasePath: setupInput.databasePath ?? input.databasePath });
+            return {
+                ok: true,
+                value: {
+                    ready: visibility.ready,
+                    evidence: setupMcpEvidence(visibility, preview),
+                    nextAction: visibility.ready ? 'Run `opencode mcp list` from inside the project to verify visibility.' : 'Preview OpenCode MCP setup, inspect `mcp install opencode --plan`, then apply with `--yes` only after review.',
+                },
+            };
+        },
+        defaultContext: (setupInput) => {
+            if (!input.opened.ok)
+                return validationFailure('Default context cannot be read until the local store is available.');
+            if (setupInput.project === undefined)
+                return validationFailure('Default context cannot be read until a project is selected.');
+            const registry = new AgentRegistryService(input.opened.value);
+            const agent = registry.getAgentByName(setupInput.project, setupInput.scope ?? 'project', setupInput.agentName);
+            if (!agent.ok)
+                return agent;
+            const selection = resolveAgentProfileModel({ agent: agent.value, providerAdapter: 'opencode' });
+            if (!selection.ok)
+                return selection;
+            return {
+                ok: true,
+                value: {
+                    agentId: agent.value.id,
+                    providerAdapter: selection.value.providerAdapter,
+                    model: selection.value.model,
+                    ...(selection.value.profile === undefined ? {} : { profile: selection.value.profile }),
+                },
+            };
+        },
+    });
+}
+function readSetupStatus(service, input) {
+    return service.getStatus(input);
+}
+function collectRunInsights(service, runs) {
+    const insightsByRunId = {};
+    for (const run of runs) {
+        const insights = service.getRunInsights(run.id);
+        if (!insights.ok)
+            return insights;
+        insightsByRunId[run.id] = insights.value;
+    }
+    return { ok: true, value: insightsByRunId };
+}
+function collectRunDetails(service, runs) {
+    const detailsByRunId = {};
+    for (const run of runs) {
+        const details = service.getRun(run.id);
+        if (!details.ok)
+            return details;
+        detailsByRunId[run.id] = details.value;
+    }
+    return { ok: true, value: detailsByRunId };
+}
+function setupMcpEvidence(visibility, preview) {
+    return [
+        visibility.ready ? 'OpenCode project config defines mcp.vgxness and is visible from the current working directory.' : `OpenCode MCP visibility is not ready at ${visibility.targetPath}.`,
+        `Preview command targets ${preview.server.args.join(' ')}.`,
+        ...visibility.guidance,
+    ];
+}
+export async function dispatchCliAsync(argv, environment) {
+    const parsed = parseArgs(argv);
+    const [area, command] = parsed.positionals;
+    if (argv.length === 0)
+        return runDashboardInteractiveCommand({ positionals: ['dashboard', 'interactive'], flags: parsed.flags }, environment);
+    if (area === 'dashboard' && command === 'interactive')
+        return runDashboardInteractiveCommand(parsed, environment);
+    if (area === 'mcp') {
+        if (!command)
+            return usageFailure('Missing command for mcp');
+        if (command === 'install')
+            return runMcpInstallCommand(parsed, environment);
+        if (command === 'setup')
+            return runMcpSetupCommand(parsed, environment);
+        if (command === 'doctor')
+            return runMcpDoctorCommand(parsed, environment);
+        return usageFailure(`Unknown mcp command: ${command}`);
+    }
+    if (area === 'doctor')
+        return runDoctorAliasCommand(parsed, environment);
+    if (area === 'init')
+        return runInitCommand(parsed, environment);
+    if (area === 'setup' && command === 'apply')
+        return runSetupApplyCommand(parsed, environment);
+    if (area === 'setup' && command === 'rollback')
+        return runSetupRollbackCommand(parsed);
+    return dispatchCli(argv, environment);
+}
+async function runInitCommand(parsed, environment) {
+    if (parsed.flags.plan === true || parsed.flags.json === true)
+        return runSetupPlanCommand(parsed, environment);
+    if (parsed.flags.yes === true)
+        return runSetupApplyCommand({ ...parsed, flags: { ...parsed.flags, yes: true } }, environment);
+    const terminal = environment.stdin?.isTTY === true && environment.stdout?.isTTY === true;
+    if (!terminal)
+        return runSetupPlanCommand(parsed, environment);
+    const defaults = defaultWizardInput(environment);
+    const answers = await promptSetupWizard(environment, defaults);
+    if (!answers.ok)
+        return resultFailure(answers);
+    const plan = createSetupPlan(answers.value.input);
+    if (!plan.ok)
+        return resultFailure(plan);
+    environment.stdout?.write(renderSetupPlanForHumans(plan.value));
+    const confirmation = (await promptLine(environment, 'Apply this setup? Type "yes" to continue: ')).trim();
+    if (confirmation !== 'yes') {
+        return okText('No changes were made. Next: run `vgx init --plan` to review the plan or `vgx setup apply --yes` when ready.\n');
+    }
+    return runSetupApplyCommand({ ...parsed, flags: answers.value.flags }, environment);
+}
+function defaultWizardInput(environment) {
+    return {
+        project: environment.cwd.replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'vgxness',
+        databaseMode: vgxnessSetupDefaults.defaultDatabaseMode,
+        provider: vgxnessSetupDefaults.defaultProvider,
+        scope: vgxnessSetupDefaults.defaultOpenCodeScope,
+        installMode: vgxnessSetupDefaults.defaultInstallMode,
+    };
+}
+async function promptSetupWizard(environment, defaults) {
+    const project = defaulted(await promptLine(environment, `Project name [${defaults.project}]: `), defaults.project);
+    const db = defaulted(await promptLine(environment, 'DB location: global default, project-local, custom path [global]: '), defaults.databaseMode);
+    const databaseMode = db === 'global default' || db === 'global' ? 'global' : db === 'project-local' ? 'project-local' : db === 'custom path' || db === 'custom' ? 'custom' : undefined;
+    if (databaseMode === undefined)
+        return validationFailure('DB location must be global, project-local, or custom path.');
+    const databasePath = databaseMode === 'custom' ? defaulted(await promptLine(environment, 'Custom DB path: '), '') : undefined;
+    if (databaseMode === 'custom' && (databasePath ?? '').length === 0)
+        return validationFailure('Custom DB path is required.');
+    const providerText = defaulted(await promptLine(environment, 'Provider: OpenCode, none/manual [OpenCode]: '), defaults.provider);
+    const provider = providerText.toLowerCase() === 'opencode' ? 'opencode' : providerText.toLowerCase() === 'none/manual' || providerText.toLowerCase() === 'none' || providerText.toLowerCase() === 'manual' ? 'none' : undefined;
+    if (provider === undefined)
+        return validationFailure('Provider must be OpenCode or none/manual.');
+    const scopeText = defaulted(await promptLine(environment, 'OpenCode scope: project, user [project]: '), defaults.scope);
+    const scope = scopeText === 'project' || scopeText === 'user' ? scopeText : undefined;
+    if (scope === undefined)
+        return validationFailure('OpenCode scope must be project or user.');
+    const modeText = defaulted(await promptLine(environment, 'Install mode: MCP + manager/SDD agents, MCP only [MCP + manager/SDD agents]: '), defaults.installMode);
+    const installMode = modeText === 'mcp-plus-agents' || modeText.toLowerCase() === 'mcp + manager/sdd agents' ? 'mcp-plus-agents' : modeText === 'mcp-only' || modeText.toLowerCase() === 'mcp only' ? 'mcp-only' : undefined;
+    if (installMode === undefined)
+        return validationFailure('Install mode must be MCP + manager/SDD agents or MCP only.');
+    const input = { project, workspaceRoot: environment.cwd, env: environment.env, databaseMode, ...(databasePath === undefined ? {} : { databasePath }), provider, scope, installMode };
+    const flags = { project, db: databaseMode, provider, scope, mode: installMode, yes: true, ...(databasePath === undefined ? {} : { 'db-path': databasePath }) };
+    return { ok: true, value: { input, flags } };
+}
+function defaulted(value, fallback) {
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? fallback : trimmed;
+}
+function promptLine(environment, prompt) {
+    environment.stdout?.write(prompt);
+    const stdin = environment.stdin;
+    if (stdin === undefined)
+        return Promise.resolve('');
+    const buffered = promptBuffers.get(stdin) ?? '';
+    const immediateNewline = buffered.search(/\r?\n/);
+    if (immediateNewline >= 0) {
+        const line = buffered.slice(0, immediateNewline);
+        promptBuffers.set(stdin, buffered.slice(immediateNewline + (buffered[immediateNewline] === '\r' && buffered[immediateNewline + 1] === '\n' ? 2 : 1)));
+        return Promise.resolve(line);
+    }
+    return new Promise((resolveLine) => {
+        const listener = (chunk) => {
+            const nextBuffered = (promptBuffers.get(stdin) ?? '') + chunk.toString();
+            const newline = nextBuffered.search(/\r?\n/);
+            if (newline >= 0) {
+                cleanup();
+                const line = nextBuffered.slice(0, newline);
+                promptBuffers.set(stdin, nextBuffered.slice(newline + (nextBuffered[newline] === '\r' && nextBuffered[newline + 1] === '\n' ? 2 : 1)));
+                resolveLine(line);
+            }
+            else {
+                promptBuffers.set(stdin, nextBuffered);
+            }
+        };
+        const cleanup = () => {
+            if (stdin.off !== undefined)
+                stdin.off('data', listener);
+            else
+                stdin.removeListener?.('data', listener);
+        };
+        stdin.on('data', listener);
+        stdin.resume?.();
+    });
+}
+function renderSetupPlanForHumans(plan) {
+    const actions = plan.actions.map((action) => `- ${action.description}${action.targetPath === undefined ? '' : ` (${action.targetPath})`}`).join('\n') || '- No provider config writes planned.';
+    const backups = plan.backupsPlanned.map((backup) => `- ${backup.targetPath}: ${backup.reason}`).join('\n') || '- None.';
+    return `\nSetup plan\nProject: ${plan.project}\nDatabase: ${plan.db.mode} (${plan.db.path})\nProvider: ${plan.provider}\nStatus: ${plan.status}\nActions:\n${actions}\nBackups:\n${backups}\n\n`;
+}
+async function runDashboardInteractiveCommand(parsed, environment) {
+    const project = optionalStringFlag(parsed.flags, 'project');
+    const terminal = resolveInteractiveTerminal(environment);
+    if (!terminal.ok)
+        return resultFailure(terminal);
+    const limit = optionalNumberFlag(parsed.flags, 'limit');
+    if (!limit.ok)
+        return resultFailure(limit);
+    const selectedDatabasePath = databasePathFor(parsed.flags, environment);
+    if (!selectedDatabasePath.ok)
+        return resultFailure(selectedDatabasePath);
+    const databasePath = selectedDatabasePath.value;
+    const opened = openCliDatabase(databasePath);
+    if (!opened.ok)
+        return resultFailure(opened);
+    try {
+        const runs = new RunService(opened.value);
+        const sdd = new SddWorkflowService(new MemoryService(opened.value));
+        const setup = createSetupLifecycleService({ opened, databasePath, environment });
+        const agents = new AgentRegistryService(opened.value);
+        const skills = new SkillRegistryService(opened.value);
+        const managerProfiles = new ManagerProfileOverlayService({ agents, overlays: new ManagerProfileOverlayRepository(opened.value) });
+        const change = optionalStringFlag(parsed.flags, 'change');
+        const loader = () => {
+            if (project === undefined) {
+                const setupStatus = readSetupStatus(setup, { projectRoot: environment.cwd, scope: 'project' });
+                const sectionErrors = {};
+                if (!setupStatus.ok)
+                    sectionErrors.setup = sanitizeDashboardError(setupStatus.error.message);
+                return {
+                    ok: true,
+                    value: {
+                        runs: [],
+                        workflows: buildDashboardWorkflowsReadModel({ generatedAt: new Date().toISOString() }),
+                        operationalRuns: buildDashboardRunsReadModel({ runs: [], generatedAt: new Date().toISOString() }),
+                        approvals: buildDashboardApprovalsReadModel({ runs: [], generatedAt: new Date().toISOString() }),
+                        doctor: { status: 'ready-without-project', summary: 'No project selected; environment-only dashboard checks are available.', warnings: ['Project-scoped run, SDD, approval, and agent checks are deferred.'], commands: ['npm run cli -- setup status', 'npm run cli -- mcp setup --provider opencode --preview'] },
+                        ...(setupStatus.ok ? { setup: setupStatus.value } : {}),
+                        sectionErrors,
+                    },
+                };
+            }
+            const listed = runs.listRuns({ project });
+            if (!listed.ok)
+                return listed;
+            const visibleRuns = listed.value.slice(0, limit.value ?? 10);
+            const details = collectRunDetails(runs, visibleRuns);
+            if (!details.ok)
+                return details;
+            const insights = collectRunInsights(runs, visibleRuns);
+            if (!insights.ok)
+                return insights;
+            const generatedAt = new Date().toISOString();
+            const workflowsReadModel = buildDashboardWorkflowsReadModel({ project, runs: visibleRuns, generatedAt });
+            const operationalRuns = buildDashboardRunsReadModel({ project, runs: visibleRuns, detailsByRunId: details.value, insightsByRunId: insights.value, generatedAt });
+            const approvalsReadModel = buildDashboardApprovalsReadModel({ project, runs: visibleRuns, detailsByRunId: details.value, generatedAt });
+            const setupStatus = readSetupStatus(setup, { project, projectRoot: environment.cwd, scope: 'project' });
+            const sectionErrors = {};
+            if (!setupStatus.ok)
+                sectionErrors.setup = sanitizeDashboardError(setupStatus.error.message);
+            const profiles = buildDashboardProfiles(managerProfiles, project, setupStatus.ok ? setupStatus.value : undefined, sectionErrors);
+            const agentsSkills = buildDashboardAgentsSkills(agents, skills, project, limit.value ?? 10, sectionErrors);
+            const doctor = buildDashboardDoctor(project, setupStatus.ok ? setupStatus.value : undefined, sectionErrors);
+            if (change === undefined)
+                return { ok: true, value: { runs: visibleRuns, runInsights: insights.value, workflows: workflowsReadModel, operationalRuns, approvals: approvalsReadModel, ...(setupStatus.ok ? { setup: setupStatus.value } : {}), profiles, agentsSkills, doctor, sectionErrors } };
+            const status = sdd.getDashboardStatus({ project, change });
+            if (!status.ok)
+                sectionErrors.sdd = sanitizeDashboardError(status.error.message);
+            const readiness = status.ok && status.value.nextReadyPhase !== undefined ? sdd.getReady({ project, change, phase: status.value.nextReadyPhase }) : undefined;
+            if (readiness !== undefined && !readiness.ok)
+                sectionErrors.sdd = sanitizeDashboardError(readiness.error.message);
+            return {
+                ok: true,
+                value: {
+                    runs: visibleRuns,
+                    runInsights: insights.value,
+                    workflows: workflowsReadModel,
+                    operationalRuns,
+                    approvals: approvalsReadModel,
+                    ...(setupStatus.ok ? { setup: setupStatus.value } : {}),
+                    ...(status.ok ? { sdd: { change, status: status.value, ...(readiness?.ok ? { readiness: readiness.value } : {}) } } : {}),
+                    profiles,
+                    agentsSkills,
+                    doctor,
+                    sectionErrors,
+                },
+            };
+        };
+        await runInteractiveDashboardLoop({ ...(project === undefined ? {} : { project }), loader, input: terminal.value.input, output: terminal.value.output, env: environment.env });
+        return { exitCode: 0, stdout: '', stderr: '' };
+    }
+    finally {
+        opened.value.close();
+    }
+}
+function buildDashboardProfiles(managerProfiles, project, setupStatus, sectionErrors) {
+    const resolved = managerProfiles.resolveEffectiveManager({ project, scope: 'project', managerName: 'vgxness-manager' });
+    if (!resolved.ok) {
+        sectionErrors.agents = sanitizeDashboardError(resolved.error.message);
+        return { status: setupStatus === undefined ? 'error' : 'blocked', managerName: 'vgxness-manager', scope: 'project', error: sectionErrors.agents };
+    }
+    const providerAdapter = setupStatus?.defaults.providerAdapter ?? Object.keys(resolved.value.manager.adapters)[0];
+    const adapter = providerAdapter === undefined ? undefined : resolved.value.manager.adapters[providerAdapter];
+    return {
+        status: providerAdapter === undefined && adapter?.model === undefined ? 'empty' : 'ready',
+        managerName: 'vgxness-manager',
+        scope: 'project',
+        agentId: resolved.value.manager.id,
+        ...(providerAdapter === undefined ? {} : { providerAdapter }),
+        ...(adapter?.model === undefined ? setupStatus?.defaults.model === undefined ? {} : { model: setupStatus.defaults.model } : { model: adapter.model }),
+        ...(setupStatus?.defaults.profile === undefined ? {} : { profile: setupStatus.defaults.profile }),
+        overlayPresent: resolved.value.overlay !== undefined,
+    };
+}
+function buildDashboardAgentsSkills(agents, skills, project, limit, sectionErrors) {
+    const agentList = agents.listAgents({ project, scope: 'project' });
+    const skillList = skills.listSkills({ project, scope: 'project' });
+    if (!agentList.ok)
+        sectionErrors.agents = sanitizeDashboardError(agentList.error.message);
+    if (!skillList.ok)
+        sectionErrors.agents = sanitizeDashboardError(skillList.error.message);
+    const agentValues = agentList.ok ? agentList.value : [];
+    const skillValues = skillList.ok ? skillList.value : [];
+    const visibleAgents = agentValues.slice(0, limit).map((summary) => {
+        const details = agents.getAgent(summary.id);
+        const providerAdapter = details.ok ? Object.keys(details.value.adapters)[0] : undefined;
+        const model = details.ok && providerAdapter !== undefined ? details.value.adapters[providerAdapter]?.model : undefined;
+        return {
+            id: summary.id,
+            name: summary.name,
+            mode: summary.mode,
+            scope: summary.scope,
+            description: summary.description,
+            ...(providerAdapter === undefined ? {} : { providerAdapter }),
+            ...(model === undefined ? {} : { model }),
+            ...(summary.parentAgentId === undefined ? {} : { parentAgentId: summary.parentAgentId }),
+        };
+    });
+    const visibleSkills = skillValues.slice(0, limit).map((skill) => ({ id: skill.id, name: skill.name, scope: skill.scope, description: skill.description }));
+    const status = sectionErrors.agents !== undefined ? 'error' : visibleAgents.length === 0 && visibleSkills.length === 0 ? 'empty' : 'ready';
+    return { status, agents: visibleAgents, skills: visibleSkills, truncated: agentValues.length > limit || skillValues.length > limit, ...(sectionErrors.agents === undefined ? {} : { error: sectionErrors.agents }) };
+}
+function buildDashboardDoctor(project, setupStatus, sectionErrors) {
+    void sectionErrors;
+    if (setupStatus === undefined) {
+        return { status: 'empty', summary: 'No setup evidence is available; the TUI did not run doctor checks.', warnings: ['Doctor execution is explicit because checks may prepare local state.'], commands: ['npm run cli -- mcp doctor', 'npm run cli -- mcp doctor opencode'] };
+    }
+    const blocked = setupStatus.store.status !== 'ready' || setupStatus.defaults.status !== 'ready' || setupStatus.mcp.status !== 'ready';
+    return {
+        status: blocked ? 'blocked' : 'ready',
+        summary: blocked ? `Setup diagnostics need attention for ${project}: ${setupStatus.nextAction.reason}` : `Setup evidence is ready for ${project}; run doctor outside TUI for fresh checks.`,
+        warnings: [...setupStatus.mcp.evidence, 'The TUI never executes doctor checks implicitly.'].slice(0, 4),
+        commands: ['npm run cli -- mcp doctor', 'npm run cli -- mcp doctor opencode', 'npm run cli -- setup status'],
+    };
+}
+async function runInteractiveDashboardLoop(input) {
+    let state = await loadInitialDashboardState(input.project, input.loader);
+    const renderStyle = resolveDashboardRenderStyle({ isTTY: input.output.isTTY, env: input.env });
+    return new Promise((resolve) => {
+        const render = () => input.output.write(`\u001Bc${renderInteractiveDashboard(state, { style: renderStyle })}`);
+        const finish = () => {
+            input.input.setRawMode?.(false);
+            input.input.pause?.();
+            if (input.input.off !== undefined)
+                input.input.off('data', onData);
+            else
+                input.input.removeListener?.('data', onData);
+            resolve();
+        };
+        const onData = (chunk) => {
+            void (async () => {
+                const key = dashboardKeyFromInput(chunk.toString());
+                if (key === undefined)
+                    return;
+                if (key === 'refresh')
+                    state = await refreshDashboard(state, input.loader);
+                else
+                    state = reduceDashboardKey(state, key);
+                render();
+                if (state.shouldExit)
+                    finish();
+            })();
+        };
+        input.input.setRawMode?.(true);
+        input.input.resume?.();
+        input.input.on('data', onData);
+        render();
+        if (state.shouldExit)
+            finish();
+    });
+}
+function resolveInteractiveTerminal(environment) {
+    const input = environment.stdin;
+    const output = environment.stdout;
+    if (input === undefined || output === undefined || input.isTTY !== true || output.isTTY !== true || input.setRawMode === undefined) {
+        return validationFailure('Interactive dashboard mode is unavailable because stdin/stdout are not an interactive terminal');
+    }
+    return { ok: true, value: { input, output } };
+}
+async function runMcpInstallCommand(parsed, environment) {
+    const client = parsed.positionals[2];
+    if (client !== 'opencode')
+        return usageFailure('mcp install requires client opencode');
+    const databasePath = databasePathSelectionFor(parsed.flags, environment);
+    if (!databasePath.ok)
+        return resultFailure(databasePath);
+    const scope = opencodeInstallScopeFlag(parsed.flags, 'scope');
+    if (!scope.ok)
+        return resultFailure(scope);
+    const mcpOnly = parsed.flags['mcp-only'] === true || parsed.flags['no-agents'] === true;
+    if (parsed.flags.plan === true) {
+        return jsonResult({
+            ok: true,
+            value: planOpenCodeMcpInstall({ cwd: environment.cwd, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: scope.value, env: environment.env, mcpOnly }),
+        });
+    }
+    const result = await installOpenCodeMcpClient({
+        cwd: environment.cwd,
+        databasePath: databasePath.value.path,
+        databasePathSource: databasePath.value.source,
+        scope: scope.value,
+        env: environment.env,
+        confirmed: parsed.flags.yes === true,
+        mcpOnly,
+    });
+    return result.status === 'installed'
+        ? jsonResult({ ok: true, value: result })
+        : resultFailure({ ok: false, error: { code: 'validation_failed', message: `${result.reason}: ${result.message} Manual doctor command: ${result.manualTest.doctorCommand.join(' ')}` } });
+}
+function runMcpSetupCommand(parsed, environment) {
+    if (parsed.flags.preview !== true)
+        return usageFailure('mcp setup requires --preview; provider config installation is not supported');
+    const provider = optionalStringFlag(parsed.flags, 'provider') ?? 'opencode';
+    if (!isMcpClientSetupProvider(provider))
+        return resultFailure(validationFailure('--provider must be opencode or claude'));
+    const databasePath = databasePathSelectionFor(parsed.flags, environment);
+    if (!databasePath.ok)
+        return resultFailure(databasePath);
+    return jsonResult({
+        ok: true,
+        value: createMcpClientSetupPreview({ provider, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source }),
+    });
+}
+async function runMcpDoctorCommand(parsed, environment) {
+    if (parsed.positionals[2] === 'opencode')
+        return runMcpDoctorOpenCodeCommand(parsed, environment);
+    const timeoutMs = optionalNumberFlag(parsed.flags, 'timeout-ms');
+    if (!timeoutMs.ok)
+        return resultFailure(timeoutMs);
+    const databasePath = databasePathFor(parsed.flags, environment);
+    if (!databasePath.ok)
+        return resultFailure(databasePath);
+    const report = await createMcpDoctorReport({
+        cwd: environment.cwd,
+        databasePath: databasePath.value,
+        project: optionalStringFlag(parsed.flags, 'project') ?? 'vgxness',
+        change: optionalStringFlag(parsed.flags, 'change') ?? 'doctor-smoke',
+        timeoutMs: timeoutMs.value ?? 5_000,
+        env: environment.env,
+    });
+    return { exitCode: report.ready ? 0 : 1, stdout: `${JSON.stringify(report, null, 2)}\n`, stderr: '' };
+}
+function runMcpDoctorOpenCodeCommand(parsed, environment) {
+    const scope = opencodeInstallScopeFlag(parsed.flags, 'scope');
+    if (!scope.ok)
+        return resultFailure(scope);
+    const projectRoot = optionalStringFlag(parsed.flags, 'project-root');
+    const report = createOpenCodeMcpVisibilityReport({
+        cwd: environment.cwd,
+        env: environment.env,
+        scope: scope.value,
+        ...(projectRoot !== undefined ? { projectRoot } : {}),
+    });
+    return { exitCode: report.ready ? 0 : 1, stdout: `${JSON.stringify(report, null, 2)}\n`, stderr: '' };
+}
+function runOpenCodeCommand(command, parsed, database, environment) {
+    if (command !== 'preview')
+        return usageFailure(`Unknown opencode command: ${command}`);
+    const scope = optionalScopeFlag(parsed.flags, 'scope');
+    if (!scope.ok)
+        return resultFailure(scope);
+    const agents = new AgentRegistryService(database);
+    const managerProfiles = new ManagerProfileOverlayService({ agents, overlays: new ManagerProfileOverlayRepository(database) });
+    const service = new OpenCodeInjectionPreviewService({
+        agents,
+        managerProfiles,
+        skills: new SkillRegistryService(database),
+        sdd: new SddWorkflowService(new MemoryService(database)),
+    });
+    const provider = optionalStringFlag(parsed.flags, 'provider');
+    const project = optionalStringFlag(parsed.flags, 'project');
+    const change = optionalStringFlag(parsed.flags, 'change');
+    const phase = optionalStringFlag(parsed.flags, 'phase');
+    const agentId = optionalStringFlag(parsed.flags, 'agent-id');
+    const agentName = optionalStringFlag(parsed.flags, 'agent');
+    return jsonResult(service.preview({
+        ...(provider !== undefined ? { provider } : {}),
+        ...(project !== undefined ? { project } : {}),
+        ...(change !== undefined ? { change } : {}),
+        ...(phase !== undefined ? { phase } : {}),
+        ...(agentId !== undefined ? { agentId } : {}),
+        ...(agentName !== undefined ? { agentName } : {}),
+        ...(scope.value !== undefined ? { scope: scope.value } : {}),
+        workspaceRoot: environment.cwd,
+    }));
+}
+function runSddCommand(command, parsed, database, environment) {
+    const memory = new MemoryService(database);
+    const service = new SddWorkflowService(memory);
+    const project = requiredFlag(parsed.flags, 'project');
+    const change = requiredFlag(parsed.flags, 'change');
+    if (!project.ok)
+        return resultFailure(project);
+    if (!change.ok)
+        return resultFailure(change);
+    if (command === 'status') {
+        return jsonResult(service.getStatus({ project: project.value, change: change.value }));
+    }
+    if (command === 'next') {
+        return jsonResult(service.getNext({ project: project.value, change: change.value }));
+    }
+    if (command === 'ready') {
+        const phase = requiredFlag(parsed.flags, 'phase');
+        if (!phase.ok)
+            return resultFailure(phase);
+        return jsonResult(service.getReady({ project: project.value, change: change.value, phase: phase.value }));
+    }
+    if (command === 'save-artifact') {
+        const phase = requiredFlag(parsed.flags, 'phase');
+        const content = requiredFlag(parsed.flags, 'content');
+        if (!phase.ok)
+            return resultFailure(phase);
+        if (!content.ok)
+            return resultFailure(content);
+        return jsonResult(service.saveArtifact({ project: project.value, change: change.value, phase: phase.value, content: content.value }));
+    }
+    if (command === 'get-artifact') {
+        const phase = requiredFlag(parsed.flags, 'phase');
+        if (!phase.ok)
+            return resultFailure(phase);
+        return jsonResult(service.getArtifact({ project: project.value, change: change.value, phase: phase.value }));
+    }
+    if (command === 'list-artifacts') {
+        return jsonResult(service.listArtifacts({ project: project.value, change: change.value }));
+    }
+    if (command === 'export') {
+        const portability = new ArtifactPortabilityService(memory, service);
+        const exported = portability.exportPackage({ project: project.value, change: change.value });
+        if (!exported.ok)
+            return resultFailure(exported);
+        const file = optionalStringFlag(parsed.flags, 'file');
+        if (file !== undefined) {
+            const written = writeJsonFile(file, exported.value, environment);
+            if (!written.ok)
+                return resultFailure(written);
+        }
+        return jsonResult(exported);
+    }
+    if (command === 'import') {
+        const file = requiredFlag(parsed.flags, 'file');
+        if (!file.ok)
+            return resultFailure(file);
+        const artifactPackage = readJsonFile(file.value, environment);
+        if (!artifactPackage.ok)
+            return resultFailure(artifactPackage);
+        const portability = new ArtifactPortabilityService(memory, service);
+        const input = { project: project.value, change: change.value, package: artifactPackage.value, overwrite: parsed.flags.overwrite === true };
+        return jsonResult(parsed.flags.write === true ? portability.importPackage(input) : portability.planImport(input));
+    }
+    return usageFailure(`Unknown sdd command: ${command}`);
+}
+function runOrchestratorCommand(command, parsed, database) {
+    if (command !== 'preview')
+        return usageFailure(`Unknown orchestrator command: ${command}`);
+    const project = requiredFlag(parsed.flags, 'project');
+    const intent = requiredFlag(parsed.flags, 'intent');
+    if (!project.ok)
+        return resultFailure(project);
+    if (!intent.ok)
+        return resultFailure(intent);
+    const change = optionalStringFlag(parsed.flags, 'change');
+    const sdd = new SddWorkflowService(new MemoryService(database));
+    const sddContext = {};
+    if (change !== undefined) {
+        const status = sdd.getStatus({ project: project.value, change });
+        if (!status.ok)
+            return resultFailure(status);
+        const next = sdd.getNext({ project: project.value, change });
+        if (!next.ok)
+            return resultFailure(next);
+        sddContext.status = status.value;
+        sddContext.next = next.value;
+    }
+    return jsonResult({
+        ok: true,
+        value: createNaturalLanguagePlan({
+            project: project.value,
+            intent: intent.value,
+            ...(change !== undefined ? { change } : {}),
+            ...(change !== undefined ? { sdd: sddContext } : {}),
+        }),
+    });
+}
+function runDashboardCommand(command, parsed, database, environment, databasePath) {
+    if (command !== 'status')
+        return usageFailure(`Unknown dashboard command: ${command}`);
+    const project = requiredFlag(parsed.flags, 'project');
+    if (!project.ok)
+        return resultFailure(project);
+    const limit = optionalNumberFlag(parsed.flags, 'limit');
+    if (!limit.ok)
+        return resultFailure(limit);
+    const runs = new RunService(database);
+    const listed = runs.listRuns({ project: project.value });
+    if (!listed.ok)
+        return resultFailure(listed);
+    const runId = optionalStringFlag(parsed.flags, 'run-id');
+    const selectedRun = runId === undefined ? undefined : runs.getRun(runId);
+    if (selectedRun !== undefined && !selectedRun.ok)
+        return resultFailure(validationFailure(`Unknown run: ${runId}`));
+    const selectedRunInsights = runId === undefined ? undefined : runs.getRunInsights(runId);
+    if (selectedRunInsights !== undefined && !selectedRunInsights.ok)
+        return resultFailure(selectedRunInsights);
+    const change = optionalStringFlag(parsed.flags, 'change');
+    const memory = new MemoryService(database);
+    const sddService = new SddWorkflowService(memory);
+    const setupService = createSetupLifecycleService({ opened: { ok: true, value: database }, databasePath, environment });
+    const setupStatus = readSetupStatus(setupService, { project: project.value, projectRoot: environment.cwd, scope: 'project' });
+    if (!setupStatus.ok)
+        return resultFailure(setupStatus);
+    const sddStatus = change === undefined ? undefined : sddService.getStatus({ project: project.value, change });
+    if (sddStatus !== undefined && !sddStatus.ok)
+        return resultFailure(sddStatus);
+    const nextReadyPhase = sddStatus?.value.nextReadyPhase;
+    const readiness = change !== undefined && nextReadyPhase !== undefined ? sddService.getReady({ project: project.value, change, phase: nextReadyPhase }) : undefined;
+    if (readiness !== undefined && !readiness.ok)
+        return resultFailure(readiness);
+    return okText(renderStatusDashboard({
+        project: project.value,
+        databasePath,
+        runs: listed.value.slice(0, limit.value ?? 5),
+        setup: setupStatus.value,
+        ...(selectedRun?.ok ? { selectedRun: selectedRun.value } : {}),
+        ...(selectedRunInsights?.ok ? { selectedRunInsights: selectedRunInsights.value } : {}),
+        ...(change !== undefined && sddStatus?.ok ? { sdd: { change, status: sddStatus.value, ...(readiness?.ok ? { readiness: readiness.value } : {}) } } : {}),
+    }));
+}
+function runSkillCommand(command, parsed, database, environment) {
+    const registry = new SkillRegistryService(database);
+    if (command === 'register') {
+        const project = requiredFlag(parsed.flags, 'project');
+        const scope = scopeFlag(parsed.flags, 'scope', 'project');
+        const name = requiredFlag(parsed.flags, 'name');
+        const description = requiredFlag(parsed.flags, 'description');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (!name.ok)
+            return resultFailure(name);
+        if (!description.ok)
+            return resultFailure(description);
+        return jsonResult(registry.registerSkill({ project: project.value, scope: scope.value, name: name.value, description: description.value }));
+    }
+    if (command === 'list') {
+        const filters = {};
+        const project = optionalStringFlag(parsed.flags, 'project');
+        if (project !== undefined)
+            filters.project = project;
+        const scope = optionalScopeFlag(parsed.flags, 'scope');
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (scope.value !== undefined)
+            filters.scope = scope.value;
+        return jsonResult(registry.listSkills(filters));
+    }
+    if (command === 'get') {
+        const skill = resolveSkill(parsed, registry);
+        return skill.ok ? jsonResult(registry.getSkillDetails(skill.value.id)) : resultFailure(skill);
+    }
+    if (command === 'add-version') {
+        const skill = resolveSkill(parsed, registry);
+        if (!skill.ok)
+            return resultFailure(skill);
+        const version = requiredFlag(parsed.flags, 'version');
+        const source = skillSourceFromFlags(parsed.flags);
+        const status = optionalSkillVersionStatusFlag(parsed.flags, 'status');
+        if (!version.ok)
+            return resultFailure(version);
+        if (!source.ok)
+            return resultFailure(source);
+        if (!status.ok)
+            return resultFailure(status);
+        const compatibility = optionalJsonFlag(parsed.flags, 'compatibility');
+        if (!compatibility.ok)
+            return resultFailure(compatibility);
+        return jsonResult(registry.addSkillVersion({
+            skillId: skill.value.id,
+            version: version.value,
+            source: source.value,
+            ...(compatibility.value !== undefined ? { compatibility: compatibility.value } : {}),
+            ...(status.value !== undefined ? { status: status.value } : {}),
+            ...(parsed.flags.activate === true ? { activate: true } : {}),
+        }));
+    }
+    if (command === 'attach') {
+        const skill = resolveSkill(parsed, registry);
+        const targetType = skillTargetTypeFlag(parsed.flags, 'target-type');
+        const targetKey = requiredFlag(parsed.flags, 'target-key');
+        if (!skill.ok)
+            return resultFailure(skill);
+        if (!targetType.ok)
+            return resultFailure(targetType);
+        if (!targetKey.ok)
+            return resultFailure(targetKey);
+        const versionId = optionalStringFlag(parsed.flags, 'version-id') ?? skill.value.currentVersionId;
+        const metadata = jsonFlag(parsed.flags, 'metadata', {});
+        if (!metadata.ok)
+            return resultFailure(metadata);
+        return jsonResult(registry.attachSkill({ skillId: skill.value.id, targetType: targetType.value, targetKey: targetKey.value, ...(versionId !== undefined ? { versionId } : {}), metadata: metadata.value }));
+    }
+    if (command === 'detach') {
+        const skill = resolveSkill(parsed, registry);
+        const targetType = skillTargetTypeFlag(parsed.flags, 'target-type');
+        const targetKey = requiredFlag(parsed.flags, 'target-key');
+        if (!skill.ok)
+            return resultFailure(skill);
+        if (!targetType.ok)
+            return resultFailure(targetType);
+        if (!targetKey.ok)
+            return resultFailure(targetKey);
+        return jsonResult(registry.detachSkill(skill.value.id, targetType.value, targetKey.value));
+    }
+    if (command === 'record-usage') {
+        const skill = resolveSkill(parsed, registry);
+        const outcome = skillUsageOutcomeFlag(parsed.flags, 'outcome');
+        if (!skill.ok)
+            return resultFailure(skill);
+        if (!outcome.ok)
+            return resultFailure(outcome);
+        const targetType = optionalSkillTargetTypeFlag(parsed.flags, 'target-type');
+        if (!targetType.ok)
+            return resultFailure(targetType);
+        const targetKey = optionalStringFlag(parsed.flags, 'target-key');
+        const versionId = optionalStringFlag(parsed.flags, 'version-id') ?? skill.value.currentVersionId;
+        const runId = optionalStringFlag(parsed.flags, 'run-id');
+        const notes = optionalStringFlag(parsed.flags, 'notes');
+        return jsonResult(registry.recordSkillUsage({
+            skillId: skill.value.id,
+            ...(versionId !== undefined ? { versionId } : {}),
+            ...(runId !== undefined ? { runId } : {}),
+            ...(targetType.value !== undefined ? { targetType: targetType.value } : {}),
+            ...(targetKey !== undefined ? { targetKey } : {}),
+            outcome: outcome.value,
+            ...(notes !== undefined ? { notes } : {}),
+        }));
+    }
+    if (command === 'resolve') {
+        const input = resolveSkillsInput(parsed.flags);
+        return input.ok ? jsonResult(registry.resolveSkills(input.value)) : resultFailure(input);
+    }
+    if (command === 'propose') {
+        const skill = resolveSkill(parsed, registry);
+        if (!skill.ok)
+            return resultFailure(skill);
+        const baseVersionId = optionalStringFlag(parsed.flags, 'base-version-id') ?? skill.value.currentVersionId;
+        if (baseVersionId === undefined)
+            return resultFailure(validationFailure('Missing required --base-version-id because the skill has no current version'));
+        const proposedVersion = requiredFlag(parsed.flags, 'proposed-version');
+        const proposedSource = skillSourceFromFlags(parsed.flags);
+        const rationale = requiredFlag(parsed.flags, 'rationale');
+        const compatibility = optionalJsonFlag(parsed.flags, 'compatibility');
+        const sourceSignal = jsonFlag(parsed.flags, 'source-signal', {});
+        if (!proposedVersion.ok)
+            return resultFailure(proposedVersion);
+        if (!proposedSource.ok)
+            return resultFailure(proposedSource);
+        if (!rationale.ok)
+            return resultFailure(rationale);
+        if (!compatibility.ok)
+            return resultFailure(compatibility);
+        if (!sourceSignal.ok)
+            return resultFailure(sourceSignal);
+        return jsonResult(registry.createSkillImprovementProposal({
+            skillId: skill.value.id,
+            baseVersionId,
+            proposedVersion: proposedVersion.value,
+            proposedSource: proposedSource.value,
+            ...(compatibility.value !== undefined ? { proposedCompatibility: compatibility.value } : {}),
+            rationale: rationale.value,
+            sourceSignal: sourceSignal.value,
+        }));
+    }
+    if (command === 'proposals') {
+        const filters = {};
+        const skillId = optionalStringFlag(parsed.flags, 'skill-id');
+        if (skillId !== undefined)
+            filters.skillId = skillId;
+        const status = optionalSkillImprovementProposalStatusFlag(parsed.flags, 'status');
+        if (!status.ok)
+            return resultFailure(status);
+        if (status.value !== undefined)
+            filters.status = status.value;
+        return jsonResult(registry.listSkillImprovementProposals(filters));
+    }
+    if (command === 'create-scenario') {
+        const skill = resolveSkill(parsed, registry);
+        if (!skill.ok)
+            return resultFailure(skill);
+        const name = scenarioNameFlag(parsed.flags);
+        const criteria = jsonFlag(parsed.flags, 'criteria', {});
+        const createdBy = requiredFlag(parsed.flags, 'created-by');
+        if (!name.ok)
+            return resultFailure(name);
+        if (!criteria.ok)
+            return resultFailure(criteria);
+        if (!createdBy.ok)
+            return resultFailure(createdBy);
+        const proposalId = optionalStringFlag(parsed.flags, 'proposal');
+        const versionId = optionalStringFlag(parsed.flags, 'version-id');
+        return jsonResult(registry.createSkillEvaluationScenario({
+            skillId: skill.value.id,
+            name: name.value,
+            criteria: criteria.value,
+            createdBy: createdBy.value,
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(versionId !== undefined ? { versionId } : {}),
+        }));
+    }
+    if (command === 'list-scenarios') {
+        const skill = resolveSkill(parsed, registry);
+        if (!skill.ok)
+            return resultFailure(skill);
+        const proposalId = optionalStringFlag(parsed.flags, 'proposal');
+        const versionId = optionalStringFlag(parsed.flags, 'version-id');
+        return jsonResult(registry.listSkillEvaluationScenarios({
+            skillId: skill.value.id,
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(versionId !== undefined ? { versionId } : {}),
+        }));
+    }
+    if (command === 'record-evaluation-result') {
+        const scenarioId = requiredFlag(parsed.flags, 'scenario');
+        const status = skillEvaluationResultStatusFlag(parsed.flags, 'status');
+        const result = jsonFlag(parsed.flags, 'result', {});
+        const observedBehavior = requiredFlag(parsed.flags, 'observed-behavior');
+        const evaluator = requiredFlag(parsed.flags, 'evaluator');
+        if (!scenarioId.ok)
+            return resultFailure(scenarioId);
+        if (!status.ok)
+            return resultFailure(status);
+        if (!result.ok)
+            return resultFailure(result);
+        if (!observedBehavior.ok)
+            return resultFailure(observedBehavior);
+        if (!evaluator.ok)
+            return resultFailure(evaluator);
+        const proposalId = optionalStringFlag(parsed.flags, 'proposal');
+        const versionId = optionalStringFlag(parsed.flags, 'version-id');
+        const notes = optionalStringFlag(parsed.flags, 'notes');
+        return jsonResult(registry.recordSkillEvaluationResult({
+            scenarioId: scenarioId.value,
+            status: status.value,
+            result: result.value,
+            observedBehavior: observedBehavior.value,
+            evaluator: evaluator.value,
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(versionId !== undefined ? { versionId } : {}),
+            ...(notes !== undefined ? { notes } : {}),
+        }));
+    }
+    if (command === 'list-evaluation-results') {
+        const status = optionalSkillEvaluationResultStatusFlag(parsed.flags, 'status');
+        if (!status.ok)
+            return resultFailure(status);
+        const scenarioId = optionalStringFlag(parsed.flags, 'scenario');
+        const skillId = optionalStringFlag(parsed.flags, 'skill-id');
+        const proposalId = optionalStringFlag(parsed.flags, 'proposal');
+        const versionId = optionalStringFlag(parsed.flags, 'version-id');
+        const evaluator = optionalStringFlag(parsed.flags, 'evaluator');
+        return jsonResult(registry.listSkillEvaluationResults({
+            ...(scenarioId !== undefined ? { scenarioId } : {}),
+            ...(skillId !== undefined ? { skillId } : {}),
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(versionId !== undefined ? { versionId } : {}),
+            ...(evaluator !== undefined ? { evaluator } : {}),
+            ...(status.value !== undefined ? { status: status.value } : {}),
+        }));
+    }
+    if (command === 'get-proposal') {
+        const proposalId = requiredFlag(parsed.flags, 'proposal');
+        return proposalId.ok ? jsonResult(registry.getSkillImprovementProposal(proposalId.value)) : resultFailure(proposalId);
+    }
+    if (command === 'submit-proposal' || command === 'approve-proposal' || command === 'reject-proposal' || command === 'cancel-proposal' || command === 'apply-proposal') {
+        const input = proposalActorInput(parsed.flags);
+        if (!input.ok)
+            return resultFailure(input);
+        if (command === 'submit-proposal')
+            return jsonResult(registry.submitSkillImprovementProposal(input.value));
+        if (command === 'approve-proposal')
+            return jsonResult(registry.approveSkillImprovementProposal(input.value));
+        if (command === 'reject-proposal')
+            return jsonResult(registry.rejectSkillImprovementProposal(input.value));
+        if (command === 'cancel-proposal')
+            return jsonResult(registry.cancelSkillImprovementProposal(input.value));
+        return jsonResult(registry.applySkillImprovementProposal(input.value));
+    }
+    if (command === 'payload') {
+        const input = skillPayloadInput(parsed.flags);
+        return input.ok ? jsonResult(registry.buildSkillPayload(input.value, { workspaceRoot: environment.cwd })) : resultFailure(input);
+    }
+    return usageFailure(`Unknown skills command: ${command}`);
+}
+function proposalActorInput(flags) {
+    const proposalId = requiredFlag(flags, 'proposal');
+    const actor = requiredFlag(flags, 'actor');
+    if (!proposalId.ok)
+        return proposalId;
+    if (!actor.ok)
+        return actor;
+    const reason = optionalStringFlag(flags, 'reason');
+    return { ok: true, value: { proposalId: proposalId.value, actor: actor.value, ...(reason !== undefined ? { reason } : {}) } };
+}
+function skillPayloadInput(flags) {
+    if (flags['record-usage'] !== undefined)
+        return validationFailure('skills payload is read-only; use skills resolve with --record-usage for explicit usage writes');
+    const input = resolveSkillsInput(flags);
+    if (!input.ok)
+        return input;
+    return { ok: true, value: input.value };
+}
+function resolveSkillsInput(flags) {
+    const scope = optionalScopeFlag(flags, 'scope');
+    if (!scope.ok)
+        return scope;
+    const recordUsage = optionalSkillResolutionUsageFlag(flags, 'record-usage');
+    if (!recordUsage.ok)
+        return recordUsage;
+    const input = {};
+    const project = optionalStringFlag(flags, 'project');
+    const agentId = optionalStringFlag(flags, 'agent-id');
+    const agentName = optionalStringFlag(flags, 'agent');
+    const workflow = optionalStringFlag(flags, 'workflow');
+    const phase = optionalStringFlag(flags, 'phase');
+    const providerAdapter = optionalStringFlag(flags, 'provider');
+    const runId = optionalStringFlag(flags, 'run');
+    if (project !== undefined)
+        input.project = project;
+    if (scope.value !== undefined)
+        input.scope = scope.value;
+    if (agentId !== undefined)
+        input.agentId = agentId;
+    if (agentName !== undefined)
+        input.agentName = agentName;
+    if (workflow !== undefined)
+        input.workflow = workflow;
+    if (phase !== undefined)
+        input.phase = phase;
+    if (providerAdapter !== undefined)
+        input.providerAdapter = providerAdapter;
+    if (runId !== undefined)
+        input.runId = runId;
+    if (recordUsage.value !== undefined)
+        input.recordUsage = recordUsage.value;
+    if (input.recordUsage !== undefined && input.runId === undefined)
+        return validationFailure('--run is required when --record-usage is set');
+    return { ok: true, value: input };
+}
+function resolveSkill(parsed, registry) {
+    const id = optionalStringFlag(parsed.flags, 'id');
+    if (id !== undefined)
+        return registry.getSkill(id);
+    const project = requiredFlag(parsed.flags, 'project');
+    const scope = scopeFlag(parsed.flags, 'scope', 'project');
+    const name = requiredFlag(parsed.flags, 'name');
+    if (!project.ok)
+        return project;
+    if (!scope.ok)
+        return scope;
+    if (!name.ok)
+        return name;
+    return registry.getSkillByName(project.value, scope.value, name.value);
+}
+function scenarioNameFlag(flags) {
+    const scenarioName = optionalStringFlag(flags, 'scenario-name');
+    if (scenarioName !== undefined)
+        return { ok: true, value: scenarioName };
+    const id = optionalStringFlag(flags, 'id');
+    if (id !== undefined)
+        return requiredFlag(flags, 'name');
+    return validationFailure('Missing required --scenario-name');
+}
+function runAgentCommand(command, parsed, database, environment) {
+    const handlers = createAgentRegistryToolHandlers({ service: new AgentRegistryService(database) });
+    const registry = new AgentRegistryService(database);
+    const managerProfiles = new ManagerProfileOverlayService({ agents: registry, overlays: new ManagerProfileOverlayRepository(database) });
+    if (command === 'seed') {
+        if (parsed.positionals[2] !== 'load')
+            return usageFailure('agents seed requires load');
+        const file = requiredFlag(parsed.flags, 'file');
+        if (!file.ok)
+            return resultFailure(file);
+        const manifest = readJsonFile(file.value, environment);
+        if (!manifest.ok)
+            return resultFailure(manifest);
+        return jsonResult(new AgentSeedService(database).loadManifest(manifest.value));
+    }
+    if (command === 'register') {
+        const payload = registerPayload(parsed, environment, false);
+        return payload.ok ? jsonResult(handlers.registerAgent(payload.value)) : resultFailure(payload);
+    }
+    if (command === 'list') {
+        const filters = {};
+        const project = optionalStringFlag(parsed.flags, 'project');
+        if (project !== undefined)
+            filters.project = project;
+        const scope = optionalScopeFlag(parsed.flags, 'scope');
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (scope.value !== undefined)
+            filters.scope = scope.value;
+        const mode = optionalModeFlag(parsed.flags, 'mode');
+        if (!mode.ok)
+            return resultFailure(mode);
+        filters.mode = mode.value ?? 'agent';
+        return jsonResult(handlers.listAgents(filters));
+    }
+    if (command === 'get') {
+        const id = optionalStringFlag(parsed.flags, 'id');
+        if (id !== undefined)
+            return jsonResult(expectAgentMode(handlers.getAgent({ id }), 'agent'));
+        const project = requiredFlag(parsed.flags, 'project');
+        const scope = scopeFlag(parsed.flags, 'scope', 'project');
+        const name = requiredFlag(parsed.flags, 'name');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (!name.ok)
+            return resultFailure(name);
+        return jsonResult(expectAgentMode(handlers.getAgentByName({ project: project.value, scope: scope.value, name: name.value }), 'agent'));
+    }
+    if (command === 'resolve') {
+        const input = resolveAgentsInput(parsed.flags);
+        return input.ok ? jsonResult(registry.resolveAgents(input.value)) : resultFailure(input);
+    }
+    if (command === 'manager-profile') {
+        const action = parsed.positionals[2];
+        if (action !== 'get' && action !== 'set')
+            return usageFailure('agents manager-profile requires get or set');
+        const input = managerProfileInput(parsed.flags);
+        if (!input.ok)
+            return resultFailure(input);
+        if (action === 'get')
+            return jsonResult(managerProfiles.resolveEffectiveManager(input.value));
+        const baseline = managerProfiles.resolveEffectiveManager(input.value);
+        if (!baseline.ok)
+            return resultFailure(baseline);
+        const instructions = requiredFlag(parsed.flags, 'instructions');
+        if (!instructions.ok)
+            return resultFailure(instructions);
+        const saved = managerProfiles.save({ ...input.value, instructions: instructions.value });
+        if (!saved.ok)
+            return resultFailure(saved);
+        return jsonResult(managerProfiles.resolveEffectiveManager(input.value));
+    }
+    if (command === 'render') {
+        const provider = requiredFlag(parsed.flags, 'provider');
+        if (!provider.ok)
+            return resultFailure(provider);
+        const renderer = getProviderRenderer(provider.value);
+        if (!renderer.ok)
+            return resultFailure(renderer);
+        const agent = resolveAgentForRender(parsed, registry, managerProfiles);
+        if (!agent.ok)
+            return resultFailure(agent);
+        const subagents = resolveSubagentsForRender(agent.value, registry);
+        if (!subagents.ok)
+            return resultFailure(subagents);
+        return jsonResult(renderer.value.render({ agent: agent.value, subagents: subagents.value }));
+    }
+    return usageFailure(`Unknown agents command: ${command}`);
+}
+function resolveAgentsInput(flags) {
+    const scope = optionalScopeFlag(flags, 'scope');
+    if (!scope.ok)
+        return scope;
+    const mode = optionalModeFlag(flags, 'mode');
+    if (!mode.ok)
+        return mode;
+    const input = {};
+    const project = optionalStringFlag(flags, 'project');
+    const taskDescription = optionalStringFlag(flags, 'task') ?? optionalStringFlag(flags, 'task-description');
+    const intent = optionalStringFlag(flags, 'intent');
+    const desiredCapabilities = csvFlag(flags, 'capabilities');
+    const workflow = optionalStringFlag(flags, 'workflow');
+    const phase = optionalStringFlag(flags, 'phase');
+    const providerAdapter = optionalStringFlag(flags, 'provider') ?? optionalStringFlag(flags, 'provider-adapter');
+    if (project !== undefined)
+        input.project = project;
+    if (scope.value !== undefined)
+        input.scope = scope.value;
+    if (taskDescription !== undefined)
+        input.taskDescription = taskDescription;
+    if (intent !== undefined)
+        input.intent = intent;
+    if (desiredCapabilities.length > 0)
+        input.desiredCapabilities = desiredCapabilities;
+    if (workflow !== undefined)
+        input.workflow = workflow;
+    if (phase !== undefined)
+        input.phase = phase;
+    if (providerAdapter !== undefined)
+        input.providerAdapter = providerAdapter;
+    if (mode.value !== undefined)
+        input.mode = mode.value;
+    return { ok: true, value: input };
+}
+function managerProfileInput(flags) {
+    const scope = scopeFlag(flags, 'scope', 'project');
+    if (!scope.ok)
+        return scope;
+    return { ok: true, value: { project: optionalStringFlag(flags, 'project') ?? 'vgxness', scope: scope.value, managerName: optionalStringFlag(flags, 'manager') ?? 'vgxness-manager' } };
+}
+function resolveAgentForRender(parsed, registry, managerProfiles) {
+    const id = optionalStringFlag(parsed.flags, 'id');
+    if (id !== undefined)
+        return registry.getAgent(id);
+    const project = requiredFlag(parsed.flags, 'project');
+    const scope = scopeFlag(parsed.flags, 'scope', 'project');
+    const name = requiredFlag(parsed.flags, 'name');
+    if (!project.ok)
+        return project;
+    if (!scope.ok)
+        return scope;
+    if (!name.ok)
+        return name;
+    if (name.value === 'vgxness-manager' && managerProfiles !== undefined) {
+        const effective = managerProfiles.resolveEffectiveManager({ project: project.value, scope: scope.value, managerName: name.value });
+        return effective.ok ? { ok: true, value: effective.value.manager } : effective;
+    }
+    return registry.getAgentByName(project.value, scope.value, name.value);
+}
+function resolveSubagentsForRender(agent, registry) {
+    if (agent.mode !== 'agent')
+        return { ok: true, value: [] };
+    const summaries = registry.listSubagents(agent.id);
+    if (!summaries.ok)
+        return summaries;
+    const subagents = [];
+    for (const summary of summaries.value) {
+        const subagent = registry.getAgent(summary.id);
+        if (!subagent.ok)
+            return subagent;
+        subagents.push(subagent.value);
+    }
+    return { ok: true, value: subagents };
+}
+function runSubagentCommand(command, parsed, database, environment) {
+    const handlers = createAgentRegistryToolHandlers({ service: new AgentRegistryService(database) });
+    if (command === 'register') {
+        const payload = registerPayload(parsed, environment, true);
+        return payload.ok ? jsonResult(handlers.registerSubagent(payload.value)) : resultFailure(payload);
+    }
+    if (command === 'list') {
+        const parentAgentId = requiredFlag(parsed.flags, 'parent-agent-id');
+        if (!parentAgentId.ok)
+            return resultFailure(parentAgentId);
+        return jsonResult(handlers.listSubagents({ parentAgentId: parentAgentId.value }));
+    }
+    if (command === 'get') {
+        const id = optionalStringFlag(parsed.flags, 'id');
+        if (id !== undefined)
+            return jsonResult(expectAgentMode(handlers.getAgent({ id }), 'subagent'));
+        const project = requiredFlag(parsed.flags, 'project');
+        const scope = scopeFlag(parsed.flags, 'scope', 'project');
+        const name = requiredFlag(parsed.flags, 'name');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (!name.ok)
+            return resultFailure(name);
+        return jsonResult(expectAgentMode(handlers.getAgentByName({ project: project.value, scope: scope.value, name: name.value }), 'subagent'));
+    }
+    return usageFailure(`Unknown subagents command: ${command}`);
+}
+function registerPayload(parsed, environment, subagent) {
+    const file = optionalStringFlag(parsed.flags, 'file');
+    if (file !== undefined) {
+        const mergeValidation = validateFileInputIsComplete(parsed.flags, subagent);
+        if (!mergeValidation.ok)
+            return mergeValidation;
+        return readJsonFile(file, environment);
+    }
+    const project = requiredFlag(parsed.flags, 'project');
+    const scope = scopeFlag(parsed.flags, 'scope', 'project');
+    const name = requiredFlag(parsed.flags, 'name');
+    const description = requiredFlag(parsed.flags, 'description');
+    const instructionKind = instructionKindFlag(parsed.flags);
+    const instructions = requiredFlag(parsed.flags, 'instructions');
+    if (!project.ok)
+        return project;
+    if (!scope.ok)
+        return scope;
+    if (!name.ok)
+        return name;
+    if (!description.ok)
+        return description;
+    if (!instructionKind.ok)
+        return instructionKind;
+    if (!instructions.ok)
+        return instructions;
+    const payload = {
+        project: project.value,
+        scope: scope.value,
+        name: name.value,
+        description: description.value,
+        instructions: { kind: instructionKind.value, value: instructions.value },
+    };
+    const capabilities = csvFlag(parsed.flags, 'capabilities');
+    if (capabilities.length)
+        payload.capabilities = capabilities;
+    const skills = csvFlag(parsed.flags, 'skills');
+    if (skills.length)
+        payload.skills = skills;
+    if (subagent) {
+        const parentAgentId = requiredFlag(parsed.flags, 'parent-agent-id');
+        if (!parentAgentId.ok)
+            return parentAgentId;
+        payload.parentAgentId = parentAgentId.value;
+    }
+    return { ok: true, value: payload };
+}
+function expectAgentMode(result, mode) {
+    if (!result.ok)
+        return result;
+    if (result.value.mode === mode)
+        return result;
+    return validationFailure(`Expected ${mode}, found ${result.value.mode}`);
+}
+function validateFileInputIsComplete(flags, subagent) {
+    const definitionFlags = ['project', 'scope', 'name', 'description', 'instructions', 'instructions-kind', 'capabilities'];
+    if (subagent)
+        definitionFlags.push('parent-agent-id');
+    const mixed = definitionFlags.filter((name) => flags[name] !== undefined);
+    return mixed.length
+        ? validationFailure(`--file is a complete definition; do not combine it with ${mixed.map((name) => `--${name}`).join(', ')}`)
+        : { ok: true, value: undefined };
+}
+function runMemoryCommand(command, parsed, database) {
+    const handlers = createMemoryToolHandlers({ service: new MemoryService(database), config: { localMemoryEnabled: true } });
+    const context = { actor: 'cli' };
+    if (command === 'save') {
+        const project = requiredFlag(parsed.flags, 'project');
+        const scope = scopeFlag(parsed.flags, 'scope', 'project');
+        const type = requiredFlag(parsed.flags, 'type');
+        const title = requiredFlag(parsed.flags, 'title');
+        const content = requiredFlag(parsed.flags, 'content');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!scope.ok)
+            return resultFailure(scope);
+        if (!type.ok)
+            return resultFailure(type);
+        if (!title.ok)
+            return resultFailure(title);
+        if (!content.ok)
+            return resultFailure(content);
+        const topicKey = optionalStringFlag(parsed.flags, 'topic-key');
+        return jsonResult(handlers.saveObservation({
+            project: project.value,
+            scope: scope.value,
+            type: type.value,
+            title: title.value,
+            content: content.value,
+            ...(topicKey !== undefined ? { topicKey } : {}),
+        }, context));
+    }
+    if (command === 'search') {
+        const scope = optionalScopeFlag(parsed.flags, 'scope');
+        if (!scope.ok)
+            return resultFailure(scope);
+        const limit = optionalNumberFlag(parsed.flags, 'limit');
+        if (!limit.ok)
+            return resultFailure(limit);
+        const filters = {};
+        const query = optionalStringFlag(parsed.flags, 'query');
+        if (query !== undefined)
+            filters.query = query;
+        const project = optionalStringFlag(parsed.flags, 'project');
+        if (project !== undefined)
+            filters.project = project;
+        if (scope.value !== undefined)
+            filters.scope = scope.value;
+        const type = optionalStringFlag(parsed.flags, 'type');
+        if (type !== undefined)
+            filters.type = type;
+        if (limit.value !== undefined)
+            filters.limit = limit.value;
+        return jsonResult(handlers.searchObservations(filters, context));
+    }
+    return usageFailure(`Unknown memory command: ${command}`);
+}
+function runMemoryImportCommand(parsed, environment) {
+    const mode = validateMemoryImportMode(parsed.flags);
+    if (!mode.ok)
+        return resultFailure(mode);
+    const file = requiredFlag(parsed.flags, 'file');
+    if (!file.ok)
+        return resultFailure(file);
+    const importPackage = readJsonFile(file.value, environment);
+    if (!importPackage.ok)
+        return resultFailure(importPackage);
+    const databasePath = databasePathSelectionFor(parsed.flags, environment);
+    if (!databasePath.ok)
+        return resultFailure(databasePath);
+    if (mode.value === 'dry-run')
+        return jsonResult(planMemoryImportDryRun({ packageJson: importPackage.value, targetDatabase: databasePath.value }));
+    const packageValidation = validateMemoryImportPackage(importPackage.value);
+    if (!packageValidation.ok)
+        return resultFailure(validationFailure(`Invalid memory import package: ${formatMemoryImportValidationErrors(packageValidation.errors)}`));
+    const opened = openCliDatabase(databasePath.value.path);
+    if (!opened.ok)
+        return resultFailure(opened);
+    try {
+        return jsonResult(writeMemoryImportObservations({ packageJson: importPackage.value, targetDatabase: databasePath.value, service: new MemoryService(opened.value), duplicatePolicy: mode.value }));
+    }
+    finally {
+        opened.value.close();
+    }
+}
+function formatMemoryImportValidationErrors(errors) {
+    return errors.map((error) => `${error.path}: ${error.message}`).join('; ');
+}
+function validateMemoryImportMode(flags) {
+    if (flags.database !== undefined)
+        return validationFailure('Use --db <path>; --database is not supported');
+    const dryRun = flags['dry-run'] === true;
+    const write = flags.write === true;
+    const skipExisting = flags['skip-existing'] === true;
+    const overwrite = flags.overwrite === true;
+    if (dryRun && write)
+        return validationFailure('Choose exactly one mode: --dry-run or --write');
+    if (!dryRun && !write)
+        return validationFailure('Missing import mode: pass --dry-run or --write');
+    if (skipExisting && overwrite)
+        return validationFailure('Choose exactly one duplicate policy: --skip-existing or --overwrite');
+    if (dryRun && (skipExisting || overwrite))
+        return validationFailure('--skip-existing and --overwrite are write-mode duplicate policies and cannot be used with --dry-run');
+    if (write) {
+        if (skipExisting === overwrite)
+            return validationFailure('--write requires exactly one duplicate policy: --skip-existing or --overwrite');
+        return { ok: true, value: skipExisting ? 'skip-existing' : 'overwrite' };
+    }
+    return { ok: true, value: 'dry-run' };
+}
+function runRunsCommand(command, parsed, database, environment) {
+    const service = new RunService(database);
+    if (command === 'timeline' || command === 'debug' || command === 'resume-plan' || command === 'resume-inspect')
+        return runRunInsightCommand(command, parsed, service);
+    if (command === 'create') {
+        const project = requiredFlag(parsed.flags, 'project');
+        const userIntent = requiredFlag(parsed.flags, 'intent');
+        const workflow = requiredFlag(parsed.flags, 'workflow');
+        const phase = requiredFlag(parsed.flags, 'phase');
+        const selectedAgentId = requiredFlag(parsed.flags, 'agent-id');
+        const providerAdapter = requiredFlag(parsed.flags, 'provider-adapter');
+        const model = requiredFlag(parsed.flags, 'model');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!userIntent.ok)
+            return resultFailure(userIntent);
+        if (!workflow.ok)
+            return resultFailure(workflow);
+        if (!phase.ok)
+            return resultFailure(phase);
+        if (!selectedAgentId.ok)
+            return resultFailure(selectedAgentId);
+        if (!providerAdapter.ok)
+            return resultFailure(providerAdapter);
+        if (!model.ok)
+            return resultFailure(model);
+        return jsonResult(service.createRun({ project: project.value, userIntent: userIntent.value, workflow: workflow.value, phase: phase.value, selectedAgentId: selectedAgentId.value, providerAdapter: providerAdapter.value, model: model.value }));
+    }
+    if (command === 'list') {
+        const status = optionalRunStatusFlag(parsed.flags, 'status');
+        if (!status.ok)
+            return resultFailure(status);
+        const filters = {};
+        const project = optionalStringFlag(parsed.flags, 'project');
+        if (project !== undefined)
+            filters.project = project;
+        if (status.value !== undefined)
+            filters.status = status.value;
+        return jsonResult(service.listRuns(filters));
+    }
+    if (command === 'get') {
+        const id = requiredFlag(parsed.flags, 'id');
+        return id.ok ? jsonResult(service.getRun(id.value)) : resultFailure(id);
+    }
+    if (command === 'export-snapshot') {
+        const project = requiredFlag(parsed.flags, 'project');
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        if (!project.ok)
+            return resultFailure(project);
+        if (!runId.ok)
+            return resultFailure(runId);
+        const exported = new RunSnapshotExportService(service).exportSnapshot({ project: project.value, runId: runId.value });
+        if (!exported.ok)
+            return resultFailure(exported);
+        const file = optionalStringFlag(parsed.flags, 'file');
+        if (file !== undefined) {
+            const written = writeJsonFile(file, exported.value, environment);
+            if (!written.ok)
+                return resultFailure(written);
+        }
+        return jsonResult(exported);
+    }
+    if (command === 'checkpoint') {
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        const label = requiredFlag(parsed.flags, 'label');
+        const state = jsonFlag(parsed.flags, 'state', {});
+        if (!runId.ok)
+            return resultFailure(runId);
+        if (!label.ok)
+            return resultFailure(label);
+        if (!state.ok)
+            return resultFailure(state);
+        return jsonResult(service.appendCheckpoint({ runId: runId.value, label: label.value, state: state.value }));
+    }
+    if (command === 'finish') {
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        const status = finalRunStatusFlag(parsed.flags, 'status');
+        const outcome = runOutcomeFlag(parsed.flags, 'outcome');
+        if (!runId.ok)
+            return resultFailure(runId);
+        if (!status.ok)
+            return resultFailure(status);
+        if (!outcome.ok)
+            return resultFailure(outcome);
+        const reason = optionalStringFlag(parsed.flags, 'reason');
+        return jsonResult(service.updateFinalStatus({ runId: runId.value, status: status.value, outcome: outcome.value, ...(reason !== undefined ? { outcomeReason: reason } : {}) }));
+    }
+    if (command === 'permission-check') {
+        const request = permissionRequestFromFlags(parsed, database, environment);
+        if (!request.ok)
+            return resultFailure(request);
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        if (!runId.ok)
+            return resultFailure(runId);
+        return jsonResult(service.evaluatePermissionForRun({ ...request.value, runId: runId.value }));
+    }
+    if (command === 'preflight') {
+        const request = permissionRequestFromFlags(parsed, database, environment);
+        if (!request.ok)
+            return resultFailure(request);
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        if (!runId.ok)
+            return resultFailure(runId);
+        return jsonResult(service.preflightOperation({ ...request.value, runId: runId.value }));
+    }
+    if (command === 'approvals') {
+        const runId = requiredFlag(parsed.flags, 'run');
+        return runId.ok ? jsonResult(service.listApprovals(runId.value)) : resultFailure(runId);
+    }
+    if (command === 'retry-check') {
+        const approvalId = requiredFlag(parsed.flags, 'approval');
+        if (!approvalId.ok)
+            return resultFailure(approvalId);
+        const policy = retryPolicyFlag(parsed.flags);
+        if (!policy.ok)
+            return resultFailure(policy);
+        const approval = service.getApproval(approvalId.value);
+        if (!approval.ok)
+            return resultFailure(approval);
+        const retry = service.evaluateOperationRetry(policy.value === undefined
+            ? { approvalId: approvalId.value }
+            : { approvalId: approvalId.value, policy: policy.value });
+        if (!retry.ok)
+            return resultFailure(retry);
+        return jsonResult({ ok: true, value: {
+                approvalId: approval.value.id,
+                runId: approval.value.runId,
+                decision: retry.value.allowed ? 'allowed' : 'blocked',
+                allowed: retry.value.allowed,
+                reasonCode: retry.value.reasonCode,
+                reason: retry.value.reason,
+                policy: retry.value.policy,
+                retryableStatuses: retry.value.retryableStatuses,
+                evaluatedAttemptCount: retry.value.evaluatedAttemptCount,
+                ...(retry.value.latestAttempt === undefined ? {} : { latestAttempt: retry.value.latestAttempt }),
+                ...(retry.value.activeAttempt === undefined ? {} : { activeAttempt: retry.value.activeAttempt }),
+                executorInvoked: false,
+                operationExecuted: false,
+            } });
+    }
+    if (command === 'resume-gate') {
+        const approvalId = requiredFlag(parsed.flags, 'approval');
+        if (!approvalId.ok)
+            return resultFailure(approvalId);
+        const policy = retryPolicyFlag(parsed.flags);
+        if (!policy.ok)
+            return resultFailure(policy);
+        return jsonResult(service.getRunResumeOrchestrationPlan(policy.value === undefined
+            ? { approvalId: approvalId.value }
+            : { approvalId: approvalId.value, policy: policy.value }));
+    }
+    if (command === 'approve' || command === 'reject' || command === 'cancel-approval') {
+        const approvalId = requiredFlag(parsed.flags, 'approval');
+        const actor = requiredFlag(parsed.flags, 'actor');
+        if (!approvalId.ok)
+            return resultFailure(approvalId);
+        if (!actor.ok)
+            return resultFailure(actor);
+        const reason = optionalStringFlag(parsed.flags, 'reason');
+        const status = command === 'approve' ? 'approved' : command === 'reject' ? 'rejected' : 'cancelled';
+        return jsonResult(service.resolveApproval({ approvalId: approvalId.value, status, actor: actor.value, ...(reason !== undefined ? { reason } : {}) }));
+    }
+    return usageFailure(`Unknown runs command: ${command}`);
+}
+function runApprovalsCommand(command, parsed, database) {
+    const service = new RunService(database);
+    if (command === 'list') {
+        const runId = optionalStringFlag(parsed.flags, 'run-id');
+        const approvals = listCliApprovals(service, runId);
+        return approvals.ok ? jsonResult({ ok: true, value: approvals.value }) : resultFailure(approvals);
+    }
+    if (command === 'approve' || command === 'reject') {
+        const id = requiredFlag(parsed.flags, 'id');
+        if (!id.ok)
+            return resultFailure(id);
+        const reason = optionalStringFlag(parsed.flags, 'reason');
+        const resolved = service.resolveApproval({
+            approvalId: id.value,
+            status: command === 'approve' ? 'approved' : 'rejected',
+            actor: 'cli',
+            ...(reason === undefined ? {} : { reason }),
+        });
+        return jsonResult(resolved);
+    }
+    return usageFailure(`Unknown approvals command: ${command}`);
+}
+function listCliApprovals(service, runId) {
+    const details = [];
+    if (runId === undefined) {
+        const runs = service.listRuns({});
+        if (!runs.ok)
+            return runs;
+        details.push(...runs.value.map((run) => service.getRun(run.id)));
+    }
+    else {
+        details.push(service.getRun(runId));
+    }
+    const values = [];
+    for (const detail of details) {
+        if (!detail.ok)
+            return detail;
+        for (const approval of detail.value.approvals) {
+            const decisionEvent = detail.value.events.find((event) => event.id === approval.decisionEventId);
+            values.push({
+                id: approval.id,
+                runId: approval.runId,
+                status: approval.status,
+                requestedAt: approval.requestedAt,
+                resolvedAt: approval.resolvedAt ?? null,
+                resolvedBy: approval.resolvedBy ?? null,
+                resolutionReason: approval.resolutionReason ?? null,
+                decisionEventId: approval.decisionEventId,
+                operation: decisionEvent === undefined || !isJsonObject(decisionEvent.payload)
+                    ? null
+                    : {
+                        category: decisionEvent.payload.category ?? null,
+                        name: decisionEvent.payload.operation ?? null,
+                        requestedOperation: decisionEvent.payload.requestedOperation ?? null,
+                        agent: decisionEvent.payload.agent ?? null,
+                    },
+            });
+        }
+    }
+    return { ok: true, value: values };
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function runRunInsightCommand(command, parsed, service) {
+    const id = requiredFlag(parsed.flags, 'id');
+    if (!id.ok)
+        return resultFailure(id);
+    if (command === 'resume-inspect')
+        return jsonResult(service.getRunOperatorResumePlan(id.value));
+    const insights = service.getRunInsights(id.value);
+    if (!insights.ok)
+        return resultFailure(insights);
+    if (command === 'timeline')
+        return jsonResult({ ok: true, value: insights.value.timeline });
+    if (command === 'debug')
+        return jsonResult({ ok: true, value: insights.value.debug });
+    return jsonResult({ ok: true, value: insights.value.resumePlan });
+}
+function runPermissionsCommand(command, parsed, database, environment) {
+    if (command !== 'check')
+        return usageFailure(`Unknown permissions command: ${command}`);
+    const request = permissionRequestFromFlags(parsed, database, environment);
+    return request.ok ? jsonResult({ ok: true, value: evaluatePermission(request.value) }) : resultFailure(request);
+}
+function permissionRequestFromFlags(parsed, database, environment) {
+    const category = permissionCategoryFlag(parsed.flags, 'category');
+    const operation = requiredFlag(parsed.flags, 'operation');
+    if (!category.ok)
+        return category;
+    if (!operation.ok)
+        return operation;
+    const request = {
+        category: category.value,
+        operation: operation.value,
+        workspaceRoot: optionalStringFlag(parsed.flags, 'workspace') ?? environment.cwd,
+    };
+    const targetPath = optionalStringFlag(parsed.flags, 'path');
+    if (targetPath !== undefined)
+        request.targetPath = targetPath;
+    const providerToolName = optionalStringFlag(parsed.flags, 'provider-tool');
+    if (providerToolName !== undefined)
+        request.providerToolName = providerToolName;
+    if (parsed.flags.destructive === true)
+        request.destructive = true;
+    if (parsed.flags.external === true)
+        request.external = true;
+    if (parsed.flags.privileged === true)
+        request.privileged = true;
+    if (parsed.flags.ambiguous === true)
+        request.ambiguous = true;
+    const agentId = optionalStringFlag(parsed.flags, 'agent-id');
+    if (agentId !== undefined) {
+        const agent = new AgentRegistryService(database).getAgent(agentId);
+        if (!agent.ok)
+            return agent;
+        request.agent = agent.value;
+    }
+    return { ok: true, value: request };
+}
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        if (current === undefined)
+            continue;
+        if (!current.startsWith('--')) {
+            positionals.push(current);
+            continue;
+        }
+        const [rawKey, inlineValue] = current.slice(2).split('=', 2);
+        if (!rawKey)
+            continue;
+        if (inlineValue !== undefined) {
+            flags[rawKey] = inlineValue;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[rawKey] = next;
+            index += 1;
+        }
+        else {
+            flags[rawKey] = true;
+        }
+    }
+    return { positionals, flags };
+}
+function databasePathFor(flags, environment) {
+    const resolved = databasePathSelectionFor(flags, environment);
+    return resolved.ok ? { ok: true, value: resolved.value.path } : resolved;
+}
+function databasePathSelectionFor(flags, environment) {
+    const flagPath = flags.db !== undefined ? requiredFlag(flags, 'db') : { ok: true, value: undefined };
+    if (!flagPath.ok)
+        return flagPath;
+    return resolveMemoryDatabasePath({ cwd: environment.cwd, env: environment.env, explicitPath: flagPath.value });
+}
+function openCliDatabase(path) {
+    const prepared = prepareMemoryDatabasePath(path);
+    if (!prepared.ok)
+        return prepared;
+    return openMemoryDatabase({ path });
+}
+function validateCommand(area, command) {
+    if (area === 'agents') {
+        return command === 'register' || command === 'list' || command === 'get' || command === 'render' || command === 'resolve' || command === 'seed' || command === 'manager-profile'
+            ? { ok: true }
+            : { ok: false, message: `Unknown agents command: ${command}` };
+    }
+    if (area === 'subagents') {
+        return command === 'register' || command === 'list' || command === 'get'
+            ? { ok: true }
+            : { ok: false, message: `Unknown subagents command: ${command}` };
+    }
+    if (area === 'memory') {
+        return command === 'save' || command === 'search' || command === 'import'
+            ? { ok: true }
+            : { ok: false, message: `Unknown memory command: ${command}` };
+    }
+    if (area === 'runs') {
+        return command === 'create' || command === 'list' || command === 'get' || command === 'timeline' || command === 'debug' || command === 'resume-plan' || command === 'resume-inspect' || command === 'export-snapshot' || command === 'checkpoint' || command === 'finish' || command === 'permission-check' || command === 'preflight' || command === 'approvals' || command === 'retry-check' || command === 'resume-gate' || command === 'approve' || command === 'reject' || command === 'cancel-approval'
+            ? { ok: true }
+            : { ok: false, message: `Unknown runs command: ${command}` };
+    }
+    if (area === 'approvals') {
+        return command === 'list' || command === 'approve' || command === 'reject'
+            ? { ok: true }
+            : { ok: false, message: `Unknown approvals command: ${command}` };
+    }
+    if (area === 'permissions') {
+        return command === 'check'
+            ? { ok: true }
+            : { ok: false, message: `Unknown permissions command: ${command}` };
+    }
+    if (area === 'skills') {
+        return command === 'register' || command === 'list' || command === 'get' || command === 'add-version' || command === 'attach' || command === 'detach' || command === 'record-usage' || command === 'resolve' || command === 'payload' || command === 'propose' || command === 'proposals' || command === 'create-scenario' || command === 'list-scenarios' || command === 'record-evaluation-result' || command === 'list-evaluation-results' || command === 'get-proposal' || command === 'submit-proposal' || command === 'approve-proposal' || command === 'reject-proposal' || command === 'cancel-proposal' || command === 'apply-proposal'
+            ? { ok: true }
+            : { ok: false, message: `Unknown skills command: ${command}` };
+    }
+    if (area === 'sdd') {
+        return command === 'preview' || command === 'run' || command === 'execute' || command === 'status' || command === 'next' || command === 'ready' || command === 'save-artifact' || command === 'get-artifact' || command === 'list-artifacts' || command === 'export' || command === 'import'
+            ? { ok: true }
+            : { ok: false, message: `Unknown sdd command: ${command}` };
+    }
+    if (findWorkflowDefinition(area) !== undefined) {
+        return command === 'preview' || command === 'run' || command === 'execute'
+            ? { ok: true }
+            : { ok: false, message: `Unknown ${area} command: ${command}` };
+    }
+    if (area === 'orchestrator') {
+        return command === 'preview'
+            ? { ok: true }
+            : { ok: false, message: `Unknown orchestrator command: ${command}` };
+    }
+    if (area === 'opencode') {
+        return command === 'preview'
+            ? { ok: true }
+            : { ok: false, message: `Unknown opencode command: ${command}` };
+    }
+    if (area === 'setup') {
+        return command === 'status' || command === 'plan' || command === 'apply' || command === 'rollback'
+            ? { ok: true }
+            : { ok: false, message: `Unknown setup command: ${command}` };
+    }
+    if (area === 'dashboard') {
+        return command === 'status'
+            ? { ok: true }
+            : { ok: false, message: `Unknown dashboard command: ${command}` };
+    }
+    return { ok: false, message: `Unknown command area: ${area}` };
+}
+function requiredFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' && value.trim() ? { ok: true, value } : validationFailure(`Missing required --${name}`);
+}
+function optionalStringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function scopeFlag(flags, name, fallback) {
+    const value = optionalStringFlag(flags, name) ?? fallback;
+    return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
+}
+function optionalScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
+}
+function opencodeInstallScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name) ?? 'project';
+    return value === 'project' || value === 'user' ? { ok: true, value } : validationFailure(`--${name} must be project or user`);
+}
+function optionalModeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'agent' || value === 'subagent' ? { ok: true, value } : validationFailure(`--${name} must be agent or subagent`);
+}
+function permissionCategoryFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return permissionCategories.includes(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be one of ${permissionCategories.join(', ')}`);
+}
+function skillSourceFromFlags(flags) {
+    const kind = skillSourceKindFlag(flags, 'source-kind');
+    if (!kind.ok)
+        return kind;
+    if (kind.value === 'path') {
+        const path = requiredFlag(flags, 'source-path');
+        return path.ok ? { ok: true, value: { kind: 'path', path: path.value } } : path;
+    }
+    if (kind.value === 'url') {
+        const url = requiredFlag(flags, 'source-url');
+        return url.ok ? { ok: true, value: { kind: 'url', url: url.value } } : url;
+    }
+    const inlineMetadata = jsonFlag(flags, 'inline-metadata', {});
+    return inlineMetadata.ok
+        ? { ok: true, value: { kind: 'inline', inlineMetadata: inlineMetadata.value } }
+        : inlineMetadata;
+}
+function skillSourceKindFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'path' || value.value === 'url' || value.value === 'inline'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be path, url, or inline`);
+}
+function optionalSkillVersionStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'draft' || value === 'active' || value === 'deprecated' || value === 'archived'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be draft, active, deprecated, or archived`);
+}
+function skillTargetTypeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return isSkillTargetType(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be agent, subagent, workflow-phase, or provider-adapter`);
+}
+function optionalSkillTargetTypeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isSkillTargetType(value)
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be agent, subagent, workflow-phase, or provider-adapter`);
+}
+function skillUsageOutcomeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'selected' || value.value === 'injected' || value.value === 'helped' || value.value === 'failed' || value.value === 'neutral'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be selected, injected, helped, failed, or neutral`);
+}
+function optionalSkillResolutionUsageFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'selected' || value === 'injected'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be selected or injected`);
+}
+function optionalSkillImprovementProposalStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'draft' || value === 'pending-approval' || value === 'approved' || value === 'rejected' || value === 'cancelled' || value === 'applied'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be draft, pending-approval, approved, rejected, cancelled, or applied`);
+}
+function skillEvaluationResultStatusFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return isSkillEvaluationResultStatus(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be passed, failed, needs-review, or not-applicable`);
+}
+function optionalSkillEvaluationResultStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isSkillEvaluationResultStatus(value)
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be passed, failed, needs-review, or not-applicable`);
+}
+function isSkillEvaluationResultStatus(value) {
+    return value === 'passed' || value === 'failed' || value === 'needs-review' || value === 'not-applicable';
+}
+function isSkillTargetType(value) {
+    return value === 'agent' || value === 'subagent' || value === 'workflow-phase' || value === 'provider-adapter';
+}
+function instructionKindFlag(flags) {
+    const value = optionalStringFlag(flags, 'instructions-kind') ?? 'inline';
+    return value === 'inline' || value === 'path' ? { ok: true, value } : validationFailure('--instructions-kind must be inline or path');
+}
+function optionalNumberFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? { ok: true, value: parsed } : validationFailure(`--${name} must be a positive integer`);
+}
+function optionalRunStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isRunStatus(value) ? { ok: true, value } : validationFailure(`--${name} must be a valid run status`);
+}
+function finalRunStatusFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'completed' || value.value === 'failed' || value.value === 'blocked' || value.value === 'cancelled'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be completed, failed, blocked, or cancelled`);
+}
+function runOutcomeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'success' || value.value === 'partial' || value.value === 'failure' || value.value === 'blocked' || value.value === 'cancelled'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be success, partial, failure, blocked, or cancelled`);
+}
+function jsonFlag(flags, name, fallback) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: fallback };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `--${name} must be valid JSON`, cause } };
+    }
+}
+function optionalJsonFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `--${name} must be valid JSON`, cause } };
+    }
+}
+function retryPolicyFlag(flags) {
+    const value = optionalStringFlag(flags, 'policy');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: '--policy must be valid JSON', cause } };
+    }
+    const policy = parseOperationRetryPolicy(parsed);
+    return policy.ok ? { ok: true, value: policy.policy } : validationFailure(`Invalid --policy: ${policy.errors.join('; ')}`);
+}
+function isRunStatus(value) {
+    return value === 'created' || value === 'planned' || value === 'running' || value === 'needs-human' || value === 'completed' || value === 'failed' || value === 'blocked' || value === 'cancelled';
+}
+function csvFlag(flags, name) {
+    return optionalStringFlag(flags, name)?.split(',').map((value) => value.trim()).filter(Boolean) ?? [];
+}
+function readJsonFile(path, environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(environment.cwd, path), 'utf8'));
+        return isRecord(parsed) ? { ok: true, value: parsed } : validationFailure(`Invalid JSON package shape in --file ${path}: expected a JSON object`);
+    }
+    catch (cause) {
+        const message = cause instanceof SyntaxError ? `Invalid JSON in --file ${path}` : `Unable to read --file ${path}`;
+        return { ok: false, error: { code: 'validation_failed', message, cause } };
+    }
+}
+function writeJsonFile(path, value, environment) {
+    try {
+        const outputPath = resolve(environment.cwd, path);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, `${JSON.stringify(value, null, 2)}\n`);
+        return { ok: true, value: undefined };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `Unable to write --file ${path}`, cause } };
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonResult(operation) {
+    if (!operation.ok)
+        return resultFailure(operation);
+    return { exitCode: 0, stdout: `${JSON.stringify(operation.value, null, 2)}\n`, stderr: '' };
+}
+function resultFailure(result) {
+    if (result.ok)
+        return { exitCode: 0, stdout: '', stderr: '' };
+    return { exitCode: 1, stdout: '', stderr: `${result.error.code}: ${result.error.message}\n` };
+}
+function usageFailure(message) {
+    return { exitCode: 1, stdout: '', stderr: `${message}\n\n${visibleHelpText()}` };
+}
+function visibleHelpText() {
+    return helpText().replace('  skills register --project <name> --name <name> --description <text>', '  agents resolve [--project <name>] [--scope project|personal] [--workflow <name>] [--phase <name>] [--provider <name>] [--capabilities <csv>] [--task <text>]\n  skills register --project <name> --name <name> --description <text>');
+}
+function okText(stdout) {
+    return { exitCode: 0, stdout, stderr: '' };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+function helpText() {
+    return `Usage: vgxness <area> <command> [flags]
+
+Areas:
+  init [--project <name>] [--provider opencode|none] [--scope project|user] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  setup plan [--project <name>] [--provider opencode|none] [--scope project|user] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  setup apply --yes [--project <name>] [--provider opencode|none] [--scope project|user] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  setup rollback --backup <path> [--json]
+  setup status [--project <name>] [--scope project|personal] [--db <path>]
+  doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
+  Setup plan/init are read-only by default. Setup apply writes OpenCode config only with --yes and uses the global user DB plus mcp-plus-agents by default.
+  Setup status is local-first and never writes provider config or executes providers.
+
+  agents register --project <name> --name <name> --description <text> --instructions <text>
+  agents register --file <agent.json>
+  agents seed load --file <seed.json>
+  agents list [--project <name>] [--scope project|personal]
+  agents get --id <id> | --project <name> --name <name> [--scope project|personal]
+  agents render --provider json|opencode|claude (--id <id> | --project <name> --name <name> [--scope project|personal])
+  agents manager-profile get [--project <name>] [--scope project|personal] [--manager <name>]
+  agents manager-profile set --instructions <text> [--project <name>] [--scope project|personal] [--manager <name>]
+  Seed loading writes only to the local registry; it does not install or write .opencode/, .claude/, or provider config.
+
+  opencode preview --provider opencode (--agent <name> | --agent-id <id>) --project <name> --change <id> --phase <phase> [--scope project|personal]
+
+  orchestrator preview --project <name> --intent <text> [--change <id>] [--db <path>]
+  Orchestrator preview classifies natural-language requests only; it never executes providers, edits files, records runs, or writes provider config.
+
+  explore|quickfix|plan|build|debug|sdd preview [--project <name>] [--intent <text>]
+  Workflow previews return registry and planner JSON only; they never execute code, edit files, record runs, or write provider config.
+  explore|quickfix|plan|build|debug|sdd run [--project <name>] --intent <text> [--phase <name>] [--agent-id <id>] [--db <path>]
+  Workflow runs record intent plus a safety checkpoint only; they do not call providers, edit files, write provider config, create subagents, or mutate SDD artifacts.
+  explore|quickfix|plan|build|debug|sdd execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--executor safe-non-dispatching|provider|command] [--command typecheck|node-version] [--command-cwd <path>] [--command-targets <paths>] [--db <path>]
+  Workflow execute is an explicit safety-gated request; default executor records preflight/ready-to-dispatch state. --executor provider remains guarded and refuses dispatch unless enforceable sandbox/preflight/adapter gates are present. --executor command runs only hardcoded allowlisted argv through bounded-process; no shell strings or provider config targets are allowed.
+
+  approvals list [--run-id <id>] [--db <path>]
+  approvals approve --id <approval-id> [--db <path>]
+  approvals reject --id <approval-id> [--reason <text>] [--db <path>]
+  Approval commands resolve explicit run/preflight approval records; they do not change agent seed permissions or globally allow shell/provider access.
+
+  mcp setup --preview --provider opencode|claude [--db <path>]
+  mcp install opencode --plan [--scope project|user] [--db <path>] [--mcp-only|--no-agents]
+  mcp install opencode --yes [--scope project|user] [--db <path>] [--mcp-only|--no-agents]
+  mcp doctor opencode [--scope project|user] [--project-root <path>]
+  mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
+  MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
+  Without --db, MCP install and setup commands use the vgxness global default database; pass --db .vgx/memory.sqlite for project-local compatibility.
+  OpenCode install defaults to project scope and installs mcp.vgxness plus vgxness-manager and hidden vgxness-sdd-* agents; use --mcp-only for legacy MCP-only config.
+  It writes only after --yes; use --scope user for $HOME/.config/opencode/opencode.json.
+  Project OpenCode config can override user config. Plans are read-only; applies refuse unsafe existing config and create backups before merge.
+
+  skills register --project <name> --name <name> --description <text>
+  skills list [--project <name>] [--scope project|personal]
+  skills get --id <id> | --project <name> --name <name> [--scope project|personal]
+  skills add-version (--id <id> | --project <name> --name <name>) --version <version> --source-kind path|url|inline [--source-path <path>] [--source-url <url>] [--inline-metadata <json>] [--activate]
+  skills attach (--id <id> | --project <name> --name <name>) --target-type agent|subagent|workflow-phase|provider-adapter --target-key <key>
+  skills detach (--id <id> | --project <name> --name <name>) --target-type agent|subagent|workflow-phase|provider-adapter --target-key <key>
+  skills record-usage (--id <id> | --project <name> --name <name>) --outcome selected|injected|helped|failed|neutral [--run-id <id>]
+  skills resolve [--agent <name> | --agent-id <id>] [--project <name>] [--workflow <name>] [--phase <name>] [--provider <name>] [--run <id>] [--record-usage selected|injected]
+  skills payload [--agent <name> | --agent-id <id>] [--project <name>] [--workflow <name>] [--phase <name>] [--provider <name>]
+  skills propose (--id <id> | --project <name> --name <name>) --proposed-version <version> --source-kind path|url|inline --rationale <text>
+  skills proposals [--skill-id <id>] [--status draft|pending-approval|approved|rejected|cancelled|applied]
+  skills create-scenario (--id <id> --name <scenario> | --project <name> --name <skill> --scenario-name <scenario>) --criteria <json> --created-by <actor> [--proposal <id>] [--version-id <id>]
+  skills list-scenarios (--id <id> | --project <name> --name <name>) [--proposal <id>] [--version-id <id>]
+  skills record-evaluation-result --scenario <id> --status passed|failed|needs-review|not-applicable --result <json> --observed-behavior <text> --evaluator <actor> [--proposal <id>] [--version-id <id>] [--notes <text>]
+  skills list-evaluation-results [--scenario <id>] [--skill-id <id>] [--proposal <id>] [--version-id <id>] [--evaluator <actor>] [--status passed|failed|needs-review|not-applicable]
+  skills get-proposal --proposal <id>
+  skills submit-proposal|approve-proposal|reject-proposal|cancel-proposal|apply-proposal --proposal <id> --actor <name> [--reason <text>]
+
+  subagents register --parent-agent-id <id> --project <name> --name <name> --description <text> --instructions <text>
+  subagents register --file <subagent.json>
+  subagents list --parent-agent-id <id>
+  subagents get --id <id> | --project <name> --name <name> [--scope project|personal]
+
+  dashboard status --project <name> [--change <id>] [--run-id <id>] [--limit <n>]
+  dashboard interactive [--project <name>] [--change <id>] [--limit <n>]
+  Dashboard menu: Setup, Workflows, Runs, Approvals, Agents, SDD, Doctor, Settings. Menu: ↑/↓ or j/k, Enter, 1-8. Section: b/Esc back, 1-8, r, ?, q.
+  Dashboard interactive may launch without --project; Setup remains available and project-scoped checks are deferred while project screens render project-required recovery states.
+  Provider setup support: OpenCode supported primary; Claude preview-only; Antigravity placeholder; Custom/future extension point.
+  Dashboard preview/status is read-only. Provider config writes/install/apply are external-only, require explicit confirmation outside the dashboard, and are not run by dashboard flows.
+
+  sdd status --project <name> --change <id>
+  sdd next --project <name> --change <id>
+  sdd ready --project <name> --change <id> --phase <phase>
+  sdd save-artifact --project <name> --change <id> --phase <phase> --content <text>
+  sdd get-artifact --project <name> --change <id> --phase <phase> [--db <path>]
+  sdd list-artifacts --project <name> --change <id> [--db <path>]
+  SDD artifact reads use the selected local SQLite memory store via --db, VGXNESS_DB_PATH, or the global default.
+  sdd export --project <name> --change <id> [--file <package.json>]
+  sdd import --project <name> --change <id> --file <package.json> [--write] [--overwrite]
+
+  memory save --project <name> --type <type> --title <title> --content <text>
+  memory search [--query <text>] [--project <name>] [--type <type>]
+  memory import --file <package.json> --dry-run [--db <path>]
+  memory import --file <package.json> --write (--skip-existing | --overwrite) [--db <path>]
+
+  runs create --project <name> --intent <text> --workflow <name> --phase <name> --agent-id <id> --provider-adapter <name> --model <name>
+  runs list [--project <name>] [--status <status>]
+  runs get --id <id>
+  runs timeline --id <id>
+  runs debug --id <id>
+  runs resume-plan --id <id>
+  runs resume-inspect --id <id>
+  resume-inspect is read-only: it prints checkpoint context, blockers, safety flags, and manual next commands without executing providers, preflight, retry, sandbox, or worktree steps.
+  runs export-snapshot --run-id <id> --project <name> [--file <snapshot.json>]
+  runs checkpoint --run-id <id> --label <text> [--state <json>]
+  runs finish --run-id <id> --status completed|failed|blocked|cancelled --outcome <outcome> [--reason <text>]
+  runs permission-check --run-id <id> --category <category> --operation <name> [--path <path>] [--agent-id <id>] [--destructive] [--external] [--privileged] [--ambiguous]
+  runs preflight --run-id <id> --category <category> --operation <name> [--workspace <path>] [--path <path>] [--provider-tool <name>] [--agent-id <id>] [--destructive] [--external] [--privileged] [--ambiguous]
+  runs approvals --run <run-id>
+  runs approve|reject|cancel-approval --approval <id> --actor <name> [--reason <text>]
+  runs retry-check --approval <id> [--policy <json>]
+  runs resume-gate --approval <id> [--policy <json>]
+  resume-gate is read-only and plan-only: it prints service planner JSON without preflight, retry admission, executors, provider config writes, sandbox creation, or worktree creation.
+
+  permissions check --category <category> --operation <name> [--path <path>] [--agent-id <id>] [--external] [--privileged]
+
+Storage:
+  Default: global user data vgxness/memory.sqlite (macOS ~/Library/Application Support/vgxness/memory.sqlite; Linux \${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite; Windows %APPDATA%\\vgxness\\memory.sqlite).
+  Precedence: --db <path> (source: flag) > VGXNESS_DB_PATH (source: environment) > global default (source: global-default).
+  Compatibility: pass --db .vgx/memory.sqlite to use the old project-local database explicitly.
+`;
+}