vgxness 1.9.0 → 1.9.1

package/dist/agents/canonical-agent-manifest.js

@@ -1,5 +1,6 @@
+import { canonicalBehaviorContractVersion } from '../behavior/behavior-contract-manifest.js';
 export const canonicalDefaultAgentName = 'vgxness-manager';
-export const canonicalPromptContractVersion = 6;
+export const canonicalPromptContractVersion = 7;
 export const canonicalSddSubagentNames = [
     'vgxness-sdd-explore',
     'vgxness-sdd-propose',
@@ -81,7 +82,7 @@ function managerDefinition() {
         memory: { scopes: ['project'] },
         workflows: ['explore', 'quickfix', 'plan', 'build', 'debug', 'sdd', 'agent-seeding', 'opencode-install'],
         skills: ['vgxness-sdd-manager'],
-        adapters: { opencode: { model: 'openai/gpt-5.5', config: { options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion }, permission: { task: createCanonicalOpenCodeSddTaskPermissions() } } } },
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion, vgxnessBehaviorContractVersion: canonicalBehaviorContractVersion }, permission: { task: createCanonicalOpenCodeSddTaskPermissions() } } } },
         providerSupport: commonSupport(),
     };
 }
@@ -100,7 +101,7 @@ function subagentDefinition(name) {
         memory: { scopes: ['project'] },
         workflows: data.workflows,
         skills: data.skills,
-        adapters: { opencode: { model: 'openai/gpt-5.5', config: { hidden: true, options: { vgxnessPromptContractVersion: canonicalPromptContractVersion } } } },
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { hidden: true, options: { vgxnessPromptContractVersion: canonicalPromptContractVersion, vgxnessBehaviorContractVersion: canonicalBehaviorContractVersion } } } },
         providerSupport: commonSupport(),
     };
 }
@@ -118,45 +119,44 @@ export const canonicalOpenCodeManagerPrompt = `# VGXNESS Manager - compact SDD o
 Bind only to the primary \`vgxness-manager\` agent. Executor agents (for example \`vgxness-sdd-apply\`) use their own prompts.
 
 ## Role
-Coordinate SDD; do not become a monolithic executor. Keep the chat thin, use VGXNESS MCP as durable state, delegate phase work to the smallest exact hidden SDD subagent, then synthesize concise evidence for the user. Be direct, practical, repository-grounded, user-controlled, and willing to challenge unsafe or weak assumptions.
-
-Coach while coordinating: teach briefly when helpful, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
+Coordinate SDD; keep chat thin, use VGXNESS MCP as durable state, delegate to the smallest exact hidden SDD subagent, then synthesize evidence. Coach while coordinating: teach briefly, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
 
 ## Non-negotiable governance
-- SDD artifact acceptance is human-only. Never infer acceptance from generated output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/unaccepted artifacts as not accepted until a human acceptance record exists.
+- SDD artifact acceptance is human-only. Never infer or fabricate acceptance from generated output, subagent/model output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/stale/unaccepted artifacts as not accepted until a human acceptance record exists.
 - Before phase advancement, call readiness/status tools: \`vgxness_sdd_status\`/\`vgxness_sdd_next\` and \`vgxness_sdd_ready\` or \`vgxness_sdd_get_readiness\`.
 - Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent context when available. If approval/block is required, stop; do not invent approval.
+- Direct human acceptance of an exact SDD artifact via \`vgxness_sdd_accept_artifact\` is not a generic SDD write for manager routing: do not call \`vgxness_run_preflight\` solely for that acceptance when the user explicitly accepted the exact project/change/phase artifact, \`acceptedBy.type\` is \`"human"\`, \`acceptedBy.id\` is non-empty, and status/readiness confirms the artifact is eligible. This shortcut applies only to \`vgxness_sdd_accept_artifact\`, not \`vgxness_sdd_save_artifact\`, edits, shell/tests, git, provider config, memory writes, external paths, secrets, destructive/privileged/ambiguous operations.
 - OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking. Report warnings; do not say native OpenCode tools are hard-blocked by config.
 - Do not mutate provider/global OpenCode config unless explicitly requested. Do not write to \`openspec/\`. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents allowed.
 - Do not publish packages unless explicitly requested.
 - Do not change model or reasoning effort.
 
 ## Flexible governance routing
-Use the lightest safe path: Tier 0-2 direct/explore/plan/debug/quickfix/build; keywords alone do not force SDD. Tier 3 needs preflight/explicit validation but not automatic SDD. Tier 4 governance, permission model, SDD acceptance, architecture/security semantics, or cross-surface workflow behavior uses formal SDD. Provider status/doctor/preview/handoff are read-only audit-only; provider config writes stay gated.
+Use the lightest safe path: Tier 0-2 direct; Tier 3 preflight/explicit validation; Tier 4 formal SDD for governance, permission model, SDD acceptance, architecture/security, or cross-surface behavior. Provider status/doctor/preview/handoff are read-only audit-only; provider config writes stay gated.
 
 ## Provider-native daily flow
-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.
+Daily SDD happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for normal flow. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
 
 ## MCP playbook
-- 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.
+- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal, not truth. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one and summarize.
+- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default so the primary context stays clean. Use verbose only when required, preferably inside the delegated phase subagent. Save with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
+- Acceptance/readiness: check SDD status/readiness for the exact project/change/phase, confirm explicit human acceptance of that exact artifact, call \`vgxness_sdd_accept_artifact\` directly with audit context (\`acceptedBy.type: "human"\`, non-empty \`acceptedBy.id\`, runId, agentId, note/rationale when useful), then re-check status/readiness before reporting state. Do not add \`vgxness_run_preflight\` solely for that exact direct acceptance call. Ambiguous replies count only when tied to an immediate exact acceptance prompt. 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\` for prior work or unclear context; 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\` are 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.
 - Runs: use \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\` for significant implementation/verification or multi-step delegated work; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, and close with \`vgxness_run_finalize\`.
 - Provider diagnostics: \`vgxness_provider_status\` and \`vgxness_provider_doctor\` are read-only reports.
 
 ## Minimum flows
-- Simple answer: respond inline; memory only if prior context is referenced; no run by default.
-- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist returned output only according to acceptance/governance.
-- Apply/verify: require tasks/apply-progress as appropriate -> read artifacts -> resolve exact subagent -> recover/start run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save apply-progress/verify -> finalize when clear.
+- Simple answer: inline; memory only for prior context; no run by default.
+- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist by governance.
+- Apply/verify: require prerequisites -> read artifacts -> resolve exact subagent -> start/recover run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save output -> finalize when clear.
 - Config/provider/prompt change: inspect manager/profile or payload first; persistent changes require explicit human authorization.
 
 ## Delegation thresholds
-Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration (4+ files), substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping: explore/propose/spec/design/tasks/apply/verify/archive/init/onboard.
+Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration, substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping.
 
 ## Output
-Be concise: what was delegated, what came back, files/decisions changed, evidence/tests, risks, and next step.`;
+Be concise: delegated work, results, files/decisions, evidence/tests, risks, next step.`;
 const registryManagerInstructions = 'You are the VGXNESS SDD coordinator, not a monolithic executor. Coach briefly while coordinating: explain useful tradeoffs, be realistic about risks and unknowns, respectfully challenge weak assumptions with better options, keep the user comfortable and in control, and stay concise. Use VGXNESS MCP as the durable control plane: restore session context with vgxness_session_restore before inferring start/resume state from chat, and close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists. Check SDD status/next/ready, read prerequisites with sdd_get_artifact or sdd_list_artifacts, save accepted phase output with sdd_save_artifact, search/get/save/update memory only for reusable knowledge, resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, and use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health. Prefer payloadMode=compact for manager-facing status/context reads, SDD artifact reads/lists, and activation handoffs so the primary context stays clean; request payloadMode=verbose only when full artifact contents, provider payloads, or skill context are actually needed, preferably inside delegated phase subagents. CLI is an escape hatch for bootstrap, doctor, rollback, recovery, MCP unavailable/setup missing, or explicit user request; do not tell users to run terminal SDD phase commands for normal daily flow. Delegate real SDD phase work to the smallest exact vgxness-sdd-* subagent allowed by permission.task, synthesize results, and persist artifacts/checkpoints. Do not perform substantial multi-file implementation inline. Do not mutate global/provider OpenCode config, install skills, publish packages, or write openspec/ unless explicitly authorized. Checked-in manager and subagent instructions are self-contained; external sdd-* skill files are optional registry assets, not requirements.';
 const subagentData = {
     'vgxness-sdd-explore': { seedDescription: 'Investigates codebase context and identifies options before proposals.', seedInstructions: 'You are the explore phase executor, not the orchestrator. Do not delegate. Explore repository evidence for the requested SDD change. Do not implement code changes. Return concise findings, risks, and recommended next artifacts.', capabilities: ['sdd-exploration', 'codebase-research', 'discovery'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:explore'], skills: ['vgxness-sdd-explore'], phaseContract: 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.' },

package/dist/agents/renderers/claude-renderer.js

@@ -1,3 +1,5 @@
+import { canonicalPromptContractVersion } from '../canonical-agent-manifest.js';
+import { canonicalBehaviorContractVersion } from '../../behavior/behavior-contract-manifest.js';
 import { ok, validationFailure } from './provider-adapter.js';
 const previewWarnings = [
     'Claude rendering returns installable preview artifacts only; it does not install and does not write provider configuration.',
@@ -66,7 +68,7 @@ export class ClaudeAgentRenderer {
     }
 }
 function renderClaudeAgentMarkdown(agent, key) {
-    return `---\nname: ${JSON.stringify(key)}\ndescription: ${JSON.stringify(agent.description)}\n---\n\n<!-- VGXNESS-GENERATED claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=6 safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
+    return `---\nname: ${JSON.stringify(key)}\ndescription: ${JSON.stringify(agent.description)}\n---\n\n<!-- VGXNESS-GENERATED claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=${canonicalPromptContractVersion} behaviorContractVersion=${canonicalBehaviorContractVersion} safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
 }
 function claudeAgentKey(value) {
     return pathSegment(value);

package/dist/agents/renderers/opencode-renderer.js

@@ -1,3 +1,4 @@
+import { behaviorContractProjectionMetadata } from '../../behavior/behavior-contract-manifest.js';
 import { ok, validationFailure } from './provider-adapter.js';
 const openCodeSchema = 'https://opencode.ai/config.json';
 const previewWarning = 'Rendering returns preview artifacts only; it does not install or write .opencode/, .claude/, or provider configuration.';
@@ -50,7 +51,7 @@ export class OpenCodeAgentRenderer {
         const artifact = {
             relativePath: `rendered/opencode/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/opencode.json`,
             contentType: 'application/json',
-            contents: `${JSON.stringify({ $schema: openCodeSchema, agent: renderedAgents, safety: previewSafety }, null, 2)}\n`,
+            contents: `${JSON.stringify({ $schema: openCodeSchema, behaviorContract: behaviorContractProjectionMetadata, agent: renderedAgents, safety: previewSafety }, null, 2)}\n`,
         };
         return ok({
             provider: this.provider,

package/dist/behavior/behavior-contract-manifest.js

@@ -0,0 +1,42 @@
+export const canonicalBehaviorContractName = 'vgxness-manager-behavior-contract';
+export const canonicalBehaviorContractVersion = '1.0.0';
+export const criticalBehaviorContractInvariantIds = [
+    'sdd.acceptance.human-only',
+    'sdd.draft-is-not-accepted',
+    'sdd.readiness-before-advance',
+    'provider.preview-status-doctor-readonly',
+    'provider.config-writes-explicit-consent',
+    'run.risky-effects-preflight',
+    'delegation.deny-by-default',
+    'delegation.no-wildcard',
+    'context.manager-compact-default',
+    'context.progressive-disclosure',
+    'flow.provider-native-no-terminal-sdd-daily',
+    'scope.exclude-vgxcode-runtime',
+    'worktree.preserve-unrelated-user-work',
+];
+export const behaviorContractManifest = {
+    name: canonicalBehaviorContractName,
+    contractVersion: canonicalBehaviorContractVersion,
+    excludedTargets: ['vgxcode', 'src/code/runtime/*', 'src/code/prompts/*'],
+    invariants: [
+        { id: 'sdd.acceptance.human-only', category: 'sdd', severity: 'critical', summary: 'SDD acceptance is recorded only from explicit human acceptance.' },
+        { id: 'sdd.draft-is-not-accepted', category: 'sdd', severity: 'critical', summary: 'Draft, rejected, superseded, legacy, or unaccepted artifacts are not accepted prerequisites.' },
+        { id: 'sdd.readiness-before-advance', category: 'sdd', severity: 'critical', summary: 'Phase advancement checks readiness/status before treating prerequisites as satisfied.' },
+        { id: 'provider.preview-status-doctor-readonly', category: 'provider', severity: 'critical', summary: 'Preview, status, and doctor surfaces are read-only and do not write provider configuration.' },
+        { id: 'provider.config-writes-explicit-consent', category: 'provider', severity: 'critical', summary: 'Provider configuration writes require explicit user consent through confirmed flows.' },
+        { id: 'run.risky-effects-preflight', category: 'run', severity: 'critical', summary: 'Risky edits, shell, git, provider, secret, destructive, privileged, or ambiguous effects require preflight.' },
+        { id: 'delegation.deny-by-default', category: 'delegation', severity: 'critical', summary: 'Delegation defaults to deny unless an exact governed path allows it.' },
+        { id: 'delegation.no-wildcard', category: 'delegation', severity: 'critical', summary: 'Wildcard delegation is not allowed; exact canonical subagents must be used.' },
+        { id: 'context.manager-compact-default', category: 'context', severity: 'critical', summary: 'Manager-facing context defaults to compact payloads.' },
+        { id: 'context.progressive-disclosure', category: 'context', severity: 'critical', summary: 'Expanded and verbose context are requested only when needed.' },
+        { id: 'flow.provider-native-no-terminal-sdd-daily', category: 'flow', severity: 'critical', summary: 'Daily SDD progression happens provider-natively through conversation and MCP, not mandatory terminal phase commands.' },
+        { id: 'scope.exclude-vgxcode-runtime', category: 'scope', severity: 'critical', summary: 'This behavior contract excludes vgxcode and src/code runtime/prompt implementation targets.' },
+        { id: 'worktree.preserve-unrelated-user-work', category: 'worktree', severity: 'critical', summary: 'Unrelated user work and dirty files are preserved.' },
+    ],
+};
+export const behaviorContractProjectionMetadata = {
+    behaviorContractName: canonicalBehaviorContractName,
+    behaviorContractVersion: canonicalBehaviorContractVersion,
+    criticalInvariantIds: criticalBehaviorContractInvariantIds,
+};

package/dist/behavior/behavior-contract-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/behavior/behavior-contract-validation.js

@@ -0,0 +1,42 @@
+import { behaviorContractManifest, criticalBehaviorContractInvariantIds } from './behavior-contract-manifest.js';
+export function validateBehaviorContractManifest(manifest = behaviorContractManifest) {
+    const errors = [];
+    if (!manifest.name.trim())
+        errors.push('behavior contract name is required');
+    if (!manifest.contractVersion.trim())
+        errors.push('behavior contract version is required');
+    const seen = new Set();
+    for (const invariant of manifest.invariants) {
+        if (!invariant.id.trim())
+            errors.push('invariant id is required');
+        if (seen.has(invariant.id))
+            errors.push(`duplicate invariant id: ${invariant.id}`);
+        seen.add(invariant.id);
+        if (!invariant.summary.trim())
+            errors.push(`invariant ${invariant.id} summary is required`);
+    }
+    for (const id of criticalBehaviorContractInvariantIds) {
+        const invariant = manifest.invariants.find((candidate) => candidate.id === id);
+        if (invariant === undefined)
+            errors.push(`missing critical invariant: ${id}`);
+        else if (invariant.severity !== 'critical')
+            errors.push(`critical invariant ${id} must have severity critical`);
+    }
+    for (const target of ['vgxcode', 'src/code/runtime/*', 'src/code/prompts/*']) {
+        if (!manifest.excludedTargets.includes(target))
+            errors.push(`missing excluded target: ${target}`);
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function validateBehaviorContractProjection(metadata, manifest = behaviorContractManifest) {
+    const errors = [];
+    if (metadata.behaviorContractName !== manifest.name)
+        errors.push(`behavior contract name mismatch: ${metadata.behaviorContractName}`);
+    if (metadata.behaviorContractVersion !== manifest.contractVersion)
+        errors.push(`behavior contract version mismatch: ${metadata.behaviorContractVersion}`);
+    for (const id of criticalBehaviorContractInvariantIds) {
+        if (!metadata.criticalInvariantIds.includes(id))
+            errors.push(`projection missing critical invariant reference: ${id}`);
+    }
+    return { ok: errors.length === 0, errors };
+}

package/dist/mcp/control-plane-snapshot-service.js

@@ -0,0 +1,272 @@
+import { ContextBudgetService } from '../payload/context-budget-service.js';
+export const contextCockpitSnapshotLevels = ['compact', 'expanded', 'verbose'];
+export class ContextCockpitSnapshotService {
+    dependencies;
+    budget;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.budget = dependencies.budget ?? new ContextBudgetService();
+    }
+    build(input) {
+        const level = input.level ?? 'compact';
+        const legacyInput = {
+            project: input.project,
+            ...(input.directory === undefined ? {} : { directory: input.directory }),
+            ...(input.limit === undefined ? {} : { limit: input.limit }),
+        };
+        const legacy = this.dependencies.memory.getContextCockpit(legacyInput);
+        if (!legacy.ok)
+            return legacy;
+        const sddResult = input.change === undefined ? undefined : this.buildSddSection({ project: input.project, change: input.change }, level);
+        if (sddResult !== undefined && !sddResult.ok)
+            return sddResult;
+        const sdd = sddResult?.value;
+        const integratesSdd = sdd !== undefined;
+        const optionalSectionsOmitted = omittedSections(legacy.value.optionalSectionsOmitted, integratesSdd ? ['provider'] : ['sdd', 'provider'], integratesSdd ? ['sdd'] : []);
+        const snapshotWithoutBudget = {
+            ...legacy.value,
+            optionalSectionsOmitted,
+            ...(sdd === undefined ? {} : { sdd }),
+            snapshotVersion: 2,
+            level,
+            references: [
+                {
+                    id: 'legacy-context-cockpit',
+                    kind: 'legacy-context-cockpit',
+                    description: 'Wrapped output from the existing no-trace context cockpit path.',
+                },
+            ],
+            warnings: [
+                ...(integratesSdd ? [] : ['sdd-snapshot-omitted:no-change']),
+                'provider-snapshot-omitted:no-workspace-root',
+            ],
+            safety: {
+                ...legacy.value.safety,
+                readOnly: true,
+                recordsTraces: false,
+                noTrace: true,
+                mutatesSessions: false,
+                noSessionMutation: true,
+                mutatesMemories: false,
+                noMemoryMutation: true,
+                mutatesArtifacts: false,
+                noArtifactMutation: true,
+                mutatesRuns: false,
+                noCheckpoints: true,
+                writesProviderConfig: false,
+                noProviderConfigWrites: true,
+                mutatesRepository: false,
+                executesProvider: false,
+                mutatesProviderConfig: false,
+                createsRun: false,
+                createsCheckpoint: false,
+                recordsTimelineEvent: false,
+                integratesSdd,
+                integratesProvider: false,
+            },
+        };
+        const report = this.budget.reportJson(budgetIdForLevel(level), snapshotWithoutBudget);
+        return {
+            ok: true,
+            value: {
+                ...snapshotWithoutBudget,
+                budget: {
+                    level,
+                    policy: budgetIdForLevel(level),
+                    report,
+                    memoryPreviewLimit: input.limit ?? legacy.value.memoryPreviews.length,
+                    includesSdd: integratesSdd,
+                    includesProvider: false,
+                    omittedSections: [
+                        ...(integratesSdd ? [] : ['sdd']),
+                        'provider',
+                        'runs',
+                        'memory-content',
+                        'session-transcripts',
+                        'provider-config-contents',
+                        'run-checkpoint-details',
+                    ],
+                    heavyContentPolicy: 'references-only',
+                    notes: ['Budget measured with ContextBudgetService.reportJson before adding the final budget section.'],
+                },
+            },
+        };
+    }
+    buildSddSection(input, level) {
+        if (this.dependencies.sdd === undefined) {
+            return { ok: false, error: { code: 'validation_failed', message: 'SDD cockpit service is not available' } };
+        }
+        const cockpit = this.dependencies.sdd.getCockpit(input);
+        if (!cockpit.ok)
+            return cockpit;
+        return { ok: true, value: toSddSection(cockpit.value, level) };
+    }
+}
+function toSddSection(cockpit, level) {
+    switch (level) {
+        case 'compact':
+            return toCompactSddSection(cockpit);
+        case 'expanded':
+            return toExpandedSddSection(cockpit);
+        case 'verbose':
+            return toVerboseSddSection(cockpit);
+    }
+}
+function toCompactSddSection(cockpit) {
+    return {
+        projection: 'compact',
+        project: cockpit.project,
+        change: cockpit.change,
+        recommendedAction: cockpit.recommendedAction,
+        ...(cockpit.actionablePhase === undefined ? {} : { actionablePhase: cockpit.actionablePhase }),
+        next: {
+            status: cockpit.next.status,
+            ...(cockpit.next.nextPhase === undefined ? {} : { nextPhase: cockpit.next.nextPhase }),
+            reason: cockpit.next.reason,
+        },
+        phases: cockpit.phases.map((phase) => ({
+            phase: phase.phase,
+            topicKey: phase.topicKey,
+            present: phase.present,
+            accepted: phase.accepted,
+            legacy: phase.legacy,
+            state: phase.state,
+            readinessReady: phase.readiness.ready,
+            blockerCount: phase.blockers.length,
+        })),
+        counts: {
+            phases: cockpit.phases.length,
+            artifacts: cockpit.artifacts.length,
+            accepted: cockpit.acceptedCount,
+            legacy: cockpit.legacyCount,
+            blockers: cockpit.aggregateBlockers.length,
+        },
+    };
+}
+function toExpandedSddSection(cockpit) {
+    return {
+        projection: 'expanded',
+        project: cockpit.project,
+        change: cockpit.change,
+        recommendedAction: cockpit.recommendedAction,
+        ...(cockpit.actionablePhase === undefined ? {} : { actionablePhase: cockpit.actionablePhase }),
+        next: {
+            status: cockpit.next.status,
+            ...(cockpit.next.nextPhase === undefined ? {} : { nextPhase: cockpit.next.nextPhase }),
+            reason: cockpit.next.reason,
+        },
+        phases: cockpit.phases.map(toExpandedSddPhase),
+        counts: {
+            phases: cockpit.phases.length,
+            artifacts: cockpit.artifacts.length,
+            accepted: cockpit.acceptedCount,
+            legacy: cockpit.legacyCount,
+            blockers: cockpit.aggregateBlockers.length,
+        },
+        blockers: cockpit.aggregateBlockers.map(toSddBlocker),
+    };
+}
+function toVerboseSddSection(cockpit) {
+    return {
+        projection: 'verbose',
+        project: cockpit.project,
+        change: cockpit.change,
+        recommendedAction: cockpit.recommendedAction,
+        ...(cockpit.actionablePhase === undefined ? {} : { actionablePhase: cockpit.actionablePhase }),
+        next: {
+            status: cockpit.next.status,
+            ...(cockpit.next.nextPhase === undefined ? {} : { nextPhase: cockpit.next.nextPhase }),
+            reason: cockpit.next.reason,
+        },
+        phases: cockpit.phases.map(toExpandedSddPhase),
+        counts: {
+            phases: cockpit.phases.length,
+            artifacts: cockpit.artifacts.length,
+            accepted: cockpit.acceptedCount,
+            legacy: cockpit.legacyCount,
+            blockers: cockpit.aggregateBlockers.length,
+        },
+        blockers: cockpit.aggregateBlockers.map(toSddBlocker),
+        artifacts: cockpit.artifacts.map(toArtifactMetadata),
+    };
+}
+function toExpandedSddPhase(phase) {
+    return {
+        phase: phase.phase,
+        topicKey: phase.topicKey,
+        present: phase.present,
+        accepted: phase.accepted,
+        legacy: phase.legacy,
+        state: phase.state,
+        readinessReady: phase.readiness.ready,
+        blockerCount: phase.blockers.length,
+        readiness: toReadinessMetadata(phase.readiness),
+        ...(phase.artifact === undefined ? {} : { artifact: toArtifactMetadata(phase.artifact) }),
+        blockers: phase.blockers.map(toSddBlocker),
+    };
+}
+function toReadinessMetadata(readiness) {
+    return {
+        change: readiness.change,
+        phase: readiness.phase,
+        ready: readiness.ready,
+        satisfiedPrerequisites: readiness.satisfiedPrerequisites,
+        missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
+        blockedPrerequisites: (readiness.blockedPrerequisites ?? []).map(toPrerequisiteBlocker),
+    };
+}
+function toPrerequisiteBlocker(blocker) {
+    return {
+        phase: blocker.phase,
+        topicKey: blocker.topicKey,
+        reason: blocker.reason,
+        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+    };
+}
+function toArtifactMetadata(artifact) {
+    return {
+        phase: artifact.phase,
+        topicKey: artifact.topicKey,
+        present: artifact.present,
+        accepted: artifact.accepted,
+        legacy: artifact.legacy,
+        state: artifact.state,
+        ...(artifact.artifactId === undefined ? {} : { artifactId: artifact.artifactId }),
+        ...(artifact.createdAt === undefined ? {} : { createdAt: artifact.createdAt }),
+        ...(artifact.updatedAt === undefined ? {} : { updatedAt: artifact.updatedAt }),
+        ...(artifact.acceptance === undefined ? {} : { acceptance: toAcceptanceMetadata(artifact.acceptance) }),
+    };
+}
+function toAcceptanceMetadata(acceptance) {
+    return {
+        actor: {
+            type: acceptance.actor.type,
+            id: acceptance.actor.id,
+            ...(acceptance.actor.displayName === undefined ? {} : { displayName: acceptance.actor.displayName }),
+        },
+        acceptedAt: acceptance.acceptedAt,
+    };
+}
+function toSddBlocker(blocker) {
+    return {
+        kind: blocker.kind,
+        phase: blocker.phase,
+        topicKey: blocker.topicKey,
+        reason: blocker.reason,
+        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+    };
+}
+function budgetIdForLevel(level) {
+    switch (level) {
+        case 'compact':
+            return 'snapshotCompact';
+        case 'expanded':
+            return 'snapshotExpanded';
+        case 'verbose':
+            return 'subagentVerbosePayload';
+    }
+}
+function omittedSections(legacy, required, resolved = []) {
+    const resolvedSet = new Set(resolved);
+    return [...new Set([...legacy, ...required])].filter((section) => !resolvedSet.has(section));
+}

package/dist/mcp/control-plane.js

@@ -12,6 +12,7 @@ import { SddWorkflowService } from '../sdd/sdd-workflow-service.js';
 import { SkillRegistryService } from '../skills/skill-registry-service.js';
 import { VerificationPlanService } from '../verification/index.js';
 import { ProviderChangePlanService } from './provider-change-plan.js';
+import { ContextCockpitSnapshotService } from './control-plane-snapshot-service.js';
 import { ProviderDoctorService } from './provider-doctor.js';
 import { ProviderStatusService } from './provider-status.js';
 import { errorEnvelope, successEnvelope, } from './schema.js';
@@ -64,7 +65,7 @@ export function callVgxTool(call, services) {
         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));
+            return toEnvelope(validated.tool, new ContextCockpitSnapshotService({ memory: services.memory, sdd: services.sdd }).build(validated.input));
         case 'vgxness_agent_resolve':
             return toEnvelope(validated.tool, services.agents.resolveAgents(validated.input));
         case 'vgxness_agent_activate':

package/dist/mcp/index.js

@@ -13,6 +13,7 @@ export * from './claude-code-scope.js';
 export * from './claude-code-user-config.js';
 export * from './claude-code-user-memory.js';
 export * from './control-plane.js';
+export * from './control-plane-snapshot-service.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';
 export * from './opencode-handoff-preview.js';

package/dist/mcp/schema.js

@@ -99,6 +99,7 @@ const runStatuses = ['created', 'planned', 'running', 'needs-human', 'completed'
 const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const payloadModes = ['compact', 'verbose'];
+const contextCockpitLevels = ['compact', 'expanded', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
@@ -264,8 +265,10 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_context_cockpit: z
         .object({
         project: z.string().min(1),
+        change: z.string().min(1).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/).optional(),
         directory: z.string().min(1).optional(),
         limit: z.number().int().min(1).max(100).optional(),
+        level: z.enum(contextCockpitLevels).optional(),
     })
         .passthrough(),
     vgxness_agent_resolve: z

package/dist/mcp/validation.js

@@ -13,6 +13,7 @@ const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const permissionDecisions = ['allow', 'ask', 'deny'];
 const payloadModes = ['compact', 'verbose'];
+const contextCockpitLevels = ['compact', 'expanded', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -238,13 +239,18 @@ function validateSddCockpitInput(input, tool) {
     return readProjectAndChange(record.value, tool);
 }
 function validateContextCockpitInput(input, tool) {
-    const record = inputRecord(input, tool, ['project', 'directory', 'limit']);
+    const record = inputRecord(input, tool, ['project', 'change', 'directory', 'limit', 'level']);
     if (!record.ok)
         return record;
     const project = readNonEmptyString(record.value, 'project', tool);
     if (!project.ok)
         return project;
     const result = { project: project.value };
+    const change = readOptionalChange(record.value, tool);
+    if (!change.ok)
+        return change;
+    if (change.value !== undefined)
+        result.change = change.value;
     const directory = readOptionalNonEmptyString(record.value, 'directory', tool);
     if (!directory.ok)
         return directory;
@@ -255,6 +261,11 @@ function validateContextCockpitInput(input, tool) {
             return validationFailure('limit must be an integer between 1 and 100', tool);
         result.limit = record.value.limit;
     }
+    const level = readOptionalOneOf(record.value, 'level', contextCockpitLevels, tool);
+    if (!level.ok)
+        return level;
+    if (level.value !== undefined)
+        result.level = level.value;
     return { ok: true, value: result };
 }
 function readProjectAndChange(record, tool) {

package/dist/payload/context-budget-policy.js

@@ -0,0 +1,17 @@
+export const defaultContextBudgetPolicy = {
+    policyVersion: '1.0.0',
+    limits: [
+        { id: 'managerPromptBase', label: 'Manager prompt base', targetBytes: 16_384, hardLimitBytes: 24_576, enforcement: 'warn' },
+        { id: 'managerInitialPayload', label: 'Manager initial payload', targetBytes: 12_288, hardLimitBytes: 18_432, enforcement: 'warn' },
+        { id: 'snapshotCompact', label: 'Compact snapshot', targetBytes: 10_240, hardLimitBytes: 15_360, enforcement: 'warn' },
+        { id: 'snapshotExpanded', label: 'Expanded snapshot', targetBytes: 30_720, hardLimitBytes: 46_080, enforcement: 'report' },
+        { id: 'subagentVerbosePayload', label: 'Subagent verbose payload', targetBytes: 122_880, hardLimitBytes: 184_320, enforcement: 'report' },
+        { id: 'initialMcpCalls', label: 'Initial MCP calls', targetBytes: 3, hardLimitBytes: 5, enforcement: 'report' },
+    ],
+};
+export function getContextBudgetLimit(policy, id) {
+    const limit = policy.limits.find((candidate) => candidate.id === id);
+    if (limit === undefined)
+        throw new Error(`Unknown context budget id: ${id}`);
+    return limit;
+}

package/dist/payload/context-budget-service.js

@@ -0,0 +1,44 @@
+import { utf8ByteCount } from './payload-summary.js';
+import { defaultContextBudgetPolicy, getContextBudgetLimit } from './context-budget-policy.js';
+export class ContextBudgetService {
+    policy;
+    constructor(policy = defaultContextBudgetPolicy) {
+        this.policy = policy;
+    }
+    measureUtf8Bytes(content) {
+        return utf8ByteCount(content);
+    }
+    measureJsonBytes(value) {
+        return utf8ByteCount(JSON.stringify(value));
+    }
+    reportContent(id, content) {
+        return this.buildReport(id, this.measureUtf8Bytes(content));
+    }
+    reportJson(id, value) {
+        return this.buildReport(id, this.measureJsonBytes(value));
+    }
+    buildReport(id, measuredBytes) {
+        if (!Number.isSafeInteger(measuredBytes) || measuredBytes < 0)
+            throw new RangeError('measuredBytes must be a non-negative safe integer');
+        const budget = getContextBudgetLimit(this.policy, id);
+        const excessTargetBytes = Math.max(0, measuredBytes - budget.targetBytes);
+        const excessHardLimitBytes = Math.max(0, measuredBytes - budget.hardLimitBytes);
+        return {
+            policyVersion: this.policy.policyVersion,
+            budget,
+            measuredBytes,
+            withinTarget: excessTargetBytes === 0,
+            withinHardLimit: excessHardLimitBytes === 0,
+            excessTargetBytes,
+            excessHardLimitBytes,
+            recommendations: budgetRecommendations(budget, excessTargetBytes, excessHardLimitBytes),
+        };
+    }
+}
+function budgetRecommendations(budget, excessTargetBytes, excessHardLimitBytes) {
+    if (excessHardLimitBytes > 0)
+        return [`Reduce ${budget.label} below hard limit by at least ${excessHardLimitBytes} bytes.`, 'Move full content behind references or verbose-only retrieval.'];
+    if (excessTargetBytes > 0)
+        return [`Reduce ${budget.label} toward target by ${excessTargetBytes} bytes.`, 'Prefer compact summaries and progressive disclosure.'];
+    return [];
+}

package/package.json

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