@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -0,0 +1,57 @@
+export declare const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
+/**
+ * The single canonical launch spec for the webpresso MCP server. `name` is the
+ * server alias every host registers; `args` are appended after the resolved
+ * `wp` launcher; `env` is forwarded to the spawned process by every
+ * env-capable channel. `WP_SKIP_UPDATE_CHECK=1` keeps MCP startup from doing a
+ * network update probe on every host session.
+ */
+export declare const WEBPRESSO_MCP_SPEC: {
+    readonly name: "webpresso";
+    readonly args: readonly ["mcp"];
+    readonly env: {
+        readonly WP_SKIP_UPDATE_CHECK: "1";
+    };
+};
+export type WebpressoMcpSpec = typeof WEBPRESSO_MCP_SPEC;
+/**
+ * Resolve `binary` against PATH, returning the first executable candidate.
+ * Returns the candidate as an absolute path: relative PATH entries (`bin`,
+ * `.`) resolve against the current working directory — persisting them
+ * verbatim into host configs would resolve differently in later sessions.
+ * No realpath is taken, so generated configs stay anchored to a stable
+ * global-bin symlink rather than a version-pinned store path.
+ */
+export declare function resolveExecutableOnPath(binary: string, env: NodeJS.ProcessEnv): string | null;
+export interface WebpressoInstallProbe {
+    /** Test seam — override the candidate roots. Default: probe in fixed order. */
+    candidates?: readonly string[];
+    /** Test seam — resolve the stable global `wp` shim available on PATH. */
+    stableEntry?: () => string | null;
+    /** Test seam — verify that a PATH entry is the Webpresso command. */
+    stableEntryIsWebpresso?: (entryPath: string) => boolean;
+}
+/**
+ * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
+ * 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
+ *   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`.
+ */
+export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
+export declare function resolveWebpressoMcpEntry(probe?: WebpressoInstallProbe): {
+    entryPath: string | null;
+    checked: readonly string[];
+};
+export declare function isWebpressoWpEntry(entryPath: string): boolean;
+/** Run a discovery probe with bounded output and SIGKILL escalation. */
+export declare function runQuiet(cmd: string, args: readonly string[], timeoutMs?: number): string | null;
+/** Launch tuple for the webpresso MCP server given a resolved `wp` launcher. */
+export declare function agentKitMcpLaunchCommand(entryPath: string): {
+    command: string;
+    args: string[];
+};

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

@@ -0,0 +1,273 @@
+/**
+ * Canonical Webpresso MCP server spec + shared `wp` binary resolver.
+ *
+ * One source of truth for how every supported host launches the webpresso MCP
+ * server. Each host channel (Claude plugin manifest, Codex plugin manifest,
+ * Codex `config.toml`, OpenCode `opencode.json`, Grok `.grok/config.toml`)
+ * projects this spec into its own config dialect. The two committed plugin
+ * manifests reference the launcher via `${CLAUDE_PLUGIN_ROOT}`/`${PLUGIN_ROOT}`;
+ * the setup-time writers resolve an absolute `bin/wp` path via
+ * {@link findWebpressoMcpEntry}. Compare channels *semantically* (command
+ * basename, args, env) — never byte-for-byte.
+ */
+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 { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { pathCandidates } from "#runtime/command-exists.js";
+export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
+/**
+ * The single canonical launch spec for the webpresso MCP server. `name` is the
+ * server alias every host registers; `args` are appended after the resolved
+ * `wp` launcher; `env` is forwarded to the spawned process by every
+ * env-capable channel. `WP_SKIP_UPDATE_CHECK=1` keeps MCP startup from doing a
+ * network update probe on every host session.
+ */
+export const WEBPRESSO_MCP_SPEC = {
+    name: WEBPRESSO_MCP_SERVER_NAME,
+    args: ["mcp"],
+    env: { WP_SKIP_UPDATE_CHECK: "1" },
+};
+/**
+ * Resolve `binary` against PATH, returning the first executable candidate.
+ * Returns the candidate as an absolute path: relative PATH entries (`bin`,
+ * `.`) resolve against the current working directory — persisting them
+ * verbatim into host configs would resolve differently in later sessions.
+ * No realpath is taken, so generated configs stay anchored to a stable
+ * global-bin symlink rather than a version-pinned store path.
+ */
+export function resolveExecutableOnPath(binary, env) {
+    for (const candidate of pathCandidates(binary, {
+        pathEnv: env.PATH,
+        pathExtEnv: env.PATHEXT,
+    })) {
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            if (process.platform !== "win32")
+                accessSync(candidate, constants.X_OK);
+            return isAbsolute(candidate) ? candidate : resolve(candidate);
+        }
+        catch {
+            // Continue scanning PATH.
+        }
+    }
+    return null;
+}
+const WP_BIN_RELATIVE = join("bin", "wp");
+const WP_LAUNCHER_REQUIRED_RELATIVES = [
+    WP_BIN_RELATIVE,
+    join("bin", "_run.js"),
+    join("bin", "runtime-lanes.js"),
+    join("bin", "runtime-manifest.json"),
+];
+/**
+ * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
+ * 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
+ *   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`.
+ */
+export function findWebpressoMcpEntry(probe = {}) {
+    return resolveWebpressoMcpEntry(probe).entryPath;
+}
+function isUsableWebpressoMcpRoot(root) {
+    return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
+}
+export function resolveWebpressoMcpEntry(probe = {}) {
+    const checked = [];
+    if (probe.candidates === undefined) {
+        const stableEntry = probe.stableEntry !== undefined
+            ? probe.stableEntry()
+            : resolveExecutableOnPath("wp", process.env);
+        if (stableEntry) {
+            checked.push(stableEntry);
+            const packageWp = packageWpFromAdjacentNpmCmdShim(stableEntry);
+            if (packageWp !== null)
+                return { entryPath: packageWp, checked };
+            const verifierAllows = probe.stableEntryIsWebpresso?.(stableEntry) ?? true;
+            if (verifierAllows && isWebpressoWpEntry(stableEntry)) {
+                return { entryPath: stableEntry, checked };
+            }
+        }
+    }
+    const candidateGroups = probe.candidates !== undefined ? [probe.candidates] : [defaultFixedCandidates()];
+    for (const candidates of candidateGroups) {
+        for (const root of candidates) {
+            if (!root)
+                continue;
+            checked.push(root);
+            const wpBin = join(root, WP_BIN_RELATIVE);
+            if (isTrustedWebpressoPackageRoot(root))
+                return { entryPath: wpBin, checked };
+        }
+    }
+    return { entryPath: null, checked };
+}
+function defaultFixedCandidates() {
+    const home = process.env.HOME || homedir();
+    const packageRoot = currentAgentKitPackageRoot();
+    const claudePlugin = join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit");
+    const bunGlobal = join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit");
+    return [packageRoot ?? "", claudePlugin, bunGlobal];
+}
+function currentAgentKitPackageRoot() {
+    let current = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 12; depth += 1) {
+        const packagePath = join(current, "package.json");
+        if (existsSync(packagePath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+                if (pkg.name === "@webpresso/agent-kit")
+                    return current;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function isUsableWebpressoPackageRoot(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return pkg.name === "@webpresso/agent-kit" && isUsableWebpressoMcpRoot(packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+function isPathInsideOrEqual(parent, candidate) {
+    const parentRoot = realpathSync(parent);
+    const candidateRoot = realpathSync(candidate);
+    const rel = relative(resolve(parentRoot), resolve(candidateRoot));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function isTrustedWebpressoPackageRoot(packageRoot) {
+    try {
+        if (!isUsableWebpressoPackageRoot(packageRoot))
+            return false;
+        const realPackageRoot = realpathSync(packageRoot);
+        const sourceRoot = currentAgentKitPackageRoot();
+        if (sourceRoot !== null && realPackageRoot === realpathSync(sourceRoot))
+            return true;
+        return trustedHomeInstallPackageRoots().some((anchor) => existsSync(anchor) && isPathInsideOrEqual(anchor, realPackageRoot));
+    }
+    catch {
+        return false;
+    }
+}
+function trustedHomeInstallPackageRoots() {
+    const home = process.env.HOME || homedir();
+    return [
+        join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit"),
+        join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit"),
+    ];
+}
+function packageWpFromAdjacentNpmCmdShim(entryPath) {
+    if (!entryPath.toLowerCase().endsWith(".cmd"))
+        return null;
+    const packageRoot = join(dirname(entryPath), "node_modules", "@webpresso", "agent-kit");
+    return isTrustedWebpressoPackageRoot(packageRoot) ? join(packageRoot, "bin", "wp") : null;
+}
+export function isWebpressoWpEntry(entryPath) {
+    try {
+        if (entryPath.toLowerCase().endsWith(".cmd"))
+            return false;
+        // Validate package ownership from the symlink target. Executing a binary
+        // and trusting its self-reported version lets any same-named PATH entry
+        // impersonate Webpresso.
+        const resolvedEntry = realpathSync(entryPath);
+        const packageRoot = dirname(dirname(resolvedEntry));
+        if (resolvedEntry !== join(packageRoot, WP_BIN_RELATIVE))
+            return false;
+        return isTrustedWebpressoPackageRoot(packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+const PROBE_SUPERVISOR = String.raw `
+const { spawn } = require("node:child_process");
+const input = JSON.parse(process.argv[1]);
+const child = spawn(input.cmd, input.args, {
+  detached: process.platform !== "win32",
+  env: { ...process.env, WP_SKIP_UPDATE_CHECK: "1" },
+  stdio: ["ignore", "pipe", "ignore"],
+  windowsHide: true,
+});
+let output = "";
+let timedOut = false;
+let finished = false;
+const signal = (name) => {
+  try {
+    if (process.platform !== "win32" && child.pid) process.kill(-child.pid, name);
+    else child.kill(name);
+  } catch {}
+};
+const finish = (value) => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(deadline);
+  clearTimeout(forceKill);
+  process.stdout.write(JSON.stringify(value));
+};
+let forceKill;
+const deadline = setTimeout(() => {
+  timedOut = true;
+  signal("SIGTERM");
+  forceKill = setTimeout(() => signal("SIGKILL"), input.killGraceMs);
+}, input.timeoutMs);
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  output += chunk;
+  if (Buffer.byteLength(output) > input.maxBytes) {
+    timedOut = true;
+    output = "";
+    child.stdout.destroy();
+    signal("SIGKILL");
+  }
+});
+child.on("error", () => finish(null));
+child.on("exit", (code) => finish(!timedOut && code === 0 ? output.trim() || null : null));
+`;
+/** Run a discovery probe with bounded output and SIGKILL escalation. */
+export function runQuiet(cmd, args, timeoutMs = 1_500) {
+    try {
+        const output = execFileSync(process.execPath, [
+            "-e",
+            PROBE_SUPERVISOR,
+            JSON.stringify({
+                cmd,
+                args: [...args],
+                timeoutMs,
+                killGraceMs: 100,
+                maxBytes: 64 * 1024,
+            }),
+        ], {
+            encoding: "utf8",
+            env: { ...process.env, WP_SKIP_UPDATE_CHECK: "1" },
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: timeoutMs + 1_000,
+            // JSON escaping can expand the supervisor's already-bounded 64 KiB payload.
+            maxBuffer: 512 * 1024,
+        });
+        return JSON.parse(output);
+    }
+    catch {
+        return null;
+    }
+}
+/** Launch tuple for the webpresso MCP server given a resolved `wp` launcher. */
+export function agentKitMcpLaunchCommand(entryPath) {
+    return { command: entryPath, args: [...WEBPRESSO_MCP_SPEC.args] };
+}

package/dist/esm/cli/commands/init/merge.d.ts

@@ -4,6 +4,7 @@ export interface MergeOptions {
     overwrite?: boolean;
     dryRun?: boolean;
     ownership?: MergeOwnership;
+    repoRoot?: string;
 }
 export interface MergeResult {
     targetPath: string;

package/dist/esm/cli/commands/init/merge.js

@@ -7,7 +7,33 @@
  * only.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { convergeUnitFromTarget } from "./convergence.js";
+import { resolveUntrackedCollision } from "./untracked-collision.js";
+function guardUntrackedOverwrite(targetPath, incoming, opts) {
+    if (!opts.repoRoot)
+        return;
+    const repoRoot = resolve(opts.repoRoot);
+    const target = resolve(targetPath);
+    const repoRelative = relative(repoRoot, target);
+    if (repoRelative.length === 0 ||
+        repoRelative === ".." ||
+        repoRelative.startsWith(`..${sep}`) ||
+        isAbsolute(repoRelative)) {
+        return;
+    }
+    const result = resolveUntrackedCollision({
+        unit: convergeUnitFromTarget(repoRoot, target, {
+            action: "modify",
+            scope: "repo-committed",
+            reason: "setup merge target",
+        }),
+        desiredContent: incoming,
+        force: opts.overwrite,
+    });
+    if (!result.ok)
+        throw new Error(result.error);
+}
 export function writeFileMerged(targetPath, incoming, opts = {}) {
     const exists = existsSync(targetPath);
     const existingContent = exists ? readFileSync(targetPath, "utf8") : null;
@@ -25,6 +51,7 @@ export function writeFileMerged(targetPath, incoming, opts = {}) {
     if (shouldOverwrite) {
         if (opts.dryRun)
             return { targetPath, action: "skipped-dry" };
+        guardUntrackedOverwrite(targetPath, incoming, opts);
         writeFileSync(targetPath, incoming);
         return { targetPath, action: "overwritten" };
     }
@@ -92,6 +119,8 @@ export function patchJsonFile(targetPath, patcher, opts = {}) {
     if (opts.dryRun) {
         return { targetPath, action: "skipped-dry" };
     }
+    if (exists)
+        guardUntrackedOverwrite(targetPath, incoming, opts);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, incoming);
     return { targetPath, action: exists ? "overwritten" : "created" };

package/dist/esm/cli/commands/init/package-root.d.ts

@@ -8,6 +8,13 @@ export interface ResolveAgentKitPackageRootOptions {
     readonly pathExtEnv?: string;
     readonly platform?: NodeJS.Platform;
     readonly requireCatalog?: boolean;
+    /**
+     * Optional cwd anchor used as a last-resort walk start when module/argv/PATH
+     * anchors cannot locate a root (virtual bunfs/vite moduleUrl, vitest entry).
+     * Not defaulted to process.cwd() so hermetic tests stay isolated from the
+     * monorepo checkout the test process runs in.
+     */
+    readonly cwd?: string;
 }
 export declare function isAgentKitPackageRoot(dir: string, options?: {
     readonly requireCatalog?: boolean;

package/dist/esm/cli/commands/init/package-root.js

@@ -84,13 +84,15 @@ export function isAgentKitPackageRoot(dir, options = {}) {
         return false;
     return hasStableAgentKitRootMarker(dir);
 }
+/** Max parent-walk hops from a start path. Deep pnpm/vitest/store layouts exceed 10. */
+const PACKAGE_ROOT_WALK_MAX_DEPTH = 32;
 export function findAgentKitPackageRoot(startPath, options = {}) {
     if (!isRunnablePath(startPath))
         return null;
     const platform = options.platform ?? process.platform;
     const pathModule = pathModuleForPlatform(platform);
     let dir = pathModule.dirname(startPath);
-    for (let depth = 0; depth < 10; depth++) {
+    for (let depth = 0; depth < PACKAGE_ROOT_WALK_MAX_DEPTH; depth++) {
         if (isAgentKitPackageRoot(dir, options))
             return dir;
         const parent = pathModule.dirname(dir);
@@ -113,7 +115,13 @@ export function resolveAgentKitPackageRoot(options = {}) {
         platform,
     });
     const requireCatalog = options.requireCatalog;
-    for (const startPath of [modulePath, argv1, execPath, pathResolvedBin, argv0]) {
+    // Opt-in cwd last: monorepo/test hosts often run from the package root when
+    // moduleUrl is virtual (bunfs/vite) or argv points outside the tree (vitest).
+    // Callers that want the fallback pass `cwd` explicitly (see hook launchers).
+    const cwdStart = typeof options.cwd === "string" && options.cwd.length > 0
+        ? join(options.cwd, "package.json")
+        : undefined;
+    for (const startPath of [modulePath, argv1, execPath, pathResolvedBin, argv0, cwdStart]) {
         const root = findAgentKitPackageRoot(startPath ?? undefined, { requireCatalog, platform });
         if (root)
             return root;

package/dist/esm/cli/commands/init/plugin-cache-prune.d.ts

@@ -10,9 +10,6 @@ export declare const PLUGIN_CACHE_TARGETS: readonly [{
 }, {
     readonly host: "opencode";
     readonly rootParts: readonly [".config", "opencode", "plugins", "cache"];
-}, {
-    readonly host: "windsurf";
-    readonly rootParts: readonly [".windsurf", "plugins", "cache"];
 }, {
     readonly host: "agents";
     readonly rootParts: readonly [".agents", "plugins", "cache"];

package/dist/esm/cli/commands/init/plugin-cache-prune.js

@@ -6,7 +6,6 @@ export const PLUGIN_CACHE_TARGETS = [
     { host: "codex", rootParts: [".codex", "plugins", "cache"] },
     { host: "opencode", rootParts: [".opencode", "plugins", "cache"] },
     { host: "opencode", rootParts: [".config", "opencode", "plugins", "cache"] },
-    { host: "windsurf", rootParts: [".windsurf", "plugins", "cache"] },
     { host: "agents", rootParts: [".agents", "plugins", "cache"] },
     { host: "factory", rootParts: [".factory", "plugins", "cache"] },
 ];

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

@@ -1,7 +1,7 @@
 import type { AgentkitConfig } from "./config.js";
 import type { ConsumerContext } from "./detect-consumer.js";
 import { type MergeOptions, type MergeResult } from "./merge.js";
-export declare const AGENTS_MD_MAX_BYTES = 8100;
+export declare const AGENTS_MD_MAX_BYTES = 8180;
 export declare function renderRepositoryMap(consumer: ConsumerContext): string;
 export declare function renderTechStack(consumer: ConsumerContext): string;
 export interface ScaffoldAgentsMdInput {

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

@@ -29,9 +29,15 @@ const TECH_STACK_RULES = [
     { dep: /^zod$/, label: "Zod" },
     { dep: /^typescript$/, label: "TypeScript" },
 ];
-// Kept under 8 KB (8192 bytes); headroom above 8_000 absorbs the longer
-// `wp_ultragoal_*` native tool names in the Codex routing surface.
-export const AGENTS_MD_MAX_BYTES = 8_100;
+// 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.
+export const AGENTS_MD_MAX_BYTES = 8_180;
 export function renderRepositoryMap(consumer) {
     const packages = consumer.workspacePackages;
     if (packages.length === 0) {

package/dist/esm/cli/commands/init/scaffold-base-kit.d.ts

@@ -14,6 +14,26 @@ interface PackageJsonLike {
     [key: string]: unknown;
 }
 export declare function readSetupWpActionRef(metaUrl: string): string;
+/**
+ * Idempotent, inject-by-content-absence repair for the managed `wp audit
+ * guardrails` CI step. On every `wp setup`, re-inserts the step into any
+ * wp-enabled quality workflow whose content lacks a guardrails invocation, so a
+ * consumer who deleted the step (with or without its comments) gets it back —
+ * and therefore keeps inheriting new guardrails (e.g. typescript-version) on
+ * their next agent-kit bump. Returns the content unchanged when the step is
+ * already present, the workflow is not a wp quality pipeline, no test step
+ * anchor exists, or `repoAlreadyWired` is true (guardrails already run in a
+ * sibling workflow of the same repo — see `migrateConsumerWorkflows`, and
+ * tech-debt h-017: without this check a consumer who deliberately hosts
+ * guardrails in a dedicated `guardrails.yml` got a duplicate step injected
+ * into `ci.yml` on every `wp setup`).
+ *
+ * `hasGuardrailsInvocation`/`findLiveTestRunAnchor` come from the shared
+ * `ci-guardrails-detection` module also used by `auditCiGuardrailsWiring`, so
+ * the audit and this injector can never disagree about what counts as a wired
+ * guardrails step or a live test-run anchor (tech-debt h-016).
+ */
+export declare function ensureGuardrailsCiStep(content: string, repoAlreadyWired?: boolean): string;
 export declare function readAgentConfigVersion(metaUrl: string): string;
 export declare function collectRuntimeContractGuidance(packageJson: PackageJsonLike | null | undefined): RuntimeContractGuidance;
 export declare const BASE_KIT_QUALITY_TARGETS: string[];

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { writeFileMerged } from "./merge.js";
 import { resolveAgentKitPackageRoot } from "./package-root.js";
+import { findLiveTestRunAnchor, hasGuardrailsInvocation } from "#audit/ci-guardrails-detection.js";
 import { readPackageVersion } from "#cli/utils";
 import { SETUP_WP_ACTION_REF } from "#build/release-action-ref.js";
 const AUTHORING_TIME_DEPENDENCIES = [
@@ -162,16 +163,71 @@ function migrateWorkflowContent(content, actionRef, version) {
     })
         .join("\n");
 }
+// A workflow is a wp-enabled quality pipeline when it both installs the `wp`
+// runtime and runs the default test suite. Gating on a wp-runtime anchor keeps
+// injection off non-wp workflows (a reusable-workflow release.yml, or
+// agent-kit's own source-built CI) that must never get a consumer step. Two
+// install shapes count as the anchor: the `setup-wp` GitHub Action, and a
+// global npm/pnpm/vp install of `@webpresso/agent-kit` — the documented
+// third-party quick start for consumers that don't use the action (see
+// `package-conventions.md`; e.g. ozby/edge-matte's ci.yml).
+const SETUP_WP_MARKER = "setup-wp@";
+const GLOBAL_AGENT_KIT_INSTALL = /^(?=.*\b(?:npm|pnpm|vp)\s+(?:install|i|add)\b)(?=.*(?:-g\b|--global\b))(?=.*@webpresso\/agent-kit\b).*$/imu;
+function hasWpRuntimeAnchor(content) {
+    return content.includes(SETUP_WP_MARKER) || GLOBAL_AGENT_KIT_INSTALL.test(content);
+}
+/**
+ * Idempotent, inject-by-content-absence repair for the managed `wp audit
+ * guardrails` CI step. On every `wp setup`, re-inserts the step into any
+ * wp-enabled quality workflow whose content lacks a guardrails invocation, so a
+ * consumer who deleted the step (with or without its comments) gets it back —
+ * and therefore keeps inheriting new guardrails (e.g. typescript-version) on
+ * their next agent-kit bump. Returns the content unchanged when the step is
+ * already present, the workflow is not a wp quality pipeline, no test step
+ * anchor exists, or `repoAlreadyWired` is true (guardrails already run in a
+ * sibling workflow of the same repo — see `migrateConsumerWorkflows`, and
+ * tech-debt h-017: without this check a consumer who deliberately hosts
+ * guardrails in a dedicated `guardrails.yml` got a duplicate step injected
+ * into `ci.yml` on every `wp setup`).
+ *
+ * `hasGuardrailsInvocation`/`findLiveTestRunAnchor` come from the shared
+ * `ci-guardrails-detection` module also used by `auditCiGuardrailsWiring`, so
+ * the audit and this injector can never disagree about what counts as a wired
+ * guardrails step or a live test-run anchor (tech-debt h-016).
+ */
+export function ensureGuardrailsCiStep(content, repoAlreadyWired = false) {
+    if (hasGuardrailsInvocation(content))
+        return content;
+    if (repoAlreadyWired)
+        return content;
+    if (!hasWpRuntimeAnchor(content))
+        return content;
+    const anchorStepStart = findLiveTestRunAnchor(content);
+    if (anchorStepStart === -1)
+        return content;
+    const lines = content.split("\n");
+    // Safe: anchorStepStart is an index returned by findLiveTestRunAnchor over
+    // this same content.split("\n"), so it is always within lines' bounds here.
+    const indent = lines[anchorStepStart].match(/^(\s*)/u)?.[1] ?? "";
+    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  run: wp audit guardrails`);
+    return lines.join("\n");
+}
 function migrateConsumerWorkflows(repoRoot, actionRef, version, options) {
     const workflowDir = join(repoRoot, ".github", "workflows");
     if (!existsSync(workflowDir))
         return [];
-    return readdirSync(workflowDir)
-        .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
-        .map((name) => {
+    const names = readdirSync(workflowDir).filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"));
+    // Read every workflow's original content once, up front, so per-file
+    // injection below can see the REPO-LEVEL wiring state (mirrors how
+    // `auditCiGuardrailsWiring` reasons across all workflows) instead of only
+    // the file it happens to be looking at. Without this, a consumer who
+    // deliberately hosts guardrails in a dedicated `guardrails.yml` gets a
+    // duplicate step injected into `ci.yml` on every `wp setup` (h-017).
+    const entries = names.map((name) => [name, readFileSync(join(workflowDir, name), "utf8")]);
+    const repoAlreadyWired = entries.some(([, content]) => hasGuardrailsInvocation(content));
+    return entries.map(([name, existing]) => {
         const targetPath = join(workflowDir, name);
-        const existing = readFileSync(targetPath, "utf8");
-        const migrated = migrateWorkflowContent(existing, actionRef, version);
+        const migrated = ensureGuardrailsCiStep(migrateWorkflowContent(existing, actionRef, version), repoAlreadyWired);
         if (migrated === existing)
             return { targetPath, action: "identical" };
         if (options.dryRun)

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/emitters/grok.d.ts

@@ -1,14 +1,20 @@
 /**
  * Grok Build native project hooks emitter.
  *
- * Writes a project-local `.grok/hooks.json` surface with managed commands
- * labeled `WP_HOOK_HOST=grok`. Claude freeload remains the fallback delivery
- * path; this is the first-class native project surface for doctor/setup.
+ * Grok reads project hook configs from `.grok/hooks/*.json` — a near-clone of
+ * the Claude Code hook contract (stdin event JSON incl. hookEventName/cwd,
+ * regex matchers, exit code 2 = deny, JSON stdout for decisions). We write one
+ * managed file, `.grok/hooks/webpresso.json`, with commands labeled
+ * `WP_HOOK_HOST=grok`. Hooks are trust-gated: the user must run `/hooks-trust`
+ * once in Grok before they fire (fail-open on timeout).
+ *
+ * Managed events are the intersection of WP_HOOK_SPECS with Grok's documented
+ * event set — notably Grok has no PermissionRequest event (it has
+ * PermissionDenied instead), so that spec is skipped.
  */
-export declare const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks.json";
+export declare const GROK_HOOKS_DIR_RELATIVE_PATH = ".grok/hooks";
+export declare const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks/webpresso.json";
 export type GrokHooksDocument = {
-    readonly version: 1;
-    readonly host: "grok";
     readonly hooks: Readonly<Record<string, readonly {
         readonly matcher?: string;
         readonly hooks: readonly {
@@ -19,8 +25,8 @@ export type GrokHooksDocument = {
     }[]>>;
 };
 /**
- * Build managed Grok hook groups. PreToolUse uses a broad Bash|Write|Edit matcher;
- * PermissionRequest and SessionStart are included without matchers.
+ * Build the managed Grok hook document (Claude-contract wrapped shape:
+ * `{ "hooks": { Event: [ { matcher?, hooks: [...] } ] } }`).
  */
 export declare function buildGrokHookDocument(input: {
     readonly resolveBin: (name: string) => string;