@webpresso/agent-kit 0.21.3 → 0.21.5

package/dist/esm/mcp/blueprint-server.js

@@ -18,6 +18,7 @@ import path from 'node:path';
 import matter from 'gray-matter';
 import { z } from 'zod';
 import { parseBlueprint } from '#core/parser';
+import { setBlueprintFrontmatterFields } from '#lifecycle/engine';
 import { openDb } from '#db/connection.js';
 import { resolveBlueprintProjectionDbPath } from '#db/paths.js';
 import { findTemplate } from '#db/templates.js';
@@ -93,6 +94,13 @@ async function resolveSyncAdapter(cwd) {
     };
 }
 const DEFAULT_PLATFORM_MUTATION_TIMEOUT_MS = 5_000;
+function todayIsoDate() {
+    return new Date().toISOString().split('T')[0] ?? new Date().toISOString();
+}
+function formatBlueprintProgress(totalTasks, doneTasks, blockedTasks) {
+    const percent = totalTasks === 0 ? 0 : Math.round((doneTasks / totalTasks) * 100);
+    return `${percent}% (${doneTasks}/${totalTasks} tasks done, ${blockedTasks} blocked, updated ${todayIsoDate()})`;
+}
 function readPlatformMutationTimeoutMs() {
     const parsed = Number.parseInt(process.env['WP_BLUEPRINT_PLATFORM_MUTATION_TIMEOUT_MS'] ??
         String(DEFAULT_PLATFORM_MUTATION_TIMEOUT_MS), 10);
@@ -242,6 +250,18 @@ function openDbRW(cwd) {
 async function reIngest(cwd) {
     await reIngestProjection(cwd);
 }
+async function persistBlueprintMarkdown(input) {
+    const { projectCwd, slug, overviewPath, markdown } = input;
+    mkdirSync(path.dirname(overviewPath), { recursive: true });
+    parseBlueprint(markdown, slug);
+    writeFileSync(overviewPath, markdown, 'utf8');
+    await reIngest(projectCwd);
+    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!refreshed.blueprint) {
+        throw new Error(`Blueprint "${slug}" did not appear in the projection after write`);
+    }
+    return refreshed.blueprint;
+}
 function findBlueprintDir(blueprintRoot, slug, states) {
     for (const state of states) {
         const d = path.join(blueprintRoot, state, slug);
@@ -963,10 +983,6 @@ async function handlePromote(projectResolver, cwd, raw) {
         return err('wp_blueprint_promote failed', `Blueprint "${slug}" not found in any state directory`);
     const { dir: currentDir, state: currentState } = found;
     const overviewPath = path.join(currentDir, '_overview.md');
-    const ts = readVt(projectCwd);
-    const mtime = existsSync(overviewPath) ? statSync(overviewPath).mtimeMs : 0;
-    if ((ts[slug] ?? 0) < mtime)
-        return err('wp_blueprint_promote refused', `Blueprint "${slug}" not validated since last write. Run wp_blueprint_validate first.`);
     if (to_state === 'completed') {
         try {
             assertBlueprintCanComplete(overviewPath, slug);
@@ -999,40 +1015,34 @@ async function handlePromote(projectResolver, cwd, raw) {
     catch (e) {
         return err('wp_blueprint_promote failed', toStr(e));
     }
-    const { renameSync } = await import('node:fs');
-    const destDir = path.join(root, to_state, slug);
-    mkdirSync(path.dirname(destDir), { recursive: true });
     try {
-        renameSync(currentDir, destDir);
+        const transitioned = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state,
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" promoted from "${currentState}" to "${to_state}"`,
+            slug,
+            from_state: currentState,
+            to_state,
+            new_path: transitioned.overviewPath,
+            status: transitioned.blueprint.status,
+            content_hash: transitioned.blueprint.content_hash,
+            revision: transitioned.blueprint.content_hash,
+            ingested_at: transitioned.blueprint.ingested_at,
+            failures: [],
+            bytes: 0,
+            tokensSaved: 0,
+        };
+        if (currentState === 'draft' && to_state === 'planned')
+            appendHint(payload, projectCwd, 'PLAN_REFINE');
+        return finishPayload(payload);
     }
     catch (e) {
-        return err('wp_blueprint_promote failed', `Directory move error: ${toStr(e)}`);
-    }
-    const destOverview = path.join(destDir, '_overview.md');
-    if (existsSync(destOverview)) {
-        const fm = matter(readFileSync(destOverview, 'utf8'));
-        fm.data['status'] = to_state;
-        writeFileSync(destOverview, matter.stringify(fm.content, fm.data), 'utf8');
-    }
-    try {
-        await reIngest(projectCwd);
-    }
-    catch {
-        /* non-fatal */
+        return err('wp_blueprint_promote failed', toStr(e));
     }
-    const payload = {
-        summary: `Blueprint "${slug}" promoted from "${currentState}" to "${to_state}"`,
-        slug,
-        from_state: currentState,
-        to_state,
-        new_path: destOverview,
-        failures: [],
-        bytes: 0,
-        tokensSaved: 0,
-    };
-    if (currentState === 'draft' && to_state === 'planned')
-        appendHint(payload, projectCwd, 'PLAN_REFINE');
-    return finishPayload(payload);
 }
 const finalizeSchema = z.object({ project_id: z.string().optional(), slug: z.string() });
 async function handleFinalize(projectResolver, cwd, raw) {
@@ -1102,39 +1112,32 @@ async function handleFinalize(projectResolver, cwd, raw) {
     catch (e) {
         return err('wp_blueprint_finalize failed', toStr(e));
     }
-    const { renameSync } = await import('node:fs');
-    const destDir = path.join(root, 'completed', slug);
-    mkdirSync(path.dirname(destDir), { recursive: true });
     try {
-        renameSync(found.dir, destDir);
+        const transitioned = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state: 'completed',
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" finalized and moved to completed`,
+            slug,
+            new_path: transitioned.overviewPath,
+            status: transitioned.blueprint.status,
+            content_hash: transitioned.blueprint.content_hash,
+            revision: transitioned.blueprint.content_hash,
+            ingested_at: transitioned.blueprint.ingested_at,
+            failures: [],
+            bytes: 0,
+            tokensSaved: 0,
+        };
+        if (hasRecentAuditFinding(projectCwd))
+            appendHint(payload, projectCwd, 'AUDIT_FIX');
+        return finishPayload(payload);
     }
     catch (e) {
-        return err('wp_blueprint_finalize failed', `Directory move error: ${toStr(e)}`);
-    }
-    const destOverview = path.join(destDir, '_overview.md');
-    if (existsSync(destOverview)) {
-        const fm = matter(readFileSync(destOverview, 'utf8'));
-        fm.data['status'] = 'completed';
-        fm.data['completed_at'] = new Date().toISOString().split('T')[0] ?? '';
-        writeFileSync(destOverview, matter.stringify(fm.content, fm.data), 'utf8');
-    }
-    try {
-        await reIngest(projectCwd);
-    }
-    catch {
-        /* non-fatal */
+        return err('wp_blueprint_finalize failed', toStr(e));
     }
-    const payload = {
-        summary: `Blueprint "${slug}" finalized and moved to completed`,
-        slug,
-        new_path: destOverview,
-        failures: [],
-        bytes: 0,
-        tokensSaved: 0,
-    };
-    if (hasRecentAuditFinding(projectCwd))
-        appendHint(payload, projectCwd, 'AUDIT_FIX');
-    return finishPayload(payload);
 }
 function assertBlueprintCanComplete(overviewPath, slug) {
     const markdown = readFileSync(overviewPath, 'utf8');
@@ -1698,6 +1701,243 @@ const createSchema = MutationTarget.extend({
     request_id: z.string().min(1).optional(),
     head_at_ingest: z.string().nullable().optional(),
 });
+const putTaskSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'dropped']).default('todo'),
+    wave: z.string().optional(),
+    lane: z.string().optional(),
+    description: z.string().optional(),
+    acceptance: z.array(z.string().min(1)).min(1),
+});
+const putDocumentSchema = z.object({
+    type: z.literal('blueprint').default('blueprint'),
+    title: z.string().min(1),
+    status: z.enum(['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived']),
+    complexity: z.enum(['XS', 'S', 'M', 'L', 'XL']),
+    owner: z.string().min(1),
+    created: z.string().min(1),
+    last_updated: z.string().min(1),
+    progress: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    product_wedge_anchor: z.object({
+        stage_outcome: z.string().min(1),
+        consuming_surface: z.string().min(1),
+        new_user_visible_capability: z.string().min(1),
+    }),
+    summary: z.string().min(1),
+    tasks: z.array(putTaskSchema).min(1),
+});
+const putSchema = MutationTarget.extend({
+    slug: z.string().min(1),
+    document: putDocumentSchema,
+    request_id: z.string().min(1).optional(),
+    head_at_ingest: z.string().nullable().optional(),
+});
+function renderBlueprintMarkdownFromDocument(slug, document) {
+    const frontmatter = [
+        '---',
+        `type: ${document.type}`,
+        `title: ${document.title}`,
+        `status: ${document.status}`,
+        `complexity: ${document.complexity}`,
+        `owner: ${document.owner}`,
+        `created: '${document.created}'`,
+        `last_updated: '${document.last_updated}'`,
+        ...(document.progress ? [`progress: ${JSON.stringify(document.progress)}`] : []),
+        ...(document.tags && document.tags.length > 0
+            ? ['tags:', ...document.tags.map((tag) => `  - ${tag}`)]
+            : []),
+        '---',
+        '',
+    ];
+    const sections = [
+        `# ${document.title}`,
+        '',
+        '## Product wedge anchor',
+        '',
+        `- **Stage outcome:** ${document.product_wedge_anchor.stage_outcome}`,
+        `- **Consuming surface:** ${document.product_wedge_anchor.consuming_surface}`,
+        `- **New user-visible capability:** ${document.product_wedge_anchor.new_user_visible_capability}`,
+        '',
+        '## Summary',
+        '',
+        document.summary,
+        '',
+    ];
+    const taskBlocks = document.tasks.flatMap((task) => [
+        `#### Task ${task.id}: ${task.title}`,
+        '',
+        `**Status:** ${task.status}`,
+        ...(task.wave ? [`**Wave:** ${task.wave}`] : []),
+        ...(task.lane ? [`**Lane:** ${task.lane}`] : []),
+        ...(task.description ? ['', task.description] : []),
+        '',
+        '**Acceptance:**',
+        ...task.acceptance.map((item) => `- [ ] ${item}`),
+        '',
+    ]);
+    return [...frontmatter, ...sections, ...taskBlocks].join('\n').trimEnd() + '\n';
+}
+async function handleBlueprintPut(projectResolver, cwd, raw) {
+    const p = putSchema.safeParse(raw);
+    if (!p.success)
+        return err('wp_blueprint_put validation error', p.error.message);
+    const { project_id, slug, document, request_id, head_at_ingest } = p.data;
+    const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
+    if ('content' in resolvedProject)
+        return resolvedProject;
+    const projectCwd = resolvedProject.cwd;
+    await ensureProjectionReady(projectCwd);
+    const freshnessFailure = validateMutationFreshnessToken(projectCwd, head_at_ingest, 'wp_blueprint_put', 'wp_blueprint_get');
+    if (freshnessFailure)
+        return freshnessFailure;
+    const payloadHash = hashMutationPayload({ slug, document });
+    const replay = request_id !== undefined
+        ? readMutationReplay(projectCwd, 'wp_blueprint_put', request_id, payloadHash)
+        : null;
+    if (replay)
+        return replay;
+    const root = resolveBlueprintRoot(projectCwd);
+    const found = findBlueprintDir(root, slug, ALL_STATES);
+    if (found && found.state !== document.status) {
+        return err('wp_blueprint_put refused', `Blueprint "${slug}" currently lives in "${found.state}" and cannot be rewritten as "${document.status}" without a lifecycle transition.`);
+    }
+    if (!found && document.status !== 'draft') {
+        return err('wp_blueprint_put refused', `New blueprint "${slug}" must start in "draft"; use wp_blueprint_transition for later lifecycle moves.`);
+    }
+    const overviewPath = found
+        ? path.join(found.dir, '_overview.md')
+        : path.join(root, document.status, slug, '_overview.md');
+    try {
+        const markdown = renderBlueprintMarkdownFromDocument(slug, document);
+        const blueprint = await persistBlueprintMarkdown({
+            projectCwd,
+            slug,
+            overviewPath,
+            markdown,
+        });
+        const payload = {
+            summary: `Blueprint "${slug}" written to ${overviewPath}`,
+            slug,
+            path: overviewPath,
+            status: blueprint.status,
+            content_hash: blueprint.content_hash,
+            ingested_at: blueprint.ingested_at,
+            revision: blueprint.content_hash,
+            idempotent: false,
+            failures: [],
+            next_action: makeNextAction('verify_task', 'Blueprint written. Next: validate or transition the latest revision token through the structured surface.'),
+            project_id: resolvedProject.project_id ?? projectCwd,
+        };
+        if (request_id !== undefined) {
+            recordMutationReplay(projectCwd, 'wp_blueprint_put', request_id, payloadHash, payload);
+        }
+        return finishPayload(payload);
+    }
+    catch (e) {
+        return err('wp_blueprint_put failed', toStr(e));
+    }
+}
+const transitionSchema = MutationTarget.extend({
+    slug: z.string().min(1),
+    to_state: z.enum(['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived']),
+    expected_version: z.string().min(1),
+});
+async function handleBlueprintTransition(projectResolver, cwd, raw) {
+    const p = transitionSchema.safeParse(raw);
+    if (!p.success)
+        return err('wp_blueprint_transition validation error', p.error.message);
+    const { project_id, slug, to_state, expected_version } = p.data;
+    const resolvedProject = await resolveToolProject(projectResolver, cwd, project_id);
+    if ('content' in resolvedProject)
+        return resolvedProject;
+    const projectCwd = resolvedProject.cwd;
+    await ensureProjectionReady(projectCwd);
+    const target = dbPath(projectCwd);
+    if (!existsSync(target))
+        return err('wp_blueprint_transition failed', 'Blueprint DB not found');
+    const current = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!current.blueprint) {
+        return err('wp_blueprint_transition failed', `Blueprint "${slug}" not found`);
+    }
+    if (current.blueprint.content_hash !== expected_version) {
+        return jsonContent({
+            summary: `wp_blueprint_transition rejected a stale blueprint revision`,
+            failures: [
+                `expected_version "${expected_version}" does not match current content hash "${current.blueprint.content_hash}"`,
+            ],
+            error: 'stale_blueprint_revision',
+            next_action: makeNextAction('reingest_project', 'Call wp_blueprint_get again to fetch the latest content_hash before retrying the transition.'),
+            bytes: 0,
+            tokensSaved: 0,
+        }, true);
+    }
+    const root = resolveBlueprintRoot(projectCwd);
+    const found = findBlueprintDir(root, slug, ALL_STATES);
+    if (!found)
+        return err('wp_blueprint_transition failed', `Blueprint "${slug}" not found on disk`);
+    try {
+        const refreshed = await applyLocalBlueprintTransition({
+            found,
+            projectCwd,
+            slug,
+            to_state,
+        });
+        return finishPayload({
+            summary: `Blueprint "${slug}" transitioned to ${to_state}`,
+            slug,
+            old_status: current.blueprint.status,
+            new_status: to_state,
+            status: refreshed.blueprint.status,
+            content_hash: refreshed.blueprint.content_hash,
+            revision: refreshed.blueprint.content_hash,
+            ingested_at: refreshed.blueprint.ingested_at,
+            failures: [],
+            project_id: resolvedProject.project_id ?? projectCwd,
+        });
+    }
+    catch (e) {
+        return err('wp_blueprint_transition failed', toStr(e));
+    }
+}
+async function applyLocalBlueprintTransition(input) {
+    const { projectCwd, slug, to_state, found } = input;
+    const root = resolveBlueprintRoot(projectCwd);
+    const overviewPath = path.join(found.dir, '_overview.md');
+    const parsed = runValidate(overviewPath);
+    if (!parsed.valid) {
+        throw new Error(parsed.gaps.join('; '));
+    }
+    const markdown = readFileSync(overviewPath, 'utf8');
+    const currentBlueprint = parseBlueprint(markdown, slug);
+    const updated = setBlueprintFrontmatterFields(markdown, {
+        status: to_state,
+        last_updated: todayIsoDate(),
+        completed_at: to_state === 'completed' ? todayIsoDate() : undefined,
+        progress: formatBlueprintProgress(currentBlueprint.tasks.length, currentBlueprint.tasks.filter((task) => task.status === 'done').length, currentBlueprint.tasks.filter((task) => task.status === 'blocked').length),
+    });
+    parseBlueprint(updated, slug);
+    const destDir = path.join(root, to_state, slug);
+    mkdirSync(path.dirname(destDir), { recursive: true });
+    let finalOverviewPath = overviewPath;
+    if (found.state !== to_state) {
+        const { renameSync } = await import('node:fs');
+        renameSync(found.dir, destDir);
+        finalOverviewPath = path.join(destDir, '_overview.md');
+    }
+    writeFileSync(finalOverviewPath, updated, 'utf8');
+    await reIngest(projectCwd);
+    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+    if (!refreshed.blueprint) {
+        throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+    }
+    return {
+        blueprint: refreshed.blueprint,
+        overviewPath: finalOverviewPath,
+        fromState: found.state,
+    };
+}
 async function handleBlueprintCreate(projectResolver, cwd, raw) {
     const p = createSchema.safeParse(raw);
     if (!p.success)
@@ -1728,9 +1968,12 @@ async function handleBlueprintCreate(projectResolver, cwd, raw) {
             .replace(/{COMPLEXITY}/g, complexity)
             .replace(/{DATE}/g, today)
             .replace('{GOAL}', goal);
-        writeFileSync(overviewPath, content, 'utf8');
-        // Re-ingest so the DB reflects the new blueprint
-        await reIngest(projectCwd);
+        await persistBlueprintMarkdown({
+            projectCwd,
+            slug,
+            overviewPath,
+            markdown: content,
+        });
         const b = bytes(content);
         const payload = {
             summary: `Blueprint "${slug}" created at ${overviewPath}`,
@@ -1788,6 +2031,58 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
         },
         required: ['title', 'goal_prompt'],
     }, undefined, (r) => handleNew(cwd, r), { title: 'Blueprint New', readOnlyHint: true, openWorldHint: false });
+    registrar.registerTool('wp_blueprint_put', 'Create or replace a blueprint from a structured whole-document payload. Renders markdown, validates it, re-ingests the projection, and returns revision metadata.', {
+        type: 'object',
+        properties: {
+            project_id: { type: 'string' },
+            slug: { type: 'string' },
+            document: { type: 'object' },
+            request_id: { type: 'string' },
+            head_at_ingest: { type: ['string', 'null'] },
+        },
+        required: ['project_id', 'slug', 'document'],
+    }, {
+        ...summaryEnvelopeOutputSchema,
+        properties: {
+            ...summaryEnvelopeOutputSchema.properties,
+            slug: { type: 'string' },
+            path: { type: 'string' },
+            status: { type: 'string' },
+            content_hash: { type: 'string' },
+            ingested_at: { type: 'number' },
+            revision: { type: 'string' },
+            idempotent: { type: 'boolean' },
+            project_id: { type: 'string' },
+            next_action: nextActionOutputSchema,
+        },
+    }, (r) => handleBlueprintPut(projectResolver, cwd, r), { title: 'Blueprint Put', destructiveHint: false, openWorldHint: false });
+    registrar.registerTool('wp_blueprint_transition', 'Transition a blueprint lifecycle state using an expected revision token. Revalidates the latest markdown, rewrites frontmatter atomically, re-ingests the projection, and returns updated revision metadata.', {
+        type: 'object',
+        properties: {
+            project_id: { type: 'string' },
+            slug: { type: 'string' },
+            to_state: {
+                type: 'string',
+                enum: ['draft', 'planned', 'in-progress', 'completed', 'parked', 'archived'],
+            },
+            expected_version: { type: 'string' },
+        },
+        required: ['project_id', 'slug', 'to_state', 'expected_version'],
+    }, {
+        ...summaryEnvelopeOutputSchema,
+        properties: {
+            ...summaryEnvelopeOutputSchema.properties,
+            slug: { type: 'string' },
+            old_status: { type: 'string' },
+            new_status: { type: 'string' },
+            status: { type: 'string' },
+            content_hash: { type: 'string' },
+            revision: { type: 'string' },
+            ingested_at: { type: 'number' },
+            project_id: { type: 'string' },
+            next_action: nextActionOutputSchema,
+        },
+    }, (r) => handleBlueprintTransition(projectResolver, cwd, r), { title: 'Blueprint Transition', destructiveHint: false, openWorldHint: false });
     registrar.registerTool('wp_blueprint_validate', 'Validate _overview.md structure. Returns { valid, gaps }. Must pass before wp_blueprint_promote.', { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] }, undefined, (r) => handleValidate(cwd, r), { title: 'Blueprint Validate', readOnlyHint: false, openWorldHint: false });
     registrar.registerTool('wp_blueprint_task_next', 'Return the next ready task (all deps done). Accepts optional project_id for nested-workspace disambiguation. Returns { summary, task }.', {
         type: 'object',

package/dist/esm/mcp/tools/audit.js

@@ -15,9 +15,8 @@
  * — the handler never throws out, so the MCP server stays responsive.
  */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { z } from 'zod';
-import { resolvePackageAsset } from '#utils/package-assets';
+import { resolveAuditScriptPath } from '#audit/resolve-audit-script';
 import { applyOutputTransform } from '#output-transforms/index';
 import { createSummaryOutputSchema, createSummaryResult } from './_shared/result.js';
 const KINDS = [
@@ -62,12 +61,7 @@ const outputSchema = createSummaryOutputSchema({
     kind: z.enum(KINDS),
 });
 function resolveAuditScript(name) {
-    // Source layout: `src/mcp/tools/audit.ts` → `../../audit/<name>`.
-    const fromSource = new URL(`../../audit/${name}`, import.meta.url);
-    if (existsSync(fromSource)) {
-        return fromSource.pathname;
-    }
-    return resolvePackageAsset(`src/audit/${name}`);
+    return resolveAuditScriptPath(name, { moduleUrl: import.meta.url });
 }
 async function runScript(script) {
     return new Promise((resolve) => {

package/dist/esm/mcp/tools/e2e.d.ts

@@ -12,8 +12,8 @@ declare const inputSchema: z.ZodObject<{
     suite: z.ZodOptional<z.ZodString>;
     runner: z.ZodOptional<z.ZodEnum<{
         command: "command";
-        playwright: "playwright";
         vitest: "vitest";
+        playwright: "playwright";
     }>>;
     config: z.ZodOptional<z.ZodString>;
     files: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;

package/dist/esm/package.json

@@ -48,6 +48,9 @@
     "#mcp/*": "./mcp/*.js",
     "#content/*.js": "./content/*.js",
     "#content/*": "./content/*.js",
+    "#tool-runtime": "./tool-runtime/index.js",
+    "#tool-runtime/*.js": "./tool-runtime/*.js",
+    "#tool-runtime/*": "./tool-runtime/*.js",
     "#output-transforms/*.js": "./output-transforms/*.js",
     "#output-transforms/*": "./output-transforms/*.js",
     "#lint/*.js": "./lint/*.js",

package/dist/esm/secret-gate/runner.js

@@ -5,9 +5,13 @@ const SIGNAL_TO_EXIT_CODE = {
     SIGKILL: 9,
     SIGTERM: 15,
 };
+const DIRECT_ENV_PROFILES = new Set(['none', 'public']);
 export function buildSecretGateCommand(options) {
     const runner = options.runner?.trim() || 'with-secrets';
     const envProfile = options.envProfile?.trim();
+    if (runner === 'with-secrets' && envProfile && DIRECT_ENV_PROFILES.has(envProfile)) {
+        return { command: options.command, args: [...(options.args ?? [])] };
+    }
     const args = envProfile
         ? ['--env-profile', envProfile, '--', options.command, ...(options.args ?? [])]
         : ['--', options.command, ...(options.args ?? [])];

package/dist/esm/test/command-builder.d.ts

@@ -17,6 +17,7 @@ export interface TestCommandOptions {
     concurrencyLimit?: number;
     log?: VpRunLogMode;
     passthrough?: readonly string[];
+    filterOutput?: boolean;
 }
 export declare function buildTestCommand(target: ResolvedTestTarget, options?: TestCommandOptions): CommandConfig;
 export declare function buildVpTestCommand(filters: readonly string[], options?: TestCommandOptions): CommandConfig;

package/dist/esm/test/command-builder.js

@@ -1,3 +1,4 @@
+import { getManagedRunner } from '#tool-runtime';
 export function buildTestCommand(target, options = {}) {
     if (target.type === 'file') {
         return buildVitestCommand(target.values, options);
@@ -17,8 +18,12 @@ export function buildVpTestCommand(filters, options = {}) {
     if (passthrough.length > 0) {
         args.push('--', ...passthrough);
     }
+    const resolution = getManagedRunner('vp', { filterOutput: options.filterOutput });
     const env = buildVpRunEnv(options);
-    return env ? { command: 'vp', args, env } : { command: 'vp', args };
+    const mergedArgs = [...resolution.args, ...args];
+    return env
+        ? { command: resolution.command, args: mergedArgs, env }
+        : { command: resolution.command, args: mergedArgs };
 }
 export function buildVitestCommand(files, options = {}) {
     const args = [options.watch ? '--watch' : 'run'];
@@ -40,7 +45,8 @@ export function buildVitestCommand(files, options = {}) {
         args.push('--config', configFile);
     }
     args.push(...buildVitestPassthrough(options), ...testFiles);
-    return { command: 'vitest', args };
+    const resolution = getManagedRunner('vitest', { filterOutput: options.filterOutput });
+    return { command: resolution.command, args: [...resolution.args, ...args] };
 }
 export function getVpTestTask(options) {
     if (options.mutation)

package/dist/esm/test-helpers/hermetic-env.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hermetic environment baseline for the whole test suite.
+ *
+ * agent-kit's suite is routinely run *inside* an agent session (Claude Code,
+ * Codex), and those sessions export ambient variables that the production code
+ * legitimately honors at runtime:
+ *
+ * - `CLAUDE_PROJECT_DIR` — `resolveProjectRoot` (src/mcp/tools/_shared/project-root.ts)
+ *   ranks this above the discovered cwd, so a leaked value makes blueprint-server
+ *   tests target the real repo + its shared SQLite DB instead of their temp dir,
+ *   producing wrong-data assertions and lock-contention timeouts.
+ * - `WP_SKIP_UPDATE_CHECK` — suppresses the managed-CLI refresh spawn that the
+ *   init scaffolder tests assert fires; a leaked value (exported by the shell or
+ *   left behind by a sibling test file under the shared forks worker) drops the
+ *   expected spawn and fails spawn-count assertions.
+ *
+ * The fix is isolation, not changing the runtime precedence: reset these before
+ * every test so the suite is deterministic regardless of the launching
+ * environment. Tests that exercise these variables set them explicitly in their
+ * own body (which runs after this hook), so behavior coverage is unaffected.
+ */
+export declare const LEAKY_ENV_KEYS: readonly ["CLAUDE_PROJECT_DIR", "WP_SKIP_UPDATE_CHECK"];
+/** Delete every agent-session-leaked env var so each test starts hermetic. */
+export declare function resetLeakyEnv(): void;
+//# sourceMappingURL=hermetic-env.d.ts.map

package/dist/esm/test-helpers/hermetic-env.js

@@ -0,0 +1,31 @@
+import { beforeEach } from 'vitest';
+/**
+ * Hermetic environment baseline for the whole test suite.
+ *
+ * agent-kit's suite is routinely run *inside* an agent session (Claude Code,
+ * Codex), and those sessions export ambient variables that the production code
+ * legitimately honors at runtime:
+ *
+ * - `CLAUDE_PROJECT_DIR` — `resolveProjectRoot` (src/mcp/tools/_shared/project-root.ts)
+ *   ranks this above the discovered cwd, so a leaked value makes blueprint-server
+ *   tests target the real repo + its shared SQLite DB instead of their temp dir,
+ *   producing wrong-data assertions and lock-contention timeouts.
+ * - `WP_SKIP_UPDATE_CHECK` — suppresses the managed-CLI refresh spawn that the
+ *   init scaffolder tests assert fires; a leaked value (exported by the shell or
+ *   left behind by a sibling test file under the shared forks worker) drops the
+ *   expected spawn and fails spawn-count assertions.
+ *
+ * The fix is isolation, not changing the runtime precedence: reset these before
+ * every test so the suite is deterministic regardless of the launching
+ * environment. Tests that exercise these variables set them explicitly in their
+ * own body (which runs after this hook), so behavior coverage is unaffected.
+ */
+export const LEAKY_ENV_KEYS = ['CLAUDE_PROJECT_DIR', 'WP_SKIP_UPDATE_CHECK'];
+/** Delete every agent-session-leaked env var so each test starts hermetic. */
+export function resetLeakyEnv() {
+    for (const key of LEAKY_ENV_KEYS) {
+        delete process.env[key];
+    }
+}
+beforeEach(resetLeakyEnv);
+//# sourceMappingURL=hermetic-env.js.map

package/dist/esm/tool-runtime/index.d.ts

@@ -0,0 +1,5 @@
+import { type ManagedRunnerResolution, type ResolveRunnerOptions } from './resolve-runner.js';
+export declare function getManagedRunner(tool: string, options?: ResolveRunnerOptions): ManagedRunnerResolution;
+export declare function clearManagedRunnerCache(): void;
+export type { ManagedRunnerResolution, ResolveRunnerOptions };
+//# sourceMappingURL=index.d.ts.map