@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/cli/commands/init/untracked-collision.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 const GIT_TIMEOUT_MS = 15_000;
 const OWNERSHIP_MARKER = /^\uFEFF?[ \t]*(?:#|\/\/|\/\*|<!--|")?[ \t]*(?:>>> managed by webpresso\b|Generated by webpresso\b)/iu;
 function git(repoRoot, args) {
@@ -12,6 +12,25 @@ function git(repoRoot, args) {
     });
     return { ok: result.status === 0 && !result.error };
 }
+/** True when `gitPath` is git-ignored in `repoRoot` (machine-local, never committed). */
+export function isGitIgnored(repoRoot, gitPath) {
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath]).ok;
+}
+function resolveIgnoredDivergence(options) {
+    const { unit } = options;
+    if (options.patchDerived) {
+        return { ok: true, resolution: "ignored-patch-derived" };
+    }
+    const current = readFileSync(unit.targetPath);
+    const backupPath = `${unit.targetPath}.bak`;
+    writeFileSync(backupPath, current);
+    return {
+        ok: true,
+        resolution: "ignored-backed-up",
+        warning: `Untracked, git-ignored ${unit.gitPath} had unmanaged content; ` +
+            `the original was backed up to ${unit.gitPath}.bak before it was overwritten.`,
+    };
+}
 export function resolveUntrackedCollision(options) {
     const { unit } = options;
     if (!existsSync(unit.targetPath))
@@ -34,6 +53,9 @@ export function resolveUntrackedCollision(options) {
         rmSync(unit.targetPath);
         return { ok: true, resolution: "removed-owned" };
     }
+    if (unit.scope === "repo-ignored") {
+        return resolveIgnoredDivergence(options);
+    }
     return {
         ok: false,
         error: `Unknown untracked content blocks ${unit.gitPath}; it was preserved${options.force ? " despite --force" : ""}. ` +

package/dist/esm/cli/commands/pr-help.js

@@ -53,7 +53,7 @@ export function getPrWaitCommandHelpText() {
         "  --branch <name>          Branch selector (defaults to current branch)",
         "  --pr <number-or-url>     Explicit PR selector",
         "  --until <target>         ready | checks-terminal | checks-green | merged (default: checks-terminal)",
-        "  --timeout-ms <ms>        Overall deadline; for ready, per-probe timeout only",
+        "  --timeout-ms <ms>        Overall deadline, max 300000 (5min); for ready, per-probe timeout only",
         "  --poll-interval-ms <ms>  Poll interval (default: 15000)",
         "  --include-checks         Include final check snapshot (default: true)",
         "  --no-include-checks      Omit final check snapshot from output",

package/dist/esm/cli/commands/pr.js

@@ -2,15 +2,29 @@ import { PR_WAIT_UNTIL_VALUES, runPrWait } from "#mcp/tools/pr-wait.js";
 import { buildStatusSnapshot, formatStatusSnapshot } from "#status/snapshot.js";
 // PR help text lives in ./pr-help.ts (dependency-free) so the `wp pr --help`
 // fast path can render it without importing this heavy command module.
-function parsePositiveInteger(value, name) {
+// Mirrors the hard cap `readonlyOpsBaseSchema` enforces downstream for `pr
+// wait` (src/mcp/tools/_readonly-ops.ts). `pr status` shares the same
+// `--timeout-ms` flag but reaches `buildStatusSnapshot` directly, which has
+// no schema of its own, so an over-cap value was silently accepted with no
+// error and no clamp. Validating here makes both subcommands fail the same
+// way, with a clear message, before any network probe starts, instead of
+// relying on a downstream schema that not every code path shares.
+const MAX_TIMEOUT_MS = 300_000;
+function parsePositiveInteger(value, name, max) {
     if (value === undefined)
         return undefined;
     const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
         throw new Error(`${name} must be a positive integer`);
     }
+    if (max !== undefined && parsed > max) {
+        throw new Error(`${name} must not exceed ${max}`);
+    }
     return parsed;
 }
+function parseTimeoutMs(value) {
+    return parsePositiveInteger(value, "--timeout-ms", MAX_TIMEOUT_MS);
+}
 function normalizeUntil(value) {
     if (value === undefined)
         return undefined;
@@ -26,7 +40,7 @@ export function registerPrCommand(cli) {
         .option("--branch <name>", "Branch selector")
         .option("--pr <number-or-url>", "Explicit PR selector")
         .option("--until <target>", "ready | checks-terminal | checks-green | merged")
-        .option("--timeout-ms <ms>", "Overall deadline; for ready, per-probe timeout only")
+        .option("--timeout-ms <ms>", "Overall deadline (max 300000ms / 5min); for ready, per-probe timeout only")
         .option("--poll-interval-ms <ms>", "Poll interval")
         .option("--include-checks", "Include final check snapshot", { default: true })
         .option("--max-output-bytes <n>", "Per-command output budget")
@@ -41,7 +55,7 @@ export function registerPrCommand(cli) {
                 includePr: true,
                 maxOutputBytes: parsePositiveInteger(options.maxOutputBytes, "--max-output-bytes"),
                 pr: options.pr === undefined ? undefined : String(options.pr),
-                timeoutMs: parsePositiveInteger(options.timeoutMs, "--timeout-ms"),
+                timeoutMs: parseTimeoutMs(options.timeoutMs),
             });
             console.log(options.json ? JSON.stringify(snapshot, null, 2) : formatStatusSnapshot(snapshot));
             return options.requireReady && snapshot.status !== "ready" ? 1 : 0;
@@ -57,7 +71,7 @@ export function registerPrCommand(cli) {
             maxOutputBytes: parsePositiveInteger(options.maxOutputBytes, "--max-output-bytes"),
             pollIntervalMs: parsePositiveInteger(options.pollIntervalMs, "--poll-interval-ms"),
             pr: options.pr === undefined ? undefined : String(options.pr),
-            timeoutMs: parsePositiveInteger(options.timeoutMs, "--timeout-ms"),
+            timeoutMs: parseTimeoutMs(options.timeoutMs),
             until,
         });
         console.log(JSON.stringify(payload, null, 2));

package/dist/esm/cli/commands/review.d.ts

@@ -220,6 +220,7 @@ export interface ReviewGateDependencies {
      */
     readonly prepareOpencodeCredential?: (account: OpencodeAccount) => string;
 }
+export declare function describeVerificationFailure(verification: ReviewGateVerification | undefined, gateId: string): string;
 /**
  * Sanctioned fallback when `wp review gate` does not reach "approved" — points
  * at the tracked-provenance path (`wp review log` / `wp_blueprint_review_log`)

package/dist/esm/cli/commands/review.js

@@ -28,6 +28,7 @@ import { isPolicyApprovalVerdict } from "#review/verdict.js";
 import { verificationArtifactSection, verificationPromptSummary, verifyDeliveryPromotionGates, } from "#review/delivery-verifier.js";
 import { createDeliverySubjectAtRef, createPlanSubjectAtRef, findUnreviewedWorkingTreeChanges, } from "#review/subject.js";
 import { runCommand } from "#mcp/tools/_shared/run-command.js";
+import { ALLOWED_WP_COMMAND_TIMEOUT_MS } from "#trust/command-runner.js";
 import { NotInGitRepoError, withLock } from "#paths/state-root.js";
 import { writeFileAtomic, writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
 export const REVIEWER_IDS = [
@@ -1463,6 +1464,35 @@ function gateFailureFromSummary(summary) {
         ...(summary.retryAfterMs === undefined ? {} : { retryAfterMs: summary.retryAfterMs }),
     };
 }
+// `providerErrorDetail`'s doc comment promises "sanitized, length-bounded"
+// text; a checkout-creation error's message/cause chain is target/environment
+// text (pnpm/git stderr), not attacker-shaped, but is still capped here so
+// the invariant holds regardless.
+const MAX_PROVIDER_ERROR_DETAIL_LENGTH = 2000;
+// Walks an `Error.cause` chain into a single human-readable line. Used to
+// surface the real reason a review checkout could not be created instead of
+// discarding it behind a fixed string (see the bare `catch` this replaces in
+// `invokeProvider`). Bounded depth + a `seen` set guard against a pathological
+// or cyclic cause chain.
+function formatErrorWithCauseChain(error, maxDepth = 5) {
+    const parts = [];
+    const seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < maxDepth; depth += 1) {
+        if (current === undefined || current === null || seen.has(current))
+            break;
+        seen.add(current);
+        if (current instanceof Error) {
+            parts.push(current.message);
+            current = current.cause;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+    }
+    return parts.join(" -> caused by: ");
+}
 export async function invokeProvider(input, executeReview = runReviewExecution, runCatalogCommand = runCommand, createTargetCheckout = createReviewTargetCheckout, 
 // A thunk (not a checkout instance) so callers that never reach a real
 // provider attempt — injected fakes included — never pay the checkout's
@@ -1475,19 +1505,34 @@ getSharedCheckout) {
         checkout = existingCheckout ?? createTargetCheckout(input.projectRoot, input.targetSha);
         checkout.beginAttempt();
     }
-    catch {
+    catch (error) {
+        // Bind + chain via Error.cause (ES2022) rather than discarding the real
+        // failure — this exact swallow previously hid a genuine supply-chain
+        // signal (`ERR_PNPM_TRUST_DOWNGRADE`) behind a fixed string for a full
+        // day. See catalog/agent/rules/ts-coding-conventions.md.
+        const isolationFailure = new Error("Unable to create the disposable review checkout; review was not started", { cause: error });
+        let cleanupError;
         if (ownsCheckout) {
             try {
                 checkout?.cleanup();
             }
-            catch {
-                // The attempt already fails closed as an isolation failure.
+            catch (cleanupFailure) {
+                // Cleanup failing must not mask the primary isolation failure above;
+                // capture it as secondary diagnostic context instead of discarding it.
+                cleanupError = cleanupFailure;
             }
         }
         const requestedModel = input.model ?? defaultReviewModel(input.provider) ?? "unresolved";
         const model = resolveReviewModel(input.provider, requestedModel);
+        // Chain from the original `error`, not `isolationFailure` — the latter's
+        // own message is already the fixed prefix below, so chaining from it
+        // would print that fixed sentence twice.
+        const providerErrorDetail = (formatErrorWithCauseChain(error) +
+            (cleanupError === undefined
+                ? ""
+                : ` | cleanup after isolation failure also failed: ${formatErrorWithCauseChain(cleanupError)}`)).slice(0, MAX_PROVIDER_ERROR_DETAIL_LENGTH);
         return {
-            output: "Unable to create the disposable review checkout; review was not started.",
+            output: `${isolationFailure.message}: ${providerErrorDetail}`,
             model,
             reviewer: input.provider === "opencode" && model !== "unresolved"
                 ? reviewerFamily(model)
@@ -1497,6 +1542,7 @@ getSharedCheckout) {
             verdict: "no-verdict",
             terminalClassification: "review-isolation-failure",
             failureCode: "review-isolation-failure",
+            providerErrorDetail,
         };
     }
     try {
@@ -1799,6 +1845,64 @@ function selectGateProviders(input) {
     const available = ordered.filter((provider) => !isProviderSuppressed(input.availability, provider));
     return available.length > 0 ? available : [];
 }
+// Builds the `message` for a "verification-failed" gate result: host-side
+// verification (delivery Promotion Gates + Trust Dossier parsing) died before
+// any review provider ran, so `attempts` is empty and the default
+// approval-gate-template message ("Approval gate not satisfied (...)") reads
+// like a reviewer rejected the work when no reviewer was ever invoked. Names
+// the actual cause and the corrective action so a failed gate does not cost
+// a repeat run just to discover what happened. Exported for tests.
+export function describeVerificationFailure(verification, gateId) {
+    const resume = `Retry with --resume ${gateId} once fixed.`;
+    const preamble = "Host verification failed before any review provider ran (0 review attempts) -- this is not a provider/quota failure.";
+    if (!verification || verification.status !== "failed") {
+        return `${preamble} ${resume}`;
+    }
+    if (verification.failureCode === "malformed-trust-dossier") {
+        const fields = (verification.violations ?? [])
+            .map((violation) => `${violation.section}: ${violation.message}`)
+            .join("; ");
+        return `${preamble} The Trust Dossier is malformed${fields ? ` (${fields})` : ""}. Fill in the named field(s) via wp_blueprint_put (or wp blueprint promote to see the same detail) before gating again. ${resume}`;
+    }
+    const failedCommand = verification.commands.find((command) => command.outcome !== "passed");
+    if (verification.failureCode === "command-timed-out" && failedCommand) {
+        const budgetSeconds = ALLOWED_WP_COMMAND_TIMEOUT_MS / 1000;
+        return (`${preamble} The Promotion Gate command \`${failedCommand.command}\` exceeded the ` +
+            `${budgetSeconds}s sandboxed gate budget and was killed -- this is a fixed per-command ` +
+            "budget, not a live outage, and raising it is not the fix. Either replace this gate with " +
+            "a faster command (e.g. `wp lint`, or a narrow `wp audit <kind>`), or mark this Promotion " +
+            'Gates row `defer: "pre-implementation"` so it is recorded without being executed at gate ' +
+            `time. ${resume}`);
+    }
+    if (failedCommand) {
+        const exitDetail = failedCommand.exitCode === null ? "no exit code" : `exit ${failedCommand.exitCode}`;
+        const logDetail = verification.logPath ? ` Log: ${verification.logPath}.` : "";
+        return (`${preamble} Gate command \`${failedCommand.command}\` failed (${exitDetail}, ` +
+            `outcome: ${failedCommand.outcome}).${logDetail} This is usually a missing dependency or ` +
+            "stale install in the sandboxed checkout -- run the repo's install command " +
+            `(e.g. \`wp install\`) and retry. ${resume}`);
+    }
+    const codeDetail = verification.failureCode ? ` (failureCode: ${verification.failureCode})` : "";
+    return `${preamble} Verification failed${codeDetail} before any gate command ran. ${resume}`;
+}
+// Human-readable summary of why every candidate provider/reviewer is
+// currently suppressed in the project's availability.json cache, so a
+// zero-candidate gate result names the file and the reason instead of
+// looking like a silent no-op.
+function describeSuppressedCandidates(availability, candidates) {
+    return candidates
+        .map((provider) => {
+        const record = availability.providers[provider];
+        if (!record?.suppressed)
+            return undefined;
+        const reason = record.suppressionReason ?? record.terminalClassification ?? "unknown reason";
+        const since = record.suppressedAt ? ` since ${record.suppressedAt}` : "";
+        const retry = record.retryAfterMs === undefined ? "" : ` (retry window ${record.retryAfterMs}ms)`;
+        return `${provider}: suppressed${since} (${reason}${retry})`;
+    })
+        .filter((value) => value !== undefined)
+        .join("; ");
+}
 function safeArtifactPath(blueprintPath, relativeArtifact) {
     if (path.isAbsolute(relativeArtifact) || relativeArtifact.split(/[\\/]/u).includes("..")) {
         throw new Error(`Unsafe review artifact path: ${relativeArtifact}`);
@@ -2127,21 +2231,30 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
         // never need one (plan-purpose reuse of an existing approval, terminal
         // rejections, exhausted scope). A setup failure is remembered so provider
         // attempts still surface the same isolation-failure evidence.
+        // Captures the real failure the first time checkoutFactory is
+        // attempted this run, so the re-throw below (reached whenever a later
+        // caller reuses the memoized failure) can chain to it via Error.cause
+        // instead of discarding it — see ts-coding-conventions.md "never
+        // swallow an error".
+        let checkoutSetupError;
         const ensureSharedCheckout = () => {
             if (sharedCheckout !== undefined || checkoutSetupFailed)
                 return sharedCheckout;
             try {
                 sharedCheckout = checkoutFactory(projectRoot, targetSha);
             }
-            catch {
+            catch (error) {
                 checkoutSetupFailed = true;
+                checkoutSetupError = error;
             }
             return sharedCheckout;
         };
         const createCheckoutForAttempt = () => {
             // Only reachable when ensureSharedCheckout() already failed — a live
             // shared checkout is always passed to the attempt as existingCheckout.
-            throw new Error("review checkout setup failed");
+            throw new Error("review checkout setup failed", {
+                cause: checkoutSetupError,
+            });
         };
         let sharedCheckoutCleaned = false;
         const cleanupSharedCheckout = () => {
@@ -2171,7 +2284,7 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                     prompt = renderPrompt(summary);
                 }
                 if (verification?.status === "failed") {
-                    const result = makeResult(currentApprovalGate(), "verification-failed");
+                    const result = makeResult(currentApprovalGate(), "verification-failed", describeVerificationFailure(verification, gateId));
                     assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
                     persistGateState(projectRoot, result);
                     cleanupSharedCheckout();
@@ -2243,6 +2356,23 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                 availability,
                 ...(explicitProvider ? { explicitProvider } : {}),
             });
+            if (providerQueue.length === 0) {
+                const candidates = hostNeutralProviderOrder(explicitProvider);
+                const detail = describeSuppressedCandidates(availability, candidates);
+                const availabilityFile = path
+                    .relative(projectRoot, reviewAvailabilityPath(projectRoot))
+                    .replace(/\\/gu, "/");
+                const result = makeResult(approvalGate, "needs-review", `No review provider was invoked: every candidate provider is suppressed by the ` +
+                    `cached availability record at ${availabilityFile}${detail ? ` (${detail})` : ""}. ` +
+                    "This is a stale-cache condition, not a live provider outage -- if the " +
+                    "account/provider has since recovered or been re-authenticated, delete the stale " +
+                    `entry (or the whole file) at ${availabilityFile}, or wait for its suppression ` +
+                    `window to elapse, then retry with --resume ${gateId}.`);
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
             const usedReviewers = new Set([
                 ...attempts
                     .filter((attempt) => !isRetryableGateAttempt(attempt))

package/dist/esm/cli/commands/sync.d.ts

@@ -1,16 +1,18 @@
 /**
- * `wp sync` — projects the canonical webpresso rule/skill catalog into the
- * supported host surfaces.
+ * `wp sync` — projects the canonical webpresso rule/skill/agent catalog into
+ * the supported host surfaces.
  *
- * Projects unified rule + skill content (catalog ∪ consumer) into per-IDE
- * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
+ * Projects unified rule + skill + agent content (catalog ∪ consumer) into
+ * per-IDE surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
  * Flags:
- *   --kind rules|skills   Filter to a single kind (default: both).
- *   --check               Dry-run; exit 1 on first drift, no writes.
+ *   --kind rules|skills|agents   Filter to a single kind (default: all).
+ *   --check                      Dry-run; exit 1 on first drift, no writes.
  */
 import type { CAC } from "cac";
+import type { ContentKind } from "#content/loader";
 import { type ConsumerContext } from "./init/detect-consumer.js";
+export declare function parseKind(input: string | undefined): readonly ContentKind[] | undefined;
 export declare function computeSyncDriftCounts(input: {
     readonly surfaceFixCount: number;
     readonly agentsChanged: boolean;

package/dist/esm/cli/commands/sync.js

@@ -1,13 +1,13 @@
 /**
- * `wp sync` — projects the canonical webpresso rule/skill catalog into the
- * supported host surfaces.
+ * `wp sync` — projects the canonical webpresso rule/skill/agent catalog into
+ * the supported host surfaces.
  *
- * Projects unified rule + skill content (catalog ∪ consumer) into per-IDE
- * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
+ * Projects unified rule + skill + agent content (catalog ∪ consumer) into
+ * per-IDE surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
  * Flags:
- *   --kind rules|skills   Filter to a single kind (default: both).
- *   --check               Dry-run; exit 1 on first drift, no writes.
+ *   --kind rules|skills|agents   Filter to a single kind (default: all).
+ *   --check                      Dry-run; exit 1 on first drift, no writes.
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -25,14 +25,16 @@ function commandError(message, exitCode = 1) {
     err.exitCode = exitCode;
     return err;
 }
-function parseKind(input) {
+export function parseKind(input) {
     if (input === undefined)
         return undefined;
     if (input === "rules" || input === "rule")
         return ["rule"];
     if (input === "skills" || input === "skill")
         return ["skill"];
-    throw commandError(`Invalid --kind: ${input}. Must be 'rules' or 'skills'.`);
+    if (input === "agents" || input === "agent")
+        return ["agent"];
+    throw commandError(`Invalid --kind: ${input}. Must be 'rules', 'skills', or 'agents'.`);
 }
 function formatMismatches(mismatches) {
     return mismatches.map((m) => `  - [${m.consumerId}] ${m.targetPath}: ${m.reason}`).join("\n");
@@ -90,7 +92,7 @@ export function isUnmaterializedAgentKitSourceWorktree(consumer) {
 export function registerSyncCommand(cli) {
     cli
         .command("sync", "Sync agent rules + skills across all supported host surfaces")
-        .option("--kind <kind>", "Filter: rules | skills (default: both)")
+        .option("--kind <kind>", "Filter: rules | skills | agents (default: all)")
         .option("--check", "Exit 1 on drift; no writes")
         .action(async (options = {}) => {
         const kinds = parseKind(options.kind);

package/dist/esm/cli/commands/worktree/router-dispatch.d.ts

@@ -8,6 +8,18 @@ export interface WorktreeCommandOptions {
     prefix?: string;
     dryRun?: boolean;
     force?: boolean;
+    /**
+     * Bypass the "primary must be on the expected branch" merge-cleanup
+     * refusal by switching a CLEAN primary checkout to that branch. Never
+     * bypasses the "primary is dirty" refusal — a dirty primary always
+     * refuses, regardless of this flag (see `decideMergeCleanup`).
+     */
+    switchPrimary?: boolean;
+    /**
+     * @deprecated Renamed to `switchPrimary`. Kept as an accepted alias only
+     * (mapped from the CLI's legacy `--stash-primary` flag) — it no longer
+     * stashes anything; a dirty primary always refuses regardless of this flag.
+     */
     stashPrimary?: boolean;
     noSetup?: boolean;
     /** Dependency hydration for `new` only: install-locked (default) or reconcile. */
@@ -41,7 +53,6 @@ export interface MergeCleanupPlan {
     readonly removeArgs: readonly string[];
     readonly fetchArgs: readonly string[];
     readonly mergeArgs: readonly string[];
-    readonly stashArgs?: readonly string[];
     readonly switchArgs?: readonly string[];
     readonly preservedPrimaryBranch?: string;
 }
@@ -54,7 +65,18 @@ export interface MergeCleanupDecisionInput {
     readonly currentBranch: string;
     readonly repoDirty: boolean;
     readonly targetDirty: boolean;
-    readonly stashPrimary?: boolean;
+    /**
+     * Bypasses the wrong-branch refusal for a CLEAN primary only. A dirty
+     * primary always refuses — see `decideMergeCleanup` — this never bypasses
+     * that refusal, and merge-cleanup never stashes primary state.
+     */
+    readonly switchPrimary?: boolean;
+    /**
+     * When the primary is dirty, optional porcelain -z lists the offending
+     * paths in the refusal message. Omitted messages stay generic (e.g. for
+     * unit tests that don't care about message content).
+     */
+    readonly repoPorcelainZ?: string;
     /**
      * When target is dirty, optional porcelain -z + slug enrich the refusal message
      * (scaffold-only vs other dirt). Omitted messages stay generic for unit tests.