@webpresso/agent-kit 3.2.0 → 3.3.1

package/dist/esm/cli/commands/init/convergence-apply.js

@@ -2,21 +2,179 @@ import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { convergeUnitFromTarget, deriveCommitAllowlist } from "./convergence.js";
 export { resolveUntrackedCollision } from "./untracked-collision.js";
-const GIT_TIMEOUT_MS = 15_000;
-function git(repoRoot, args) {
+/** Bounded timeout for non-hook Git probes (status, add, rev-parse, diff-tree). */
+export const GIT_PROBE_TIMEOUT_MS = 15_000;
+/**
+ * Default wall for the single hookful `git commit`. Consumer pre-commit chains
+ * (format + audits) routinely exceed the probe budget; Node's spawnSync kills
+ * the child with SIGTERM when `timeout` elapses, which left staged residue and
+ * multi-line partial hook output that looked like success.
+ *
+ * 10 minutes is a durable consumer budget, not infinite hang. Operators can
+ * raise/lower via `WP_SETUP_COMMIT_TIMEOUT_MS` or `AuthorCommitOptions.commitTimeoutMs`.
+ */
+export const DEFAULT_GIT_COMMIT_TIMEOUT_MS = 600_000;
+/** Max stdout+stderr retained from probe git subprocesses (Node spawnSync maxBuffer). */
+export const GIT_MAX_BUFFER = 1024 * 1024;
+/**
+ * Max stdout+stderr for the single hookful `git commit`. Quiet hooks cost nothing
+ * (Node does not preallocate); chatty consumer format+audit chains can exceed 1 MiB
+ * and would otherwise die with ENOBUFS+SIGTERM mid-commit.
+ */
+export const GIT_COMMIT_MAX_BUFFER = 16 * 1024 * 1024;
+/** Hook output snippet size kept in first-class failure diagnoses (tail, not head). */
+const HOOK_OUTPUT_SNIPPET_CHARS = 800;
+/** spawnSync error codes that mean maxBuffer / stdio overflow killed the child. */
+const BUFFER_OVERFLOW_ERROR_CODES = new Set(["ENOBUFS", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"]);
+function git(repoRoot, args, timeoutMs, maxBuffer = GIT_MAX_BUFFER) {
     const result = spawnSync("git", [...args], {
         cwd: repoRoot,
         encoding: "utf8",
-        timeout: GIT_TIMEOUT_MS,
-        maxBuffer: 1024 * 1024,
+        // Node: timeout > 0 arms SIGTERM; 0 / omitted means no artificial wall.
+        ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+        maxBuffer,
         stdio: ["ignore", "pipe", "pipe"],
     });
+    const errorCode = result.error !== undefined && "code" in result.error && result.error.code != null
+        ? String(result.error.code)
+        : null;
+    const timedOut = errorCode === "ETIMEDOUT";
     return {
         ok: result.status === 0 && !result.error,
-        stdout: result.stdout.trim(),
-        stderr: result.stderr.trim(),
+        stdout: (result.stdout ?? "").trim(),
+        stderr: (result.stderr ?? "").trim(),
+        timedOut,
+        signal: result.signal,
+        errorCode,
     };
 }
+/** True when spawnSync killed the child for maxBuffer / stdio overflow. */
+export function isBufferOverflowErrorCode(code) {
+    return typeof code === "string" && BUFFER_OVERFLOW_ERROR_CODES.has(code);
+}
+/**
+ * Resolve the hookful-commit timeout. Preference order:
+ * 1. explicit `commitTimeoutMs` option (tests / programmatic callers)
+ * 2. `WP_SETUP_COMMIT_TIMEOUT_MS` env (operator override)
+ * 3. {@link DEFAULT_GIT_COMMIT_TIMEOUT_MS}
+ *
+ * Values must be finite numbers ≥ 0. `0` disables the artificial wall (Node default).
+ */
+export function resolveCommitTimeoutMs(options) {
+    const env = options?.env ?? process.env;
+    if (typeof options?.commitTimeoutMs === "number" &&
+        Number.isFinite(options.commitTimeoutMs) &&
+        options.commitTimeoutMs >= 0) {
+        return options.commitTimeoutMs;
+    }
+    const raw = env.WP_SETUP_COMMIT_TIMEOUT_MS;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return DEFAULT_GIT_COMMIT_TIMEOUT_MS;
+}
+function appendHookOutput(diagnosis, hookOutput) {
+    const trimmed = hookOutput?.trim();
+    if (!trimmed)
+        return diagnosis;
+    // Keep the tail: failing audits / last lines at kill time matter more than husky banner.
+    const snippet = trimmed.length > HOOK_OUTPUT_SNIPPET_CHARS
+        ? `…${trimmed.slice(-HOOK_OUTPUT_SNIPPET_CHARS)}`
+        : trimmed;
+    return `${diagnosis}\n--- hook output (truncated) ---\n${snippet}`;
+}
+/** First-class timeout diagnosis; partial hook stdout/stderr is diagnostic only. */
+export function formatCommitTimeoutError(options) {
+    const budget = options.timeoutMs > 0
+        ? `${options.timeoutMs}ms`
+        : "the configured budget (no artificial wall was set, but the process was still interrupted)";
+    const diagnosis = `Convergence commit timed out after ${budget} while repository hooks were still running. ` +
+        `Node spawnSync kills the git process with SIGTERM on timeout, so no setup commit was authored. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `Re-run after hooks complete, raise WP_SETUP_COMMIT_TIMEOUT_MS / commitTimeoutMs, or fix slow hooks. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
+/**
+ * First-class interrupt diagnosis for non-timeout signal kills (operator kill,
+ * external SIGTERM/SIGKILL). Must not surface raw hook "passed" lines as the
+ * leading operator message.
+ */
+export function formatCommitInterruptError(options) {
+    const diagnosis = `Convergence commit was interrupted by ${options.signal} before completion, so no setup commit was authored. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `This is not a successful setup run. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
+/**
+ * First-class diagnosis when Node spawnSync kills the child because hook/git
+ * output exceeded maxBuffer (ENOBUFS / ERR_CHILD_PROCESS_STDIO_MAXBUFFER).
+ * Distinct from budget timeout and from external signal kills.
+ */
+export function formatCommitBufferError(options) {
+    const code = options.errorCode?.trim() || "ENOBUFS";
+    const diagnosis = `Convergence commit failed because git/hook output exceeded the spawnSync maxBuffer limit ` +
+        `(${options.maxBufferBytes} bytes; Node error ${code}), so no setup commit was authored. ` +
+        `This is a buffer/output-limit failure, not a time budget timeout and not an external kill. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `Reduce hook verbosity, raise the maxBuffer only with measured need, or fix chatty hooks. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
+/**
+ * Classify a failed hookful `git commit` result.
+ *
+ * Order (first match wins):
+ * 1. `timedOut` (spawnSync ETIMEDOUT) → budget timeout diagnosis
+ * 2. buffer overflow (ENOBUFS / ERR_CHILD_PROCESS_STDIO_MAXBUFFER) → buffer-limit diagnosis
+ * 3. non-null `signal` → interrupt diagnosis (names the signal)
+ * 4. otherwise → hook/git stderr when present, else spawn errorCode / generic preserved-index
+ *
+ * Never lead with bare hook "passed" lines for first-class failure paths.
+ */
+export function classifyCommitFailure(result, timeoutMs, maxBufferBytes = GIT_COMMIT_MAX_BUFFER) {
+    const hookOutput = [result.stderr, result.stdout].filter(Boolean).join("\n");
+    if (result.timedOut) {
+        return formatCommitTimeoutError({ timeoutMs, hookOutput });
+    }
+    if (isBufferOverflowErrorCode(result.errorCode)) {
+        return formatCommitBufferError({
+            maxBufferBytes,
+            errorCode: result.errorCode,
+            hookOutput,
+        });
+    }
+    if (result.signal) {
+        return formatCommitInterruptError({ signal: result.signal, hookOutput });
+    }
+    if (hookOutput) {
+        if (result.errorCode) {
+            return `${hookOutput}\n(spawn error ${result.errorCode})`;
+        }
+        return hookOutput;
+    }
+    if (result.errorCode) {
+        return `git commit failed (spawn error ${result.errorCode}); hook changes were preserved.`;
+    }
+    return "git commit failed; hook changes were preserved.";
+}
+/**
+ * Prefix every line of a setup failure so multi-line timeout diagnoses stay
+ * labeled when printed via console.error (avoids a single `wp setup: ` on the
+ * first line and bare hook "passed" lines after it).
+ */
+export function formatWpSetupError(message) {
+    const body = message.trimEnd();
+    if (body.length === 0)
+        return "wp setup: Unable to author convergence commit.";
+    return body
+        .split("\n")
+        .map((line) => `wp setup: ${line}`)
+        .join("\n");
+}
 function lines(value) {
     return value.length === 0 ? [] : value.split("\n").filter(Boolean).sort();
 }
@@ -32,8 +190,8 @@ function readPorcelainStatus(repoRoot, gitPath) {
     ], {
         cwd: repoRoot,
         encoding: "utf8",
-        timeout: GIT_TIMEOUT_MS,
-        maxBuffer: 1024 * 1024,
+        timeout: GIT_PROBE_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
         stdio: ["ignore", "pipe", "pipe"],
     });
     if (result.status !== 0 || result.error)
@@ -52,7 +210,8 @@ function readPorcelainStatus(repoRoot, gitPath) {
     return entries;
 }
 function isIgnored(repoRoot, gitPath) {
-    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath]).ok;
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath], GIT_PROBE_TIMEOUT_MS)
+        .ok;
 }
 export function collectAppliedConvergeUnits(repoRoot, candidates) {
     const units = [];
@@ -107,31 +266,42 @@ export function authorConvergenceCommit(options) {
         return { status: "skipped-ci", ok: true, allowlist };
     if (allowlist.length === 0)
         return { status: "no-change", ok: true, allowlist };
-    const before = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    const probe = (args) => git(options.repoRoot, args, GIT_PROBE_TIMEOUT_MS);
+    const before = probe(["rev-parse", "--verify", "HEAD"]);
     if (!before.ok) {
         return { status: "failed", ok: false, allowlist, error: before.stderr || "Missing HEAD." };
     }
-    const add = git(options.repoRoot, ["add", "--", ...allowlist]);
+    const add = probe(["add", "--", ...allowlist]);
     if (!add.ok) {
         return { status: "failed", ok: false, allowlist, error: add.stderr || "git add failed." };
     }
-    const staged = git(options.repoRoot, ["diff", "--cached", "--name-only"]);
+    const staged = probe(["diff", "--cached", "--name-only"]);
     if (!staged.ok) {
         return { status: "failed", ok: false, allowlist, error: staged.stderr || "git diff failed." };
     }
     if (lines(staged.stdout).length === 0) {
         return { status: "no-change", ok: true, allowlist };
     }
-    const commit = git(options.repoRoot, ["commit", "-m", options.message]);
+    const commitTimeoutMs = resolveCommitTimeoutMs({
+        commitTimeoutMs: options.commitTimeoutMs,
+    });
+    const budgetLabel = commitTimeoutMs > 0
+        ? commitTimeoutMs >= 60_000
+            ? `up to ${Math.round(commitTimeoutMs / 60_000)}m`
+            : `up to ${commitTimeoutMs}ms`
+        : "no artificial time wall";
+    // stderr: setup success path stays machine-friendly on stdout; hooks can take minutes.
+    console.error(`wp setup: running repository pre-commit hooks (${budgetLabel})…`);
+    const commit = git(options.repoRoot, ["commit", "-m", options.message], commitTimeoutMs, GIT_COMMIT_MAX_BUFFER);
     if (!commit.ok) {
         return {
             status: "failed",
             ok: false,
             allowlist,
-            error: commit.stderr || commit.stdout || "git commit failed; hook changes were preserved.",
+            error: classifyCommitFailure(commit, commitTimeoutMs, GIT_COMMIT_MAX_BUFFER),
         };
     }
-    const committedHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    const committedHead = probe(["rev-parse", "--verify", "HEAD"]);
     if (!committedHead.ok) {
         return {
             status: "failed",
@@ -140,11 +310,7 @@ export function authorConvergenceCommit(options) {
             error: committedHead.stderr || "Unable to validate the authored commit.",
         };
     }
-    const committedParent = git(options.repoRoot, [
-        "rev-parse",
-        "--verify",
-        `${committedHead.stdout}^`,
-    ]);
+    const committedParent = probe(["rev-parse", "--verify", `${committedHead.stdout}^`]);
     if (!committedParent.ok || committedParent.stdout !== before.stdout) {
         return {
             status: "failed",
@@ -154,7 +320,7 @@ export function authorConvergenceCommit(options) {
             error: "The observed commit does not directly follow the recorded HEAD; no rollback was attempted. Inspect Git history and recover manually.",
         };
     }
-    const committedPathsResult = git(options.repoRoot, [
+    const committedPathsResult = probe([
         "diff-tree",
         "--root",
         "--no-commit-id",
@@ -184,7 +350,7 @@ export function authorConvergenceCommit(options) {
             commit: committedHead.stdout,
         };
     }
-    const currentHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    const currentHead = probe(["rev-parse", "--verify", "HEAD"]);
     if (!currentHead.ok || currentHead.stdout !== committedHead.stdout) {
         return {
             status: "failed",
@@ -196,7 +362,7 @@ export function authorConvergenceCommit(options) {
             error: "The setup-authored commit changed before validation; no rollback was attempted. Inspect Git history and recover manually.",
         };
     }
-    const rollback = git(options.repoRoot, ["reset", "--mixed", before.stdout]);
+    const rollback = probe(["reset", "--mixed", before.stdout]);
     if (!rollback.ok) {
         return {
             status: "failed",

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

@@ -84,6 +84,8 @@ export interface ResolveCatalogDirOptions {
     readonly argv0?: string;
     readonly argv1?: string;
     readonly pathEnv?: string;
+    readonly pathExtEnv?: string;
+    readonly platform?: NodeJS.Platform;
 }
 export declare function resolveCatalogDir(options?: ResolveCatalogDirOptions): string;
 export declare function formatHostSetupSurfaceVisibility(input: {

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

@@ -24,7 +24,7 @@ import { isAgentKitSourceRepo } from "./source-repo-hook-policy.js";
 import { summarizeResults } from "./merge.js";
 import { WritePlan, collectRepoWriteEntries, renderWritePlan } from "./write-plan.js";
 import { writeConvergenceState } from "./convergence-state.js";
-import { authorConvergenceCommit, collectAppliedConvergeUnits, } from "./convergence-apply.js";
+import { authorConvergenceCommit, collectAppliedConvergeUnits, formatWpSetupError, } from "./convergence-apply.js";
 import { prepareRepositoryForConvergence } from "./git-convergence.js";
 import { collectUserScopeSteps, userScopeStepsToEntries, } from "./user-scope-plan.js";
 import { clearUserScopeConsentMarker, resolveUserScopeConsent, writeUserScopeConsentMarker, } from "./user-scope-consent.js";
@@ -1979,7 +1979,7 @@ export async function runInit(flags, deps = {}) {
                 isCi: isCiEnvironment,
             });
             if (!commitResult.ok) {
-                console.error(`wp setup: ${commitResult.error ?? "Unable to author convergence commit."}`);
+                console.error(formatWpSetupError(commitResult.error ?? "Unable to author convergence commit."));
                 return EXIT_WRITE_FAIL;
             }
             if (commitResult.status === "committed") {

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/scaffold-base-kit.d.ts

@@ -21,10 +21,19 @@ export declare function readSetupWpActionRef(metaUrl: string): string;
  * 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, or no test step
- * anchor exists.
+ * 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): string;
+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,12 +163,6 @@ function migrateWorkflowContent(content, actionRef, version) {
     })
         .join("\n");
 }
-// Detects whether a workflow already invokes `wp audit guardrails`, keyed on the
-// command itself (not a `wp` prefix nor a marker comment) — mirrors how
-// `hasAuditBlock()` (audit-hooks scaffolder) self-heals the pre-commit hook by
-// scanning for the invocation string, so re-injection works even if a consumer
-// stripped every surrounding comment.
-const GUARDRAILS_CI_INVOCATION = /\baudit guardrails\b/u;
 // 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
@@ -178,7 +173,6 @@ const GUARDRAILS_CI_INVOCATION = /\baudit guardrails\b/u;
 // `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;
-const GUARDRAILS_CI_TEST_RUN = /(?:\bvp\s+run\s+test\b|\bpnpm\s+(?:run\s+)?test\b|\bnpm\s+(?:run\s+)?test\b|\bbun\s+(?:run\s+)?test\b|\bwp\s+test\b|\bvitest\s+run\b)/iu;
 function hasWpRuntimeAnchor(content) {
     return content.includes(SETUP_WP_MARKER) || GLOBAL_AGENT_KIT_INSTALL.test(content);
 }
@@ -189,30 +183,31 @@ function hasWpRuntimeAnchor(content) {
  * 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, or no test step
- * anchor exists.
+ * 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) {
-    if (GUARDRAILS_CI_INVOCATION.test(content))
+export function ensureGuardrailsCiStep(content, repoAlreadyWired = false) {
+    if (hasGuardrailsInvocation(content))
+        return content;
+    if (repoAlreadyWired)
         return content;
     if (!hasWpRuntimeAnchor(content))
         return content;
-    const lines = content.split("\n");
-    let anchorStepStart = -1;
-    let lastStepStart = -1;
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index];
-        if (line.trim().startsWith("#"))
-            continue;
-        if (/^\s*-\s/u.test(line))
-            lastStepStart = index;
-        if (GUARDRAILS_CI_TEST_RUN.test(line)) {
-            anchorStepStart = lastStepStart;
-            break;
-        }
-    }
+    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");
@@ -221,12 +216,18 @@ 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 = ensureGuardrailsCiStep(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/index.js

@@ -581,7 +581,9 @@ export function disableManagedHooksFromManifest(input, manifest, vendors) {
     return result;
 }
 export function resolvePackageRootForHookLaunchers(options = {}) {
-    return resolveAgentKitPackageRootOrThrow("wp setup: could not locate @webpresso/agent-kit package root for hook launchers.", options);
+    // Default cwd so vitest/bunfs hosts that lose moduleUrl still resolve from
+    // the monorepo/package checkout the process is running in (CI flake fix).
+    return resolveAgentKitPackageRootOrThrow("wp setup: could not locate @webpresso/agent-kit package root for hook launchers.", { cwd: process.cwd(), ...options });
 }
 /**
  * The `wp hook <sub>` subcommand maps each catalogued `wp-*` hook bin to the

package/dist/esm/cli/commands/init/scaffolders/file-transaction.d.ts

@@ -1,5 +1,20 @@
-/** Serialize a complete read/modify/write transaction for a host config file. */
-export declare function withScaffolderFileLock<T>(path: string, action: () => T): T;
+/**
+ * Test-only seams following the `claimInstallLock` options precedent. `isAlive`
+ * and `now` make liveness/age deterministic; `onBeforeReclaimDelete` fires while
+ * the reaper is held, just before a stale lock is removed, so a test can prove
+ * reclaim is serialized. Never supplied in production.
+ */
+export interface ScaffolderLockSeams {
+    readonly isAlive?: (pid: number) => boolean;
+    readonly now?: () => number;
+    readonly onBeforeReclaimDelete?: () => void;
+}
+/**
+ * Serialize a complete read/modify/write transaction for a host config file.
+ * These are local single-machine home-config locks (`~/.codex`, `~/.grok`), so
+ * owner-pid liveness is meaningful; this is not a shared-filesystem lock.
+ */
+export declare function withScaffolderFileLock<T>(path: string, action: () => T, seams?: ScaffolderLockSeams): T;
 /**
  * Serialize a text-file read/modify/write and install the replacement strictly
  * atomically without weakening an existing file's permissions.