@webpresso/agent-kit 3.3.0 → 3.3.2

package/dist/esm/cli/commands/worktree/router-dispatch.js

@@ -15,6 +15,7 @@ import { runWorktreeSetup, runWorktreeTeardown } from "#worktrees/lifecycle-scri
 import { hydrateWorktreeDependencies, reconcileWorktreeDependencies, } from "#worktrees/dependencies.js";
 import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.js";
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
+import { formatTargetDirtyRefusal } from "#worktrees/owner-dirt.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
 import { findRegistryCandidatesByPath, planStaleWorktreeRegistryPrune, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
 import { buildRegistryRepoRootMap, classifyOrphanCandidate, discoverOrphanScanCandidates, resolveRepoRootFromGitPointer, } from "#worktrees/orphan-scan.js";
@@ -182,6 +183,13 @@ export function decideMergeCleanup(input) {
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} is locked`);
     }
     if (input.targetDirty) {
+        if (input.targetPorcelainZ !== undefined) {
+            throw new Error(formatTargetDirtyRefusal({
+                targetPath: input.targetPath,
+                porcelainZ: input.targetPorcelainZ,
+                slug: input.targetBlueprintSlug,
+            }));
+        }
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} has uncommitted changes`);
     }
     if (input.repoDirty) {
@@ -561,6 +569,12 @@ function isDirty(path) {
         return true;
     return String(status.stdout ?? "").trim().length > 0;
 }
+/** `.../blueprints/<slug>/owner` → slug */
+export function inferBlueprintSlugFromOwnerPath(ownerPath) {
+    const normalized = ownerPath.replace(/\\/gu, "/");
+    const match = /\/blueprints\/([^/]+)\/owner\/?$/u.exec(normalized);
+    return match?.[1];
+}
 function currentBranch(repoRoot) {
     const result = spawnSync("git", ["branch", "--show-current"], {
         cwd: repoRoot,
@@ -691,6 +705,14 @@ async function handleMergeCleanup(nameOrPath, opts) {
     const scopedRegistryEntries = findRegistryCandidatesByPath(resolved)
         .filter((candidate) => classifyMembership(candidate.entry.repoRoot, mergeAuthKey) === "same")
         .map((candidate) => candidate.entry);
+    const targetDirty = isDirty(resolved);
+    const targetPorcelainZ = targetDirty
+        ? (() => {
+            const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all", "--ignored=no", "-z"], { cwd: resolved, encoding: "utf8" });
+            return status.status === 0 ? String(status.stdout ?? "") : "?? (git-status-failed)\0";
+        })()
+        : undefined;
+    const targetBlueprintSlug = inferBlueprintSlugFromOwnerPath(resolved);
     const plan = decideMergeCleanup({
         repoRoot,
         targetPath: resolved,
@@ -699,8 +721,10 @@ async function handleMergeCleanup(nameOrPath, opts) {
         registryEntries: scopedRegistryEntries,
         currentBranch: currentBranch(repoRoot),
         repoDirty: isDirty(repoRoot),
-        targetDirty: isDirty(resolved),
+        targetDirty,
         stashPrimary: opts.stashPrimary === true,
+        ...(targetPorcelainZ !== undefined ? { targetPorcelainZ } : {}),
+        ...(targetBlueprintSlug !== undefined ? { targetBlueprintSlug } : {}),
     });
     if (opts.dryRun) {
         console.log("[dry-run] Would run merge cleanup:");

package/dist/esm/cli/utils.d.ts

@@ -15,7 +15,14 @@ interface GetProjectRootOptions {
 }
 /**
  * Walks upward from startDir looking for any marker in
- * `PROJECT_ROOT_MARKERS` (priority order). Throws if nothing is found.
+ * `PROJECT_ROOT_MARKERS` (priority order). The walk is clamped at the
+ * enclosing git repository boundary: a directory containing `.git` (dir for
+ * a normal checkout, file for a linked worktree or submodule) is itself a
+ * project root when no marker matched at or below it. Without the clamp, a
+ * markerless git repo silently resolves to whatever ancestor happens to
+ * carry a `package.json` (e.g. editor-tooling junk in `$HOME`) and commands
+ * like `wp blueprint new` write outside the repo. Throws if neither a
+ * marker nor a git boundary is found.
  */
 export declare function findProjectRoot(startDir: string): string;
 export declare function getProjectRoot(options?: GetProjectRootOptions): string;

package/dist/esm/cli/utils.js

@@ -35,7 +35,14 @@ function findMarker(rootDir) {
 }
 /**
  * Walks upward from startDir looking for any marker in
- * `PROJECT_ROOT_MARKERS` (priority order). Throws if nothing is found.
+ * `PROJECT_ROOT_MARKERS` (priority order). The walk is clamped at the
+ * enclosing git repository boundary: a directory containing `.git` (dir for
+ * a normal checkout, file for a linked worktree or submodule) is itself a
+ * project root when no marker matched at or below it. Without the clamp, a
+ * markerless git repo silently resolves to whatever ancestor happens to
+ * carry a `package.json` (e.g. editor-tooling junk in `$HOME`) and commands
+ * like `wp blueprint new` write outside the repo. Throws if neither a
+ * marker nor a git boundary is found.
  */
 export function findProjectRoot(startDir) {
     let current = path.resolve(startDir);
@@ -43,9 +50,12 @@ export function findProjectRoot(startDir) {
         if (findMarker(current)) {
             return current;
         }
+        if (existsSync(path.join(current, ".git"))) {
+            return current;
+        }
         const parent = path.dirname(current);
         if (parent === current) {
-            throw new Error(`Could not find project root (looked for ${PROJECT_ROOT_MARKERS.join(", ")}). Started from: ${startDir}`);
+            throw new Error(`Could not find project root (looked for ${PROJECT_ROOT_MARKERS.join(", ")} or a .git boundary). Started from: ${startDir}`);
         }
         current = parent;
     }

package/dist/esm/hooks/pretool-guard/validators/plan-frontmatter.js

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from "yaml";
 import { getContent, getFilePath } from "#hooks/shared/types";
+import { buildTaskHeadingRegex, buildWrongDepthTaskHeadingRegex } from "#markdown/task-heading";
 import { getNonCanonicalPlanningPathViolation, isBlueprintPath, isCanonicalBlueprintDocumentPath, } from "./path-contract.js";
 import { createSkipResult } from "./skip-result.js";
 // Keep aligned with webpresso/blueprint planStatusSchema + plan type enum.
@@ -53,10 +54,10 @@ export function collectFieldViolations(data) {
     return violations;
 }
 export function countTaskHeadings(content) {
-    return content.match(/^####\s+Task\s+\d+(?:\.\d+)+:/gm)?.length ?? 0;
+    return content.match(buildTaskHeadingRegex("gm"))?.length ?? 0;
 }
 export function detectWrongTaskFormat(content) {
-    return content.match(/^###\s+Task\s+\d+(?:\.\d+)+:/gm)?.length ?? 0;
+    return content.match(buildWrongDepthTaskHeadingRegex("gm"))?.length ?? 0;
 }
 export function validatePlanFrontmatter(input) {
     const filePath = getFilePath(input);

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

@@ -4,4 +4,11 @@ export interface ReviewTargetCheckout {
     readonly changes: () => readonly string[];
     readonly cleanup: () => void;
 }
+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;
+};
+export {};