@webpresso/agent-kit 3.3.1 → 3.3.3

package/dist/esm/ci/release-progress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Classify a GitHub Actions Release run into operator-facing progress phases.
+ *
+ * After Version Packages merge, agents must not sit on silent `npm view` polls:
+ * merge, native matrix, and npm publish are separate states. This pure helper
+ * maps job list snapshots (from `gh run view --json jobs`) into those states.
+ */
+export type ReleaseProgressPhase = "detect" | "native-matrix" | "publish" | "done" | "failed";
+export interface ReleaseJobSnapshot {
+    readonly name: string;
+    readonly status: string;
+    readonly conclusion: string | null | undefined;
+}
+export interface ReleaseProgress {
+    readonly phase: ReleaseProgressPhase;
+    readonly detail: string;
+    readonly native: {
+        readonly done: number;
+        readonly total: number;
+        readonly failed: number;
+        readonly inProgress: number;
+    };
+    readonly publishRunning: boolean;
+    readonly publishDone: boolean;
+    readonly publishFailed: boolean;
+}
+/**
+ * Classify release workflow jobs into a single progress phase for agent/ops reporting.
+ */
+export declare function classifyReleaseRunProgress(jobs: readonly ReleaseJobSnapshot[]): ReleaseProgress;
+/** Format one line for agent/ops logs (merge vs matrix vs publish). */
+export declare function formatReleaseProgressLine(progress: ReleaseProgress): string;
+/**
+ * Parse `gh run view <id> --json jobs` (or full run object with `jobs`) into snapshots.
+ * Production CLI and tests share this path so classification is never reimplemented.
+ */
+export declare function jobsFromGhRunViewJson(payload: unknown): ReleaseJobSnapshot[];

package/dist/esm/ci/release-progress.js

@@ -0,0 +1,139 @@
+/**
+ * Classify a GitHub Actions Release run into operator-facing progress phases.
+ *
+ * After Version Packages merge, agents must not sit on silent `npm view` polls:
+ * merge, native matrix, and npm publish are separate states. This pure helper
+ * maps job list snapshots (from `gh run view --json jobs`) into those states.
+ */
+const NATIVE_JOB_PREFIX = "Session memory native";
+function isNativeJob(name) {
+    return name.startsWith(NATIVE_JOB_PREFIX);
+}
+function isFailure(conclusion) {
+    return conclusion === "failure" || conclusion === "cancelled" || conclusion === "timed_out";
+}
+function isSuccess(conclusion) {
+    return conclusion === "success" || conclusion === "skipped";
+}
+/**
+ * Classify release workflow jobs into a single progress phase for agent/ops reporting.
+ */
+export function classifyReleaseRunProgress(jobs) {
+    const nativeJobs = jobs.filter((job) => isNativeJob(job.name));
+    const detect = jobs.find((job) => job.name === "Detect publishable versions");
+    const release = jobs.find((job) => job.name === "Release");
+    const nativeDone = nativeJobs.filter((job) => job.status === "completed" && isSuccess(job.conclusion)).length;
+    const nativeFailed = nativeJobs.filter((job) => job.status === "completed" && isFailure(job.conclusion)).length;
+    const nativeInProgress = nativeJobs.filter((job) => job.status === "in_progress").length;
+    const native = {
+        done: nativeDone,
+        total: nativeJobs.length,
+        failed: nativeFailed,
+        inProgress: nativeInProgress,
+    };
+    const publishRunning = release?.status === "in_progress";
+    const publishDone = release?.status === "completed" && isSuccess(release.conclusion);
+    const publishFailed = release?.status === "completed" && isFailure(release.conclusion);
+    if (nativeFailed > 0 || publishFailed) {
+        return {
+            phase: "failed",
+            detail: nativeFailed > 0
+                ? `Native matrix failed (${nativeFailed} cell(s))`
+                : `Release/publish job failed (${release?.conclusion ?? "unknown"})`,
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (publishDone) {
+        return {
+            phase: "done",
+            detail: "Release job completed successfully (check npm for version)",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (publishRunning || (native.total > 0 && nativeDone === native.total && release)) {
+        return {
+            phase: "publish",
+            detail: publishRunning
+                ? "Native matrix complete; Release/publish job in progress"
+                : "Native matrix complete; waiting for Release job",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (native.total > 0 && (nativeInProgress > 0 || nativeDone < native.total)) {
+        return {
+            phase: "native-matrix",
+            detail: `Building session-memory natives ${nativeDone}/${native.total} complete` +
+                (nativeInProgress > 0 ? ` (${nativeInProgress} in progress)` : ""),
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (detect && detect.status !== "completed") {
+        return {
+            phase: "detect",
+            detail: "Detecting whether this run will publish",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    return {
+        phase: "detect",
+        detail: "Release run starting",
+        native,
+        publishRunning,
+        publishDone,
+        publishFailed,
+    };
+}
+/** Format one line for agent/ops logs (merge vs matrix vs publish). */
+export function formatReleaseProgressLine(progress) {
+    return `release-progress phase=${progress.phase} native=${progress.native.done}/${progress.native.total} ${progress.detail}`;
+}
+/**
+ * Parse `gh run view <id> --json jobs` (or full run object with `jobs`) into snapshots.
+ * Production CLI and tests share this path so classification is never reimplemented.
+ */
+export function jobsFromGhRunViewJson(payload) {
+    if (payload == null || typeof payload !== "object") {
+        throw new Error("gh run view JSON must be an object with a jobs array");
+    }
+    const record = payload;
+    const jobsRaw = Array.isArray(payload)
+        ? payload
+        : Array.isArray(record.jobs)
+            ? record.jobs
+            : null;
+    if (!jobsRaw) {
+        throw new Error("gh run view JSON must include a jobs array");
+    }
+    return jobsRaw.map((entry, index) => {
+        if (entry == null || typeof entry !== "object") {
+            throw new Error(`jobs[${index}] must be an object`);
+        }
+        const job = entry;
+        const name = typeof job.name === "string" ? job.name : "";
+        const status = typeof job.status === "string" ? job.status : "";
+        if (!name || !status) {
+            throw new Error(`jobs[${index}] requires string name and status`);
+        }
+        const conclusion = job.conclusion === null || job.conclusion === undefined
+            ? null
+            : typeof job.conclusion === "string"
+                ? job.conclusion
+                : null;
+        return { name, status, conclusion };
+    });
+}

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

@@ -5,7 +5,7 @@
  * Lazy-loads subcommand modules based on the first argv to keep startup
  * cheap. Modeled on apps/cli-wp/src/cli.ts.
  */
-declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "public:readiness", "typecheck", "lint", "format", "rust-check", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "optional-tool-refresh", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
+declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "release-progress", "public:readiness", "typecheck", "lint", "format", "rust-check", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "optional-tool-refresh", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
 export type SupportedCommand = (typeof SUPPORTED_COMMANDS)[number];
 type RootHelpEntry = {
     readonly command: string;

package/dist/esm/cli/cli.js

@@ -55,6 +55,7 @@ const SUPPORTED_COMMANDS = [
     "e2e",
     "ci",
     "ci-preflight",
+    "release-progress",
     "public:readiness",
     "typecheck",
     "lint",
@@ -118,6 +119,10 @@ const ROOT_HELP_CORE_ENTRIES = [
         command: "ci-preflight",
         description: "Run the locally-runnable required CI checks fail-fast (the pre-push gate)",
     },
+    {
+        command: "release-progress",
+        description: "Report Release workflow phase (detect / native-matrix / publish) instead of silent npm view waits",
+    },
     {
         command: "public:readiness",
         description: "Run the public package readiness gate through the portable wp surface",
@@ -375,6 +380,10 @@ const COMMAND_REGISTRARS = {
         const { registerCiPreflightCommand } = await import("./commands/ci-preflight.js");
         registerCiPreflightCommand(cli);
     },
+    "release-progress": async (cli) => {
+        const { registerReleaseProgressCommand } = await import("./commands/release-progress.js");
+        registerReleaseProgressCommand(cli);
+    },
     "public:readiness": async (cli) => {
         const { registerPublicReadinessCommand } = await import("./commands/public-readiness.js");
         registerPublicReadinessCommand(cli);

package/dist/esm/cli/commands/audit-core.js

@@ -79,7 +79,15 @@ export async function runAuditDispatch(auditKind, targets, options, deps) {
         case "blueprint-pr-coverage": {
             const { auditBlueprintPrCoverage } = await import("#audit/blueprint-pr-coverage");
             const root = options.root ?? target ?? deps.root;
-            const baseRef = options.baseRef ?? options.base;
+            const explicitBaseRef = options.baseRef ?? options.base;
+            // Same pinned-base hazard as the branch-scoped audits: CI's
+            // `github.event.pull_request.base.sha` stops being the fork point once the
+            // branch is rebased, and this audit diffs `<baseRef>...HEAD`. Narrow it to
+            // the real fork point so coverage is judged on this PR's own files.
+            const { resolveBranchDiffBase } = await import("#git/changed-files");
+            const baseRef = explicitBaseRef
+                ? resolveBranchDiffBase(root, explicitBaseRef)
+                : explicitBaseRef;
             const result = auditBlueprintPrCoverage(root, { baseRef, headRef: options.headRef });
             return { kind: "repo-result", name: "blueprint-pr-coverage", result };
         }

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

@@ -9,7 +9,7 @@ import { STRYKER_COMMAND } from "#audit/run-stryker.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { addAffectedOptions, resolveAffectedTargets } from "#git/affected";
-import { defaultBranchBaseRef, getBranchRemovedFiles, getStagedRemovedFiles, } from "#git/changed-files";
+import { defaultBranchBaseRef, getBranchRemovedFiles, getStagedRemovedFiles, resolveBranchDiffBase, } from "#git/changed-files";
 import { runAuditDispatch } from "#cli/commands/audit-core.js";
 import { createCliLogSink } from "#cli/commands/quality-log-store.js";
 import { emitCliCommandOutput, runLoggedChildCommand } from "#cli/commands/quality-runner.js";
@@ -284,6 +284,17 @@ export function registerAuditCommand(cli) {
         let dispatchOptions = options;
         let auditScope = "full";
         let changeRemovesFile = false;
+        // A caller-supplied `--base` is a PINNED sha (CI passes
+        // `github.event.pull_request.base.sha`, which does not advance with the
+        // base branch). After a rebase it stops being the fork point, so scoping
+        // off it silently absorbs everything merged into the base branch since
+        // the PR opened. Narrow it to the real fork point once, and use that one
+        // value everywhere the branch scope is derived so the affected file set,
+        // the removal probe, and the audit's own base-vs-head range agree.
+        const explicitBaseRef = options.baseRef ?? options.base;
+        const branchBaseRef = branch && explicitBaseRef
+            ? resolveBranchDiffBase(auditRoot, explicitBaseRef)
+            : explicitBaseRef;
         if (affected || branch) {
             if (kind &&
                 AUDIT_KINDS.includes(kind) &&
@@ -309,7 +320,7 @@ export function registerAuditCommand(cli) {
                 cwd: auditRoot,
                 affected,
                 branch,
-                baseRef: options.baseRef ?? options.base,
+                baseRef: branchBaseRef,
                 explicitTargets: [],
                 policy: "fail-closed",
                 mapChangedFiles: (files) => files,
@@ -360,7 +371,7 @@ export function registerAuditCommand(cli) {
             changeRemovesFile = affected
                 ? affectedChangeRemovesFile(auditRoot, {
                     branch,
-                    baseRef: options.baseRef ?? options.base,
+                    baseRef: branchBaseRef,
                 })
                 : false;
             if (resolution.kind === "empty" && !changeRemovesFile) {
@@ -392,7 +403,7 @@ export function registerAuditCommand(cli) {
                     changedOnly: true,
                     affectedFiles: [],
                     root: options.root ?? resolution.cwd,
-                    baseRef: options.baseRef ?? options.base,
+                    baseRef: branchBaseRef,
                 };
             }
             if (resolution.kind === "scoped") {
@@ -404,7 +415,7 @@ export function registerAuditCommand(cli) {
                     changedOnly: true,
                     affectedFiles: [...resolution.targets],
                     root: options.root ?? resolution.cwd,
-                    baseRef: options.baseRef ?? options.base,
+                    baseRef: branchBaseRef,
                 };
             }
         }

package/dist/esm/cli/commands/blueprint/mutations.js

@@ -17,7 +17,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { parseBlueprint } from "#core/parser";
-import { escapeRegex } from "#utils/string";
+import { buildTaskHeaderRegexForId } from "#markdown/task-heading";
 import { openDb } from "#db/connection.js";
 import { resolveBlueprintProjectionDbPath, withMarkdownWriteLock } from "#db/paths.js";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
@@ -209,8 +209,7 @@ function upsertCompletedAt(content, isoDate) {
  * Returns { lineIndex, currentStatus } or null if not found.
  */
 function findTaskStatusLine(lines, taskId) {
-    const escapedId = escapeRegex(taskId);
-    const taskPattern = new RegExp(`^####\\s+(?:\\[[^\\]]+\\]\\s+)?Task\\s+${escapedId}[:\\s]`);
+    const taskPattern = buildTaskHeaderRegexForId(taskId);
     let inBlock = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i] ?? "";

package/dist/esm/cli/commands/init/mcp-spec.d.ts

@@ -36,13 +36,28 @@ export interface WebpressoInstallProbe {
  * machine. Probes the locations consumers use to install webpresso, in order
  * of stability:
  *
- *   1. the stable global `wp` shim available on PATH
- *   2. the currently executing `@webpresso/agent-kit` package
+ *   1. the stable global `wp` shim available on PATH (including the
+ *      vite-plus multi-package shim at `~/.vite-plus/bin/wp`)
+ *   2. the currently executing `@webpresso/agent-kit` package **only when it
+ *      is not a vite-plus `agent-kit#<installId>` payload path**
  *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
  *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- * Returns `null` when none of the candidates contain a usable `bin/wp`.
+ *
+ * Host MCP configs (Grok/Codex/etc.) must never be pinned to a versioned
+ * installId tree: the next `wp update` / `vp update -g` deletes that path and
+ * leaves every host with a dead launcher. Returns `null` when none of the
+ * candidates yield a durable `wp`.
  */
 export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
+/**
+ * True when `entryPath` is the stable vite-plus multi-package `wp` shim that
+ * dispatches to `@webpresso/agent-kit` via `~/.vite-plus/bins/wp.json`.
+ *
+ * Unlike {@link isWebpressoWpEntry}, this does **not** require realpath to land
+ * inside a package `bin/wp` tree — vite-plus's `wp` is a symlink to the `vp`
+ * binary, so package-root ownership is proven via the bins metadata instead.
+ */
+export declare function isVitePlusManagedWebpressoWp(entryPath: string): boolean;
 export declare function resolveWebpressoMcpEntry(probe?: WebpressoInstallProbe): {
     entryPath: string | null;
     checked: readonly string[];

package/dist/esm/cli/commands/init/mcp-spec.js

@@ -12,9 +12,10 @@
  */
 import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { isVersionedAgentKitPayloadPath } from "#cli/auto-update/self-invocation.js";
 import { pathCandidates } from "#runtime/command-exists.js";
 export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 /**
@@ -67,11 +68,17 @@ const WP_LAUNCHER_REQUIRED_RELATIVES = [
  * machine. Probes the locations consumers use to install webpresso, in order
  * of stability:
  *
- *   1. the stable global `wp` shim available on PATH
- *   2. the currently executing `@webpresso/agent-kit` package
+ *   1. the stable global `wp` shim available on PATH (including the
+ *      vite-plus multi-package shim at `~/.vite-plus/bin/wp`)
+ *   2. the currently executing `@webpresso/agent-kit` package **only when it
+ *      is not a vite-plus `agent-kit#<installId>` payload path**
  *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
  *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- * Returns `null` when none of the candidates contain a usable `bin/wp`.
+ *
+ * Host MCP configs (Grok/Codex/etc.) must never be pinned to a versioned
+ * installId tree: the next `wp update` / `vp update -g` deletes that path and
+ * leaves every host with a dead launcher. Returns `null` when none of the
+ * candidates yield a durable `wp`.
  */
 export function findWebpressoMcpEntry(probe = {}) {
     return resolveWebpressoMcpEntry(probe).entryPath;
@@ -79,6 +86,37 @@ export function findWebpressoMcpEntry(probe = {}) {
 function isUsableWebpressoMcpRoot(root) {
     return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
 }
+/**
+ * True when `entryPath` is the stable vite-plus multi-package `wp` shim that
+ * dispatches to `@webpresso/agent-kit` via `~/.vite-plus/bins/wp.json`.
+ *
+ * Unlike {@link isWebpressoWpEntry}, this does **not** require realpath to land
+ * inside a package `bin/wp` tree — vite-plus's `wp` is a symlink to the `vp`
+ * binary, so package-root ownership is proven via the bins metadata instead.
+ */
+export function isVitePlusManagedWebpressoWp(entryPath) {
+    try {
+        if (isVersionedAgentKitPayloadPath(entryPath))
+            return false;
+        const binDir = dirname(entryPath);
+        if (basename(binDir) !== "bin")
+            return false;
+        if (basename(dirname(binDir)) !== ".vite-plus")
+            return false;
+        const base = basename(entryPath).toLowerCase();
+        if (base !== "wp" && base !== "wp.exe")
+            return false;
+        const metaPath = join(dirname(binDir), "bins", "wp.json");
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+        return meta.package === "@webpresso/agent-kit";
+    }
+    catch {
+        return false;
+    }
+}
+function isDurableMcpEntryPath(entryPath) {
+    return !isVersionedAgentKitPayloadPath(entryPath);
+}
 export function resolveWebpressoMcpEntry(probe = {}) {
     const checked = [];
     if (probe.candidates === undefined) {
@@ -88,10 +126,17 @@ export function resolveWebpressoMcpEntry(probe = {}) {
         if (stableEntry) {
             checked.push(stableEntry);
             const packageWp = packageWpFromAdjacentNpmCmdShim(stableEntry);
-            if (packageWp !== null)
+            if (packageWp !== null && isDurableMcpEntryPath(packageWp)) {
                 return { entryPath: packageWp, checked };
+            }
             const verifierAllows = probe.stableEntryIsWebpresso?.(stableEntry) ?? true;
-            if (verifierAllows && isWebpressoWpEntry(stableEntry)) {
+            // Prefer the vite-plus multi-package shim before package-root ownership:
+            // it survives installId swaps and is what PATH `wp` resolves to in the
+            // default consumer install.
+            if (verifierAllows && isVitePlusManagedWebpressoWp(stableEntry)) {
+                return { entryPath: stableEntry, checked };
+            }
+            if (verifierAllows && isWebpressoWpEntry(stableEntry) && isDurableMcpEntryPath(stableEntry)) {
                 return { entryPath: stableEntry, checked };
             }
         }
@@ -103,6 +148,9 @@ export function resolveWebpressoMcpEntry(probe = {}) {
                 continue;
             checked.push(root);
             const wpBin = join(root, WP_BIN_RELATIVE);
+            // Never materialize host MCP configs against a vite-plus installId tree.
+            if (!isDurableMcpEntryPath(wpBin))
+                continue;
             if (isTrustedWebpressoPackageRoot(root))
                 return { entryPath: wpBin, checked };
         }

package/dist/esm/cli/commands/init/scaffold-agents-md.js

@@ -30,13 +30,11 @@ const TECH_STACK_RULES = [
     { dep: /^typescript$/, label: "TypeScript" },
 ];
 // Kept under the 8 KB (8192-byte) hard ceiling. The rendered template embeds
-// the full `native_tool_names` registry list, so this soft target tracks the
-// tool count: adding an MCP tool grows the list by ~15-17 bytes. Bumped
-// 8_100 -> 8_180 for the four-tool batch (wp_ci_preflight, wp_session_id,
-// wp_session_info, wp_review_run), which renders ~8_160 — still 30+ bytes under
-// 8_192. The 8_192 ceiling is the real guardrail; the next addition that would
-// breach it should trigger a conscious restructure (or exclude the
-// auto-generated tool list from the prose budget), not another reflexive bump.
+// the full `native_tool_names` registry list (~15-17 bytes per tool). Soft
+// target 8_180 leaves headroom under 8_192. The ui-compose batch
+// (wp_ui_blocks_list, wp_ui_compose, wp_ui_preview) required trimming catalog
+// AGENTS.md.tpl prose rather than raising the ceiling. Next breach of 8_192
+// should restructure (or stop embedding the full tool list), not bump again.
 export const AGENTS_MD_MAX_BYTES = 8_180;
 export function renderRepositoryMap(consumer) {
     const packages = consumer.workspacePackages;

package/dist/esm/cli/commands/package-manager.js

@@ -184,6 +184,9 @@ function runGlobalUpdateCommand(deps) {
                 else {
                     failed = true;
                     console.error(message);
+                    // Required step failed — stop so optional host refreshes cannot
+                    // look like a successful update after a broken agent-kit install.
+                    break;
                 }
             }
         }
@@ -195,6 +198,7 @@ function runGlobalUpdateCommand(deps) {
             else {
                 failed = true;
                 console.error(message);
+                break;
             }
         }
     }
@@ -313,8 +317,10 @@ function runAgentKitSelfUpdateStep(deps) {
             return spawnLike(status, new Error("another agent-kit installer is active; re-run `wp update` once it finishes"));
         case GUARD_EXIT_OWNERSHIP_LOST:
             return spawnLike(status, new Error("install lease ownership was lost mid-update; the takeover installer verifies the store — re-run `wp update` to confirm"));
-        default:
-            return spawnLike(status === 0 ? 1 : status, new Error(`self-install-guard exited ${status}`));
+        default: {
+            const code = status === 0 ? 1 : status;
+            return spawnLike(code, new Error(`agent-kit self-install failed (self-install-guard exit ${code}); re-run \`wp update\` or \`vp install -g @webpresso/agent-kit\``));
+        }
     }
 }
 function refreshCodexPlugin(deps) {

package/dist/esm/cli/commands/release-progress.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `wp release-progress` — report Release workflow phase (detect / native-matrix / publish).
+ *
+ * Agents must not poll only `npm view` after Version Packages merge. This command
+ * loads the live GitHub Actions job list and classifies progress via
+ * {@link classifyReleaseRunProgress}.
+ */
+import type { CAC } from "cac";
+import { type ReleaseJobSnapshot, type ReleaseProgress } from "#ci/release-progress.js";
+export declare const RELEASE_PROGRESS_COMMAND_HELP: string;
+export interface GhRunJobsFetcher {
+    (options: {
+        readonly runId: string;
+        readonly repo: string;
+    }): ReleaseJobSnapshot[];
+}
+export interface LatestReleaseRunResolver {
+    (options: {
+        readonly repo: string;
+    }): string;
+}
+/** Production fetcher: `gh run view --json jobs`. */
+export declare function fetchReleaseJobsViaGh(options: {
+    readonly runId: string;
+    readonly repo: string;
+}): ReleaseJobSnapshot[];
+/** Production resolver: latest Release workflow run for the repo. */
+export declare function resolveLatestReleaseRunIdViaGh(options: {
+    readonly repo: string;
+}): string;
+export interface RunReleaseProgressOptions {
+    readonly runId?: string | number;
+    readonly repo?: string;
+    readonly json?: boolean;
+    readonly fetchJobs?: GhRunJobsFetcher;
+    readonly resolveLatestRunId?: LatestReleaseRunResolver;
+    readonly stdout?: {
+        write(chunk: string): void;
+    };
+    readonly stderr?: {
+        write(chunk: string): void;
+    };
+}
+/**
+ * Core command body — injectable for tests; production uses gh CLI defaults.
+ */
+export declare function runReleaseProgress(options?: RunReleaseProgressOptions): {
+    readonly exitCode: number;
+    readonly progress: ReleaseProgress;
+    readonly runId: string;
+    readonly line: string;
+};
+export declare function registerReleaseProgressCommand(cli: CAC): void;