vgxness 1.0.0 → 1.0.2

package/dist/cli/cli-help.js

@@ -138,7 +138,7 @@ Areas:
   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).
+  Default: global user data vgxness/memory.sqlite (macOS ~/Library/Application Support/vgxness/memory.sqlite; Linux \${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite; Windows %LOCALAPPDATA%\\vgxness\\memory.sqlite, falling back to %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.
 `;

package/dist/cli/dashboard-screen-renderers.js

@@ -1,4 +1,4 @@
-import { classifySetupForProject, copyOnly, isSetupReady } from './dashboard-tui-read-model.js';
+import { classifySetupForProject, copyOnly, isSetupReady, } from './dashboard-tui-read-model.js';
 import { dashboardScreens } from './dashboard-tui-state.js';
 import { renderSetupStatus } from './setup-status-renderer.js';
 import { joinSections, renderFooterGroups, renderPanel, renderTabRow, styleFocusedRow } from './tui-render-helpers.js';
@@ -26,6 +26,7 @@ export function renderDashboardFrame(state, options = {}) {
         renderErrorsPanel(state, options),
         renderBackControl(options),
         renderPanel(`Content · ${activeLabel(state.activeScreen)}`, renderActiveScreen(state, options).split('\n'), options),
+        renderActionPreviewPanel(state.actionPreview, options),
         renderDashboardFooter(state, options),
     ]);
 }
@@ -83,12 +84,33 @@ function renderErrorsPanel(state, options) {
 function renderDashboardFooter(state, options) {
     const modeGroups = state.viewMode === 'menu'
         ? [{ label: 'Menu', items: ['↑/↓ or j/k move', 'Enter open', '1-9/0 open'] }]
-        : [{ label: 'Section', items: ['j/k or ↑/↓ move', 'Enter detail only', 'b/Esc/Backspace back'] }];
+        : [{ label: 'Section', items: ['j/k or ↑/↓ move', 'Enter detail only', '[a] Action preview', 'b/Esc/Backspace back'] }];
     return renderPanel('Footer/help', [
         ...renderFooterGroups([...modeGroups, { label: 'Global', items: ['r refresh', '? help', 'q quit'] }], options),
         'Safety: read-only dashboard; actions are copy-only and never apply/install/approve.',
     ], options);
 }
+function renderActionPreviewPanel(preview, options) {
+    if (preview === undefined)
+        return undefined;
+    if (!preview.available)
+        return renderPanel('Action preview', [
+            `Source: ${preview.screen}`,
+            `State: unavailable`,
+            preview.message,
+            'Safety: display-only; does not run in TUI.',
+        ], options);
+    const descriptor = preview.descriptor;
+    return renderPanel('Action preview', [
+        `Label: ${descriptor.label}`,
+        `Source: ${descriptor.source.screen} · ${descriptor.source.rowTitle} (${descriptor.source.rowId})`,
+        `Mode: ${descriptor.mode}`,
+        `Safety: ${descriptor.safety}; copyOnly=${String(descriptor.copyOnly)}; executesInTui=${String(descriptor.executesInTui)}`,
+        `Command: ${descriptor.command}`,
+        `Guidance: ${descriptor.guidance}`,
+        'This preview does not run in TUI.',
+    ], options);
+}
 function renderActiveScreen(state, options) {
     if (state.activeScreen === 'installation')
         return renderInstallationScreen(state, options);

package/dist/cli/dashboard-tui-state.js

@@ -71,6 +71,8 @@ export function createDashboardState(input) {
         state.management = input.management;
     if (input.runInsights !== undefined)
         state.runInsights = input.runInsights;
+    if (input.actionPreview !== undefined)
+        state.actionPreview = input.actionPreview;
     if (input.navigationNotice !== undefined)
         state.navigationNotice = input.navigationNotice;
     if (input.error !== undefined)
@@ -83,19 +85,19 @@ export function initialDashboardScreen(setup, setupError) {
 export function reduceDashboardKey(state, key) {
     const screen = screenForKey(key);
     if (screen !== undefined) {
-        const { navigationNotice: _navigationNotice, ...rest } = state;
+        const { actionPreview: _actionPreview, navigationNotice: _navigationNotice, ...rest } = state;
         return { ...rest, viewMode: 'screen', activeScreen: screen, focusedScreen: screen };
     }
     if (key === 'menu-back')
         return state.viewMode === 'screen' ? backFromScreen(state) : state;
     if (key === 'menu-left')
-        return moveMenuFocus(state, -1);
+        return moveMenuFocus(clearActionPreview(state), -1);
     if (key === 'menu-right')
-        return moveMenuFocus(state, 1);
+        return moveMenuFocus(clearActionPreview(state), 1);
     if (key === 'menu-open') {
         if (state.viewMode === 'screen')
             return showDetail(state);
-        const { navigationNotice: _navigationNotice, ...rest } = state;
+        const { actionPreview: _actionPreview, navigationNotice: _navigationNotice, ...rest } = state;
         return { ...rest, viewMode: 'screen', activeScreen: state.focusedScreen };
     }
     if (isSetupKey(key))
@@ -104,8 +106,12 @@ export function reduceDashboardKey(state, key) {
         return state.viewMode === 'menu' ? moveMenuFocus(state, -1) : navigateScreenRows(state, -1);
     if (key === 'down')
         return state.viewMode === 'menu' ? moveMenuFocus(state, 1) : navigateScreenRows(state, 1);
+    if (key === 'action-preview')
+        return state.viewMode === 'screen' ? showActionPreview(state) : state;
     if (key === 'help')
         return { ...state, helpVisible: !state.helpVisible };
+    if (key === 'refresh')
+        return clearActionPreview(state);
     if (key === 'quit')
         return { ...state, shouldExit: true };
     return state;
@@ -137,6 +143,8 @@ export function dashboardKeyFromInput(input) {
         return 'menu-right';
     if (input === '\r' || input === '\n')
         return 'menu-open';
+    if (input === 'a')
+        return 'action-preview';
     if (input === 'b' || input === '\u001B' || input === '\u007F')
         return 'menu-back';
     if (input === 'd')
@@ -216,22 +224,65 @@ function screenForKey(key) {
     return undefined;
 }
 function backFromScreen(state) {
+    if (state.actionPreview !== undefined)
+        return clearActionPreview(state);
     if (state.detailVisibleByScreen[state.activeScreen] === true)
-        return { ...state, detailVisibleByScreen: { ...state.detailVisibleByScreen, [state.activeScreen]: false } };
-    return { ...state, viewMode: 'menu' };
+        return { ...clearActionPreview(state), detailVisibleByScreen: { ...state.detailVisibleByScreen, [state.activeScreen]: false } };
+    return { ...clearActionPreview(state), viewMode: 'menu' };
 }
 function showDetail(state) {
-    return { ...state, detailVisibleByScreen: { ...state.detailVisibleByScreen, [state.activeScreen]: true } };
+    return { ...clearActionPreview(state), detailVisibleByScreen: { ...state.detailVisibleByScreen, [state.activeScreen]: true } };
 }
 function navigateScreenRows(state, delta) {
-    const rows = state.management?.[state.activeScreen]?.rows.length ?? 0;
+    const rows = isManagementScreen(state.activeScreen) ? (state.management?.[state.activeScreen]?.rows.length ?? 0) : 0;
     if (rows === 0 && state.activeScreen === 'runs')
-        return navigateRuns(state, delta);
+        return navigateRuns(clearActionPreview(state), delta);
     if (rows === 0)
         return state;
     const current = state.selectedByScreen[state.activeScreen] ?? 0;
     const next = (current + delta + rows) % rows;
-    return { ...state, selectedByScreen: { ...state.selectedByScreen, [state.activeScreen]: next } };
+    return { ...clearActionPreview(state), selectedByScreen: { ...state.selectedByScreen, [state.activeScreen]: next } };
+}
+function showActionPreview(state) {
+    if (!isManagementScreen(state.activeScreen))
+        return { ...state, actionPreview: { available: false, screen: state.activeScreen, message: 'No action preview is available for this screen.' } };
+    const model = state.management?.[state.activeScreen];
+    const row = model?.rows[state.selectedByScreen[state.activeScreen] ?? 0];
+    if (row === undefined)
+        return { ...state, actionPreview: { available: false, screen: state.activeScreen, message: 'No selected row has an action to preview.' } };
+    const action = row.copyActions[0];
+    if (action === undefined)
+        return { ...state, actionPreview: { available: false, screen: state.activeScreen, message: 'The selected row has no copy-only action.' } };
+    return { ...state, actionPreview: { available: true, descriptor: actionDescriptor(state.activeScreen, row.id, row.title, action) } };
+}
+function actionDescriptor(screen, rowId, rowTitle, action) {
+    return {
+        id: `${screen}:${rowId}:copy-action:0`,
+        label: action.label,
+        source: { screen, rowId, rowTitle },
+        mode: 'copy-command',
+        safety: action.safety,
+        command: action.command,
+        guidance: 'Copy and run outside the TUI only after manual review. This dashboard does not execute the action.',
+        copyOnly: true,
+        executesInTui: false,
+    };
+}
+function clearActionPreview(state) {
+    if (state.actionPreview === undefined)
+        return state;
+    const { actionPreview: _actionPreview, ...rest } = state;
+    return rest;
+}
+function isManagementScreen(screen) {
+    return (screen === 'agents' ||
+        screen === 'skills' ||
+        screen === 'memory' ||
+        screen === 'sdd' ||
+        screen === 'runs' ||
+        screen === 'approvals' ||
+        screen === 'permissions' ||
+        screen === 'settings');
 }
 function isSetupKey(key) {
     return key.startsWith('setup-');

package/dist/code/runtime/code-runtime.js

@@ -12,7 +12,7 @@ import { prepareWorkspaceApprovalRequest, WorkspaceToolExecutor } from '../tools
 import { createApprovalId, ConservativePermissionGateway, PolicyApprovalBroker, PolicyApprovalPrompt, StdioApprovalBroker, } from './approval-coordinator.js';
 import { InMemoryRunGateway, InMemorySddGateway } from './gateways.js';
 import { detectProject } from './project-detection.js';
-import { implementationEnabledForSddPhase, isSddCodePhase, loadSddContext, shellEnabledForSddPhase, validateSddReadiness, } from './sdd-context.js';
+import { activeBlockedPrerequisites, implementationEnabledForSddPhase, isSddCodePhase, loadSddContext, shellEnabledForSddPhase, validateSddReadiness, } from './sdd-context.js';
 import { createVerificationToolCall, VerificationCoordinator } from './verification-coordinator.js';
 export class CodeRuntime {
     provider;
@@ -122,8 +122,22 @@ export class CodeRuntime {
             await this.checkpoint(run.id, session, 'sdd-context-loaded', {
                 changeId: sddContext.changeId,
                 phase: sddContext.phase,
-                artifacts: sddContext.artifacts.map((artifact) => ({ phase: artifact.phase, role: artifact.role, bytes: artifact.content.length })),
-                next: { ...sddContext.next, missingArtifactTopicKeys: [...sddContext.next.missingArtifactTopicKeys] },
+                artifacts: sddContext.artifacts.map((artifact) => ({
+                    phase: artifact.phase,
+                    role: artifact.role,
+                    bytes: artifact.content.length,
+                    state: artifact.state ?? null,
+                    accepted: artifact.accepted === true,
+                    legacy: artifact.legacy === true,
+                    artifactId: artifact.artifactId ?? null,
+                    topicKey: artifact.topicKey ?? null,
+                })),
+                activePhase: sddContext.status.phases.find((phase) => phase.phase === sddContext.phase) ?? null,
+                next: {
+                    ...sddContext.next,
+                    missingArtifactTopicKeys: [...sddContext.next.missingArtifactTopicKeys],
+                    blockedPrerequisites: [...(sddContext.next.blockedPrerequisites ?? [])],
+                },
             });
             const readiness = validateSddReadiness(sddContext);
             if (!readiness.ok) {
@@ -555,7 +569,11 @@ export class CodeRuntime {
                     events: [],
                     changedFiles: [],
                 };
-            if (call.name === 'sdd_get_readiness')
+            if (call.name === 'sdd_get_readiness') {
+                const blockedPrerequisites = activeBlockedPrerequisites(context);
+                const missingArtifactTopicKeys = blockedPrerequisites.length > 0
+                    ? blockedPrerequisites.filter((blocker) => blocker.reason === 'missing').map((blocker) => blocker.topicKey)
+                    : [...context.next.missingArtifactTopicKeys];
                 return {
                     result: {
                         toolCallId: call.id,
@@ -566,6 +584,8 @@ export class CodeRuntime {
                             phase: context.phase,
                             next: context.next,
                             activePhase: context.status.phases.find((phase) => phase.phase === context.phase) ?? null,
+                            blockedPrerequisites: blockedPrerequisites.length > 0 ? blockedPrerequisites : [...(context.next.blockedPrerequisites ?? [])],
+                            missingArtifactTopicKeys,
                         },
                         metadata: { capability, truncated: false },
                     },
@@ -577,12 +597,15 @@ export class CodeRuntime {
                                 phase: context.phase,
                                 nextPhase: context.next.nextPhase ?? null,
                                 status: context.next.status,
-                                missingArtifactTopicKeys: [...context.next.missingArtifactTopicKeys],
+                                activePhase: context.status.phases.find((phase) => phase.phase === context.phase) ?? null,
+                                blockedPrerequisites: blockedPrerequisites.length > 0 ? blockedPrerequisites : [...(context.next.blockedPrerequisites ?? [])],
+                                missingArtifactTopicKeys,
                             },
                         },
                     ],
                     changedFiles: [],
                 };
+            }
             if (call.name === 'sdd_next_phase')
                 return {
                     result: {

package/dist/code/runtime/gateways.js

@@ -26,29 +26,26 @@ export class InMemorySddGateway {
     artifacts = new Map();
     saved = [];
     constructor(initialArtifacts = {}) {
-        for (const [key, content] of Object.entries(initialArtifacts))
-            this.artifacts.set(key, content);
+        for (const [key, artifact] of Object.entries(initialArtifacts))
+            this.artifacts.set(key, normalizeInMemoryArtifact(artifact));
     }
     async getStatus(input) {
-        const phases = sddPhaseOrder.map((phase) => ({
-            phase,
-            topicKey: artifactKey(input.project, input.change, phase),
-            present: this.artifacts.has(artifactKey(input.project, input.change, phase)),
-        }));
-        const nextReadyPhase = phases.find((status) => !status.present && sddPrerequisites[status.phase].every((phase) => this.artifacts.has(artifactKey(input.project, input.change, phase))))?.phase;
+        const phases = sddPhaseOrder.map((phase) => inMemoryPhaseStatus(this.artifacts.get(artifactKey(input.project, input.change, phase)), input.change, phase));
+        const nextReadyPhase = phases.find((status) => !status.accepted && blockersForPhase(this.artifacts, input.project, input.change, status.phase).length === 0)?.phase;
         return { change: input.change, phases, ...(nextReadyPhase === undefined ? {} : { nextReadyPhase }) };
     }
     async getArtifact(input) {
-        const content = this.artifacts.get(artifactKey(input.project, input.change, input.phase));
-        return content === undefined ? null : { content };
+        const artifact = this.artifacts.get(artifactKey(input.project, input.change, input.phase));
+        return artifact === undefined ? null : { content: artifact.content };
     }
     async saveArtifact(input) {
-        this.artifacts.set(artifactKey(input.project, input.change, input.phase), input.content);
+        this.artifacts.set(artifactKey(input.project, input.change, input.phase), normalizeInMemoryArtifact({ content: input.content, state: 'draft', accepted: false }));
         this.saved.push(input);
     }
     async markReady() { }
     async getNextPhase(input) {
         const status = await this.getStatus(input);
+        const blockedPrerequisites = status.nextReadyPhase === undefined ? blockersForFirstBlockedPhase(this.artifacts, input.project, input.change) : [];
         if (status.nextReadyPhase !== undefined)
             return {
                 status: 'runnable',
@@ -57,7 +54,7 @@ export class InMemorySddGateway {
                 recommendedAction: `Run the ${status.nextReadyPhase} SDD phase for ${input.change}.`,
                 missingArtifactTopicKeys: [],
             };
-        const missing = sddPhaseOrder.find((phase) => !status.phases.find((candidate) => candidate.phase === phase)?.present);
+        const missing = sddPhaseOrder.find((phase) => !status.phases.find((candidate) => candidate.phase === phase)?.accepted);
         if (missing === undefined)
             return {
                 status: 'complete',
@@ -71,12 +68,76 @@ export class InMemorySddGateway {
         return {
             status: 'blocked',
             nextPhase: missing,
-            reason: `${missing} is blocked by missing prerequisite artifacts.`,
-            recommendedAction: `Create or restore ${missingArtifactTopicKeys.join(', ')} before running ${missing}.`,
+            reason: `${missing} is blocked by prerequisite artifact governance.`,
+            recommendedAction: `Accept or restore prerequisites before running ${missing}.`,
             missingArtifactTopicKeys,
+            blockedPrerequisites,
         };
     }
 }
 function artifactKey(project, change, phase) {
     return `${project}:${change}:${phase}`;
 }
+function normalizeInMemoryArtifact(input) {
+    if (typeof input === 'string')
+        return { content: input, state: 'accepted', accepted: true, legacy: false };
+    const state = input.state ?? (input.accepted === true ? 'accepted' : 'draft');
+    return {
+        content: input.content,
+        state,
+        accepted: input.accepted ?? state === 'accepted',
+        legacy: input.legacy ?? false,
+        ...(input.artifactId === undefined ? {} : { artifactId: input.artifactId }),
+    };
+}
+function inMemoryPhaseStatus(artifact, change, phase) {
+    const topicKey = `sdd/${change}/${phase}`;
+    if (artifact === undefined)
+        return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false };
+    return {
+        phase,
+        topicKey,
+        present: true,
+        state: artifact.state,
+        accepted: artifact.accepted,
+        legacy: artifact.legacy,
+        ...(artifact.artifactId === undefined ? {} : { artifactId: artifact.artifactId }),
+    };
+}
+function blockersForFirstBlockedPhase(artifacts, project, change) {
+    for (const phase of sddPhaseOrder) {
+        const status = inMemoryPhaseStatus(artifacts.get(artifactKey(project, change, phase)), change, phase);
+        if (status.accepted === true)
+            continue;
+        const blockers = blockersForPhase(artifacts, project, change, phase);
+        if (blockers.length > 0)
+            return blockers;
+    }
+    return [];
+}
+function blockersForPhase(artifacts, project, change, phase) {
+    return sddPrerequisites[phase].flatMap((prerequisite) => {
+        const key = artifactKey(project, change, prerequisite);
+        const artifact = artifacts.get(key);
+        const topicKey = `sdd/${change}/${prerequisite}`;
+        if (artifact === undefined)
+            return [{ phase: prerequisite, topicKey, reason: 'missing' }];
+        if (artifact.accepted === true && artifact.legacy !== true)
+            return [];
+        return [
+            {
+                phase: prerequisite,
+                topicKey,
+                reason: blockerReasonForInMemoryArtifact(artifact),
+                ...(artifact.artifactId === undefined ? {} : { artifactId: artifact.artifactId }),
+            },
+        ];
+    });
+}
+function blockerReasonForInMemoryArtifact(artifact) {
+    if (artifact.legacy === true)
+        return 'legacy';
+    if (artifact.state === 'rejected' || artifact.state === 'superseded')
+        return artifact.state;
+    return 'draft';
+}

package/dist/code/runtime/sdd-context.js

@@ -47,8 +47,8 @@ export function compactSddArtifactForPrompt(input) {
         project: input.project,
         change: input.change,
         phase: input.artifact.phase,
-        state: input.artifact.state ?? (input.artifact.role === 'accepted' ? 'accepted' : 'draft'),
-        accepted: input.artifact.accepted ?? input.artifact.role === 'accepted',
+        state: input.artifact.state ?? 'draft',
+        accepted: input.artifact.accepted === true,
         legacy: input.artifact.legacy ?? false,
         ...(input.artifact.artifactId === undefined ? {} : { artifactId: input.artifact.artifactId }),
         ...(input.artifact.topicKey === undefined ? {} : { topicKey: input.artifact.topicKey }),
@@ -65,10 +65,10 @@ export function compactSddArtifactForPrompt(input) {
 }
 function contextPhaseStatus(status, phase) {
     const value = status.phases.find((candidate) => candidate.phase === phase);
-    const state = typeof value?.state === 'string' ? value.state : value?.present === true ? 'accepted' : 'missing';
+    const state = typeof value?.state === 'string' ? value.state : value?.present === true ? 'draft' : 'missing';
     return {
         state,
-        accepted: typeof value?.accepted === 'boolean' ? value.accepted : state === 'accepted',
+        accepted: value?.accepted === true,
         legacy: typeof value?.legacy === 'boolean' ? value.legacy : false,
         ...(typeof value?.artifactId === 'string' ? { artifactId: value.artifactId } : {}),
         ...(typeof value?.topicKey === 'string' ? { topicKey: value.topicKey } : {}),
@@ -86,6 +86,20 @@ export function validateSddReadiness(context) {
     const present = context.status.phases.find((candidate) => candidate.phase === context.phase)?.present === true;
     if (present)
         return { ok: true };
+    const blockedPrerequisites = activeBlockedPrerequisites(context);
+    if (blockedPrerequisites.length > 0)
+        return {
+            ok: false,
+            reason: `${context.phase} is blocked by prerequisite artifact governance.`,
+            state: {
+                phase: context.phase,
+                nextPhase: context.next.nextPhase ?? null,
+                activePhase: context.status.phases.find((candidate) => candidate.phase === context.phase) ?? null,
+                blockedPrerequisites,
+                missingArtifactTopicKeys: blockedPrerequisites.filter((blocker) => blocker.reason === 'missing').map((blocker) => blocker.topicKey),
+                recommendedAction: `Accept or restore prerequisites before running ${context.phase}.`,
+            },
+        };
     if (context.status.nextReadyPhase === context.phase)
         return { ok: true };
     return {
@@ -94,20 +108,39 @@ export function validateSddReadiness(context) {
         state: {
             phase: context.phase,
             nextPhase: context.next.nextPhase ?? null,
+            activePhase: context.status.phases.find((candidate) => candidate.phase === context.phase) ?? null,
+            blockedPrerequisites: [...(context.next.blockedPrerequisites ?? [])],
             missingArtifactTopicKeys: [...context.next.missingArtifactTopicKeys],
             recommendedAction: context.next.recommendedAction,
         },
     };
 }
+export function activeBlockedPrerequisites(context) {
+    return prerequisitePhases(context.phase).flatMap((phase) => {
+        const status = context.status.phases.find((candidate) => candidate.phase === phase);
+        const topicKey = status?.topicKey ?? `sdd/${context.changeId}/${phase}`;
+        if (status === undefined || status.present !== true)
+            return [{ phase, topicKey, reason: 'missing' }];
+        if (status.accepted === true && status.legacy !== true)
+            return [];
+        const reason = status.legacy === true ? 'legacy' : status.state === 'rejected' || status.state === 'superseded' ? status.state : 'draft';
+        return [{ phase, topicKey, reason, ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }) }];
+    });
+}
 function acceptedArtifactPhases(active) {
+    return prerequisitePhases(active);
+}
+function prerequisitePhases(active) {
+    if (active === 'proposal')
+        return ['explore'];
     if (active === 'spec')
-        return [];
+        return ['proposal'];
     if (active === 'design')
-        return ['spec'];
+        return ['proposal', 'spec'];
     if (active === 'tasks')
-        return ['spec', 'design'];
+        return ['proposal', 'spec', 'design'];
     if (active === 'apply-progress' || active === 'verify' || active === 'archive')
-        return ['spec', 'design', 'tasks'];
+        return ['proposal', 'spec', 'design', 'tasks'];
     return [];
 }
 function uniquePhases(phases) {

package/dist/code/runtime/sdd-workflow-gateway.js

@@ -9,7 +9,15 @@ export class SddWorkflowGateway {
             throw new Error(result.error.message);
         return {
             change: result.value.change,
-            phases: result.value.phases.map((phase) => ({ phase: phase.phase, present: phase.present, topicKey: phase.topicKey })),
+            phases: result.value.phases.map((phase) => ({
+                phase: phase.phase,
+                present: phase.present,
+                topicKey: phase.topicKey,
+                ...(phase.state === undefined ? {} : { state: phase.state }),
+                ...(phase.accepted === undefined ? {} : { accepted: phase.accepted }),
+                ...(phase.legacy === undefined ? {} : { legacy: phase.legacy }),
+                ...(phase.artifactId === undefined ? {} : { artifactId: phase.artifactId }),
+            })),
             ...(result.value.nextReadyPhase === undefined ? {} : { nextReadyPhase: result.value.nextReadyPhase }),
         };
     }
@@ -33,12 +41,23 @@ export class SddWorkflowGateway {
         const result = this.service.getNext(input);
         if (!result.ok)
             throw new Error(result.error.message);
+        const status = this.service.getStatus(input);
+        if (!status.ok)
+            throw new Error(status.error.message);
+        const legacyPrerequisites = new Set(status.value.phases.filter((phase) => phase.legacy === true).map((phase) => `${phase.phase}:${phase.topicKey}`));
+        const blockedPrerequisites = (result.value.blockedPrerequisites ?? []).map((blocker) => ({
+            phase: blocker.phase,
+            topicKey: blocker.topicKey,
+            reason: legacyPrerequisites.has(`${blocker.phase}:${blocker.topicKey}`) ? 'legacy' : blocker.reason,
+            ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+        }));
         return {
             status: result.value.status,
             ...(result.value.nextPhase === undefined ? {} : { nextPhase: result.value.nextPhase }),
             reason: result.value.reason,
             recommendedAction: result.value.recommendedAction,
             missingArtifactTopicKeys: result.value.missingArtifactTopicKeys,
+            ...(blockedPrerequisites.length === 0 ? {} : { blockedPrerequisites }),
         };
     }
 }

package/dist/mcp/control-plane.js

@@ -16,6 +16,7 @@ import { ProviderDoctorService } from './provider-doctor.js';
 import { ProviderStatusService } from './provider-status.js';
 import { errorEnvelope, successEnvelope, } from './schema.js';
 import { validateVgxMcpToolCall } from './validation.js';
+import { OpenCodeHandoffPreviewService } from './opencode-handoff-preview.js';
 export function callVgxTool(call, services) {
     const validated = validateVgxMcpToolCall(call);
     if (!validated.ok)
@@ -74,6 +75,10 @@ export function callVgxTool(call, services) {
             return buildSkillPayloadEnvelope(validated.input, services);
         case 'vgxness_opencode_manager_payload':
             return toEnvelope(validated.tool, services.opencodeManagerPayload.build(validated.input));
+        case 'vgxness_opencode_handoff_preview':
+            if (services.opencodeHandoffPreview === undefined)
+                return errorEnvelope('validation_failed', 'OpenCode handoff preview service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.opencodeHandoffPreview.build(validated.input));
         case 'vgxness_run_list':
             return listRunsEnvelope(validated.input, services);
         case 'vgxness_run_get':
@@ -86,6 +91,10 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.runs.appendCheckpoint(validated.input));
         case 'vgxness_run_finalize':
             return toEnvelope(validated.tool, services.runs.updateFinalStatus(validated.input));
+        case 'vgxness_run_resume_inspect':
+            return toEnvelope(validated.tool, services.runs.getRunOperatorResumePlan(validated.input.runId));
+        case 'vgxness_run_resume_gate':
+            return toEnvelope(validated.tool, services.runs.getRunResumeOrchestrationPlan(validated.input));
         case 'vgxness_provider_status':
             if (services.providerStatus === undefined)
                 return errorEnvelope('validation_failed', 'Provider status service is not available', validated.tool);
@@ -234,15 +243,17 @@ function createServices(database) {
     const runs = new RunService(database);
     const managerProfiles = new ManagerProfileOverlayService({ agents, overlays: new ManagerProfileOverlayRepository(database) });
     const opencodeManagerPayload = new OpenCodeManagerPayloadService({ agents, managerProfiles, skills });
-    const providerStatus = new ProviderStatusService({ sdd: new SddWorkflowService(memory, { actor: 'mcp-control-plane' }) });
+    const sdd = new SddWorkflowService(memory, { actor: 'mcp-control-plane' });
+    const providerStatus = new ProviderStatusService({ sdd });
     const providerDoctor = new ProviderDoctorService();
     return {
-        sdd: new SddWorkflowService(memory, { actor: 'mcp-control-plane' }),
+        sdd,
         memory,
         agents,
         managerProfiles,
         skills,
         opencodeManagerPayload,
+        opencodeHandoffPreview: new OpenCodeHandoffPreviewService({ managerPayload: opencodeManagerPayload, sdd, providerStatus }),
         activation: new AgentActivationService({ agents, managerProfiles, runs, opencodeManagerPayload }),
         runs,
         providerStatus,

package/dist/mcp/index.js

@@ -6,6 +6,7 @@ export * from './client-setup-preview.js';
 export * from './control-plane.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';
+export * from './opencode-handoff-preview.js';
 export * from './provider-change-plan.js';
 export * from './provider-doctor.js';
 export * from './provider-health-types.js';

package/dist/mcp/opencode-handoff-preview.js

@@ -0,0 +1,95 @@
+export class OpenCodeHandoffPreviewService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    build(input) {
+        const scope = input.scope ?? 'project';
+        const warnings = [
+            'This handoff preview does not launch, control, or execute OpenCode.',
+            'This handoff preview does not write .opencode, provider config, backups, .vgx, worktrees, or sandboxes.',
+            'This handoff preview does not create runs, checkpoints, timeline events, sessions, or skill-usage records.',
+        ];
+        const manager = this.deps.managerPayload.build(managerInput(input, scope));
+        if (!manager.ok)
+            return manager;
+        const provider = this.providerSummary(input, scope, warnings);
+        if (!provider.ok)
+            return provider;
+        const sdd = this.sddSummary(input, warnings);
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'opencode-handoff-preview',
+                provider: 'opencode',
+                context: context(input, scope, manager.value),
+                managerPayload: compactManager(manager.value),
+                ...(sdd !== undefined ? { sdd } : {}),
+                ...(provider.value !== undefined ? { providerStatus: compactProvider(provider.value) } : {}),
+                nextSafeAction: 'Manually continue in OpenCode using this preview context; call opencode_manager_payload separately if a verbose payload is needed.',
+                safety: {
+                    readOnly: true,
+                    executesProvider: false,
+                    writesProviderConfig: false,
+                    mutatesProviderConfig: false,
+                    createsRun: false,
+                    createsCheckpoint: false,
+                    recordsTimelineEvent: false,
+                    recordsSkillUsage: false,
+                },
+                warnings: [...warnings, ...manager.value.warnings],
+            },
+        };
+    }
+    sddSummary(input, warnings) {
+        if (input.change === undefined && input.phase === undefined)
+            return undefined;
+        if (input.change === undefined) {
+            warnings.push('phase was provided without change; SDD status/readiness was not queried.');
+            return { ...(input.phase === undefined ? {} : { phase: input.phase }), unavailableReason: 'change is required to read SDD status/readiness' };
+        }
+        const summary = { change: input.change, ...(input.phase === undefined ? {} : { phase: input.phase }) };
+        if (this.deps.sdd === undefined)
+            return { ...summary, unavailableReason: 'SDD service is unavailable' };
+        const status = this.deps.sdd.getStatus({ project: input.project, change: input.change });
+        const next = this.deps.sdd.getNext({ project: input.project, change: input.change });
+        if (status.ok)
+            summary.status = status.value;
+        else
+            warnings.push(`SDD status unavailable: ${status.error.message}`);
+        if (next.ok)
+            summary.next = next.value;
+        else
+            warnings.push(`SDD next phase unavailable: ${next.error.message}`);
+        if (input.phase !== undefined) {
+            const ready = this.deps.sdd.getReady({ project: input.project, change: input.change, phase: input.phase });
+            if (ready.ok)
+                summary.readiness = ready.value;
+            else
+                warnings.push(`SDD readiness unavailable: ${ready.error.message}`);
+        }
+        return summary;
+    }
+    providerSummary(input, scope, warnings) {
+        if (input.workspaceRoot === undefined)
+            return { ok: true, value: undefined };
+        if (this.deps.providerStatus === undefined) {
+            warnings.push('Provider status service is unavailable; provider summary was not inspected.');
+            return { ok: true, value: undefined };
+        }
+        return this.deps.providerStatus.getStatus({ project: input.project, scope, providerAdapter: 'opencode', workspaceRoot: input.workspaceRoot, ...(input.change === undefined ? {} : { change: input.change }), payloadMode: 'compact' });
+    }
+}
+function managerInput(input, scope) {
+    return { project: input.project, scope, agentName: input.agentName ?? 'vgxness-manager', ...(input.agentId === undefined ? {} : { agentId: input.agentId }), ...(input.workspaceRoot === undefined ? {} : { workspaceRoot: input.workspaceRoot }), ...(input.maxSourceBytes === undefined ? {} : { maxSourceBytes: input.maxSourceBytes }), payloadMode: 'compact' };
+}
+function context(input, scope, manager) {
+    return { project: input.project, scope, ...(input.change === undefined ? {} : { change: input.change }), ...(input.phase === undefined ? {} : { phase: input.phase }), ...(input.workspaceRoot === undefined ? {} : { workspaceRoot: input.workspaceRoot }), selectedAgent: manager.selection.agent };
+}
+function compactManager(payload) {
+    return { version: payload.version, provider: payload.provider, selection: payload.selection, payloadMode: payload.payloadMode, providerArtifacts: payload.providerArtifacts, ...(payload.skillDiagnostics === undefined ? {} : { skillDiagnostics: payload.skillDiagnostics }), safety: payload.safety, warnings: payload.warnings };
+}
+function compactProvider(status) {
+    return { version: status.version, kind: status.kind, project: status.project, providerAdapter: status.providerAdapter, scope: status.scope, workspaceRoot: status.workspaceRoot, status: status.status, overallStatus: status.overallStatus, summary: status.summary, nextAction: status.nextAction, issueCount: status.issueCount, warningCount: status.warningCount, safety: status.safety };
+}

package/dist/mcp/schema.js

@@ -27,12 +27,15 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_manager_profile_set',
     'vgxness_skill_payload',
     'vgxness_opencode_manager_payload',
+    'vgxness_opencode_handoff_preview',
     'vgxness_run_list',
     'vgxness_run_get',
     'vgxness_run_preflight',
     'vgxness_run_start',
     'vgxness_run_checkpoint',
     'vgxness_run_finalize',
+    'vgxness_run_resume_inspect',
+    'vgxness_run_resume_gate',
     'vgxness_provider_status',
     'vgxness_provider_doctor',
     'vgxness_provider_change_plan',
@@ -63,12 +66,15 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'manager_profile_set',
     'skill_payload',
     'opencode_manager_payload',
+    'opencode_handoff_preview',
     'run_list',
     'run_get',
     'run_preflight',
     'run_start',
     'run_checkpoint',
     'run_finalize',
+    'run_resume_inspect',
+    'run_resume_gate',
     'provider_status',
     'provider_doctor',
     'provider_change_plan',
@@ -319,6 +325,18 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         payloadMode: z.enum(payloadModes).optional(),
     })
         .passthrough(),
+    vgxness_opencode_handoff_preview: z
+        .object({
+        project: z.string().min(1),
+        scope: z.enum(scopes).optional(),
+        agentId: z.string().min(1).optional(),
+        agentName: z.string().min(1).optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        maxSourceBytes: z.number().int().positive().optional(),
+        change: z.string().min(1).optional(),
+        phase: z.enum(sddPhases).optional(),
+    })
+        .passthrough(),
     vgxness_run_list: z
         .object({
         project: z.string().min(1).optional(),
@@ -382,6 +400,23 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         outcomeReason: z.string().min(1).optional(),
     })
         .passthrough(),
+    vgxness_run_resume_inspect: z
+        .object({
+        runId: z.string().min(1),
+    })
+        .passthrough(),
+    vgxness_run_resume_gate: z
+        .object({
+        approvalId: z.string().min(1),
+        policy: z
+            .object({
+            mode: z.enum(['never', 'after-abandoned', 'after-failure', 'after-failure-or-abandoned']),
+            retryableStatuses: z.array(z.enum(['failed', 'abandoned'])).optional(),
+        })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough(),
     vgxness_provider_status: z
         .object({
         project: z.string().min(1).optional(),

package/dist/mcp/stdio-server.js

@@ -51,8 +51,14 @@ function descriptionForTool(publicToolName) {
         return 'Read-only provider doctor checks; reports OpenCode MCP configuration health without repair/install side effects.';
     if (publicToolName === 'provider_change_plan')
         return 'Read-only provider change plan preview; composes status, doctor, and OpenCode install planning without writing provider config.';
+    if (publicToolName === 'opencode_handoff_preview')
+        return 'Read-only OpenCode handoff preview; returns context for manual continuation only, does not execute/control OpenCode, write .opencode/provider config, or create runs, checkpoints, events, sessions, or skill-usage records.';
     if (publicToolName === 'verification_plan')
         return 'Read-only verification plan recommendations only; does not execute commands, write provider config, persist results, create checkpoints, or infer SDD acceptance.';
+    if (publicToolName === 'run_resume_inspect')
+        return 'Read-only run resume advisory inspect; plan-only and does not execute resume logic, invoke providers, write provider config, mutate retry/abandon/attempt state, or reconstruct sandboxes, worktrees, sessions, or transcripts.';
+    if (publicToolName === 'run_resume_gate')
+        return 'Read-only run resume gate advisory; plan-only and does not execute resume logic, invoke providers, write provider config, admit retries, abandon or mutate attempts, or reconstruct sandboxes, worktrees, sessions, or transcripts.';
     if (publicToolName === 'sdd_cockpit')
         return 'Read-only SDD cockpit summary with next decision, explicit acceptance state, metadata-only artifact summaries, and aggregate blockers.';
     const toolName = toInternalVgxMcpToolName(publicToolName);

package/dist/mcp/validation.js

@@ -1,4 +1,5 @@
 import { isRiskyPermissionCategory, permissionCategories } from '../permissions/schema.js';
+import { parseOperationRetryPolicy } from '../runs/operation-retry.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
 import { supportedTypeMessage, verificationChangeTypes } from '../verification/index.js';
 import { errorEnvelope, isVgxMcpToolName, } from './schema.js';
@@ -77,6 +78,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSkillPayloadInput(input, tool.value));
         case 'vgxness_opencode_manager_payload':
             return validationSuccess(tool.value, validateOpenCodeManagerPayloadInput(input, tool.value));
+        case 'vgxness_opencode_handoff_preview':
+            return validationSuccess(tool.value, validateOpenCodeHandoffPreviewInput(input, tool.value));
         case 'vgxness_run_list':
             return validationSuccess(tool.value, validateRunListInput(input, tool.value));
         case 'vgxness_run_get':
@@ -89,6 +92,10 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateRunCheckpointInput(input, tool.value));
         case 'vgxness_run_finalize':
             return validationSuccess(tool.value, validateRunFinalizeInput(input, tool.value));
+        case 'vgxness_run_resume_inspect':
+            return validationSuccess(tool.value, validateRunResumeInspectInput(input, tool.value));
+        case 'vgxness_run_resume_gate':
+            return validationSuccess(tool.value, validateRunResumeGateInput(input, tool.value));
         case 'vgxness_provider_status':
             return validationSuccess(tool.value, validateProviderHealthInput(input, tool.value));
         case 'vgxness_provider_doctor':
@@ -722,6 +729,40 @@ function validateOpenCodeManagerPayloadInput(input, tool) {
     }
     return { ok: true, value: result };
 }
+function validateOpenCodeHandoffPreviewInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'scope', 'agentId', 'agentName', 'workspaceRoot', 'maxSourceBytes', 'change', 'phase']);
+    if (!record.ok)
+        return record;
+    const project = readNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    const result = { project: project.value, scope: 'project', agentName: 'vgxness-manager' };
+    const copied = copyOptionalStrings(result, record.value, tool, ['agentId', 'agentName', 'workspaceRoot']);
+    if (!copied.ok)
+        return copied;
+    const scope = readOptionalOneOf(record.value, 'scope', scopes, tool);
+    if (!scope.ok)
+        return scope;
+    result.scope = scope.value ?? 'project';
+    const change = readOptionalChange(record.value, tool);
+    if (!change.ok)
+        return change;
+    if (change.value !== undefined)
+        result.change = change.value;
+    if (record.value.phase !== undefined) {
+        const phase = readPhase(record.value, tool);
+        if (!phase.ok)
+            return phase;
+        result.phase = phase.value;
+    }
+    if (record.value.maxSourceBytes !== undefined) {
+        const maxSourceBytes = record.value.maxSourceBytes;
+        if (typeof maxSourceBytes !== 'number' || !Number.isSafeInteger(maxSourceBytes) || maxSourceBytes <= 0)
+            return validationFailure('maxSourceBytes must be a positive safe integer', tool);
+        result.maxSourceBytes = maxSourceBytes;
+    }
+    return { ok: true, value: result };
+}
 function validateRunListInput(input, tool) {
     const record = inputRecord(input, tool, ['project', 'status', 'limit']);
     if (!record.ok)
@@ -850,6 +891,31 @@ function validateRunFinalizeInput(input, tool) {
         return copied;
     return { ok: true, value: result };
 }
+function validateRunResumeInspectInput(input, tool) {
+    const record = inputRecord(input, tool, ['runId']);
+    if (!record.ok)
+        return record;
+    const runId = readNonEmptyString(record.value, 'runId', tool);
+    if (!runId.ok)
+        return runId;
+    return { ok: true, value: { runId: runId.value } };
+}
+function validateRunResumeGateInput(input, tool) {
+    const record = inputRecord(input, tool, ['approvalId', 'policy']);
+    if (!record.ok)
+        return record;
+    const approvalId = readNonEmptyString(record.value, 'approvalId', tool);
+    if (!approvalId.ok)
+        return approvalId;
+    const result = { approvalId: approvalId.value };
+    if (record.value.policy !== undefined) {
+        const policy = parseOperationRetryPolicy(record.value.policy);
+        if (!policy.ok)
+            return validationFailure(policy.errors.join('; '), tool);
+        result.policy = policy.policy;
+    }
+    return { ok: true, value: result };
+}
 function validationSuccess(tool, validation) {
     if (!validation.ok)
         return validation;
@@ -898,6 +964,11 @@ function readChange(record, tool) {
         return validationFailure(`Invalid SDD change id: ${change.value}`, tool);
     return change;
 }
+function readOptionalChange(record, tool) {
+    if (record.change === undefined)
+        return { ok: true, value: undefined };
+    return readChange(record, tool);
+}
 function readPhase(record, tool) {
     const phase = readNonEmptyString(record, 'phase', tool);
     if (!phase.ok)

package/dist/memory/repositories/sessions.js

@@ -52,6 +52,9 @@ export class SessionRepository {
         }
     }
     appendActivity(input) {
+        const session = this.getById(input.sessionId);
+        if (!session.ok)
+            return session;
         const result = this.db.transaction(() => {
             const next = this.db.connection
                 .prepare('SELECT COALESCE(MAX(sequence), 0) + 1 AS sequence FROM session_activity WHERE session_id=?')

package/dist/memory/storage-paths.js

@@ -40,9 +40,11 @@ function linuxDataPath(env) {
     return homeRelativePath(env, ['.local', 'share', 'vgxness', 'memory.sqlite']);
 }
 function windowsAppDataPath(env) {
-    if (!hasPathValue(env.APPDATA))
-        return missingBase('APPDATA');
-    return { ok: true, value: path.win32.join(env.APPDATA, 'vgxness', 'memory.sqlite') };
+    if (hasPathValue(env.LOCALAPPDATA))
+        return { ok: true, value: path.win32.join(env.LOCALAPPDATA, 'vgxness', 'memory.sqlite') };
+    if (hasPathValue(env.APPDATA))
+        return { ok: true, value: path.win32.join(env.APPDATA, 'vgxness', 'memory.sqlite') };
+    return missingBase('LOCALAPPDATA or APPDATA');
 }
 function homeRelativePath(env, segments) {
     const home = userHome(env);

package/dist/sdd/sdd-workflow-service.js

@@ -459,6 +459,8 @@ function phaseFromTopicKey(change, topicKey) {
     return 'explore';
 }
 function blockerReasonForStatus(status) {
+    if (status.legacy === true)
+        return 'legacy';
     const state = status.state ?? (status.present ? 'draft' : 'missing');
     if (state === 'missing')
         return 'missing';

package/docs/cli.md

@@ -742,7 +742,7 @@ By default, vgxness uses a global user data database and creates the parent dire
 |---|---|
 | macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
 | Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
-| Windows | `%APPDATA%\\vgxness\\memory.sqlite` |
+| Windows | `%LOCALAPPDATA%\\vgxness\\memory.sqlite` when available; otherwise `%APPDATA%\\vgxness\\memory.sqlite` |
 
 Selection precedence is `--db <path>` (selected source: `flag`) > `VGXNESS_DB_PATH` (selected source: `environment`) > global default (selected source: `global-default`). The resolver fails clearly if no user data base directory is available instead of falling back to the current working directory.
 

package/docs/funcionamiento-del-sistema.md

@@ -149,7 +149,7 @@ Ruta por defecto de usuario:
 ```text
 macOS: ~/Library/Application Support/vgxness/memory.sqlite
 Linux: ${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite
-Windows: %APPDATA%\vgxness\memory.sqlite
+Windows: %LOCALAPPDATA%\vgxness\memory.sqlite; fallback a %APPDATA%\vgxness\memory.sqlite
 ```
 
 La ruta `.vgx/memory.sqlite` se sigue usando para dogfood local o pruebas cuando se pasa explicitamente con `--db`.
@@ -407,7 +407,7 @@ Por defecto, la CLI instalada usa una base global de usuario. Esto permite insta
 |---|---|
 | macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
 | Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
-| Windows | `%APPDATA%\vgxness\memory.sqlite` |
+| Windows | `%LOCALAPPDATA%\vgxness\memory.sqlite` si existe; si no, `%APPDATA%\vgxness\memory.sqlite` |
 
 La precedencia de seleccion de base es:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {