vgxness 1.10.0 → 1.11.0

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

@@ -55,7 +55,7 @@ export async function installOpenCodeMcpClient(input) {
     });
     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, plan.bashPermissionPolicy);
-    const backup = createBackup(plan.targetPath, plan.scope);
+    const backup = createBackup(plan.targetPath, plan.scope, input.env?.HOME);
     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, plan.overwriteVgxness, plan.bashPermissionPolicy);
     const config = parsed.value;
@@ -97,7 +97,7 @@ function writeConfig(path, config) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
 }
-function createBackup(path, scope) {
+function createBackup(path, scope, allowedManagedHome) {
     return createManagedProviderConfigBackup({
         targetPath: path,
         provider: 'opencode',
@@ -105,6 +105,7 @@ function createBackup(path, scope) {
         createdByOperation: 'mcp-client-install-opencode',
         reason: 'pre-merge-safety',
         description: 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
+        ...(allowedManagedHome !== undefined ? { allowedManagedHome } : {}),
     });
 }
 function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {

package/dist/mcp/provider-change-plan.js

@@ -100,7 +100,7 @@ function unsupportedProviderEnvelope(input) {
         supported: false,
         status: 'unsupported',
         code: 'UNSUPPORTED_PROVIDER',
-        summary: `${input.provider} is a recognized provider value, but read-only provider change planning currently supports OpenCode and Claude.`,
+        summary: `[read-only] ${input.provider} is a recognized provider value, but provider change planning currently supports OpenCode and Claude. No provider config was written. This diagnostic does not install or repair provider config.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -114,7 +114,7 @@ function unsupportedProviderEnvelope(input) {
         backupRollback: descriptiveBackupPolicy(false),
         confirmations: confirmationPolicy(),
         risks: ['No provider-specific change preview is available for this provider yet.'],
-        warnings: ['Known provider enum value is unsupported by this read-only planner.'],
+        warnings: ['Known provider enum value is unsupported by this read-only planner. No files were written.'],
     };
 }
 function blockedPlanEnvelope(input, status, doctor, message) {
@@ -124,7 +124,7 @@ function blockedPlanEnvelope(input, status, doctor, message) {
         supported: true,
         status: 'blocked',
         code: 'PLAN_UNAVAILABLE',
-        summary: `${providerName} change planning could not resolve the future MCP server command: ${message}`,
+        summary: `[read-only] ${providerName} change planning could not resolve the future MCP server command: ${message}. No provider config was written. This diagnostic does not install or repair provider config.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -143,7 +143,7 @@ function blockedPlanEnvelope(input, status, doctor, message) {
         backupRollback: descriptiveBackupPolicy(false),
         confirmations: confirmationPolicy(),
         risks: ['Future write planning requires a resolvable VGXNESS database path.'],
-        warnings: [message],
+        warnings: [message, 'No files were written.'],
     };
 }
 function opencodeEnvelope(input, status, doctor, installPlan, source) {
@@ -185,7 +185,7 @@ function claudeEnvelope(input, status, doctor, installPlan, source) {
         supported: true,
         status: installPlan.status === 'refused' ? 'blocked' : 'planned',
         ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
-        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : 'Read-only Claude planning completed; future confirmed write would update ~/.claude.json, user agents, and ~/.claude/CLAUDE.md as needed. Project/local Claude files are diagnostics only.',
+        summary: installPlan.status === 'refused' ? `[read-only] Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}. No provider config was written. This diagnostic does not install or repair provider config.` : '[read-only] Claude planning completed. No provider config was written. This diagnostic does not install or repair provider config. A future confirmed write would update ~/.claude.json, user agents, and ~/.claude/CLAUDE.md as needed. Project/local Claude files are diagnostics only.',
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
@@ -307,7 +307,7 @@ function confirmationPolicy() {
         requiredNow: false,
         requiredBeforeFutureWrite: true,
         acceptedMutationInputs: false,
-        message: 'This response is read-only; any future provider config write must be requested and confirmed separately.',
+        message: '[read-only] No provider config was written. Any future provider config write must be requested and confirmed separately.',
     };
 }
 function statusWarnings(status) {
@@ -339,6 +339,6 @@ function risksForClaude(status, doctor, plan, source) {
 }
 function summaryForOpenCode(input, plan) {
     if (plan.status === 'refused')
-        return `Read-only OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}`;
-    return `Read-only OpenCode ${input.changeType} planning completed; future confirmed write would ${plan.action} ${plan.targetPath}.`;
+        return `[read-only] OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}. No provider config was written. This diagnostic does not install or repair provider config.`;
+    return `[read-only] OpenCode ${input.changeType} planning completed. No provider config was written. This diagnostic does not install or repair provider config. A future confirmed write would ${plan.action} ${plan.targetPath}.`;
 }

package/dist/mcp/provider-doctor.js

@@ -174,15 +174,16 @@ function managedUserGlobalClassification(paths) {
     return { managedUserGlobalConfig: [...paths], detectedExternalProjectConfig: [], detectedExternalUserConfig: [] };
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'healthy')
-        return 'Provider doctor checks passed; no configuration was changed.';
+        return `Provider doctor checks passed. ${suffix}`;
     if (status === 'degraded')
-        return `Provider doctor found warnings and ${recommendationCount} recommendation(s); no configuration was changed.`;
+        return `Provider doctor found warnings and ${recommendationCount} recommendation(s). ${suffix}`;
     if (status === 'failed')
-        return `Provider doctor found ${failedCount} failed check(s); no configuration was changed.`;
+        return `Provider doctor found ${failedCount} failed check(s). ${suffix}`;
     if (status === 'skipped')
-        return 'Provider doctor checks were skipped.';
-    return 'Provider doctor status is unknown; review checks before continuing.';
+        return `Provider doctor checks were skipped. ${suffix}`;
+    return `Provider doctor status is unknown; review checks before continuing. ${suffix}`;
 }
 function compactChecks(checks, mode) {
     if (mode === 'verbose')
@@ -280,7 +281,7 @@ function readonlySafetyCheck(before, after) {
         ? {
             id: 'provider-config-readonly-safety',
             status: 'pass',
-            detail: 'Provider config path existence and mtimes were unchanged; no repair/install/write occurred.',
+            detail: '[read-only] Provider config path existence and mtimes were unchanged. No files were written. This diagnostic does not install or repair provider config.',
         }
         : { id: 'provider-config-readonly-safety', status: 'fail', detail: 'Provider config path existence or mtimes changed during read-only doctor.' };
 }

package/dist/mcp/provider-status.js

@@ -354,22 +354,24 @@ function hasProjectConfigAlongsideUser(paths) {
     return paths.some((path) => path.label.startsWith('user ') && path.exists) && paths.some((path) => !path.label.startsWith('user ') && path.exists);
 }
 function summarizeStatus(status, mcpEntry) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'ready')
-        return 'OpenCode provider config is readable and the vgxness MCP entry is present.';
+        return `OpenCode provider config is readable and the vgxness MCP entry is present. ${suffix}`;
     if (status === 'not-configured')
-        return mcpEntry.detail;
+        return `${mcpEntry.detail} ${suffix}`;
     if (status === 'warning')
-        return 'OpenCode provider config has warnings; no changes were made.';
-    return 'OpenCode provider status check found a blocking issue; no changes were made.';
+        return `OpenCode provider config has warnings. ${suffix}`;
+    return `OpenCode provider status check found a blocking issue. ${suffix}`;
 }
 function summarizeClaudeStatus(status, mcpEntry) {
+    const suffix = '[read-only] No provider config was written. This diagnostic does not install or repair provider config.';
     if (status === 'ready')
-        return 'Claude project .mcp.json and VGXNESS agent files are readable and configured.';
+        return `Claude provider files were inspected and VGXNESS entries are readable. ${suffix}`;
     if (status === 'not-configured')
-        return mcpEntry.detail;
+        return `${mcpEntry.detail} ${suffix}`;
     if (status === 'warning')
-        return 'Claude provider project config has warnings; no changes were made.';
-    return 'Claude provider status check found a blocking issue; no changes were made.';
+        return `Claude provider project config has warnings. ${suffix}`;
+    return `Claude provider status check found a blocking issue. ${suffix}`;
 }
 function nextActionFor(status, mcpEntry, sddNext) {
     if (sddNext !== undefined)

package/dist/runs/execution-planning.js

@@ -79,11 +79,11 @@ function conditionRequirements(operation, decision, realpathHardeningRequired, s
     return conditions;
 }
 function planLimitations(operation, decision, strategy, sandbox) {
-    const limitations = ['planning-only: no command, provider tool, worktree, sandbox, directory, or filesystem mutation is performed'];
+    const limitations = ['planning-only: this preflight records an execution plan only; no command, provider tool, worktree, sandbox, directory, or filesystem mutation was performed'];
     if (strategy === 'worktree')
-        limitations.push('worktree is a planned isolation target only; creation is future executor work');
+        limitations.push('worktree is only the planned isolation target; no worktree was created and mutations still require a separate executor or manual worktree');
     if (strategy === 'process-sandbox')
-        limitations.push('process-sandbox is a planned isolation target only; launch/enforcement is future executor work');
+        limitations.push('process-sandbox is only the planned isolation target; no sandbox was launched and execution still requires a separate executor');
     if (decision.decision === 'deny')
         limitations.push(`permission policy denies execution: ${decision.reason}`);
     if (sandbox?.decision === 'rejected')

package/dist/sdd/sdd-continuation-plan.js

@@ -4,8 +4,7 @@ export function sddContinuationPlanFrom(input) {
     const inspectCommand = `vgxness sdd cockpit --project ${input.project} --change ${input.next.change} --json${dbFlag}`;
     const suggestedCommand = suggestedContinuationCommand(input.project, input.next, inspectCommand, dbFlag);
     const blockerGuidance = input.next.blockerGuidance ?? [];
-    const blockerActions = blockerGuidance.map((blocker) => continuationBlockerAction(input.project, input.next.change, input.next.nextPhase, blocker, dbFlag));
-    const hasDraftRunAction = blockerActions.some((action) => action.draftRunCommand !== undefined);
+    const blockerActions = blockerGuidance.map((blocker) => continuationBlockerAction(input.project, input.next.change, blocker, dbFlag));
     const relatedRunContext = relatedRunContextView(input.project, input.relatedRunContext, dbFlag);
     return {
         kind: 'sdd-continuation-plan',
@@ -24,7 +23,7 @@ export function sddContinuationPlanFrom(input) {
         safety: [
             'Read-only planner: this command does not execute providers or mutate SDD artifacts, runs, provider config, or openspec/ files.',
             'Human acceptance remains explicit; artifact presence is not treated as acceptance.',
-            ...(hasDraftRunAction ? [draftRunWarning()] : []),
+            'Continue SDD phases in OpenCode conversation through VGXNESS MCP and hidden SDD subagents; the removed code runtime is not a CLI fallback.',
             'No openspec/ files are created or written.',
         ],
     };
@@ -43,15 +42,13 @@ function suggestedContinuationCommand(project, next, fallbackInspectCommand, dbF
         return runPhaseCommand(project, next.change, next.nextPhase, dbFlag);
     return fallbackInspectCommand;
 }
-function continuationBlockerAction(project, change, blockedPhase, blocker, dbFlag) {
-    const draftRunCommand = blocker.reason === 'draft' && isDraftRunPlanningPhase(blockedPhase) ? draftRunPhaseCommand(project, change, blockedPhase, dbFlag) : undefined;
+function continuationBlockerAction(project, change, blocker, dbFlag) {
     return {
         phase: blocker.phase,
         topicKey: blocker.topicKey,
         reason: blocker.reason,
         action: blocker.action,
         command: blockerCommand(project, change, blocker, dbFlag),
-        ...(draftRunCommand === undefined ? {} : { draftRunCommand, warning: draftRunWarning() }),
         ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
     };
 }
@@ -65,16 +62,8 @@ function blockerCommand(project, change, blocker, dbFlag) {
     return `vgxness sdd get-artifact --project ${project} --change ${change} --phase ${blocker.phase} --json${dbFlag}`;
 }
 function runPhaseCommand(project, change, phase, dbFlag) {
-    return `vgxness code sdd ${change} ${phase} --project ${project} --save-artifact${dbFlag}`;
-}
-function draftRunPhaseCommand(project, change, phase, dbFlag) {
-    return `vgxness code sdd ${change} ${phase} --project ${project} --draft-run --save-artifact${dbFlag}`;
-}
-function isDraftRunPlanningPhase(phase) {
-    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
-}
-function draftRunWarning() {
-    return 'Draft-run is planning-only; human acceptance is still required; apply-progress remains gated.';
+    void phase;
+    return `vgxness sdd continue --project ${project} --change ${change}${dbFlag}`;
 }
 function continuationDbFlag(explicitDatabasePath) {
     return explicitDatabasePath === undefined ? '' : ` --db ${explicitDatabasePath}`;

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

@@ -644,7 +644,7 @@ function blockerActionForBlocker(blocker, blockedPhase) {
             return `Run or create the ${blocker.phase} SDD phase artifact at ${blocker.topicKey}`;
         case 'draft':
             if (blockedPhase !== undefined && isDraftRunPlanningPhase(blockedPhase))
-                return `Accept ${blocker.topicKey} if it is ready, or intentionally continue planning ${blockedPhase} with --draft-run; draft-run is planning-only, human acceptance is still required, and apply-progress remains gated`;
+                return `Accept ${blocker.topicKey} if it is ready, or continue planning ${blockedPhase} in OpenCode with VGXNESS MCP after explicitly acknowledging that human acceptance is still required and apply-progress remains gated`;
             return `Accept ${blocker.topicKey}, or continue and re-run the ${blocker.phase} phase if the draft is incomplete`;
         case 'accepted':
             return `Inspect ${blocker.topicKey}; it is marked accepted but still appears in blocker data`;

package/dist/setup/backup-rollback-service.js

@@ -10,6 +10,9 @@ export function createManagedProviderConfigBackup(input) {
     const readable = validateReadableFile(targetPath, 'target');
     if (!readable.ok)
         return readable;
+    const rollbackTargetBlocker = validateProviderRollbackTarget(targetPath, input.allowedManagedHome);
+    if (rollbackTargetBlocker !== undefined)
+        return { ok: false, error: { code: 'validation_failed', message: rollbackTargetBlocker } };
     const provider = input.provider ?? 'opencode';
     const createdAt = (input.now ?? new Date()).toISOString();
     const timestamp = createdAt.replaceAll(/[-:.]/g, '');
@@ -250,14 +253,14 @@ function validateMetadataBinding(backupPath, metadata) {
         blockers.push(rollbackTargetBlocker);
     return { blockers, warnings };
 }
-function validateProviderRollbackTarget(targetPath) {
+function validateProviderRollbackTarget(targetPath, allowedManagedHome) {
     const normalizedTarget = resolve(targetPath);
-    if (isManagedUserGlobalProviderTarget(normalizedTarget))
+    if (isManagedUserGlobalProviderTarget(normalizedTarget, allowedManagedHome))
         return undefined;
     return `Refusing to restore provider config backup to ${normalizedTarget}. VGX-managed provider rollback writes user-global OpenCode/Claude targets only; project-local provider files are external/manual diagnostics and will not be restored.`;
 }
-function isManagedUserGlobalProviderTarget(targetPath) {
-    const home = resolve(homedir());
+function isManagedUserGlobalProviderTarget(targetPath, allowedManagedHome) {
+    const home = resolveManagedHome(allowedManagedHome);
     if (targetPath === resolve(home, '.config', 'opencode', 'opencode.json'))
         return true;
     if (targetPath === resolve(home, '.claude.json'))
@@ -267,6 +270,9 @@ function isManagedUserGlobalProviderTarget(targetPath) {
     const claudeAgentsRoot = resolve(home, '.claude', 'agents');
     return isPathInside(claudeAgentsRoot, targetPath) && dirname(targetPath) === claudeAgentsRoot && basename(targetPath).endsWith('.md');
 }
+function resolveManagedHome(allowedManagedHome) {
+    return resolve(typeof allowedManagedHome === 'string' && allowedManagedHome.trim().length > 0 ? allowedManagedHome : homedir());
+}
 function isPathInside(parentPath, candidatePath) {
     const relation = relative(parentPath, candidatePath);
     return relation === '' || (relation !== '' && !relation.startsWith('..') && !isAbsolute(relation));

package/dist/status/product-status.js

@@ -65,7 +65,7 @@ function resolveProject(input) {
 function fromSddCockpit(cockpit, project, baseSafety, relatedRunContext) {
     const nextLabel = cockpit.next.nextPhase === undefined ? cockpit.next.status : `${cockpit.next.status} / ${cockpit.next.nextPhase}`;
     const command = cockpit.next.status === 'runnable' && cockpit.next.nextPhase !== undefined
-        ? `vgxness code sdd ${cockpit.change} ${cockpit.next.nextPhase} --project ${cockpit.project} --save-artifact`
+        ? `vgxness sdd continue --project ${cockpit.project} --change ${cockpit.change}`
         : `vgxness sdd cockpit --project ${cockpit.project} --change ${cockpit.change} --json`;
     return {
         version: 1,

package/docs/architecture.md

@@ -1,12 +1,12 @@
 # vgxness Architecture
 
-> **Scope:** this document describes the v1.5.1 architecture as it is actually built. It is the source of truth for how the product works today. Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
+> **Scope:** this document describes the current v1.10.x architecture as it is actually built. It is the source of truth for how the product works today, with the latest health snapshot captured in [Project health audit v1.10.x](./project-health-audit-v1.10.x.md). Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
 
 `vgxness` is a local-first, provider-agnostic, Gentle-AI-like harness for agentic development. Its core architecture separates the product domain from provider-specific tooling so agents, skills, memory, SDD workflows, runs, and traces can work across OpenCode, Claude Code, and future adapters such as Pi.
 
-The architectural goal is not only to install better prompts or agent configs. `vgxness` combines an ecosystem configurator with a runtime control plane and a native code runtime: configured agents may execute the work, the control plane keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence, and the code runtime performs bounded agentic work in the local workspace with explicit permission decisions.
+The architectural goal is not only to install better prompts or agent configs. `vgxness` combines an ecosystem configurator with a runtime control plane: configured agents may execute the work, and the control plane keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence.
 
-The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI for scriptable operator control**, **TUI for guided setup and visual local operations**, and **code runtime (`vgxness code`)** for bounded agentic work in the workspace. All four call the same core services instead of reimplementing workflow rules.
+The user-facing shape is deliberately provider-native: **MCP for agents** and **CLI for scriptable operator control**, with TUI/setup work deferred. The experimental `vgxness code` runtime and principal OpenTUI code surface were removed temporarily.
 
 ## Architecture decision summary
 
@@ -16,9 +16,9 @@ The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI fo
 | Reference model | Similar product surface to Gentle-AI/`gentle-pi`: agent setup, SDD orchestration, memory wiring, skills, profiles, permissions, verification. |
 | Differentiator | Verifiable runtime state engine: SDD phases, artifacts, runs, approvals, checkpoints, and audit trails are queryable product state, not prompt-only convention. |
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
-| Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
+| Interfaces | MCP server for AI tools and CLI for automation/power users. The experimental `vgxness code` runtime and principal OpenTUI code surface are temporarily unavailable. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for user-global CLI MCP registration, direct user `~/.claude.json` MCP merge, and VGXNESS-owned user agent/memory files. VGX-managed OpenCode and Claude provider configuration is user-global only. Project-local provider files are external/manual diagnostics that may still affect providers externally, but VGXNESS does not repair, write, back up, or delete them. Read-only status/doctor/change-plan never execute providers. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for user-global CLI MCP registration, direct user `~/.claude.json` MCP merge, and VGXNESS-owned user agent/memory files. VGX-managed OpenCode and Claude provider configuration is user-global only. Project-local provider files are external/manual diagnostics that may still affect providers externally, but VGXNESS does not repair, write, back up, or delete them. Read-only status/doctor/change-plan never execute providers. Pi/`gentle-pi` compatibility is a future adapter/reference target. |
 | Memory | Project memory plus personal/global memory, backed locally. |
 | Agents | Agents/subagents are registered in a neutral schema, then rendered into provider-specific config. |
 | Skills | Skills are first-class, versioned, attachable to agents/workflows/adapters, and improved through reviewable proposals. |
@@ -474,7 +474,7 @@ The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` def
 
 ## Run lifecycle
 
-A run is the core unit of execution. Run records are stored locally in SQLite and stay provider-neutral. The lifecycle is complete in v1.5.1:
+A run is the core unit of execution. Run records are stored locally in SQLite and stay provider-neutral. The lifecycle is complete in the current architecture:
 
 ```text
 created → planned → running → needs-human
@@ -501,16 +501,16 @@ Timeline events store audit entries such as tool calls, permission decisions, ap
 
 Current operation enforcement is safe-by-default and executor-injected: `RunService.executeOperation(...)` evaluates permission, records the `permission-decision`, then either blocks or calls the supplied `RunOperationExecutor`.
 
-Execution isolation is currently **planning-only**. `planExecutionIsolation(...)` and `RunService.planOperationExecution(...)` produce an auditable plan before any real executor exists; they do not create worktrees, launch sandboxes, run shell commands, call providers, or mutate files.
+Execution isolation is currently **planning-only**. `planExecutionIsolation(...)` and `RunService.planOperationExecution(...)` produce an auditable plan before any real executor exists; they do not create worktrees, launch sandboxes, run shell commands, call providers, or mutate files. Treat `strategy: "worktree"` as a recommended future/manual isolation boundary, not proof that isolation has already happened.
 
 | Operation shape | Current planned strategy | Current behavior |
 |---|---|---|
 | In-workspace read | `workspace` | Allowed when permission policy allows it; filesystem plans require realpath/symlink hardening before any future execution. |
-| Edit, git, destructive mutation | `git-worktree` | Planned as isolated mutation work, but still asks/blocks according to permission policy. No worktree is created yet. |
-| Shell, network, provider tool, privileged operation | `process-sandbox` | Planned as sandboxed process/provider work, but approval is still required by default. No sandbox is launched yet. |
+| Edit, git, destructive mutation | `git-worktree` | Planned as isolated mutation work, but still asks/blocks according to permission policy. No worktree is created yet; mutation still happens in the current checkout unless a human or future executor creates a separate worktree first. |
+| Shell, network, provider tool, privileged operation | `process-sandbox` | Planned as sandboxed process/provider work, but approval is still required by default. No sandbox is launched yet; execution requires a separate executor with enforceable sandbox evidence. |
 | External directory or out-of-workspace path | `process-sandbox` or blocked workspace plan | Denied by default or requires explicit stronger future approval conditions; external paths are not allowed by current plans. |
 
-Every plan includes path constraints, required approvals/conditions, whether realpath hardening must happen before execution, and limitations that state the future boundary. Real sandbox/worktree executors are follow-up work after this planner is connected to a safe execution backend.
+Every plan includes path constraints, required approvals/conditions, whether realpath hardening must happen before execution, and limitations that state the future boundary. Real sandbox/worktree executors are follow-up work after this planner is connected to a safe execution backend. Until then, large or risky edits should use a human-created branch/worktree and PR flow.
 
 | Decision | Current behavior |
 |---|---|
@@ -619,17 +619,17 @@ Current foundation API: `evaluatePermission(request)` in `src/permissions/policy
 - destructive, external, privileged, or ambiguous requests require ask even when an agent override would otherwise allow the category
 - workspace boundary denials cannot be relaxed by agent/subagent overrides
 
-The code runtime layers a second, finer-grained decision on top of the policy evaluator: per-tool definitions declare whether a tool is `read`, `confirm`, or `restricted`; `PolicyApprovalBroker`, `StdioApprovalBroker`, and `ConservativePermissionGateway` (in `src/code/runtime/approval-coordinator.ts`) wire approval prompts to the runtime event stream. See [Code runtime](./code-runtime.md) for the workspace-side contract.
+The experimental code runtime layer was removed. Current risky side effects are governed through the policy evaluator, run preflight, SDD phase permissions, and explicit setup confirmation.
 
 ## Interface surface (current)
 
 CLI surface groups are documented in [CLI reference](./cli.md). The plural form is canonical — singular shortcuts are not added.
 
-MCP tools mirror the same core services for agent use. The full, current list of 41 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
+MCP tools mirror the same core services for agent use. The full, current list of 41 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI is the human/operator control surface. MCP is the agent-facing control surface.
 
 ## Evaluation strategy
 
-Minimum eval/test targets (asserted through `node:test` files under `test/`, totaling 95 files as of v1.5.1):
+Minimum eval/test targets, asserted through `node:test` files under `test/`:
 
 - Agent resolution selects the expected agent (`test/agents/agent-resolver.test.ts`).
 - Skill resolution injects the expected skill (`test/skills/`).
@@ -640,7 +640,6 @@ Minimum eval/test targets (asserted through `node:test` files under `test/`, tot
 - Run resume restores expected run state and respects retry policies (`test/runs/`).
 - Skill improvement proposals are versioned and require approval (`test/skills/`).
 - MCP tools call the same core services as CLI/TUI and return actionable blocked states (`test/mcp/`).
-- Code runtime behavior across inspect, plan, craft-preview, and craft modes (`test/code/`).
 - OpenCode config rendering and drift detection (`test/mcp/opencode-agent-config-drift.test.ts`).
 - Installation dry-run reports the exact provider config changes before mutation.
 

package/docs/cli.md

@@ -53,8 +53,8 @@ Recommended bootstrap and diagnostic flow after `npm install -g vgxness`:
 
 ```bash
 vgxness --help
-vgxness                      # OpenTUI main menu in a TTY; static safe setup guidance in CI/non-TTY
-vgxness init                 # setup wizard in a TTY; read-only plan in CI/non-TTY
+vgxness                      # static safe guidance; no DB open, provider write, or OpenTUI import
+vgxness init                 # read-only setup plan unless --yes is provided
 vgxness setup plan           # human-readable, read-only plan
 vgxness setup status         # human-readable, read-only setup status
 vgxness setup apply --yes    # writes OpenCode config only after explicit consent
@@ -70,7 +70,7 @@ Daily SDD phase progression is OpenCode-first: talk to OpenCode with the VGXNESS
 
 `setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default and only VGX-managed OpenCode target is `$HOME/.config/opencode/opencode.json`; Claude managed targets are user-global (`~/.claude.json`, `~/.claude/agents/*.md`, and `~/.claude/CLAUDE.md`). `setup apply --yes` is the explicit provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current user-global target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
-`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, user-global provider target, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd cockpit`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
+`vgxness init` returns the read-only setup plan by default, including in interactive terminals. It applies only when `--yes` is provided, preserving the same explicit confirmation path as `vgxness setup apply --yes`. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd cockpit`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
 `vgxness sdd cockpit --json` returns the same additive compatibility shape as the MCP cockpit: all existing raw `SddCockpit` top-level fields remain present, with an additional top-level `readModel`. The cockpit is read-only and metadata-only: it does not include artifact bodies, infer acceptance from artifact presence, advance phases, execute acceptance, call providers, or write provider config. Text output renders from read-model concepts such as next action, phase metadata, blockers, guidance, and `Content included: no`.
 
@@ -87,7 +87,7 @@ Use OpenCode conversation + VGXNESS MCP + hidden SDD subagents for normal daily
 
 Without `--change`, `--project`, or `--run-id`, these commands stay orientation-only and do not open the local memory store. With a selected change, project, or run, top-level `status`, `next`, and `resume` inspect SQLite read-only; formal `sdd` commands are non-provider, non-run-executing planning/artifact commands that may use the normal local store path. Pass `--json` for automation.
 
-The usual SDD operator loop happens inside OpenCode: continue the phase in conversation while VGXNESS MCP and hidden SDD subagents inspect readiness, persist artifacts, and report evidence. CLI commands remain fallback/recovery tools: inspect `status`, ask `next`, run `sdd continue` for a copyable manual continuation plan, then either run `vgxness code sdd ...` as an explicit fallback or `vgxness resume ...` for interrupted work. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
+The usual SDD operator loop happens inside OpenCode: continue the phase in conversation while VGXNESS MCP and hidden SDD subagents inspect readiness, persist artifacts, and report evidence. CLI commands remain fallback/recovery tools: inspect `status`, ask `next`, run `sdd continue` for a read-only continuation plan, or run `vgxness resume ...` for interrupted work. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
 
 ## Bun-first repository verification
 
@@ -232,17 +232,17 @@ The checked-in agent seed is currently a repository development asset. It is not
 
 `opencode preview` returns a combined, preview-only injection envelope for future OpenCode/MCP/hook callers. It does **not** execute OpenCode, install hooks or MCP servers, create runs, record skill usage, or write provider config.
 
-## OpenTUI main menu
+## Principal entrypoint
 
-Use no arguments in a TTY to open the main menu from a checkout:
+Use no arguments from a checkout to print static safe guidance:
 
 ```bash
 bun run cli:bun --
 ```
 
-The installed `vgxness`/`vgx` binary opens the OpenTUI main menu when run with no arguments in a TTY. With no TTY, no-args prints deterministic safe setup guidance, exits 0, and does not infer a project, open project state, toggle raw mode, or write provider/config artifacts. Use `vgxness --help` or `vgxness -h` to print command help without starting the main menu; explicit subcommands keep their normal behavior.
+The installed `vgxness`/`vgx` binary prints deterministic safe setup guidance with no arguments, exits 0, and does not infer a project, open project state, import OpenTUI, toggle raw mode, or write provider/config artifacts. The experimental principal code/OpenTUI surface was removed and is temporarily unavailable. Use `vgxness --help` or `vgxness -h` to print command help; explicit subcommands keep their normal behavior.
 
-The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. It is a read-only setup, diagnostics, recovery, and fallback surface; daily SDD progression stays in OpenCode with VGXNESS MCP. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
+Setup is CLI-only: use `setup plan` and `setup status` for read-only guidance, and `setup apply --yes` only after review. Daily SDD progression stays in OpenCode with VGXNESS MCP.
 
 For scriptable status, use explicit read-only commands:
 
@@ -253,14 +253,14 @@ bun run cli:bun -- next --project vgxness --change my-change
 bun run cli:bun -- resume --project vgxness --run-id <id>
 ```
 
-Provider support shown in the Installation surface is:
+Provider support for setup is:
 
 - **OpenCode** — supported primary provider with preview/status/doctor and read-only install planning.
 - **Claude** — supported secondary provider for user-global Claude CLI MCP registration, user `~/.claude.json` MCP merge, and VGXNESS-owned user agents/memory. Project-local Claude files are external/manual diagnostics only. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope user --yes --run-id <id>`. Read-only status/doctor/change-plan do not execute Claude Code.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
-Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. They print diagnostics, recovery hints, and manual fallback commands; daily SDD work should continue in OpenCode.
+Setup CLI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. They print diagnostics, recovery hints, and manual fallback commands; daily SDD work should continue in OpenCode.
 
 ## Natural-language orchestrator preview
 
@@ -280,42 +280,7 @@ Safety boundary: this is a preview only. It does **not** call providers, edit fi
 
 ## Code runtime CLI (`vgxness code`)
 
-`vgxness code` is the native workspace runtime for bounded agentic work. It is not a wrapper around OpenCode or any provider; provider adapters translate VGXNESS-native requests only. See [Code runtime](./code-runtime.md) for the full contract; this section lists the CLI surface.
-
-Modes (read-only by default unless `--approval-channel` and `--approval-policy` are passed):
-
-| Mode | Purpose | Mutations |
-|---|---|---|
-| `inspect` | Read-only investigation of the workspace. | None. |
-| `plan` | Read-only implementation planning. | None. |
-| `craft-preview` | Show the diff that would be applied. | None. |
-| `craft` | Approval-gated, bounded edit-capable work. | Edits, shell, network, git, SDD persistence all routed through explicit policy decisions. |
-
-Common flags across modes:
-
-```bash
-vgxness code inspect "<question>"   \
-  --provider openai-compatible      \  # or "fake" for offline testing
-  --model <model-id>                 \
-  --stream                           \  # emit JSONL runtime events as they happen
-  --json                             \  # final response as JSON
-  --max-source-bytes <bytes>         \  # bound on sources loaded into prompt
-  --approval-policy ask|allow|deny   \
-  --approval-channel stdio|auto      \
-  --verification none|suggest|run|repair \
-  --transcript off|summary|full      \
-  --memory off|ask|auto
-```
-
-SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools. `--draft-run` lets planning phases use draft prerequisites for planning only; human acceptance is still required, and `apply-progress` remains gated. `apply` is accepted as a user-facing alias for `apply-progress`.
-
-Useful events-only output for piping into the OpenTUI shell or your own tooling:
-
-```bash
-vgxness code inspect "Summarize the current architecture" --events-jsonl
-```
-
-Safety boundary: `inspect`, `plan`, and `craft-preview` never mutate. `craft` may only mutate through the permission-aware executors and the explicit approval channel; it never writes outside the workspace, never pushes to remote, and never edits `openspec/`. Secret-like values are redacted from prompts, transcripts, checkpoints, and memory saves. See [Safety model](./safety.md).
+The experimental `vgxness code` runtime and principal OpenTUI code surface were removed and are temporarily unavailable. Do not use `vgxness code` as an SDD fallback. Continue SDD phases in OpenCode conversation with VGXNESS MCP and hidden SDD subagents, and use `vgxness status`, `vgxness next`, `vgxness sdd continue`, or `vgxness resume` for safe CLI diagnostics and recovery.
 
 ## Workflow CLI
 
@@ -570,7 +535,6 @@ bun run cli:bun -- sdd status --project vgxness --change sdd-workflow-engine --d
 bun run cli:bun -- sdd ready --project vgxness --change sdd-workflow-engine --phase spec --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd save-artifact --project vgxness --change sdd-workflow-engine --phase proposal --content "# Proposal" --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd continue --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
-bun run cli:bun -- code sdd sdd-workflow-engine spec --project vgxness --draft-run --save-artifact --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd accept-artifact --project vgxness --change sdd-workflow-engine --phase proposal --actor user --note "Approved for spec" --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- resume --project vgxness --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd get-artifact --project vgxness --change sdd-workflow-engine --phase proposal --db /tmp/vgxness-memory.sqlite
@@ -580,7 +544,7 @@ bun run cli:bun -- sdd reopen-artifact --project vgxness --change sdd-workflow-e
 VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
 ```
 
-Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change and frames runnable phase work as OpenCode-first while preserving fallback command fields. `sdd continue` turns that state into a read-only continuation plan, including manual fallback commands, draft-run suggestions for planning phases, and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change and frames runnable phase work as OpenCode-first while preserving safe continuation command fields. `sdd continue` turns that state into a read-only continuation plan and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
 
 `sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance. `sdd reopen-artifact` moves a rejected artifact back to draft after an explicit human decision, so the artifact can be revised and accepted again.
 
@@ -978,7 +942,6 @@ For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
 ## See also
 
 - [Architecture](./architecture.md) — current-state architecture and core domain model.
-- [Code runtime](./code-runtime.md) — `vgxness code` modes, tools, providers, and approval flow.
 - [MCP tools](./mcp.md) — full reference for the 41 MCP tools exposed to agents.
 - [Safety model](./safety.md) — permission categories, approval flow, redactors, and runtime gates.
 - [Storage](./storage.md) — SQLite schema, scopes, and lifecycle.

package/docs/contributing.md

@@ -8,7 +8,6 @@ VGXNESS is an alpha local-first control plane. The repository follows a few rule
 src/
   agents/         # agent + subagent registry, resolver, canonical manifest
   cli/            # CLI dispatch, command modules, TUI, OpenTUI
-  code/           # native code runtime (vgxness code)
   export/         # redaction and export helpers
   governance/     # governance report builder, overlay fingerprint
   harness/        # harness-side tool handlers
@@ -74,7 +73,7 @@ These rules are non-negotiable. The harness is loaded with capability; do not re
 - Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
 - Human acceptance is distinct from artifact presence. Do not infer acceptance from generated content or saved drafts. The runtime rejects `acceptedBy.type !== 'human'`.
 - Workspace boundary denials cannot be relaxed by agent or subagent overrides. The policy evaluator uses `realpathSync` to defeat symlink escapes.
-- Secrets and external directory access deny by default. Redaction helpers in `src/code/reporting/redaction.ts` and `src/export/redaction.ts` are the only place secret-shaped values should be stripped.
+- Secrets and external directory access deny by default. Redaction helpers in `src/export/redaction.ts` strip secret-shaped values for export surfaces.
 
 ## Style
 
@@ -92,7 +91,7 @@ The docs are the user-facing contract. When the code drifts, the docs must catch
 - When you add a new CLI command, document it in [CLI reference](./cli.md).
 - When you change a permission category, default, or phase mode, update [Safety model](./safety.md).
 - When you add a migration, append it to the table in [Storage](./storage.md).
-- When you add or change a provider, update [Providers](./providers.md) and the [Code runtime](./code-runtime.md) tool list.
+- When you add or change a provider, update [Providers](./providers.md) and setup/status documentation.
 
 ## Pull request process
 
@@ -106,6 +105,22 @@ VGXNESS is shipped as a proprietary package. The npm publication step is a separ
 
 PRs that touch safety gates, permission categories, default policies, the run lifecycle, or the SDD acceptance gate are reviewed by a maintainer who can answer "does this still match the safety model?" without consulting the diff. If you are unsure, open the PR as a draft and ask.
 
+Do not push directly to `main` for normal development. Use a branch, open a PR, and let CI/check requirements enforce the review boundary. Direct pushes are reserved for exceptional maintainer recovery and must be followed by an explicit note that branch protection was bypassed.
+
+### Stacked PRs
+
+Use stacked PRs when a change naturally splits into reviewable layers, for example docs groundwork → safety-policy hardening → CLI/MCP behavior. A stacked PR keeps each review small while preserving dependency order.
+
+Recommended pattern:
+
+1. Start from `main` for the first branch: `feature/base-slice`.
+2. Open PR 1 into `main`.
+3. Branch PR 2 from PR 1: `feature/follow-up-slice`, and open PR 2 with PR 1 as its base.
+4. Keep each PR focused on one logical change and explain its base PR in the description.
+5. Rebase or retarget follow-up PRs after their base merges; do not squash unrelated stacked slices into one large review.
+
+Avoid stacked PRs for emergency CI repairs: use one small hotfix PR against `main` unless the repair truly depends on another unmerged branch.
+
 ## Commit conventions
 
 - Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `build:`, `ci:`).