vgxness 1.20.4 → 1.20.6

package/dist/adapters/claude/agent-renderer.js

@@ -0,0 +1,82 @@
+import { canonicalBehaviorContractVersion } from '../../behavior/behavior-contract-manifest.js';
+import { canonicalPromptContractVersion } from '../../domain/agents/canonical-agent-manifest.js';
+import { ok, validationFailure } from '../provider-renderer.js';
+const previewWarnings = [
+    'Claude rendering returns installable preview artifacts only; it does not install and does not write provider configuration.',
+    'VGX does not execute Claude or run Claude Code from this preview.',
+    'VGXNESS does not install Claude Code or write provider configuration from renderer previews; project-root CLAUDE.md is only managed by confirmed/preflighted Claude project install.',
+    'VGX does not guarantee exact Claude Code configuration compatibility; this output is a neutral preview only.',
+];
+const _previewSafety = {
+    executesProvider: false,
+    writesProviderConfig: false,
+    installable: true,
+    previewOnly: true,
+};
+const claudeCapabilities = {
+    supportedAgentFields: ['name', 'description', 'instructions', 'mode', 'adapter model', 'adapter profile', 'permissions', 'memory', 'skills'],
+    skillInjectionModes: ['included as neutral skill identifiers in preview output'],
+    permissionCategories: ['included as registry permission metadata in preview output'],
+    memoryInjectionModes: ['included as registry memory metadata in preview output'],
+    delegationModel: 'registry agents and subagents are represented in preview output without executing Claude delegation',
+    lifecycleHooks: ['preview render/export only; confirmed install is handled by MCP install service'],
+    configFileLocations: ['rendered/claude/.../.mcp.json', 'rendered/claude/.../.claude/agents/*.md'],
+    limitations: [
+        'Preview artifacts only; does not execute Claude or Claude Code.',
+        'Does not install Claude Code or provider tooling.',
+        'Renderer preview does not write .claude/, CLAUDE.md, or provider configuration.',
+        'Confirmed apply writes only project .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block.',
+        'Claude Code compatibility can drift; validate with provider doctor after confirmed install.',
+    ],
+    render: {
+        format: 'claude-code-project-preview',
+        artifactContentTypes: ['application/json', 'text/markdown'],
+        installable: true,
+        previewOnly: true,
+    },
+};
+export class ClaudeAgentRenderer {
+    provider = 'claude';
+    capabilities = claudeCapabilities;
+    render(input) {
+        const agents = [input.agent, ...(input.subagents ?? [])];
+        const artifacts = [
+            {
+                relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/.mcp.json`,
+                contentType: 'application/json',
+                contents: `${JSON.stringify({ mcpServers: { vgxness: { type: 'stdio', command: 'vgxness', args: ['mcp', 'start'] } } }, null, 2)}\n`,
+            },
+        ];
+        const renderedKeys = new Set();
+        for (const agent of agents) {
+            const key = claudeAgentKey(agent.name);
+            if (renderedKeys.has(key))
+                return validationFailure(`Rendered Claude agent key collision: ${key}`);
+            renderedKeys.add(key);
+            artifacts.push({
+                relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/.claude/agents/${key}.md`,
+                contentType: 'text/markdown',
+                contents: renderClaudeAgentMarkdown(agent, key),
+            });
+        }
+        return ok({
+            provider: this.provider,
+            installable: true,
+            artifacts,
+            warnings: previewWarnings,
+        });
+    }
+}
+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=${canonicalPromptContractVersion} behaviorContractVersion=${canonicalBehaviorContractVersion} safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
+}
+function claudeAgentKey(value) {
+    return pathSegment(value);
+}
+function pathSegment(value) {
+    return (value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'unnamed');
+}

package/dist/{mcp → adapters/claude/install}/claude-code-agent-config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, parse, resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeCode } from '../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeCode } from '../../../agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
 export function expectedClaudeCodeAgentFiles(input) {
@@ -18,13 +18,28 @@ export function renderClaudeCodeAgentMarkdown(agent) {
 }
 export function inspectClaudeCodeAgents(input) {
     const target = typeof input === 'string' ? resolveClaudeAgentTarget({ workspaceRoot: input, scope: 'project' }) : resolveClaudeAgentTarget(input);
-    const expected = expectedClaudeCodeAgentFiles({ workspaceRoot: target.workspaceRoot, scope: target.scope, ...(target.env === undefined ? {} : { env: target.env }) });
-    return { scope: target.scope, directoryPath: target.directoryPath, directoryExists: existsSync(target.directoryPath), external: target.scope === 'user', agents: expected.map(inspectAgent) };
+    const expected = expectedClaudeCodeAgentFiles({
+        workspaceRoot: target.workspaceRoot,
+        scope: target.scope,
+        ...(target.env === undefined ? {} : { env: target.env }),
+    });
+    return {
+        scope: target.scope,
+        directoryPath: target.directoryPath,
+        directoryExists: existsSync(target.directoryPath),
+        external: target.scope === 'user',
+        agents: expected.map(inspectAgent),
+    };
 }
 export function resolveClaudeAgentTarget(input) {
     const scope = input.scope ?? 'project';
     if (scope === 'project')
-        return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(input.workspaceRoot, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
+        return {
+            workspaceRoot: input.workspaceRoot,
+            scope,
+            directoryPath: join(input.workspaceRoot, '.claude', 'agents'),
+            ...(input.env === undefined ? {} : { env: input.env }),
+        };
     const home = safeHomeDirectory(input.env);
     return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(home, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
 }
@@ -67,7 +82,15 @@ export function parseClaudeAgentFrontmatter(contents) {
 }
 function inspectAgent(agent) {
     if (!existsSync(agent.path))
-        return { agentName: agent.name, path: agent.path, exists: false, status: 'missing', frontmatter: 'missing', generatedMarker: false, detail: 'Expected Claude agent file is missing.' };
+        return {
+            agentName: agent.name,
+            path: agent.path,
+            exists: false,
+            status: 'missing',
+            frontmatter: 'missing',
+            generatedMarker: false,
+            detail: 'Expected Claude agent file is missing.',
+        };
     try {
         const contents = readFileSync(agent.path, 'utf8');
         const frontmatter = parseClaudeAgentFrontmatter(contents);
@@ -75,14 +98,46 @@ function inspectAgent(agent) {
         if (!frontmatter.ok)
             return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker, detail: frontmatter.reason };
         if (frontmatter.data.name !== agent.name)
-            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: `Frontmatter name ${frontmatter.data.name} does not match expected ${agent.name}.` };
+            return {
+                agentName: agent.name,
+                path: agent.path,
+                exists: true,
+                status: 'conflicting',
+                frontmatter: 'valid',
+                generatedMarker,
+                detail: `Frontmatter name ${frontmatter.data.name} does not match expected ${agent.name}.`,
+            };
         if (!generatedMarker)
-            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: 'Existing agent file is not marked as VGXNESS-generated.' };
-        return { agentName: agent.name, path: agent.path, exists: true, status: 'managed', frontmatter: 'valid', generatedMarker, detail: 'Claude agent file is VGXNESS-managed.' };
+            return {
+                agentName: agent.name,
+                path: agent.path,
+                exists: true,
+                status: 'conflicting',
+                frontmatter: 'valid',
+                generatedMarker,
+                detail: 'Existing agent file is not marked as VGXNESS-generated.',
+            };
+        return {
+            agentName: agent.name,
+            path: agent.path,
+            exists: true,
+            status: 'managed',
+            frontmatter: 'valid',
+            generatedMarker,
+            detail: 'Claude agent file is VGXNESS-managed.',
+        };
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
-        return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker: false, detail: `Unable to read Claude agent file: ${message}` };
+        return {
+            agentName: agent.name,
+            path: agent.path,
+            exists: true,
+            status: 'invalid',
+            frontmatter: 'invalid',
+            generatedMarker: false,
+            detail: `Unable to read Claude agent file: ${message}`,
+        };
     }
 }
 function yamlScalar(value) {

package/dist/{mcp → adapters/claude/install}/claude-code-config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { providerConfigPathDiagnostics } from './provider-health-types.js';
+import { providerConfigPathDiagnostics, } from '../../../application/provider-setup/provider-health-types.js';
 export function resolveClaudeCodeMcpJsonPath(workspaceRoot) {
     const target = resolve(workspaceRoot, '.mcp.json');
     assertInsideWorkspace(workspaceRoot, target);
@@ -19,7 +19,8 @@ export function isManagedClaudeArgs(value) {
     if (!Array.isArray(value) || !value.every((item) => typeof item === 'string'))
         return false;
     const dbPath = value[3];
-    return arraysEqual(value, ['mcp', 'start']) || (value.length === 4 && value[0] === 'mcp' && value[1] === 'start' && value[2] === '--db' && typeof dbPath === 'string' && dbPath.trim().length > 0);
+    return (arraysEqual(value, ['mcp', 'start']) ||
+        (value.length === 4 && value[0] === 'mcp' && value[1] === 'start' && value[2] === '--db' && typeof dbPath === 'string' && dbPath.trim().length > 0));
 }
 export function inspectClaudeCodeMcpConfig(workspaceRoot) {
     const path = resolveClaudeCodeMcpJsonPath(workspaceRoot);
@@ -34,10 +35,31 @@ export function inspectClaudeCodeMcpConfig(workspaceRoot) {
         }
         const entry = isRecord(parsed.mcpServers) ? parsed.mcpServers.vgxness : undefined;
         if (entry === undefined)
-            return { status: 'stale', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json is readable but mcpServers.vgxness is missing.' };
+            return {
+                status: 'stale',
+                path,
+                exists: true,
+                parsed: true,
+                config: parsed,
+                message: 'Claude project .mcp.json is readable but mcpServers.vgxness is missing.',
+            };
         if (isManagedClaudeCodeMcpServer(entry))
-            return { status: 'configured', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a managed mcpServers.vgxness entry.' };
-        return { status: 'conflicting', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a conflicting mcpServers.vgxness entry.' };
+            return {
+                status: 'configured',
+                path,
+                exists: true,
+                parsed: true,
+                config: parsed,
+                message: 'Claude project .mcp.json has a managed mcpServers.vgxness entry.',
+            };
+        return {
+            status: 'conflicting',
+            path,
+            exists: true,
+            parsed: true,
+            config: parsed,
+            message: 'Claude project .mcp.json has a conflicting mcpServers.vgxness entry.',
+        };
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
@@ -72,7 +94,7 @@ export function assertInsideWorkspace(workspaceRoot, targetPath) {
     const root = resolve(workspaceRoot);
     const target = resolve(targetPath);
     const rel = relative(root, target);
-    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || rel === '' && target !== root)
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || (rel === '' && target !== root))
         throw new Error(`Target path is outside workspace root: ${targetPath}`);
 }
 export function claudeAdvisoryPaths(workspaceRoot) {

package/dist/{mcp → adapters/claude/install}/claude-code-project-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
 export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
@@ -47,7 +47,15 @@ export function inspectClaudeProjectMemory(workspaceRoot) {
     const beginCount = countOccurrences(contents, claudeProjectMemoryBeginMarker);
     const endCount = countOccurrences(contents, claudeProjectMemoryEndMarker);
     if (beginCount === 0 && endCount === 0)
-        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude project memory exists without a VGXNESS managed block; future apply would append one after backup.', contents };
+        return {
+            status: 'unmanaged',
+            path,
+            exists: true,
+            action: 'append-managed-block',
+            backupRequired: true,
+            message: 'Claude project memory exists without a VGXNESS managed block; future apply would append one after backup.',
+            contents,
+        };
     if (beginCount === 0)
         return blocked(path, true, 'missing_begin_marker', 'Claude project memory has an end marker without a begin marker.');
     if (endCount === 0)
@@ -71,8 +79,27 @@ export function inspectClaudeProjectMemory(workspaceRoot) {
     const expected = renderClaudeProjectMemoryBlock();
     const actual = contents.slice(start, end);
     if (actual === expected)
-        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude project memory has the current VGXNESS managed block.', blockRange: { start, end }, contents };
-    return { status: 'managed-stale', path, exists: true, action: 'update-managed-block', backupRequired: true, message: 'Claude project memory has a stale VGXNESS managed block; future apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+        return {
+            status: 'managed-current',
+            path,
+            exists: true,
+            action: 'none',
+            backupRequired: false,
+            message: 'Claude project memory has the current VGXNESS managed block.',
+            blockRange: { start, end },
+            contents,
+        };
+    return {
+        status: 'managed-stale',
+        path,
+        exists: true,
+        action: 'update-managed-block',
+        backupRequired: true,
+        message: 'Claude project memory has a stale VGXNESS managed block; future apply would update only that block after backup.',
+        blockRange: { start, end },
+        staleReasons: ['managed_block_differs_from_canonical_render'],
+        contents,
+    };
 }
 export function mergeClaudeProjectMemory(state) {
     const block = renderClaudeProjectMemoryBlock();
@@ -83,7 +110,10 @@ export function mergeClaudeProjectMemory(state) {
         return { ok: true, value: { path: state.path, contents: `${state.contents}${separator}${block}\n` } };
     }
     if (state.status === 'managed-stale')
-        return { ok: true, value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) } };
+        return {
+            ok: true,
+            value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) },
+        };
     if (state.status === 'managed-current')
         return { ok: true, value: { path: state.path, contents: state.contents } };
     return { ok: false, error: { code: 'validation_failed', message: state.message } };

package/dist/{mcp → adapters/claude/install}/claude-code-scope.js

@@ -1,17 +1,26 @@
 export const claudeCodeCanonicalScopes = ['local', 'project', 'user'];
 export function resolveClaudeCodeScope(input, fallback = 'project') {
     if (input !== undefined && input.trim().length === 0)
-        return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+        return {
+            ok: false,
+            error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' },
+        };
     const raw = input?.trim() || fallback;
     if (raw === 'local' || raw === 'project' || raw === 'user')
         return { ok: true, value: { canonical: raw, input: raw, warnings: [] } };
     if (raw === 'personal') {
-        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code scope `personal` is accepted for VGXNESS compatibility and maps to Claude `user`.'] } };
+        return {
+            ok: true,
+            value: { canonical: 'user', input: raw, warnings: ['Claude Code scope `personal` is accepted for VGXNESS compatibility and maps to Claude `user`.'] },
+        };
     }
     if (raw === 'global') {
         return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code legacy scope `global` is deprecated and maps to Claude `user`.'] } };
     }
-    return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+    return {
+        ok: false,
+        error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' },
+    };
 }
 export function isClaudeCodeUserScope(scope) {
     return scope === 'user';

package/dist/{mcp → adapters/claude/install}/claude-code-user-config.js

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { providerConfigPathDiagnostics } from './provider-health-types.js';
-import { isManagedClaudeCodeMcpServer } from './claude-code-config.js';
+import { providerConfigPathDiagnostics, } from '../../../application/provider-setup/provider-health-types.js';
 import { safeHomeDirectory } from './claude-code-agent-config.js';
+import { isManagedClaudeCodeMcpServer } from './claude-code-config.js';
 export function resolveClaudeCodeUserMcpJsonPath(env = process.env) {
     return join(safeHomeDirectory(env), '.claude.json');
 }
@@ -18,10 +18,31 @@ export function inspectClaudeCodeUserMcpConfig(env = process.env) {
             return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude user ~/.claude.json mcpServers must be a JSON object.' };
         const entry = isRecord(parsed.mcpServers) ? parsed.mcpServers.vgxness : undefined;
         if (entry === undefined)
-            return { status: 'stale', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json is readable but mcpServers.vgxness is missing.' };
+            return {
+                status: 'stale',
+                path,
+                exists: true,
+                parsed: true,
+                config: parsed,
+                message: 'Claude user ~/.claude.json is readable but mcpServers.vgxness is missing.',
+            };
         if (isManagedClaudeCodeMcpServer(entry))
-            return { status: 'configured', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json has a managed mcpServers.vgxness entry.' };
-        return { status: 'conflicting', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json has a conflicting mcpServers.vgxness entry.' };
+            return {
+                status: 'configured',
+                path,
+                exists: true,
+                parsed: true,
+                config: parsed,
+                message: 'Claude user ~/.claude.json has a managed mcpServers.vgxness entry.',
+            };
+        return {
+            status: 'conflicting',
+            path,
+            exists: true,
+            parsed: true,
+            config: parsed,
+            message: 'Claude user ~/.claude.json has a conflicting mcpServers.vgxness entry.',
+        };
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);

package/dist/{mcp → adapters/claude/install}/claude-code-user-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
 import { safeHomeDirectory } from './claude-code-agent-config.js';
 export const claudeUserMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE USER MEMORY -->';
 export const claudeUserMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE USER MEMORY -->';
@@ -25,7 +25,14 @@ export function renderClaudeUserMemoryBlock() {
 export function inspectClaudeUserMemory(env = process.env) {
     const path = resolveClaudeUserMemoryPath(env);
     if (!existsSync(path))
-        return { status: 'missing', path, exists: false, action: 'create', backupRequired: false, message: 'Claude user memory ~/.claude/CLAUDE.md does not exist.' };
+        return {
+            status: 'missing',
+            path,
+            exists: false,
+            action: 'create',
+            backupRequired: false,
+            message: 'Claude user memory ~/.claude/CLAUDE.md does not exist.',
+        };
     let contents;
     try {
         const bytes = readFileSync(path);
@@ -39,7 +46,15 @@ export function inspectClaudeUserMemory(env = process.env) {
     const beginCount = countOccurrences(contents, claudeUserMemoryBeginMarker);
     const endCount = countOccurrences(contents, claudeUserMemoryEndMarker);
     if (beginCount === 0 && endCount === 0)
-        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude user memory exists without a VGXNESS managed block; apply would append one after backup.', contents };
+        return {
+            status: 'unmanaged',
+            path,
+            exists: true,
+            action: 'append-managed-block',
+            backupRequired: true,
+            message: 'Claude user memory exists without a VGXNESS managed block; apply would append one after backup.',
+            contents,
+        };
     if (beginCount === 0)
         return blocked(path, true, 'missing_begin_marker', 'Claude user memory has an end marker without a begin marker.');
     if (endCount === 0)
@@ -54,13 +69,35 @@ export function inspectClaudeUserMemory(env = process.env) {
     const inner = contents.slice(start + claudeUserMemoryBeginMarker.length, endMarkerStart);
     if (inner.includes(claudeUserMemoryBeginMarker) || inner.includes(claudeUserMemoryEndMarker))
         return blocked(path, true, 'nested_markers', 'Claude user memory has nested VGXNESS managed-block markers.');
-    if (!inner.includes('owner=vgxness') || !inner.includes('provider=claude') || !inner.includes('artifact=claude-user-memory') || !inner.includes('safe-update=true'))
+    if (!inner.includes('owner=vgxness') ||
+        !inner.includes('provider=claude') ||
+        !inner.includes('artifact=claude-user-memory') ||
+        !inner.includes('safe-update=true'))
         return blocked(path, true, 'conflicting_ownership', 'Claude user memory managed block is not a VGXNESS-owned user-memory block.');
     const expected = renderClaudeUserMemoryBlock();
     const actual = contents.slice(start, end);
     if (actual === expected)
-        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude user memory has the current VGXNESS managed block.', blockRange: { start, end }, contents };
-    return { status: 'managed-stale', path, exists: true, action: 'update-managed-block', backupRequired: true, message: 'Claude user memory has a stale VGXNESS managed block; apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+        return {
+            status: 'managed-current',
+            path,
+            exists: true,
+            action: 'none',
+            backupRequired: false,
+            message: 'Claude user memory has the current VGXNESS managed block.',
+            blockRange: { start, end },
+            contents,
+        };
+    return {
+        status: 'managed-stale',
+        path,
+        exists: true,
+        action: 'update-managed-block',
+        backupRequired: true,
+        message: 'Claude user memory has a stale VGXNESS managed block; apply would update only that block after backup.',
+        blockRange: { start, end },
+        staleReasons: ['managed_block_differs_from_canonical_render'],
+        contents,
+    };
 }
 export function mergeClaudeUserMemory(state) {
     const block = renderClaudeUserMemoryBlock();
@@ -71,7 +108,10 @@ export function mergeClaudeUserMemory(state) {
         return { ok: true, value: { path: state.path, contents: `${state.contents}${separator}${block}\n` } };
     }
     if (state.status === 'managed-stale')
-        return { ok: true, value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) } };
+        return {
+            ok: true,
+            value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) },
+        };
     if (state.status === 'managed-current')
         return { ok: true, value: { path: state.path, contents: state.contents } };
     return { ok: false, error: { code: 'validation_failed', message: state.message } };

package/dist/{mcp → adapters/claude/install}/client-install-claude-code-contract.js

@@ -1,4 +1,4 @@
-import { withEffectiveManagerInstructions } from '../agents/canonical-agent-projection.js';
+import { withEffectiveManagerInstructions } from '../../../agents/canonical-agent-projection.js';
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
 import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig } from './claude-code-config.js';
@@ -58,23 +58,53 @@ function planUserInstall(input, server, overwriteVgxness, cliCommand, scopeWarni
         else if (agent.status === 'managed')
             targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'user', external: true, action: 'update-vgxness' });
         else
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'user', external: true, action: 'blocked', reason: agent.detail });
+            targets.push({
+                kind: 'agent-file',
+                path: agent.path,
+                agentName: agent.agentName,
+                scope: 'user',
+                external: true,
+                action: 'blocked',
+                reason: agent.detail,
+            });
     }
     const userMemory = inspectClaudeUserMemory(input.env);
-    targets.push({ kind: 'user-memory', path: userMemory.path, external: true, action: userMemory.action, status: userMemory.status, backupRequired: userMemory.backupRequired, ...(userMemory.status === 'blocked' ? { reason: userMemory.message } : {}) });
+    targets.push({
+        kind: 'user-memory',
+        path: userMemory.path,
+        external: true,
+        action: userMemory.action,
+        status: userMemory.status,
+        backupRequired: userMemory.backupRequired,
+        ...(userMemory.status === 'blocked' ? { reason: userMemory.message } : {}),
+    });
     const blocked = targets.find((target) => target.action === 'blocked');
     if (blocked !== undefined) {
-        const reason = blocked.kind === 'user-mcp-json' ? userMcpRefusalReason(mcpState.status) : blocked.kind === 'user-memory' ? userMemoryRefusalReason(userMemory) : 'existing_vgxness_agent';
+        const reason = blocked.kind === 'user-mcp-json'
+            ? userMcpRefusalReason(mcpState.status)
+            : blocked.kind === 'user-memory'
+                ? userMemoryRefusalReason(userMemory)
+                : 'existing_vgxness_agent';
         return refused(input, server, reason, blocked.reason ?? 'Claude user install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
     }
-    const backupRequired = targets.some((target) => (target.kind === 'user-mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'user-memory' && target.backupRequired));
-    return { ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, 'user', cliCommand, scopeWarnings), status: 'would_install' };
+    const backupRequired = targets.some((target) => (target.kind === 'user-mcp-json' && target.action !== 'create') ||
+        (target.kind === 'agent-file' && target.action === 'update-vgxness') ||
+        (target.kind === 'user-memory' && target.backupRequired));
+    return {
+        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, 'user', cliCommand, scopeWarnings),
+        status: 'would_install',
+    };
 }
 function refused(input, server, reason, message, targets, preservedTopLevelKeys, overwriteVgxness) {
     const resolved = resolveClaudeCodeScope(input.scope, 'user');
     const canonical = resolved.ok ? resolved.value.canonical : 'user';
     const cli = canonical === 'user' ? buildClaudeCodeMcpAddCommand({ scope: canonical }) : undefined;
-    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli?.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
+    return {
+        ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli?.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []),
+        status: 'refused',
+        reason,
+        message,
+    };
 }
 function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
     const source = input.databasePathSource ?? 'flag';
@@ -89,7 +119,14 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
         targetPath,
         targets,
         backupRequired,
-        safety: { operation: 'plan', mutating: false, writesProviderConfig: false, targetPath, backupRequired, mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create' },
+        safety: {
+            operation: 'plan',
+            mutating: false,
+            writesProviderConfig: false,
+            targetPath,
+            backupRequired,
+            mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create',
+        },
         warnings: [
             ...scopeWarnings,
             'Claude Code MCP registration is modeled as structured config/argv, never shell strings.',