@webpresso/agent-kit 3.3.1 → 3.3.2

package/dist/esm/mcp/blueprint/handlers/document-mutations.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import matter from "gray-matter";
 import { parseBlueprint } from "#core/parser";
 import { taskIdSchema } from "#core/schema";
+import { formatTaskHeading } from "#markdown/task-heading";
 import { evaluateApprovalGate, formatApprovalGateRequirement } from "#lifecycle/audit";
 import { canonicalizeBlueprint } from "#lifecycle/canonicalize.js";
 import { BlueprintCreationService } from "#service/BlueprintCreationService";
@@ -290,7 +291,7 @@ function renderBlueprintMarkdownFromDocument(slug, document) {
         "",
     ];
     const taskBlocks = document.tasks.flatMap((task) => [
-        `#### Task ${task.id}: ${task.title}`,
+        formatTaskHeading(task.id, task.title),
         "",
         `**Status:** ${task.status}`,
         ...(task.wave ? [`**Wave:** ${task.wave}`] : []),

package/dist/esm/mcp/blueprint/handlers/task-advance.js

@@ -11,23 +11,13 @@ import { toStr } from "#mcp/blueprint/_shared/payload";
 import { findBlueprintDir, resolveToolProject } from "#mcp/blueprint/_shared/project";
 import { resolveSyncAdapter, runPlatformMutationSync } from "#mcp/blueprint/_shared/sync";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
-import { escapeRegex } from "#utils/string";
+import { buildTaskHeaderRegexForId } from "#markdown/task-heading";
 import { withMarkdownWriteLock } from "#db/paths.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 const ALL_STATES = ["draft", "planned", "in-progress", "parked", "archived", "completed"];
-/**
- * Matches the canonical task-heading grammar `parser.ts`'s `extractTasks`
- * uses (`^####\s+(?:\[lane\]\s+)?Task\s+<id>:`), not a looser ad hoc pattern.
- * The id is anchored on a trailing colon so "1.1" cannot match "1.10", and
- * an optional `[lane]` prefix is accepted the same way the canonical parser
- * does.
- */
-function buildTaskHeadingPattern(taskId) {
-    return new RegExp(`^####\\s+(?:\\[[^\\]]+\\]\\s+)?Task\\s+${escapeRegex(taskId)}:`, "u");
-}
 function findTaskStatusLine(markdown, taskId) {
     const lines = markdown.split("\n");
-    const headingPattern = buildTaskHeadingPattern(taskId);
+    const headingPattern = buildTaskHeaderRegexForId(taskId);
     let inBlock = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i] ?? "";

package/dist/esm/review/delivery-verifier.d.ts

@@ -1,5 +1,6 @@
-import { executeAllowedWpCommand } from "#trust/command-runner.js";
+import { executeAllowedWpCommand, type AllowedWpCommandResult } from "#trust/command-runner.js";
 import type { ReviewTargetCheckout } from "#review/execution/review-checkout.js";
+import type { SandboxAvailability } from "#review/execution/sandbox/types.js";
 export interface ReviewGateVerificationCommand {
     readonly command: string;
     readonly outcome: "passed" | "failed" | "timed-out" | "deferred";
@@ -7,12 +8,29 @@ export interface ReviewGateVerificationCommand {
     readonly exitCode: number | null;
     readonly signal?: string;
 }
+/**
+ * How the gate commands were isolated. `srt` = OS-sandboxed; `disabled-by-operator`
+ * = an explicit `WP_REVIEW_UNSANDBOXED_GATES=1` override ran them unsandboxed;
+ * `unavailable` = no backend and no override, so no gate ran (fail-closed).
+ */
+export type ReviewSandboxMode = "srt" | "disabled-by-operator" | "unavailable";
 export interface ReviewGateVerification {
     readonly status: "passed" | "failed";
     readonly commands: readonly ReviewGateVerificationCommand[];
     readonly failureCode?: string;
     readonly logPath?: string;
+    readonly sandbox?: ReviewSandboxMode;
+    readonly sandboxReason?: string;
 }
+/** Runs one gate command in the review checkout and returns its raw result. */
+export type RunSandboxedGate = (args: {
+    readonly command: string;
+    readonly executionRoot: string;
+    readonly logRoot: string;
+    readonly runTmpDir: string;
+    readonly projectRoot: string;
+    readonly signal?: AbortSignal;
+}) => Promise<AllowedWpCommandResult>;
 export interface VerifyDeliveryGatesInput {
     readonly purpose: "plan" | "delivery";
     readonly blueprintContent: string;
@@ -20,8 +38,21 @@ export interface VerifyDeliveryGatesInput {
     readonly gateId: string;
     readonly checkout: ReviewTargetCheckout;
     readonly signal?: AbortSignal;
+    /** Legacy/override execution path (unsandboxed). */
     readonly executeCommand?: typeof executeAllowedWpCommand;
+    /** Test seam: resolve the sandbox backend. */
+    readonly resolveAvailability?: () => Promise<SandboxAvailability>;
+    /** Test seam: run a single sandboxed gate. */
+    readonly runSandboxedGate?: RunSandboxedGate;
 }
-export declare function verifyDeliveryPromotionGates(input: VerifyDeliveryGatesInput): ReviewGateVerification | undefined;
+export declare function verifyDeliveryPromotionGates(input: VerifyDeliveryGatesInput): Promise<ReviewGateVerification | undefined>;
+/**
+ * Builds the real {@link RunSandboxedGate}. `cleanupSandbox` is a test-only
+ * seam (defaults to the real {@link cleanupSandboxCommand}) so unit tests can
+ * force the fail-closed "passing gate, leaky sandbox" path without a real srt
+ * backend; every non-test caller gets the real cleanup and byte-identical
+ * behavior to before this seam existed.
+ */
+export declare function createRunSandboxedGate(cleanupSandbox?: () => Promise<void>): RunSandboxedGate;
 export declare function verificationPromptSummary(verification: ReviewGateVerification | undefined): string | undefined;
 export declare function verificationArtifactSection(verification: ReviewGateVerification | undefined): string;

package/dist/esm/review/delivery-verifier.js

@@ -1,8 +1,14 @@
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
-import { executeAllowedWpCommand, relativeCommandLogPath, } from "#trust/command-runner.js";
+import { executeAllowedWpCommand, rejectedInvocationResult, relativeCommandLogPath, resolveInvocationFromCommand, runResolvedInvocationAsync, } from "#trust/command-runner.js";
 import { parseTrustDossier } from "#trust/dossier.js";
 import { parseAllowedWpCommand } from "#trust/gates.js";
-export function verifyDeliveryPromotionGates(input) {
+import { buildSandboxedGateEnv } from "#review/execution/sandbox/env.js";
+import { cleanupSandboxCommand, wrapGateForSandbox } from "#review/execution/sandbox/adapter.js";
+import { resolveSandboxAvailability } from "#review/execution/sandbox/probe.js";
+const UNSANDBOXED_OVERRIDE_ENV = "WP_REVIEW_UNSANDBOXED_GATES";
+export async function verifyDeliveryPromotionGates(input) {
     if (input.purpose !== "delivery")
         return undefined;
     const parsed = parseTrustDossier(input.blueprintContent);
@@ -12,48 +18,82 @@ export function verifyDeliveryPromotionGates(input) {
             parsed.violations[0]?.message === "missing Trust Dossier section") {
             return undefined;
         }
+        return { status: "failed", commands: [], failureCode: "malformed-trust-dossier" };
+    }
+    const gates = parsed.dossier?.gates ?? [];
+    if (gates.length === 0)
+        return undefined;
+    const overrideUnsandboxed = process.env[UNSANDBOXED_OVERRIDE_ENV] === "1";
+    const availability = await (input.resolveAvailability?.() ?? resolveSandboxAvailability());
+    if (availability.kind === "none" && !overrideUnsandboxed) {
         return {
             status: "failed",
             commands: [],
-            failureCode: "malformed-trust-dossier",
+            failureCode: "sandbox-unavailable",
+            sandbox: "unavailable",
+            sandboxReason: availability.reason,
         };
     }
-    const gates = parsed.dossier?.gates ?? [];
-    if (gates.length === 0)
-        return undefined;
-    const commands = [];
-    const executeCommand = input.executeCommand ?? executeAllowedWpCommand;
+    const sandbox = overrideUnsandboxed ? "disabled-by-operator" : "srt";
     const logRoot = path.join(input.projectRoot, ".webpresso", "logs", "delivery-verification", input.gateId);
-    for (const gate of gates) {
+    const runTmpDir = sandbox === "srt" ? mkdtempSync(path.join(tmpdir(), "wp-review-run-")) : undefined;
+    try {
+        return await runGateLoop(input, { gates, sandbox, logRoot, runTmpDir });
+    }
+    finally {
+        if (runTmpDir !== undefined)
+            rmSync(runTmpDir, { recursive: true, force: true });
+    }
+}
+async function runGateLoop(input, ctx) {
+    const commands = [];
+    const runSandboxedGate = input.runSandboxedGate ?? defaultRunSandboxedGate;
+    for (const gate of ctx.gates) {
         if (input.signal?.aborted) {
             return {
                 status: "failed",
                 commands,
                 failureCode: "verification-cancelled",
+                sandbox: ctx.sandbox,
             };
         }
         if (isApprovalDependentLifecycleGate(gate.command)) {
-            commands.push({
-                command: gate.command,
-                outcome: "deferred",
-                durationMs: 0,
-                exitCode: null,
-            });
+            commands.push({ command: gate.command, outcome: "deferred", durationMs: 0, exitCode: null });
             continue;
         }
-        const result = executeCommand({
-            command: gate.command,
-            executionRoot: input.checkout.cwd,
-            logRoot,
-            env: { CI: "1", NO_COLOR: "1", WP_FORCE_SOURCE: "1" },
-        });
+        const result = ctx.sandbox === "srt"
+            ? await runSandboxedGate({
+                command: gate.command,
+                executionRoot: input.checkout.cwd,
+                logRoot: ctx.logRoot,
+                runTmpDir: ctx.runTmpDir ?? "",
+                projectRoot: input.projectRoot,
+                ...(input.signal ? { signal: input.signal } : {}),
+            })
+            : (input.executeCommand ?? executeAllowedWpCommand)({
+                command: gate.command,
+                executionRoot: input.checkout.cwd,
+                logRoot: ctx.logRoot,
+                env: { CI: "1", NO_COLOR: "1", WP_FORCE_SOURCE: "1" },
+            });
         commands.push(publicCommandResult(result));
+        // A cancellation DURING a gate (abort mid-execution) must report as
+        // cancelled, not a generic command failure.
+        if (input.signal?.aborted || result.failureCode === "command-cancelled") {
+            return {
+                status: "failed",
+                commands,
+                failureCode: "verification-cancelled",
+                sandbox: ctx.sandbox,
+            };
+        }
         if (result.outcome !== "passed") {
             return {
                 status: "failed",
                 commands,
                 failureCode: result.failureCode ?? "verification-command-failed",
                 logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+                sandbox: ctx.sandbox,
             };
         }
         const changes = input.checkout.changes();
@@ -63,12 +103,76 @@ export function verifyDeliveryPromotionGates(input) {
                 commands,
                 failureCode: "verification-worktree-contaminated",
                 logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+                sandbox: ctx.sandbox,
             };
         }
     }
+    return { status: "passed", commands, sandbox: ctx.sandbox };
+}
+/**
+ * Builds the real {@link RunSandboxedGate}. `cleanupSandbox` is a test-only
+ * seam (defaults to the real {@link cleanupSandboxCommand}) so unit tests can
+ * force the fail-closed "passing gate, leaky sandbox" path without a real srt
+ * backend; every non-test caller gets the real cleanup and byte-identical
+ * behavior to before this seam existed.
+ */
+export function createRunSandboxedGate(cleanupSandbox = cleanupSandboxCommand) {
+    return async (args) => {
+        const startedAt = Date.now();
+        const env = buildSandboxedGateEnv(args.runTmpDir);
+        let invocation;
+        try {
+            invocation = resolveInvocationFromCommand(args.executionRoot, args.command, env, {
+                replaceProcessEnv: true,
+            });
+        }
+        catch (error) {
+            return rejectedInvocationResult(args.command, args.logRoot, startedAt, error);
+        }
+        let result;
+        try {
+            // The wrap is INSIDE the try so a wrap failure (unresolvable srt, empty
+            // argv) still produces a persisted failed verification instead of escaping.
+            const wrapped = await wrapGateForSandbox(invocation, {
+                checkoutRoot: realpathSync(args.executionRoot),
+                runTmpDir: realpathSync(args.runTmpDir),
+                projectRoot: args.projectRoot,
+            });
+            result = await runResolvedInvocationAsync({ command: wrapped.command, args: [...wrapped.args], env: wrapped.env }, {
+                command: args.command,
+                executionRoot: args.executionRoot,
+                logRoot: args.logRoot,
+                startedAt,
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+        }
+        catch (error) {
+            result = rejectedInvocationResult(args.command, args.logRoot, startedAt, error);
+        }
+        // Sandbox cleanup is part of the gate's integrity: an unbalanced srt counter
+        // or leftover mounts must NOT be reported as a clean pass. If cleanup fails
+        // after an otherwise-passing gate, convert the result to a failed
+        // verification and keep the gate output as secondary evidence. A gate that
+        // already failed keeps its more-informative primary failure.
+        try {
+            await cleanupSandbox();
+        }
+        catch (error) {
+            if (result.outcome === "passed")
+                return sandboxCleanupFailedResult(result, error);
+        }
+        return result;
+    };
+}
+const defaultRunSandboxedGate = createRunSandboxedGate();
+function sandboxCleanupFailedResult(gateResult, error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
-        status: "passed",
-        commands,
+        ...gateResult,
+        outcome: "failed",
+        failureCode: "sandbox-cleanup-failed",
+        errorMessage: `sandbox cleanup did not complete after a passing gate: ${message}`,
+        stderr: `${gateResult.stderr}\n[sandbox-cleanup-failed] ${message}`.trim(),
     };
 }
 export function verificationPromptSummary(verification) {
@@ -77,7 +181,7 @@ export function verificationPromptSummary(verification) {
     if (verification.status !== "passed")
         return undefined;
     return [
-        "Host verification before outside review: passed.",
+        `Host verification before outside review: passed (sandbox: ${verification.sandbox ?? "unknown"}).`,
         ...verification.commands.map((command, index) => `${index + 1}. ${command.command}: ${command.outcome === "deferred" ? "deferred until review publication" : "passed"}`),
     ].join("\n");
 }
@@ -97,6 +201,8 @@ export function verificationArtifactSection(verification) {
         "## Host Verification",
         "",
         `Status: ${verification.status}`,
+        `Sandbox: ${verification.sandbox ?? "unknown"}`,
+        ...(verification.sandboxReason ? [`Sandbox detail: ${verification.sandboxReason}`] : []),
         ...verification.commands.map((command, index) => `${index + 1}. ${command.command} -> ${command.outcome} (${command.durationMs}ms, exit ${command.exitCode ?? "null"})`),
         ...(verification.failureCode ? [`Failure code: ${verification.failureCode}`] : []),
         ...(verification.logPath ? [`Log: ${verification.logPath}`] : []),

package/dist/esm/review/execution/review-checkout.d.ts

@@ -6,6 +6,7 @@ export interface ReviewTargetCheckout {
 }
 declare function statusEntryPath(line: string): string;
 export declare function createReviewTargetCheckout(repositoryRoot: string, targetSha: string): ReviewTargetCheckout;
+export declare function assertDependencyContainment(checkoutRoot: string): void;
 /** Test-only surface for porcelain path parsing. */
 export declare const reviewCheckoutInternals: {
     statusEntryPath: typeof statusEntryPath;