vgxness 1.4.0 → 1.5.1

package/dist/cli/cli-help.js

@@ -57,13 +57,14 @@ Areas:
   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 user|project] [--db <path>] [--mcp-only|--no-agents]
-  mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents]
+  mcp install opencode --plan [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
   mcp doctor opencode [--scope user|project] [--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 user/global scope and installs mcp.vgxness plus vgxness-manager and hidden vgxness-sdd-* agents; use --mcp-only for legacy MCP-only config.
+  Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
   It writes only after --yes. The default target is $HOME/.config/opencode/opencode.json; use --scope project to target .opencode/opencode.json explicitly.
   Project OpenCode config can override user config. Plans are read-only; applies refuse unsafe existing config and create backups before merge.
 

package/dist/cli/commands/mcp-dispatcher.js

@@ -19,6 +19,7 @@ export function runMcpInstallCommand(parsed, environment) {
         if (!scope.ok)
             return resultFailure(scope);
         const mcpOnly = parsed.flags['mcp-only'] === true || parsed.flags['no-agents'] === true;
+        const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
         if (parsed.flags.plan === true) {
             return jsonResult({
                 ok: true,
@@ -29,6 +30,7 @@ export function runMcpInstallCommand(parsed, environment) {
                     scope: scope.value,
                     env: environment.env,
                     mcpOnly,
+                    overwriteVgxness,
                 }),
             });
         }
@@ -40,6 +42,7 @@ export function runMcpInstallCommand(parsed, environment) {
             env: environment.env,
             confirmed: parsed.flags.yes === true,
             mcpOnly,
+            overwriteVgxness,
         });
         return result.status === 'installed'
             ? jsonResult({ ok: true, value: result })

package/dist/cli/commands/setup-dispatcher.js

@@ -143,6 +143,7 @@ export async function applySetupPlanInput(input, environment) {
         env: environment.env,
         confirmed: true,
         mcpOnly: input.installMode === 'mcp-only',
+        ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
     });
     return result.status === 'installed'
         ? {
@@ -172,6 +173,7 @@ export function setupPlanInputFromFlags(parsed, environment) {
     const installMode = setupInstallModeFlag(parsed.flags);
     if (!installMode.ok)
         return installMode;
+    const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
     return {
         ok: true,
         value: {
@@ -183,6 +185,7 @@ export function setupPlanInputFromFlags(parsed, environment) {
             provider: provider.value,
             scope: scope.value,
             installMode: installMode.value,
+            overwriteVgxness,
         },
     };
 }
@@ -196,6 +199,7 @@ function defaultWizardInput(environment) {
         provider: vgxnessSetupDefaults.defaultProvider,
         scope: vgxnessSetupDefaults.defaultOpenCodeScope,
         installMode: vgxnessSetupDefaults.defaultInstallMode,
+        overwriteVgxness: false,
     };
 }
 function defaulted(value, fallback) {
@@ -281,6 +285,8 @@ export function promptSetupWizard(environment, defaults) {
                 : undefined;
         if (installMode === undefined)
             return validationFailure('Install mode must be MCP + manager/SDD agents or MCP only.');
+        const overwriteText = defaulted(await promptLine(environment, 'Reinstall VGXNESS entries: overwrite existing mcp.vgxness and VGXNESS agents after final confirmation; preserve unrelated OpenCode config [no]: '), 'no');
+        const overwriteVgxness = overwriteText.toLowerCase() === 'yes' || overwriteText.toLowerCase() === 'y' || overwriteText.toLowerCase() === 'true';
         const input = {
             project,
             workspaceRoot: environment.cwd,
@@ -290,6 +296,7 @@ export function promptSetupWizard(environment, defaults) {
             provider,
             scope,
             installMode,
+            overwriteVgxness,
         };
         const flags = {
             project,
@@ -298,6 +305,7 @@ export function promptSetupWizard(environment, defaults) {
             scope,
             mode: installMode,
             yes: true,
+            ...(overwriteVgxness ? { 'overwrite-vgxness': true } : {}),
             ...(databasePath === undefined ? {} : { 'db-path': databasePath }),
         };
         return { ok: true, value: { input, flags } };
@@ -355,6 +363,7 @@ export async function runSetupTuiCommand(environment, input) {
             provider: vgxnessSetupDefaults.defaultProvider,
             scope: vgxnessSetupDefaults.defaultOpenCodeScope,
             installMode: vgxnessSetupDefaults.defaultInstallMode,
+            overwriteVgxness: false,
         },
     };
     try {

package/dist/cli/setup-plan-renderer.js

@@ -23,6 +23,7 @@ function renderOpenCode(plan) {
         `- Action: ${plan.opencode.action}`,
         `- Target path: ${target}`,
         `- Installs agents: ${String(plan.opencode.installsAgents)}`,
+        `- Reinstall VGXNESS entries: ${String(plan.opencode.overwriteVgxness)}`,
         `- Agent names: ${plan.opencode.agentNames.length === 0 ? 'none' : plan.opencode.agentNames.join(', ')}`,
     ];
 }

package/dist/cli/tui/setup/setup-tui-controller.js

@@ -59,20 +59,24 @@ function canApplyCurrentState(previous, reduced) {
     if (plan?.provider !== 'opencode' || plan.status !== 'ready' || plan.opencode === undefined)
         return false;
     const installMode = plan.opencode.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents';
-    return plan.opencode.scope === reduced.selections.scope && installMode === reduced.selections.installMode;
+    return (plan.opencode.scope === reduced.selections.scope &&
+        installMode === reduced.selections.installMode &&
+        (plan.opencode.overwriteVgxness === true) === (reduced.selections.overwriteVgxness === true));
 }
 function shouldRefreshPlan(previous, next, action) {
     if (action.type !== 'select-focused-choice' &&
         action.type !== 'select-database-mode' &&
         action.type !== 'select-provider' &&
         action.type !== 'select-scope' &&
-        action.type !== 'select-install-mode')
+        action.type !== 'select-install-mode' &&
+        action.type !== 'toggle-overwrite-vgxness')
         return false;
     return (previous.selections.databaseMode !== next.selections.databaseMode ||
         previous.selections.databasePath !== next.selections.databasePath ||
         previous.selections.provider !== next.selections.provider ||
         previous.selections.scope !== next.selections.scope ||
-        previous.selections.installMode !== next.selections.installMode);
+        previous.selections.installMode !== next.selections.installMode ||
+        (previous.selections.overwriteVgxness === true) !== (next.selections.overwriteVgxness === true));
 }
 function refreshPlan(state, services, runtime) {
     const plan = services.createPlan(setupPlanInputFromTui(runtime));

package/dist/cli/tui/setup/setup-tui-read-model.js

@@ -59,7 +59,9 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         backupLabel: backups.length === 0 ? 'Backup: none planned' : `Backup planned: ${backups.join('; ')}`,
         nextCommands: plan?.nextCommands ?? ['vgxness setup plan'],
         canAutoApply: plan?.provider === 'opencode' && plan.status === 'ready' && state?.selections.provider !== 'none' && plan.opencode !== undefined,
-        safetyWarning: 'Final confirmation is required before any provider config write. OpenCode config may be modified and backed up.',
+        safetyWarning: isOpenCode && (selections?.overwriteVgxness === true || opencode?.overwriteVgxness === true)
+            ? 'Final confirmation is required. Reinstall is enabled: VGXNESS OpenCode entries will be overwritten after a managed backup when the target exists; unrelated config is preserved.'
+            : 'Final confirmation is required before any provider config write. OpenCode config may be modified and backed up.',
         frameLabel: 'VGXNESS Setup Assistant workspace',
         progressLabel: progressLabel(state?.screen),
         previewLabel,
@@ -89,6 +91,11 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
                 choice('install:mcp-only', 'MCP only', 'Install only the MCP server entry after confirmation.', (selections?.installMode ?? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents')) === 'mcp-only', state?.focusedChoiceId, [badgeLabels.writeAfterConfirm]),
             ]
             : [],
+        overwriteChoices: isOpenCode
+            ? [
+                choice('overwrite:vgxness', 'Reinstall VGXNESS entries', 'Default off. When enabled, final confirmation overwrites existing VGXNESS OpenCode entries and preserves unrelated OpenCode config.', selections?.overwriteVgxness ?? opencode?.overwriteVgxness ?? false, state?.focusedChoiceId, [badgeLabels.warning, badgeLabels.writeAfterConfirm]),
+            ]
+            : [],
     };
 }
 function previewDetailLines(input) {
@@ -101,6 +108,7 @@ function previewDetailLines(input) {
         `Memory guidance: ${memoryPathExplanation(plan, input.databasePath, input.databaseSource)}`,
         `Scope: ${input.isOpenCode ? (opencode?.scope ?? 'user') : 'disabled for manual/none provider'}`,
         `Install mode: ${input.isOpenCode ? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents') : 'disabled for manual/none provider'}`,
+        `Reinstall VGXNESS entries: ${input.isOpenCode ? String(opencode?.overwriteVgxness ?? false) : 'disabled for manual/none provider'}`,
         `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude deferred/not installable.' : 'No provider installable; OpenCode controls disabled and Claude deferred.'}`,
         `Agent readiness: ${agentReadinessFromPlan(plan)}`,
         `Target config: ${input.isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'none; no provider config will be written'}`,

package/dist/cli/tui/setup/setup-tui-render-shape.js

@@ -40,6 +40,7 @@ function screenLines(input, width) {
                     'OpenCode plan ' + badgeLabels.writeAfterConfirm,
                     ...choiceLines(vm.scopeChoices),
                     ...choiceLines(vm.installModeChoices),
+                    ...choiceLines(vm.overwriteChoices),
                     `Scope: ${vm.scopeLabel}`,
                     `Install mode: ${vm.installModeLabel}`,
                     `Target config: ${compactPath(vm.targetPathLabel, width - 15)}`,
@@ -70,6 +71,7 @@ function screenLines(input, width) {
                 'Confirm OpenCode setup',
                 ...planLines(vm, width),
                 'WARNING: OpenCode provider config may be modified at the target path above. Existing config is backed up when planned.',
+                vm.safetyWarning,
                 'After confirmation: run doctor, then restart OpenCode to reload MCP configuration.',
                 'Press Enter to confirm and apply OpenCode setup, or Esc/q to cancel without writing.',
             ], width, [setupFooterHints.confirmApply, setupFooterHints.back, setupFooterHints.cancel]);
@@ -98,6 +100,7 @@ function planLines(vm, width) {
         `Database path: ${compactPath(vm.databasePathLabel, width - 15)}`,
         `OpenCode scope: ${vm.scopeLabel}`,
         `Install mode: ${vm.installModeLabel}`,
+        vm.safetyWarning,
         `Provider installability: ${vm.providerInstallabilityLabel}`,
         `Agent readiness: ${vm.agentReadinessLabel}`,
         `Agent detail: ${vm.agentReadinessDetail}`,

package/dist/cli/tui/setup/setup-tui-services.js

@@ -11,6 +11,7 @@ export function setupPlanInputFromTui(input) {
         provider: input.selections.provider,
         scope: input.selections.scope,
         installMode: input.selections.installMode,
+        ...(input.selections.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.selections.overwriteVgxness }),
     };
 }
 export function createDefaultSetupTuiServices(input) {
@@ -44,6 +45,7 @@ export async function applySetupTuiPlan(planInput, runtime) {
         env: runtime.env,
         confirmed: true,
         mcpOnly: planInput.installMode === 'mcp-only',
+        ...(planInput.overwriteVgxness === undefined ? {} : { overwriteVgxness: planInput.overwriteVgxness }),
     });
     if (installed.status !== 'installed')
         return { ok: false, error: { code: 'validation_failed', message: `${installed.reason}: ${installed.message}` } };

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

@@ -4,7 +4,7 @@ const screenChoiceIds = {
     welcome: [],
     'project-database': ['database:global', 'database:project-local', 'database:custom'],
     provider: ['provider:opencode', 'provider:none'],
-    'opencode-details': ['scope:project', 'scope:user', 'install:mcp-plus-agents', 'install:mcp-only'],
+    'opencode-details': ['scope:project', 'scope:user', 'install:mcp-plus-agents', 'install:mcp-only', 'overwrite:vgxness'],
     'plan-review': [],
     'final-confirmation': [],
     applying: [],
@@ -20,6 +20,7 @@ export function createSetupTuiState(input = {}) {
             provider: vgxnessSetupDefaults.defaultProvider,
             scope: vgxnessSetupDefaults.defaultOpenCodeScope,
             installMode: vgxnessSetupDefaults.defaultInstallMode,
+            overwriteVgxness: false,
         },
         ...(input.focusedChoiceId === undefined ? {} : { focusedChoiceId: input.focusedChoiceId }),
         helpVisible: input.helpVisible ?? false,
@@ -55,6 +56,8 @@ export function reduceSetupTuiState(state, action) {
             return { ...state, selections: { ...state.selections, scope: action.scope } };
         case 'select-install-mode':
             return { ...state, selections: { ...state.selections, installMode: action.installMode } };
+        case 'toggle-overwrite-vgxness':
+            return { ...state, selections: { ...state.selections, overwriteVgxness: state.selections.overwriteVgxness !== true } };
         case 'refresh-plan-start':
             return { ...state, previewRefresh: 'refreshing' };
         case 'refresh-plan-success':
@@ -131,6 +134,8 @@ function selectFocusedChoice(state) {
             return reduceSetupTuiState(state, { type: 'select-install-mode', installMode: 'mcp-plus-agents' });
         case 'install:mcp-only':
             return reduceSetupTuiState(state, { type: 'select-install-mode', installMode: 'mcp-only' });
+        case 'overwrite:vgxness':
+            return reduceSetupTuiState(state, { type: 'toggle-overwrite-vgxness' });
         default:
             return state;
     }
@@ -154,7 +159,9 @@ function canAutoApplyFromState(state) {
     if (state.plan?.provider !== 'opencode' || state.plan.status !== 'ready' || state.plan.opencode === undefined)
         return false;
     const installMode = state.plan.opencode.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents';
-    return state.plan.opencode.scope === state.selections.scope && installMode === state.selections.installMode;
+    return (state.plan.opencode.scope === state.selections.scope &&
+        installMode === state.selections.installMode &&
+        (state.plan.opencode.overwriteVgxness === true) === (state.selections.overwriteVgxness === true));
 }
 function advance(state) {
     const index = setupTuiScreenOrder.indexOf(state.screen);

package/dist/mcp/client-install-opencode-contract.js

@@ -33,8 +33,9 @@ export function planOpenCodeMcpInstall(input) {
     const agentPlan = createOpenCodeDefaultAgentInstallPlan({
         mcpOnly: input.mcpOnly,
     });
+    const overwriteVgxness = input.overwriteVgxness === true;
     if (scope === 'user') {
-        return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan);
+        return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness);
     }
     const existingTargets = supportedConfigTargets
         .map((relativePath) => ({
@@ -48,11 +49,11 @@ export function planOpenCodeMcpInstall(input) {
                 kind: 'manual-check',
                 message: 'Remove ambiguity by keeping exactly one OpenCode project config target before installing.',
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
     }
     if (existingTargets.length === 0) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan),
+            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan, overwriteVgxness),
             status: 'would_install',
             action: 'create',
             targetPath: join(input.cwd, '.opencode', 'opencode.json'),
@@ -64,31 +65,34 @@ export function planOpenCodeMcpInstall(input) {
     }
     const [target] = existingTargets;
     if (target === undefined)
-        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope);
+        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope, undefined, [], undefined, overwriteVgxness);
     if (target.relativePath.endsWith('.jsonc')) {
-        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     const parsed = parseConfig(target.absolutePath);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
-    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    if (agentConflict.length > 0) {
+    if (agentConflict.length > 0 && !overwriteVgxness) {
         return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, scope, target.absolutePath, [
             {
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
+    }
+    if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan),
+        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan, overwriteVgxness),
         status: 'would_install',
         action: 'merge',
         targetPath: target.absolutePath,
@@ -98,22 +102,22 @@ export function planOpenCodeMcpInstall(input) {
         existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
     };
 }
-function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan) {
+function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness) {
     const target = resolveOpenCodeMcpInstallTarget({
         cwd: input.cwd,
         scope: 'user',
         env: input.env,
     });
     if (!target.ok) {
-        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user');
+        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness);
     }
     const jsoncPath = `${target.path}c`;
     if (existsSync(jsoncPath)) {
-        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan);
+        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness);
     }
     if (!existsSync(target.path)) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan),
+            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness),
             status: 'would_install',
             action: 'create',
             targetPath: target.path,
@@ -125,25 +129,28 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
     }
     const parsed = parseConfig(target.path);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
-    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    if (agentConflict.length > 0) {
+    if (agentConflict.length > 0 && !overwriteVgxness) {
         return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, 'user', target.path, [
             {
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
+    }
+    if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan),
+        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness),
         status: 'would_install',
         action: 'merge',
         targetPath: target.path,
@@ -206,7 +213,7 @@ function deepEqual(left, right) {
     const rightKeys = Object.keys(right).sort();
     return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && deepEqual(left[key], right[key]));
 }
-function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -221,16 +228,17 @@ function baseContract(databasePath, source, scope, targetPath, backupRequired, m
             mergePolicy,
         },
         scope,
-        warnings: warningsForScope(scope),
+        warnings: warningsForScope(scope, overwriteVgxness, agentPlan),
         verificationHints: verificationHints(databasePath, source),
         manualTest: manualTestForScope(scope, databasePath, source),
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
-function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
-    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan);
+function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
+    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness);
     return {
         ...contract,
         verificationHints: [...extraVerificationHints, ...contract.verificationHints],
@@ -240,12 +248,18 @@ function refusal(reason, message, databasePath, source, scope, targetPath, extra
         ...(targetPath !== undefined ? { targetPath } : {}),
     };
 }
-function warningsForScope(scope) {
+function warningsForScope(scope, overwriteVgxness, agentPlan) {
+    const overwriteWarnings = overwriteVgxness
+        ? [
+            `Reinstall/overwrite is enabled: existing VGXNESS-managed OpenCode entries will be replaced (${agentPlan.installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}); unrelated OpenCode config is preserved.`,
+        ]
+        : [];
     if (scope === 'project')
-        return ['Restart OpenCode after installation so it reloads the project MCP config.'];
+        return ['Restart OpenCode after installation so it reloads the project MCP config.', ...overwriteWarnings];
     return [
         'Restart OpenCode after installation so it reloads the user MCP config.',
         'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
+        ...overwriteWarnings,
     ];
 }
 function manualTestForScope(scope, databasePath, source) {

package/dist/mcp/client-install-opencode.js

@@ -25,9 +25,10 @@ export async function installOpenCodeMcpClient(input) {
         ...(input.scope !== undefined ? { scope: input.scope } : {}),
         ...(input.env !== undefined ? { env: input.env } : {}),
         ...(input.mcpOnly !== undefined ? { mcpOnly: input.mcpOnly } : {}),
+        ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}),
     });
     if (!input.confirmed) {
-        return refusal('confirmation_required', confirmationRequiredMessage(plan.scope), input.databasePath, databasePathSource, server, confirmationRequiredSafety(plan), 'targetPath' in plan ? plan.targetPath : undefined, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal('confirmation_required', confirmationRequiredMessage(plan.scope), input.databasePath, databasePathSource, server, confirmationRequiredSafety(plan), 'targetPath' in plan ? plan.targetPath : undefined, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     }
     if (plan.status === 'refused')
         return refusalFromPlan(plan, input.databasePath, databasePathSource, server);
@@ -35,28 +36,28 @@ export async function installOpenCodeMcpClient(input) {
         if (existsSync(plan.targetPath)) {
             const reparsed = parseConfig(plan.targetPath);
             if (!reparsed.ok)
-                return refusal(reparsed.reason, reparsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+                return refusal(reparsed.reason, reparsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
             const conflictingAgents = findConflictingVgxnessAgents(reparsed.value, agentPlan);
-            if (conflictingAgents.length > 0)
+            if (conflictingAgents.length > 0 && input.overwriteVgxness !== true)
                 return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
-            return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+            return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
         }
         writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents));
-        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     }
     const parsed = parseConfig(plan.targetPath);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     const conflictingAgents = findConflictingVgxnessAgents(parsed.value, agentPlan);
-    if (conflictingAgents.length > 0)
+    if (conflictingAgents.length > 0 && input.overwriteVgxness !== true)
         return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
     const backup = createBackup(plan.targetPath, plan.scope);
     if (!backup.ok)
-        return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     const config = parsed.value;
     const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents);
     writeConfig(plan.targetPath, mergedConfig);
-    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
 }
 function mergeVgxnessOpenCodeConfig(config, server, installsAgents) {
     const merged = {
@@ -101,7 +102,7 @@ function createBackup(path, scope) {
         description: 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
     });
 }
-function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
+function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false) {
     const parsed = parseConfig(targetPath);
     if (!parsed.ok)
         return refusal('post_write_validation_failed', 'OpenCode config could not be re-read after write.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
@@ -129,6 +130,7 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         manualTest: manualTestGuidance,
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
@@ -153,7 +155,7 @@ function isOpenCodeLocalMcpServerConfig(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function refusal(reason, message, databasePath, source, server, safety, targetPath, verificationHints = defaultVerificationHints(databasePath, source), warningMessages = warnings(), manualTestGuidance = manualTest(databasePath, source), agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+function refusal(reason, message, databasePath, source, server, safety, targetPath, verificationHints = defaultVerificationHints(databasePath, source), warningMessages = warnings(), manualTestGuidance = manualTest(databasePath, source), agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -168,11 +170,12 @@ function refusal(reason, message, databasePath, source, server, safety, targetPa
         manualTest: manualTestGuidance,
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
 function refusalFromPlan(plan, databasePath, source, server) {
-    return refusal(plan.reason, plan.message, databasePath, source, server, plan.safety, plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, plan);
+    return refusal(plan.reason, plan.message, databasePath, source, server, plan.safety, plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, plan, plan.overwriteVgxness);
 }
 function agentConflictRefusal(conflictingAgents, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
     return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${conflictingAgents.join(', ')}. Remove, rename, or manually reconcile them before installing.`, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);

package/dist/mcp/control-plane.js

@@ -63,6 +63,8 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.memory.closeSession(validated.input, memoryContext(validated.input.sessionId)));
         case 'vgxness_session_restore':
             return toEnvelope(validated.tool, services.memory.restoreSession(validated.input));
+        case 'vgxness_context_cockpit':
+            return toEnvelope(validated.tool, services.memory.getContextCockpit(validated.input));
         case 'vgxness_agent_resolve':
             return toEnvelope(validated.tool, services.agents.resolveAgents(validated.input));
         case 'vgxness_agent_activate':

package/dist/mcp/opencode-default-agent-config.js

@@ -1,5 +1,5 @@
 export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
-export const vgxnessOpenCodePromptContractVersion = 4;
+export const vgxnessOpenCodePromptContractVersion = 6;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
 export const vgxnessOpenCodeSddSubagents = [
     'vgxness-sdd-explore',
@@ -65,7 +65,7 @@ export function createOpenCodeDefaultAgentConfig() {
 }
 function createSddSubagentPrompt(name) {
     const phase = name.replace('vgxness-sdd-', '');
-    const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and local repository evidence as needed. Do not depend on external local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
+    const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and local repository evidence as needed. Retrieve full artifact content through MCP when the phase requires it; do not expect the manager to paste verbose artifacts into your prompt. Do not depend on external local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
     const contracts = {
         'vgxness-sdd-explore': 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.',
         'vgxness-sdd-propose': 'Create or refine a focused SDD proposal from exploration evidence. Do not implement code changes. Include scope, tradeoffs, non-goals, and acceptance direction.',
@@ -102,8 +102,8 @@ Coach while coordinating: teach briefly when helpful, explain practical tradeoff
 Normal SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for daily flow. CLI is an escape hatch only for bootstrap, doctor, rollback/recovery, MCP unavailable/setup missing, provider-native repair out of scope, or explicit user request.
 
 ## MCP playbook
-- For starting, resuming, or recovering context: \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
-- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
+- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal inside the cockpit, not authoritative truth. If cockpit is unavailable, use \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
+- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default for manager-facing reads/lists so the primary context stays clean. Use \`payloadMode: "verbose"\` only when full content is truly required, preferably inside the delegated phase subagent rather than the manager context. Save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
 - Acceptance/readiness: confirm explicit human acceptance, use \`vgxness_sdd_accept_artifact\` only for explicit human acceptance, then \`vgxness_sdd_get_readiness\`/readiness tools before reporting state. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
 - Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` when prior work or unclear project context is referenced; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
 - Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` prepare/read preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.

package/dist/mcp/provider-health-types.js

@@ -1,3 +1,4 @@
+import { vgxnessOpenCodePromptContractVersion } from './opencode-default-agent-config.js';
 export const PROVIDER_HEALTH_SAFETY = {
     readOnly: true,
     writesProviderConfig: false,
@@ -29,6 +30,7 @@ export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
     'vgxness_memory_search',
     'vgxness_memory_get',
     'vgxness_memory_save',
+    'vgxness_context_cockpit',
     'vgxness_session_restore',
     'vgxness_session_close',
 ];
@@ -40,7 +42,7 @@ export function normalizeProviderHealthInput(input) {
         workspaceRoot: input.workspaceRoot?.trim() || process.cwd(),
         env: input.env ?? process.env,
         change: input.change?.trim() ?? '',
-        expectedPromptContractVersion: input.expectedPromptContractVersion ?? 4,
+        expectedPromptContractVersion: input.expectedPromptContractVersion ?? vgxnessOpenCodePromptContractVersion,
         payloadMode: input.payloadMode ?? 'compact',
     };
 }

package/dist/mcp/schema.js

@@ -21,6 +21,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_session_append_activity',
     'vgxness_session_close',
     'vgxness_session_restore',
+    'vgxness_context_cockpit',
     'vgxness_agent_resolve',
     'vgxness_agent_activate',
     'vgxness_manager_profile_get',
@@ -60,6 +61,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'session_append_activity',
     'session_close',
     'session_restore',
+    'context_cockpit',
     'agent_resolve',
     'agent_activate',
     'manager_profile_get',
@@ -257,6 +259,13 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         directory: z.string().min(1).optional(),
     })
         .passthrough(),
+    vgxness_context_cockpit: z
+        .object({
+        project: z.string().min(1),
+        directory: z.string().min(1).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    })
+        .passthrough(),
     vgxness_agent_resolve: z
         .object({
         project: z.string().min(1).optional(),

package/dist/mcp/stdio-server.js

@@ -59,6 +59,8 @@ function descriptionForTool(publicToolName) {
         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 === 'context_cockpit')
+        return 'Read-only context cockpit for start/resume/recovery; returns latest restorable session plus bounded memory previews without traces, provider config writes, repository writes, runs, artifacts, or session mutations.';
     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

@@ -66,6 +66,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSessionCloseInput(input, tool.value));
         case 'vgxness_session_restore':
             return validationSuccess(tool.value, validateSessionRestoreInput(input, tool.value));
+        case 'vgxness_context_cockpit':
+            return validationSuccess(tool.value, validateContextCockpitInput(input, tool.value));
         case 'vgxness_agent_resolve':
             return validationSuccess(tool.value, validateAgentResolveInput(input, tool.value));
         case 'vgxness_agent_activate':
@@ -234,6 +236,26 @@ function validateSddCockpitInput(input, tool) {
         return record;
     return readProjectAndChange(record.value, tool);
 }
+function validateContextCockpitInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'directory', 'limit']);
+    if (!record.ok)
+        return record;
+    const project = readNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    const result = { project: project.value };
+    const directory = readOptionalNonEmptyString(record.value, 'directory', tool);
+    if (!directory.ok)
+        return directory;
+    if (directory.value !== undefined)
+        result.directory = directory.value;
+    if (record.value.limit !== undefined) {
+        if (typeof record.value.limit !== 'number' || !Number.isSafeInteger(record.value.limit) || record.value.limit < 1 || record.value.limit > 100)
+            return validationFailure('limit must be an integer between 1 and 100', tool);
+        result.limit = record.value.limit;
+    }
+    return { ok: true, value: result };
+}
 function readProjectAndChange(record, tool) {
     const project = readNonEmptyString(record, 'project', tool);
     if (!project.ok)

package/dist/memory/memory-service.js

@@ -50,6 +50,54 @@ export class MemoryService {
         const result = this.observations.searchPreviews(filters);
         return this.record(result, context, { operation: 'observation.search', targetType: 'observation', topicKey: filters.topicKey });
     }
+    /** Read memory previews without writing provenance traces. */
+    searchObservationPreviewsNoTrace(filters) {
+        return this.observations.searchPreviews(filters);
+    }
+    /** Read compact current context without writing traces or mutating durable state. */
+    getContextCockpit(input) {
+        const limit = normalizeContextLimit(input.limit);
+        const memories = this.searchObservationPreviewsNoTrace({ project: input.project, limit });
+        if (!memories.ok)
+            return { ok: false, error: memories.error };
+        const session = this.restoreSession(input.directory === undefined ? { project: input.project } : { project: input.project, directory: input.directory });
+        if (!session.ok && session.error.code !== 'not_found')
+            return { ok: false, error: session.error };
+        const latestRestorableSession = session.ok ? session.value : undefined;
+        const newestMemoryUpdatedAt = memories.value[0]?.updatedAt;
+        const latestSessionEndedAt = latestRestorableSession?.endedAt;
+        const stale = latestRestorableSession === undefined || (newestMemoryUpdatedAt !== undefined && latestSessionEndedAt !== undefined && newestMemoryUpdatedAt > latestSessionEndedAt);
+        const staleness = {
+            stale,
+            reason: latestRestorableSession === undefined ? 'no-restorable-session' : stale ? 'memory-newer-than-session' : 'current',
+            ...(newestMemoryUpdatedAt === undefined ? {} : { newestMemoryUpdatedAt }),
+            ...(latestSessionEndedAt === undefined ? {} : { latestSessionEndedAt }),
+        };
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'context-cockpit',
+                project: input.project,
+                ...(input.directory === undefined ? {} : { directory: input.directory }),
+                ...(latestRestorableSession === undefined ? {} : { latestRestorableSession }),
+                memoryPreviews: memories.value,
+                staleness,
+                optionalSectionsOmitted: ['sdd', 'runs'],
+                notes: ['SDD and run summaries are omitted because safe no-trace metadata-only aggregation is not part of this cockpit path yet.'],
+                safety: {
+                    readOnly: true,
+                    recordsTraces: false,
+                    mutatesSessions: false,
+                    mutatesMemories: false,
+                    mutatesArtifacts: false,
+                    mutatesRuns: false,
+                    writesProviderConfig: false,
+                    mutatesRepository: false,
+                },
+            },
+        };
+    }
     listObservationRevisions(id, context) {
         const result = this.observations.listRevisions(id);
         return this.record(result, context, { operation: 'observation.revisions.list', targetType: 'observation', targetId: id });
@@ -140,3 +188,10 @@ class MemoryServiceTransactionRollback extends Error {
         super('Memory service transaction rolled back');
     }
 }
+function normalizeContextLimit(limit) {
+    if (limit === undefined)
+        return 5;
+    if (!Number.isFinite(limit))
+        return 5;
+    return Math.max(1, Math.min(100, Math.trunc(limit)));
+}

package/dist/memory/repositories/sessions.js

@@ -39,7 +39,7 @@ export class SessionRepository {
           AND summary IS NOT NULL
           AND TRIM(summary) <> ''
           AND (@directory IS NULL OR directory = @directory)
-        ORDER BY ended_at DESC
+        ORDER BY ended_at DESC, started_at DESC, id DESC
         LIMIT 1
       `)
                 .get({ project: input.project, directory: input.directory ?? null });

package/dist/setup/providers/opencode-setup-adapter.js

@@ -49,9 +49,10 @@ export const openCodeSetupAdapter = {
             databasePath,
             ...(context.databasePathSource !== undefined ? { databasePathSource: context.databasePathSource } : {}),
             ...(context.env !== undefined ? { env: context.env } : {}),
+            ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
         });
         const targetPath = 'targetPath' in contract ? contract.targetPath : undefined;
-        const actions = contract.status === 'would_install' ? [externalInstallAction(contract.scope, targetPath)] : [];
+        const actions = contract.status === 'would_install' ? [externalInstallAction(contract.scope, targetPath, contract.overwriteVgxness)] : [];
         return {
             providerId: 'opencode',
             status: contract.status === 'would_install' ? 'available' : 'blocked',
@@ -59,7 +60,9 @@ export const openCodeSetupAdapter = {
             mutating: false,
             writesProviderConfig: false,
             summary: contract.status === 'would_install'
-                ? `OpenCode ${contract.action} plan is available for external application; confirmed merges create managed VGXNESS backups.`
+                ? contract.overwriteVgxness
+                    ? `OpenCode ${contract.action} reinstall plan is available; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, and creates managed backups for existing targets.`
+                    : `OpenCode ${contract.action} plan is available for external application; confirmed merges create managed VGXNESS backups.`
                 : contract.message,
             ...(targetPath !== undefined ? { targetPath } : {}),
             warnings: contract.warnings,
@@ -105,7 +108,11 @@ function openCodePlanPreview(visibility, plan) {
     if (!isOpenCodeInstallContract(source))
         return undefined;
     if (source.status === 'would_install') {
-        const action = source.action === 'create' ? 'Install OpenCode MCP config' : 'Update OpenCode MCP config';
+        const action = source.overwriteVgxness
+            ? 'Reinstall VGXNESS OpenCode entries'
+            : source.action === 'create'
+                ? 'Install OpenCode MCP config'
+                : 'Update OpenCode MCP config';
         return {
             kind: source.action === 'create' ? 'install' : 'update',
             action,
@@ -115,7 +122,7 @@ function openCodePlanPreview(visibility, plan) {
             targetPath: source.targetPath,
             backupRequired: source.backupRequired,
             confirmationRequired: Boolean(plan?.actions.some((candidate) => candidate.safety.requiresExplicitConfirmation)),
-            risks: source.action === 'create' ? createInstallRisks() : mergeInstallRisks(),
+            risks: source.overwriteVgxness ? overwriteInstallRisks(source.installsAgents) : source.action === 'create' ? createInstallRisks() : mergeInstallRisks(),
             warnings: source.warnings,
         };
     }
@@ -140,6 +147,13 @@ function mergeInstallRisks() {
         'OpenCode config discovery may still be affected by target precedence or malformed local config.',
     ];
 }
+function overwriteInstallRisks(installsAgents) {
+    return [
+        `Existing VGXNESS-managed OpenCode entries will be replaced (${installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}).`,
+        'Unrelated OpenCode config, unrelated agents, and unrelated MCP servers are preserved; existing targets still receive managed backups before writes.',
+        'OpenCode must be restarted after external installation before it discovers the updated vgxness MCP server.',
+    ];
+}
 function refusedRepairRisks(message) {
     return [
         `Install planner refused automatic repair: ${message}`,
@@ -155,13 +169,15 @@ function isOpenCodeInstallContract(value) {
 function databasePathOrPlaceholder(context) {
     return context.databasePath ?? '<database-path>';
 }
-function externalInstallAction(scope, targetPath) {
+function externalInstallAction(scope, targetPath, overwriteVgxness = false) {
     return {
         id: `opencode-mcp-install-${scope}`,
         label: `Copy external OpenCode ${scope === 'user' ? 'user/global' : 'project'} install command`,
         kind: 'copy-command',
-        command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes'],
-        description: 'Copy and run this outside the TUI only after reviewing the read-only plan.',
+        command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        description: overwriteVgxness
+            ? 'Copy and run this outside the TUI only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
+            : 'Copy and run this outside the TUI only after reviewing the read-only plan.',
         safety: externalProviderWriteSafety(targetPath),
     };
 }

package/dist/setup/setup-plan.js

@@ -54,6 +54,7 @@ export function createSetupPlan(input) {
         scope,
         env: input.env,
         mcpOnly: installMode === 'mcp-only',
+        ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
     });
     return { ok: true, value: setupPlanFromOpenCode({ ...common, provider: 'opencode', installMode, scope, opencode }) };
 }
@@ -70,6 +71,7 @@ function setupPlanFromOpenCode(input) {
                 ...(input.opencode.targetPath === undefined ? {} : { targetPath: input.opencode.targetPath }),
                 installsAgents: input.opencode.installsAgents,
                 agentNames: input.opencode.agentNames,
+                ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
             },
             actions: [],
             conflicts: [
@@ -96,11 +98,12 @@ function setupPlanFromOpenCode(input) {
             mcpServer: input.opencode.server,
             installsAgents: input.opencode.installsAgents,
             agentNames: input.opencode.agentNames,
+            ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
         },
         actions: [
             {
                 id: `opencode-${input.opencode.action}`,
-                description: `${input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}.`,
+                description: `${input.opencode.overwriteVgxness ? 'Reinstall/overwrite VGXNESS entries in' : input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}${input.opencode.overwriteVgxness ? '; unrelated OpenCode config is preserved' : ''}.`,
                 mutating: false,
                 targetPath: input.opencode.targetPath,
                 backupRequired: input.opencode.backupRequired,
@@ -111,7 +114,9 @@ function setupPlanFromOpenCode(input) {
             ? [
                 {
                     targetPath: input.opencode.targetPath,
-                    reason: 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
+                    reason: input.opencode.overwriteVgxness
+                        ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
+                        : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
                 },
             ]
             : [],

package/package.json

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