vgxness 1.9.1 → 1.9.2

package/README.md

@@ -8,6 +8,8 @@ This package is proprietary software. The npm package ships inspectable JavaScri
 
 OpenCode is the primary supported provider. Other providers remain preview/manual only. Provider config writes require explicit CLI confirmation.
 
+VGXNESS v1.9.1 has a canonical project health audit with validated evidence: 38 MCP tools, 106 test files, and the official Bun validation path passing, including package evidence with `releaseReadiness: pass`. See [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md) for the versioned matrix and safety taxonomy.
+
 ## Requirements
 
 - Bun >= 1.3.14 for the installed `vgxness`/`vgx` CLI/MCP runtime and repository verification
@@ -25,6 +27,7 @@ bun install --frozen-lockfile
 bun run check:bun-lock
 bun run verify:typecheck
 bun run verify:test
+bun run verify:test:bun-storage
 bun run verify:bun-sqlite
 bun run verify:package
 bun run package:bun:evidence -- --require-pass
@@ -86,7 +89,7 @@ Release-candidate checklist, still non-publishing:
 
 1. `bun install --frozen-lockfile` completes on a clean checkout.
 2. `bun run check:bun-lock` passes.
-3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+3. `bun run verify:typecheck`, `bun run verify:test`, `bun run verify:test:bun-storage`, and `bun run verify:bun-sqlite` pass.
 4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
 5. JSON evidence shows `status: pass`, artifact/install smoke pass, no retired bridge scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
 6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
@@ -156,7 +159,7 @@ Apply only after reviewing the plan:
 vgxness setup apply --yes
 ```
 
-`vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, and `vgxness sdd accept-artifact` are also human-readable by default. Pass `--json` when you need parseable automation output. `vgxness setup apply --yes` is the explicit provider-config write path.
+`vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when a command needs the selected SQLite store. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, and `vgxness sdd accept-artifact` are also human-readable by default. Pass `--json` when you need parseable automation output. `vgxness setup apply --yes` is the explicit provider-config write path.
 
 ## Code runtime (`vgxness code`)
 
@@ -173,7 +176,7 @@ Edits, shell, network, git mutations, SDD persistence, and memory saves route th
 
 ## Safety model
 
-- Preview, status, and plan commands are read-only.
+- Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
 - Provider config writes require explicit `--yes` confirmation.
 - Setup/status TUI surfaces are preview-oriented; run copied commands explicitly when you choose to act.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
@@ -236,6 +239,7 @@ bun install --frozen-lockfile
 bun run check:bun-lock
 bun run verify:typecheck
 bun run verify:test
+bun run verify:test:bun-storage
 bun run verify:bun-sqlite
 bun run package:bun:evidence -- --require-pass
 ```
@@ -255,6 +259,7 @@ Remove any OpenCode config entries and local/global VGXNESS data manually if you
 ## More docs
 
 - [CLI reference](./docs/cli.md)
+- [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md)
 - [Architecture](./docs/architecture.md)
 - [Code runtime](./docs/code-runtime.md)
 - [MCP tools](./docs/mcp.md)

package/dist/agents/agent-activation-service.js

@@ -98,14 +98,23 @@ export class AgentActivationService {
         return this.dependencies.agents.getAgentByName(input.project, input.scope, defaultAgentName);
     }
     failAfterRun(runId, code, message) {
-        this.dependencies.runs.appendEvent({
+        const nestedFailures = [];
+        const eventResult = this.dependencies.runs.appendEvent({
             runId,
             kind: 'timeline',
             title: 'Agent activation failed',
-            payload: { error: { code: String(code), message }, nextSafeActionReturned: false },
+            payload: toJson({ error: { code: String(code), message }, nextSafeActionReturned: false }),
         });
-        this.dependencies.runs.updateFinalStatus({ runId, status: 'failed', outcome: 'failure', outcomeReason: message });
-        return { ok: false, error: { code, message } };
+        if (!eventResult.ok) {
+            nestedFailures.push({ step: 'append-event', code: String(eventResult.error.code), message: eventResult.error.message });
+        }
+        const finalStatusResult = this.dependencies.runs.updateFinalStatus({ runId, status: 'failed', outcome: 'failure', outcomeReason: message });
+        if (!finalStatusResult.ok) {
+            nestedFailures.push({ step: 'update-final-status', code: String(finalStatusResult.error.code), message: finalStatusResult.error.message });
+        }
+        return nestedFailures.length === 0
+            ? { ok: false, error: { code, message } }
+            : { ok: false, error: { code, message, cause: { nestedFailures } } };
     }
 }
 function validateActivationInput(input) {

package/dist/agents/agent-registry-service.js

@@ -32,8 +32,14 @@ export class AgentRegistryService {
         this.database.close();
     }
     listAgentDefinitions(input) {
-        void input;
-        const summaries = this.agents.list();
+        const filters = {};
+        if (input.project !== undefined)
+            filters.project = input.project;
+        if (input.scope !== undefined)
+            filters.scope = input.scope;
+        if (input.mode !== undefined)
+            filters.mode = input.mode;
+        const summaries = this.agents.list(filters);
         if (!summaries.ok)
             return summaries;
         const definitions = [];

package/dist/agents/agent-seed-upgrade-service.js

@@ -0,0 +1,231 @@
+import { canonicalAgentManifest, canonicalPromptContractVersion, canonicalSddSubagentNames } from './canonical-agent-manifest.js';
+import { projectCanonicalAgentManifestToSeed } from './canonical-agent-projection.js';
+export class AgentSeedUpgradeService {
+    agents;
+    history;
+    database;
+    constructor(dependencies) {
+        this.agents = dependencies.agents;
+        this.history = dependencies.history;
+        this.database = dependencies.database;
+    }
+    upgrade(input) {
+        if (!input.project.trim())
+            return validationFailure('Agent seed upgrade project is required');
+        if (input.scope !== 'project' && input.scope !== 'personal')
+            return validationFailure('Agent seed upgrade scope is invalid');
+        const seed = projectCanonicalAgentManifestToSeed();
+        const canonicalByName = new Map();
+        for (const agent of seed.agents)
+            canonicalByName.set(agent.name, agent);
+        for (const subagent of seed.subagents)
+            canonicalByName.set(subagent.name, subagent);
+        const source = input.source ?? 'boot-upgrade';
+        const summary = {
+            created: [],
+            upgraded: [],
+            noop: [],
+            overwritten: [],
+            errors: [],
+            skipped: false,
+        };
+        const expected = canonicalPromptContractVersion;
+        const transaction = this.database.transaction(() => {
+            for (const [name, definition] of canonicalByName) {
+                const outcome = this.upgradeOne(input.project, input.scope, name, definition, source, expected);
+                if (outcome.ok) {
+                    switch (outcome.value.outcome) {
+                        case 'created':
+                            summary.created.push(name);
+                            break;
+                        case 'upgraded':
+                            summary.upgraded.push(name);
+                            break;
+                        case 'overwrote-custom-instructions':
+                            summary.overwritten.push(name);
+                            break;
+                        case 'noop':
+                            summary.noop.push(name);
+                            break;
+                    }
+                }
+                else {
+                    const failureOutcome = outcome.error.code === 'validation_failed' ? 'validation_failed' : 'db_error';
+                    summary.errors.push({ agentName: name, outcome: failureOutcome, reason: outcome.error.message });
+                }
+            }
+            return summary;
+        });
+        if (!transaction.ok) {
+            return { ok: false, error: transaction.error };
+        }
+        return transaction;
+    }
+    hasDrift(input) {
+        const expected = input.expectedVersion ?? canonicalPromptContractVersion;
+        try {
+            const canonicalNames = [canonicalAgentManifest.defaultAgentName, ...canonicalSddSubagentNames];
+            const placeholders = canonicalNames.map(() => '?').join(', ');
+            const row = this.database.connection
+                .prepare(`
+        SELECT COUNT(*) AS stale_count
+        FROM agents
+        WHERE project = ? AND scope = ? AND name IN (${placeholders})
+          AND json_extract(adapters_json, '$.opencode.config.options.vgxnessPromptContractVersion') <> ?
+      `)
+                .get(input.project, input.scope, ...canonicalNames, expected);
+            return ok((row?.stale_count ?? 0) > 0);
+        }
+        catch (cause) {
+            return fail('Failed to detect agent seed drift', cause);
+        }
+    }
+    upgradeOne(project, scope, name, definition, source, expected) {
+        const existing = this.agents.getByName(project, scope, name);
+        const fromVersion = existing.ok ? readPromptContractVersion(existing.value) : null;
+        if (existing.ok && fromVersion === expected && isByteEqualToCanonical(existing.value, definition)) {
+            return ok({ outcome: 'noop', fromVersion: expected });
+        }
+        const parentAgentId = 'parentAgentName' in definition ? this.resolveParentId(project, scope, definition.parentAgentName) : undefined;
+        if ('parentAgentName' in definition && parentAgentId === undefined) {
+            return validationFailure(`Unresolved parentAgentName: ${definition.parentAgentName}`);
+        }
+        const registerInput = toRegisterInput(project, scope, definition, parentAgentId);
+        const registered = this.agents.register(registerInput);
+        if (!registered.ok) {
+            this.appendHistory({
+                project,
+                scope,
+                agentName: name,
+                fromVersion,
+                toVersion: expected,
+                outcome: registered.error.code === 'validation_failed' ? 'validation_failed' : 'db_error',
+                reason: registered.error.message,
+                source,
+            });
+            return registered;
+        }
+        let outcome;
+        if (!existing.ok) {
+            outcome = 'created';
+        }
+        else if (fromVersion !== null && fromVersion !== expected) {
+            outcome = 'upgraded';
+        }
+        else {
+            outcome = 'overwrote-custom-instructions';
+        }
+        this.appendHistory({
+            project,
+            scope,
+            agentName: name,
+            fromVersion,
+            toVersion: expected,
+            outcome,
+            reason: outcomeReason(outcome, fromVersion, expected, existing.ok),
+            source,
+        });
+        return ok({ outcome, fromVersion });
+    }
+    resolveParentId(project, scope, parentAgentName) {
+        const parent = this.agents.getByName(project, scope, parentAgentName);
+        if (!parent.ok || parent.value.mode !== 'agent')
+            return undefined;
+        return parent.value.id;
+    }
+    appendHistory(input) {
+        this.history.append({
+            project: input.project,
+            scope: input.scope,
+            agentName: input.agentName,
+            fromVersion: input.fromVersion,
+            toVersion: input.toVersion,
+            outcome: input.outcome,
+            reason: input.reason,
+            source: input.source,
+        });
+    }
+}
+function toRegisterInput(project, scope, definition, parentAgentId) {
+    const input = {
+        project,
+        scope,
+        mode: 'parentAgentName' in definition ? 'subagent' : 'agent',
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+    };
+    if (definition.capabilities !== undefined)
+        input.capabilities = definition.capabilities;
+    if (definition.permissions !== undefined)
+        input.permissions = definition.permissions;
+    if (definition.memory !== undefined)
+        input.memory = definition.memory;
+    if (definition.workflows !== undefined)
+        input.workflows = definition.workflows;
+    if (definition.skills !== undefined)
+        input.skills = definition.skills;
+    if (definition.adapters !== undefined)
+        input.adapters = definition.adapters;
+    if (parentAgentId !== undefined)
+        input.parentAgentId = parentAgentId;
+    return input;
+}
+function isByteEqualToCanonical(existing, definition) {
+    if (existing.description !== definition.description)
+        return false;
+    if (existing.instructions.value !== definition.instructions.value)
+        return false;
+    if (!adaptersEqual(existing.adapters, definition.adapters ?? {}))
+        return false;
+    if (!arraysEqual(existing.capabilities, definition.capabilities ?? []))
+        return false;
+    if (!arraysEqual(existing.workflows, definition.workflows ?? []))
+        return false;
+    if (!arraysEqual(existing.skills, definition.skills ?? []))
+        return false;
+    return true;
+}
+function adaptersEqual(a, b) {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function readPromptContractVersion(agent) {
+    const opencode = agent.adapters?.opencode;
+    if (opencode === undefined)
+        return null;
+    const options = opencode.config?.options;
+    const value = options?.vgxnessPromptContractVersion;
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return null;
+    return value;
+}
+function outcomeReason(outcome, fromVersion, toVersion, existed) {
+    if (outcome === 'created')
+        return `created canonical row at v${toVersion}`;
+    if (outcome === 'upgraded')
+        return `upgraded v${fromVersion ?? 'unknown'} -> v${toVersion}`;
+    if (outcome === 'overwrote-custom-instructions')
+        return `overwrote customized row (was v${fromVersion ?? 'unknown'}) with v${toVersion} canonical`;
+    return existed ? `noop at v${toVersion}` : `noop at v${toVersion}`;
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+function fail(message, cause) {
+    const error = { code: 'validation_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}

package/dist/agents/boot-upgrade.js

@@ -0,0 +1,59 @@
+import { AgentSeedUpgradeService } from './agent-seed-upgrade-service.js';
+import { AgentRepository } from './repositories/agents.js';
+import { AgentSeedHistoryRepository } from './repositories/agent-seed-history.js';
+import { canonicalAgentManifest } from './canonical-agent-manifest.js';
+const skipEnvVar = 'VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE';
+export function runBootAgentSeedUpgrade(database, env = process.env, project = canonicalAgentManifest.project, scope = canonicalAgentManifest.scope) {
+    if (isOptOut(env)) {
+        return { ok: true, skipped: true, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 0 };
+    }
+    try {
+        const service = new AgentSeedUpgradeService({
+            agents: new AgentRepository(database),
+            history: new AgentSeedHistoryRepository(database),
+            database,
+        });
+        const result = service.upgrade({ project, scope, source: 'boot-upgrade' });
+        if (!result.ok) {
+            const message = `boot-upgrade failed: ${result.error.message} (code=${result.error.code})`;
+            process.stderr.write(`[vgxness] ${message}\n`);
+            return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+        }
+        const value = result.value;
+        const touched = value.created.length + value.upgraded.length + value.overwritten.length + value.errors.length;
+        if (touched > 0) {
+            const parts = [];
+            if (value.created.length > 0)
+                parts.push(`created ${value.created.length}`);
+            if (value.upgraded.length > 0)
+                parts.push(`upgraded ${value.upgraded.length}`);
+            if (value.overwritten.length > 0)
+                parts.push(`overwrote ${value.overwritten.length}`);
+            if (value.errors.length > 0)
+                parts.push(`errors ${value.errors.length}`);
+            process.stderr.write(`[vgxness] boot-upgrade: ${parts.join(', ')}\n`);
+            for (const error of value.errors) {
+                process.stderr.write(`[vgxness] boot-upgrade: ${error.agentName} ${error.outcome}: ${error.reason}\n`);
+            }
+        }
+        return {
+            ok: true,
+            skipped: false,
+            created: value.created.length,
+            upgraded: value.upgraded.length,
+            overwritten: value.overwritten.length,
+            noop: value.noop.length,
+            errors: value.errors.length,
+        };
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+        const message = `boot-upgrade threw: ${detail}`;
+        process.stderr.write(`[vgxness] ${message}\n`);
+        return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+    }
+}
+function isOptOut(env) {
+    const value = env[skipEnvVar];
+    return value === '1' || value === 'true';
+}

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

@@ -73,6 +73,13 @@ export function projectCanonicalAgentManifestToClaudeCode(manifest = canonicalAg
     }
     return { defaultAgent: canonicalDefaultAgentName, agents };
 }
+export function withEffectiveManagerInstructions(projection, instructions) {
+    const trimmed = instructions?.trim() ?? '';
+    if (trimmed === '')
+        return projection;
+    const agents = projection.agents.map((agent) => agent.canonicalName === projection.defaultAgent ? { ...agent, instructions: trimmed } : agent);
+    return { defaultAgent: projection.defaultAgent, agents };
+}
 export function projectCanonicalAgentManifestToClaudeProjectMemory(manifest = canonicalAgentManifest) {
     assertValidCanonicalManifest(manifest);
     return {

package/dist/agents/manager-profile-overlay-service.js

@@ -1,3 +1,5 @@
+import { AgentRegistryService } from './agent-registry-service.js';
+import { ManagerProfileOverlayRepository } from './repositories/manager-profile-overlays.js';
 export class ManagerProfileOverlayService {
     dependencies;
     constructor(dependencies) {
@@ -36,3 +38,15 @@ function ok(value) {
 function validationFailure(message) {
     return { ok: false, error: { code: 'validation_failed', message } };
 }
+export function computeEffectiveManagerInstructions(database, project = 'vgxness', scope = 'project', managerName = 'vgxness-manager') {
+    const registry = new AgentRegistryService(database);
+    const overlays = new ManagerProfileOverlayRepository(database);
+    const service = new ManagerProfileOverlayService({ agents: registry, overlays });
+    const resolved = service.resolveEffectiveManager({ project, scope, managerName });
+    if (!resolved.ok || resolved.value.overlay === undefined)
+        return undefined;
+    const overlayInstructions = resolved.value.overlay.instructions.trim();
+    if (overlayInstructions === '')
+        return undefined;
+    return overlayInstructions;
+}

package/dist/agents/repositories/agent-seed-history.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+export class AgentSeedHistoryRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    append(input) {
+        const validation = validate(input);
+        if (!validation.ok)
+            return validation;
+        try {
+            const id = randomUUID();
+            const appliedAt = new Date().toISOString();
+            this.db.connection
+                .prepare(`
+        INSERT INTO agent_seed_history(id, applied_at, from_version, to_version, agent_name, project, scope, outcome, reason, source)
+        VALUES (@id, @appliedAt, @fromVersion, @toVersion, @agentName, @project, @scope, @outcome, @reason, @source)
+      `)
+                .run({
+                id,
+                appliedAt,
+                fromVersion: input.fromVersion,
+                toVersion: input.toVersion,
+                agentName: input.agentName,
+                project: input.project,
+                scope: input.scope,
+                outcome: input.outcome,
+                reason: input.reason ?? null,
+                source: input.source,
+            });
+            const entry = {
+                id,
+                appliedAt,
+                fromVersion: input.fromVersion,
+                toVersion: input.toVersion,
+                agentName: input.agentName,
+                project: input.project,
+                scope: input.scope,
+                outcome: input.outcome,
+                reason: input.reason ?? null,
+                source: input.source,
+            };
+            return ok(entry);
+        }
+        catch (cause) {
+            return fail('Failed to append agent_seed_history entry', cause);
+        }
+    }
+    listRecent(filters = {}) {
+        try {
+            const where = [];
+            const parameters = {};
+            for (const [key, column] of [
+                ['project', 'project'],
+                ['scope', 'scope'],
+                ['agentName', 'agent_name'],
+            ]) {
+                const value = filters[key];
+                if (value !== undefined) {
+                    where.push(`${column}=@${key}`);
+                    parameters[key] = value;
+                }
+            }
+            const limit = Math.max(1, Math.min(filters.limit ?? 100, 1000));
+            const rows = this.db.connection
+                .prepare(`
+        SELECT * FROM agent_seed_history
+        ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+        ORDER BY applied_at DESC
+        LIMIT ${limit}
+      `)
+                .all(parameters);
+            return ok(rows.map(map));
+        }
+        catch (cause) {
+            return fail('Failed to list agent_seed_history entries', cause);
+        }
+    }
+}
+function validate(input) {
+    if (!input.project.trim())
+        return validationFailure('agent_seed_history project is required');
+    if (input.scope !== 'project' && input.scope !== 'personal')
+        return validationFailure('agent_seed_history scope is invalid');
+    if (!input.agentName.trim())
+        return validationFailure('agent_seed_history agentName is required');
+    if (!Number.isInteger(input.toVersion) || input.toVersion <= 0)
+        return validationFailure('agent_seed_history toVersion must be a positive integer');
+    if (input.fromVersion !== null && (!Number.isInteger(input.fromVersion) || input.fromVersion < 0))
+        return validationFailure('agent_seed_history fromVersion must be null or non-negative integer');
+    if (!input.source.trim())
+        return validationFailure('agent_seed_history source is required');
+    if (input.outcome !== 'created' &&
+        input.outcome !== 'upgraded' &&
+        input.outcome !== 'noop' &&
+        input.outcome !== 'overwrote-custom-instructions' &&
+        input.outcome !== 'validation_failed' &&
+        input.outcome !== 'db_error') {
+        return validationFailure(`agent_seed_history outcome is invalid: ${input.outcome}`);
+    }
+    return ok(undefined);
+}
+function map(row) {
+    return {
+        id: String(row.id),
+        appliedAt: String(row.applied_at),
+        fromVersion: row.from_version === null || row.from_version === undefined ? null : Number(row.from_version),
+        toVersion: Number(row.to_version),
+        agentName: String(row.agent_name),
+        project: String(row.project),
+        scope: row.scope,
+        outcome: String(row.outcome),
+        reason: row.reason === null || row.reason === undefined ? null : String(row.reason),
+        source: String(row.source),
+    };
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+function fail(message, cause) {
+    const error = { code: 'validation_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}

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

@@ -6,7 +6,9 @@ import { createMcpClientSetupPreview, isMcpClientSetupProvider } from '../../mcp
 import { createMcpDoctorReport } from '../../mcp/doctor.js';
 import { createOpenCodeMcpVisibilityReport } from '../../mcp/opencode-visibility.js';
 import { resolveClaudeCodeScope } from '../../mcp/claude-code-scope.js';
+import { computeEffectiveManagerInstructions } from '../../agents/manager-profile-overlay-service.js';
 import { RunService } from '../../runs/run-service.js';
+import { isTerminalRunStatus } from '../../runs/schema.js';
 import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag } from '../cli-flags.js';
 import { usageFailure, validationFailure } from '../cli-help.js';
 import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
@@ -42,6 +44,7 @@ export function runMcpInstallCommand(parsed, environment) {
                 return resultFailure(opened);
             try {
                 const preflight = createClaudeCodeInstallPreflight(parsed, opened.value, environment);
+                const effectiveManagerInstructions = computeEffectiveManagerInstructions(opened.value);
                 const result = await installClaudeCodeMcpClient({
                     cwd: environment.cwd,
                     databasePath: databasePath.value.path,
@@ -50,6 +53,7 @@ export function runMcpInstallCommand(parsed, environment) {
                     overwriteVgxness,
                     scope: claudeScope.value,
                     preflight,
+                    ...(effectiveManagerInstructions === undefined ? {} : { effectiveManagerInstructions }),
                 });
                 return result.status === 'installed' ? jsonResult({ ok: true, value: result }) : resultFailure({ ok: false, error: { code: 'validation_failed', message: `${result.reason}: ${result.message}` } });
             }
@@ -107,6 +111,9 @@ function createClaudeCodeInstallPreflight(parsed, database, environment) {
         const details = service.getRun(runId);
         if (!details.ok)
             return details;
+        if (isTerminalRunStatus(details.value.status)) {
+            return validationFailure(`VGXNESS run ${runId} is in terminal state '${details.value.status}'; Claude Code provider config writes require a live run (created/planned/running/needs-human). Start a new run with \`vgxness run start\` and pass its --run-id.`);
+        }
         const phase = optionalStringFlag(parsed.flags, 'phase') ?? details.value.phase;
         const agentId = optionalStringFlag(parsed.flags, 'agent-id') ?? details.value.selectedAgentId;
         const preflight = service.preflightOperation({

package/dist/cli/dispatcher.js

@@ -4,6 +4,7 @@ import { isWorkflowId } from '../workflows/schema.js';
 import { databasePathFor, parseArgs, requiredFlag } from './cli-flags.js';
 import { okText, usageFailure, visibleHelpText } from './cli-help.js';
 import { openCliDatabase, resultFailure } from './cli-helpers.js';
+import { runBootAgentSeedUpgrade } from '../agents/boot-upgrade.js';
 import { runAgentCommand, runApprovalsCommand, runCodeCliCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
 const _promptBuffers = new WeakMap();
 const require = createRequire(import.meta.url);
@@ -48,6 +49,7 @@ export function dispatchCli(argv, environment) {
     const opened = openCliDatabase(databasePath);
     if (!opened.ok)
         return resultFailure(opened);
+    runBootAgentSeedUpgrade(opened.value, environment.env);
     try {
         if (isWorkflowId(area) && command === 'run')
             return runWorkflowRunCommand(area, parsed, opened.value);

package/dist/mcp/client-install-claude-code-contract.js

@@ -1,3 +1,4 @@
+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, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
@@ -63,11 +64,25 @@ export function planClaudeCodeMcpInstall(input) {
         status: 'would_install',
     };
 }
-export function expectedClaudeCodeRenderedAgents(workspaceRoot) {
-    return expectedClaudeCodeAgentFiles(workspaceRoot).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+export function expectedClaudeCodeRenderedAgents(workspaceRoot, options) {
+    const files = expectedClaudeCodeAgentFiles(workspaceRoot);
+    const projection = withEffectiveManagerInstructions({ defaultAgent: 'vgxness-manager', agents: files.map(({ path: _path, ...rest }) => rest) }, options?.effectiveManagerInstructions);
+    return projection.agents.map((agent) => {
+        const file = files.find((entry) => entry.name === agent.name);
+        if (file === undefined)
+            throw new Error(`Expected Claude agent file missing for ${agent.name}`);
+        return { path: file.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) };
+    });
 }
-export function expectedClaudeCodeRenderedUserAgents(workspaceRoot, env) {
-    return expectedClaudeCodeAgentFiles({ workspaceRoot, scope: 'user', ...(env === undefined ? {} : { env }) }).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+export function expectedClaudeCodeRenderedUserAgents(workspaceRoot, env, options) {
+    const files = expectedClaudeCodeAgentFiles({ workspaceRoot, scope: 'user', ...(env === undefined ? {} : { env }) });
+    const projection = withEffectiveManagerInstructions({ defaultAgent: 'vgxness-manager', agents: files.map(({ path: _path, ...rest }) => rest) }, options?.effectiveManagerInstructions);
+    return projection.agents.map((agent) => {
+        const file = files.find((entry) => entry.name === agent.name);
+        if (file === undefined)
+            throw new Error(`Expected Claude user agent file missing for ${agent.name}`);
+        return { path: file.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) };
+    });
 }
 function planUserInstall(input, server, overwriteVgxness, cliCommand, scopeWarnings) {
     const mcpState = inspectClaudeCodeUserMcpConfig(input.env);