@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/ci/act-worktree-git.js

@@ -0,0 +1,219 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+export function prepareActGitWorkspace(cwd) {
+    const sourceCwd = resolve(cwd);
+    const linked = readLinkedWorktreeGitMetadata(sourceCwd);
+    if (!linked) {
+        return {
+            cwd: sourceCwd,
+            prepared: false,
+            cleanup() { },
+        };
+    }
+    assertExistingDirectory(linked.gitDir, "linked-worktree gitdir");
+    const commonDir = resolveGitCommonDir(linked.gitDir);
+    assertExistingDirectory(commonDir, "linked-worktree commondir");
+    const tempRoot = mkdtempSync(join(tmpdir(), "wp-ci-act-worktree-"));
+    const preparedCwd = join(tempRoot, "workspace");
+    try {
+        const head = git(sourceCwd, ["rev-parse", "HEAD"]);
+        git(sourceCwd, ["rev-parse", "--is-inside-work-tree"]);
+        execFileSync("git", [
+            "clone",
+            "--local",
+            "--no-hardlinks",
+            "--dissociate",
+            "--no-checkout",
+            sourceCwd,
+            preparedCwd,
+        ], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        syncOriginRemote(sourceCwd, preparedCwd);
+        git(preparedCwd, ["checkout", "--detach", "--quiet", head]);
+        overlayWorkingTreeChanges(sourceCwd, preparedCwd);
+        assertPreparedGitMetadataIsSelfContained(preparedCwd);
+        return {
+            cwd: preparedCwd,
+            prepared: true,
+            cleanup() {
+                rmSync(tempRoot, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        rmSync(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function readLinkedWorktreeGitMetadata(cwd) {
+    const gitPath = join(cwd, ".git");
+    if (!existsSync(gitPath)) {
+        return null;
+    }
+    const stat = lstatSync(gitPath);
+    if (stat.isDirectory())
+        return null;
+    if (!stat.isFile()) {
+        throw new Error(`Cannot prepare ci act workspace: ${gitPath} is not a file or directory.`);
+    }
+    const content = readFileSync(gitPath, "utf8").trim();
+    const match = /^gitdir:\s*(.+)$/u.exec(content);
+    if (!match?.[1]) {
+        throw new Error(`Cannot prepare ci act workspace: ${gitPath} is not a valid gitdir file.`);
+    }
+    return { gitDir: resolve(cwd, match[1]) };
+}
+function resolveGitCommonDir(gitDir) {
+    const commonDirPath = join(gitDir, "commondir");
+    if (!existsSync(commonDirPath))
+        return gitDir;
+    const raw = readFileSync(commonDirPath, "utf8").trim();
+    if (!raw)
+        throw new Error(`Cannot prepare ci act workspace: ${commonDirPath} is empty.`);
+    return resolve(gitDir, raw);
+}
+function overlayWorkingTreeChanges(sourceCwd, preparedCwd) {
+    const changed = parseGitDiffNameStatus(splitGitNullOutput(gitRaw(sourceCwd, ["diff", "--name-status", "--find-renames", "-z", "HEAD", "--"])));
+    const untracked = splitGitNullOutput(gitRaw(sourceCwd, ["ls-files", "--others", "--exclude-standard", "-z"]));
+    const copyPaths = new Set([...changed.copyPaths, ...untracked]);
+    for (const relativePath of changed.removePaths) {
+        assertSafeGitRelativePath(relativePath);
+        rmSync(join(preparedCwd, relativePath), { recursive: true, force: true });
+    }
+    for (const relativePath of copyPaths) {
+        assertSafeGitRelativePath(relativePath);
+        const sourcePath = join(sourceCwd, relativePath);
+        const preparedPath = join(preparedCwd, relativePath);
+        const sourceStat = tryLstat(sourcePath);
+        if (!sourceStat) {
+            rmSync(preparedPath, { recursive: true, force: true });
+            continue;
+        }
+        mkdirSync(dirname(preparedPath), { recursive: true });
+        if (sourceStat.isSymbolicLink()) {
+            rmSync(preparedPath, { recursive: true, force: true });
+            symlinkSync(readlinkSync(sourcePath), preparedPath);
+            continue;
+        }
+        rmSync(preparedPath, { recursive: true, force: true });
+        cpSync(sourcePath, preparedPath, { recursive: true, force: true, errorOnExist: false });
+    }
+}
+function tryLstat(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function parseGitDiffNameStatus(entries) {
+    const copyPaths = new Set();
+    const removePaths = new Set();
+    for (let index = 0; index < entries.length;) {
+        const status = entries[index++];
+        if (!status)
+            continue;
+        if (status.startsWith("R")) {
+            const oldPath = entries[index++];
+            const newPath = entries[index++];
+            if (oldPath)
+                removePaths.add(oldPath);
+            if (newPath)
+                copyPaths.add(newPath);
+            continue;
+        }
+        if (status.startsWith("C")) {
+            index++;
+            const newPath = entries[index++];
+            if (newPath)
+                copyPaths.add(newPath);
+            continue;
+        }
+        const path = entries[index++];
+        if (!path)
+            continue;
+        if (status.startsWith("D")) {
+            removePaths.add(path);
+        }
+        else {
+            copyPaths.add(path);
+        }
+    }
+    return { copyPaths, removePaths };
+}
+function syncOriginRemote(sourceCwd, preparedCwd) {
+    const originUrl = tryGit(sourceCwd, ["remote", "get-url", "origin"]);
+    if (originUrl) {
+        git(preparedCwd, ["remote", "set-url", "origin", originUrl]);
+        return;
+    }
+    tryGit(preparedCwd, ["remote", "remove", "origin"]);
+}
+function assertPreparedGitMetadataIsSelfContained(preparedCwd) {
+    const gitPath = join(preparedCwd, ".git");
+    if (!existsSync(gitPath) || !lstatSync(gitPath).isDirectory()) {
+        throw new Error("Cannot prepare ci act workspace: prepared .git metadata is not a directory.");
+    }
+    const commonDir = resolve(preparedCwd, git(preparedCwd, ["rev-parse", "--git-common-dir"]));
+    const relative = commonDirRelativeToPrepared(preparedCwd, commonDir);
+    if (relative === null) {
+        throw new Error(`Cannot prepare ci act workspace: prepared git common dir escaped the execution workspace (${commonDir}).`);
+    }
+    const alternatesPath = join(commonDir, "objects", "info", "alternates");
+    if (existsSync(alternatesPath) && readFileSync(alternatesPath, "utf8").trim().length > 0) {
+        throw new Error(`Cannot prepare ci act workspace: prepared git objects still depend on alternates (${alternatesPath}).`);
+    }
+}
+function commonDirRelativeToPrepared(preparedCwd, commonDir) {
+    const normalizedRoot = resolve(preparedCwd);
+    const normalizedCommon = resolve(commonDir);
+    if (normalizedCommon === normalizedRoot)
+        return "";
+    if (normalizedCommon.startsWith(`${normalizedRoot}${sep}`)) {
+        return normalizedCommon.slice(normalizedRoot.length + 1);
+    }
+    return null;
+}
+function splitGitNullOutput(output) {
+    return output.split("\0").filter((entry) => entry.length > 0);
+}
+function assertSafeGitRelativePath(relativePath) {
+    if (relativePath.length === 0 ||
+        relativePath.startsWith("/") ||
+        relativePath === ".." ||
+        relativePath.startsWith("../") ||
+        relativePath.includes("/../")) {
+        throw new Error(`Unsafe git path returned while preparing ci act workspace: ${relativePath}`);
+    }
+}
+function assertExistingDirectory(path, label) {
+    if (!existsSync(path) || !lstatSync(path).isDirectory()) {
+        throw new Error(`Cannot prepare ci act workspace: ${label} is missing or unreadable: ${path}`);
+    }
+}
+function git(cwd, args) {
+    return gitRaw(cwd, args).trim();
+}
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return null;
+    }
+}
+function gitRaw(cwd, args) {
+    return execFileSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}

package/dist/esm/cli/bundle/commands/blueprint.d.ts

@@ -1,6 +1,7 @@
 import type { CliCommand } from "@webpresso/cli-contract";
 export declare const blueprintCommands: {
     audit: CliCommand<Record<string, unknown>>;
+    canonicalize: CliCommand<Record<string, unknown>>;
     exec: CliCommand<Record<string, unknown>>;
     finalize: CliCommand<Record<string, unknown>>;
     list: CliCommand<Record<string, unknown>>;

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

@@ -35,6 +35,7 @@ function createBlueprintAuditCommand() {
 }
 export const blueprintCommands = {
     audit: createBlueprintAuditCommand(),
+    canonicalize: placeholderCommand(SCOPE, "canonicalize", "Canonicalize a flat blueprint to folder shape"),
     exec: placeholderGroup(SCOPE, "exec", "Execute a blueprint", {
         logs: placeholderCommand(SCOPE, "logs", "Show blueprint execution logs"),
         resume: placeholderCommand(SCOPE, "resume", "Resume blueprint execution"),

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", "typecheck", "lint", "format", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "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", "public:readiness", "typecheck", "lint", "format", "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",
+    "public:readiness",
     "typecheck",
     "lint",
     "format",
@@ -70,6 +71,7 @@ const SUPPORTED_COMMANDS = [
     "hook",
     "hooks",
     "self-install-guard",
+    "optional-tool-refresh",
     "gain",
     "bench",
     "install",
@@ -111,6 +113,10 @@ const ROOT_HELP_CORE_ENTRIES = [
         command: "ci-preflight",
         description: "Run the locally-runnable required CI checks fail-fast (the pre-push gate)",
     },
+    {
+        command: "public:readiness",
+        description: "Run the public package readiness gate through the portable wp surface",
+    },
     { command: "logs", description: "Print persisted raw output from recent quality runs" },
     { command: "dev", description: "Run a manifest-backed development target" },
     { command: "status", description: "Show unified local readiness and next action" },
@@ -364,6 +370,10 @@ const COMMAND_REGISTRARS = {
         const { registerCiPreflightCommand } = await import("./commands/ci-preflight.js");
         registerCiPreflightCommand(cli);
     },
+    "public:readiness": async (cli) => {
+        const { registerPublicReadinessCommand } = await import("./commands/public-readiness.js");
+        registerPublicReadinessCommand(cli);
+    },
     typecheck: async (cli) => {
         const { registerTypecheckCommand } = await import("./commands/typecheck.js");
         registerTypecheckCommand(cli);
@@ -422,6 +432,15 @@ const COMMAND_REGISTRARS = {
         const { registerSelfInstallGuardCommand } = await import("./commands/self-install-guard.js");
         registerSelfInstallGuardCommand(cli);
     },
+    "optional-tool-refresh": async (cli) => {
+        cli
+            .command("optional-tool-refresh <tool> [...args]", "Internal detached optional-tool freshness worker")
+            .allowUnknownOptions()
+            .action(async (tool, args = []) => {
+            const { runOptionalToolRefreshWorker } = await import("./optional-tool-freshness.js");
+            process.exitCode = runOptionalToolRefreshWorker([tool, ...args]);
+        });
+    },
     gain: async (cli) => {
         const { registerGainCommand } = await import("./commands/gain/index.js");
         registerGainCommand(cli);
@@ -636,6 +655,21 @@ export async function main() {
         console.error(formatUnknownCommandError(command, SUPPORTED_COMMANDS));
         return 1;
     }
+    // `wp run wait` is the read-only workflow-run waiter, intercepted before the
+    // package-manager `run` facade (which maps `wp run <script>` to `vp run
+    // <script>`). Without this, `wait` would be treated as a package script name.
+    // Errors resolve to an exit code here, mirroring main()'s catch below, so a
+    // bad flag never rejects the main() promise.
+    if (resolvedCommand === "run" && argv[3] === "wait") {
+        const { runRunWaitCommand } = await import("./commands/run-wait.js");
+        try {
+            return await runRunWaitCommand(argv.slice(4));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     await COMMAND_REGISTRARS[resolvedCommand](cli, resolvedCommand);
     if (resolvedCommand === "session") {
         const { runSessionCommand } = await import("./commands/session.js");

package/dist/esm/cli/commands/agent-launch.d.ts

@@ -2,6 +2,7 @@ import type { CAC } from "cac";
 import { type DashPermissionMode, type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
 import { type RuntimeCommandOptions } from "#runtime/executor.js";
 import { type SecretsConfig } from "#runtime/secrets-config.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
 export declare const AGENT_LAUNCH_COMMANDS: readonly ["claude", "codex", "grok", "opencode"];
 export type AgentLaunchCommand = DashProvider;
 export declare const DEFAULT_AGENT_SECRET_PROFILE = "preview";
@@ -18,6 +19,10 @@ export interface AgentLaunchDeps {
         error?: Error;
     };
     readonly ensureCodexSkillSurface?: (cwd: string, env?: NodeJS.ProcessEnv) => string | null;
+    readonly resolveOpencodeAccounts?: typeof resolveOpencodeAccountsGracefully;
+    readonly materializeGlobalOpencodeAuth?: (key: string) => void;
+    readonly readActiveKey?: () => string | undefined;
+    readonly recordCooldown?: (canonicalId: string) => Promise<unknown>;
 }
 export declare function buildDefaultAgentArgs(command: AgentLaunchCommand, args?: readonly string[], permissionMode?: DashPermissionMode): readonly string[];
 export declare function isAgentLaunchCommand(command: string | undefined): command is AgentLaunchCommand;
@@ -29,5 +34,5 @@ export declare function buildAgentRuntimeCommandOptions(input: {
     readonly env?: NodeJS.ProcessEnv;
     readonly secretsConfig: SecretsConfig | null;
 }): RuntimeCommandOptions;
-export declare function runAgentLaunchCommand(command: AgentLaunchCommand, args?: readonly string[], options?: AgentLaunchOptions, deps?: AgentLaunchDeps): number;
+export declare function runAgentLaunchCommand(command: AgentLaunchCommand, args?: readonly string[], options?: AgentLaunchOptions, deps?: AgentLaunchDeps): Promise<number>;
 export declare function registerAgentLaunchCommand(cli: CAC, command: AgentLaunchCommand): void;

package/dist/esm/cli/commands/agent-launch.js

@@ -7,6 +7,11 @@ import { WP_AGENT_LAUNCHED_VIA_WP_ENV, WP_AGENT_LAUNCHED_VIA_WP_VALUE, } from "#
 import { readSecretsConfig } from "#runtime/secrets-config.js";
 import { resolveFreshAgentKitPackageRoot } from "#cli/commands/init/package-root";
 import { ensureCodexUserPlugin } from "#cli/commands/init/scaffolders/codex-plugin/index.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppressions, } from "#review/availability.js";
+import { selectActiveOpencodeAccount } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth } from "#review/opencode-auth.js";
+import { describeOpencodeRotate, OPENCODE_ROTATE_FLAG, rotateActiveOpencodeAccount, } from "#cli/commands/opencode-rotate.js";
 export const AGENT_LAUNCH_COMMANDS = DASH_PROVIDERS;
 export const DEFAULT_AGENT_SECRET_PROFILE = "preview";
 export const AGENT_SECRET_PROFILE_ENV = "WP_AGENT_SECRET_PROFILE";
@@ -83,7 +88,67 @@ function ensureCodexSkillSurface(cwd, env = process.env) {
             return `Codex plugin refresh failed (${result.kind}). Run \`wp install codex\` and retry.`;
     }
 }
-export function runAgentLaunchCommand(command, args = [], options = {}, deps = {}) {
+/**
+ * Choose the active opencode-go account and materialize its key into the
+ * global opencode `auth.json` before the TUI launches.
+ *
+ * Honest limitation: interactive opencode is a long-lived TUI — the account is
+ * chosen once at launch and a mid-session dollar-cap is NOT auto-swapped. A
+ * plain relaunch does NOT rotate either: nothing on this path records a
+ * cooldown, so an exhausted account stays "first non-suppressed" and gets
+ * re-picked every time. Run `wp opencode --wp-rotate` to cool the current
+ * account and launch on the next one. Only the review gate does automatic
+ * in-flight failover, because only it can observe the usage-limit response.
+ *
+ * Never throws: a Doppler outage or materialize failure must not block the
+ * TUI from launching, so every failure is logged and swallowed.
+ */
+function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile) {
+    try {
+        const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
+            cwd,
+            secretProfile,
+        });
+        if (!resolution.ok)
+            return;
+        const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+        const selection = selectActiveOpencodeAccount(resolution.accounts, pruned.state);
+        if (!selection)
+            return;
+        (deps.materializeGlobalOpencodeAuth ?? ((key) => materializeOpencodeGoAuth(key)))(selection.account.key);
+        if (selection.cooled) {
+            console.error(`wp opencode: all OpenCode Go accounts are within their usage cooldown; launching on the soonest-expiring account (${selection.account.id}).`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`wp opencode: account selection failed, launching without it (${message}).`);
+    }
+}
+/**
+ * Run the opencode-only pre-launch credential step and return the args to
+ * forward to the binary. `--wp-rotate` is consumed here and must never reach
+ * opencode, which would treat it as a prompt.
+ */
+async function prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile) {
+    if (!args.includes(OPENCODE_ROTATE_FLAG)) {
+        if (secretsConfig !== null)
+            selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+        return args;
+    }
+    const outcome = await rotateActiveOpencodeAccount(cwd, secretProfile, deps);
+    for (const line of describeOpencodeRotate(outcome))
+        console.error(line);
+    // A successful rotation already materialized the next account, so the normal
+    // launch-time selection is skipped to avoid a second, redundant write. When
+    // rotation could not run, fall through to that selection so the launch still
+    // gets the best account it can rather than whatever the store happens to hold.
+    if (outcome.kind === "unavailable" && secretsConfig !== null) {
+        selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+    }
+    return args.filter((arg) => arg !== OPENCODE_ROTATE_FLAG);
+}
+export async function runAgentLaunchCommand(command, args = [], options = {}, deps = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (command === "codex") {
         const skillSurfaceError = (deps.ensureCodexSkillSurface ?? ensureCodexSkillSurface)(cwd, options.env ?? process.env);
@@ -93,9 +158,19 @@ export function runAgentLaunchCommand(command, args = [], options = {}, deps = {
         }
     }
     const secretsConfig = (deps.readSecretsConfig ?? readSecretsConfig)(cwd);
+    // Account discovery must resolve secrets through the same profile the launch
+    // itself uses (below, via buildAgentRuntimeCommandOptions). Without it no
+    // environment selector reaches the secret manager, which then falls back to
+    // its own ambient, path-scoped config — that resolves only in a checkout that
+    // happens to sit under the scoped directory and fails in every managed
+    // worktree, CI clone, and fresh checkout.
+    const secretProfile = resolveAgentSecretProfile(options.env ?? process.env);
+    const launchArgs = command === "opencode"
+        ? await prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile)
+        : args;
     const runtimeOptions = buildAgentRuntimeCommandOptions({
         command,
-        args,
+        args: launchArgs,
         cwd,
         env: options.env ?? process.env,
         secretsConfig,
@@ -108,8 +183,11 @@ export function runAgentLaunchCommand(command, args = [], options = {}, deps = {
     return result.status ?? 1;
 }
 export function registerAgentLaunchCommand(cli, command) {
+    const rotateHint = command === "opencode"
+        ? ` (pass \`${OPENCODE_ROTATE_FLAG}\` to cool the current OpenCode Go account and launch on the next one)`
+        : "";
     cli
-        .command(`${command} [...args]`, `Launch ${command} with provider-backed agent secrets and safe-by-default permissions (run \`wp yolo on\` for persistent full-auto)`)
+        .command(`${command} [...args]`, `Launch ${command} with provider-backed agent secrets and safe-by-default permissions (run \`wp yolo on\` for persistent full-auto)${rotateHint}`)
         .allowUnknownOptions()
-        .action((args = []) => runAgentLaunchCommand(command, args, { cwd: process.cwd() }));
+        .action(async (args = []) => await runAgentLaunchCommand(command, args, { cwd: process.cwd() }));
 }

package/dist/esm/cli/commands/audit-core.d.ts

@@ -1,4 +1,4 @@
-import type { AuditKindId } from "#audit/registry";
+import { type AuditKindId } from "#audit/registry";
 import type { RepoAuditResult } from "#audit/repo-guardrails";
 export type AuditKind = AuditKindId;
 export type AuditOutcome = {

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

@@ -1,3 +1,4 @@
+import { getAuditKindDescriptor } from "#audit/registry";
 function optionsForCompositeRepoAudit(name, options) {
     if (name !== "reference-parity-matrix" || options.strict !== true)
         return options;
@@ -94,7 +95,13 @@ export async function runAuditDispatch(auditKind, targets, options, deps) {
             let allOk = true;
             for (const name of deps.knownRepoKinds) {
                 const result = await deps.runRepoAudit(name, root, optionsForCompositeRepoAudit(name, options));
-                if (!result.ok)
+                // Signal-class kinds (registry.ts gateClass) still run and still
+                // report their findings via `results` below, but a failing signal
+                // kind must not flip the umbrella — only blocking-class failures do.
+                // Unclassified kinds default to blocking, matching the registry's
+                // own descriptor() default.
+                const gateClass = getAuditKindDescriptor(name)?.gateClass ?? "blocking";
+                if (!result.ok && gateClass !== "signal")
                     allOk = false;
                 results.push({ name, result });
             }

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

@@ -15,6 +15,7 @@ import { createCliLogSink } from "#cli/commands/quality-log-store.js";
 import { emitCliCommandOutput, runLoggedChildCommand } from "#cli/commands/quality-runner.js";
 export const REPO_AUDIT_REGISTRY = {
     "catalog-drift": async (root) => (await import("#audit/repo-guardrails")).auditCatalogDrift(root),
+    "typescript-version": async (root) => (await import("#audit/typescript-version")).auditTypescriptVersion(root),
     "package-surface": async (root) => (await import("#audit/package-surface")).auditPackageSurface(root),
     "command-surface": async (root) => (await import("#audit/command-surface")).auditCommandSurface(root),
     "reference-parity-matrix": async (root, options) => (await import("#audit/reference-parity-matrix")).auditReferenceParityMatrix(root, undefined, {
@@ -123,6 +124,10 @@ export const REPO_AUDIT_REGISTRY = {
     "secrets-config": async (root) => (await import("#audit/secrets-config")).auditSecretsConfig(root),
     "consumer-agent-kit-dependency": async (root) => (await import("#audit/consumer-agent-kit-dependency")).auditConsumerAgentKitDependency(root),
     "ci-test-perf": async (root) => (await import("#audit/ci-test-perf")).auditCiTestPerf(root),
+    "ci-guardrails-wiring": async (root) => (await import("#audit/ci-guardrails-wiring")).auditCiGuardrailsWiring(root),
+    "test-scan-perf": async (root, options) => (await import("#audit/test-scan-perf")).auditTestScanPerf(root, {
+        affectedFiles: options.affectedFiles,
+    }),
     "worktree-main-ownership": async (root) => (await import("#audit/worktree-main-ownership")).auditWorktreeMainOwnership(root),
     sast: async (root, options) => (await import("#audit/sast")).auditSast(root, {
         bin: options.bin,
@@ -137,6 +142,7 @@ export const REPO_AUDIT_REGISTRY = {
         draftTechDebt: options.draftTechDebt,
     }),
     "harness-overlay-evidence": async (root) => (await import("#audit/harness-overlay-evidence")).auditHarnessOverlayEvidence(root),
+    "host-substitution-risk": async (root) => (await import("#audit/host-substitution-risk")).auditHostSubstitutionRisk(root),
     "legacy-workflow-identity": async (root) => (await import("#audit/legacy-workflow-identity")).auditLegacyWorkflowIdentity(root),
     rules: async (root) => runContentAudit(root, "rule"),
     skills: async (root) => runContentAudit(root, "skill"),
@@ -464,22 +470,31 @@ export function registerAuditCommand(cli) {
             }
             case "aggregate-result": {
                 const { formatRepoAuditReport } = await import("#audit/repo-guardrails");
+                const isSignal = (name) => getAuditKindDescriptor(name)?.gateClass === "signal";
                 for (const { name, result } of outcome.results) {
                     if (result.ok)
                         continue;
-                    sink.write(`\n[${name}]\n${formatRepoAuditReport(result)}\n`);
+                    const label = isSignal(name) ? `${name} (signal, non-blocking)` : name;
+                    sink.write(`\n[${label}]\n${formatRepoAuditReport(result)}\n`);
                 }
                 const failed = outcome.results.filter(({ result }) => !result.ok);
+                const blockingFailed = failed.filter(({ name }) => !isSignal(name));
+                const signalFailed = failed.filter(({ name }) => isSignal(name));
                 if (failed.length > 0) {
-                    sink.write(`\nguardrails: ${failed.length}/${outcome.results.length} audits failed: ${failed
-                        .map(({ name }) => name)
-                        .join(", ")}\n`);
+                    const parts = [];
+                    if (blockingFailed.length > 0) {
+                        parts.push(`${blockingFailed.length} blocking: ${blockingFailed.map(({ name }) => name).join(", ")}`);
+                    }
+                    if (signalFailed.length > 0) {
+                        parts.push(`${signalFailed.length} signal/non-blocking: ${signalFailed.map(({ name }) => name).join(", ")}`);
+                    }
+                    sink.write(`\nguardrails: ${failed.length}/${outcome.results.length} audits reported findings (${parts.join("; ")})\n`);
                 }
                 exitCode = outcome.code;
                 summary =
                     outcome.code === 0
                         ? "audit guardrails passed"
-                        : `audit guardrails failed (${failed.length}/${outcome.results.length})`;
+                        : `audit guardrails failed (${blockingFailed.length}/${outcome.results.length})`;
                 break;
             }
             case "quality-exit": {

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

@@ -9,6 +9,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { applyRuntimeProgressSnapshot, buildBlueprintProgressBridgeState, normalizeRuntimeTaskSnapshot, projectBlueprintLifecycleFromRuntime, readBlueprintExecutionArtifacts, runtimeStateSnapshotSchema, writeBlueprintExecutionArtifacts, writeBlueprintExecutionMetadata, } from "#index";
 import { applyBlueprintLifecycleToFile, parseBlueprint } from "#local";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
+import { resolveBlueprintDocumentIdentity } from "#utils/document-paths.js";
 import { clearBlueprintExecutionState, persistBlueprintExecutionArtifacts, persistBlueprintExecutionMetadata, persistBlueprintProgressBridgeState, readBlueprintExecutionArtifactsState, readBlueprintExecutionState, readBlueprintProgressBridgeState, readBlueprintRuntimeSnapshot, writeBlueprintRuntimeSnapshot, } from "./execution-io.js";
 import { assertCompletionEvidence, mergeExecutionArtifacts, } from "./execution-state.js";
 import { buildBlueprintExecutionControlCommand, buildBlueprintExecutionLaunchCommand, buildBlueprintExecutionRuntimePaths, buildBlueprintLaunchSpec, buildListTasksVerificationCommand, isMissingFileError, nowIsoTimestamp, parseRuntimeApiResponse, parseTeamExecutionId, resolveControlStatus, toProjectRelativePath, uniqueStrings, } from "./execution-spec.js";
@@ -114,22 +115,33 @@ export async function reconcileBlueprintRuntimeSnapshot(projectRoot, blueprintPa
     const currentStatus = currentDir.split(blueprintsRoot + path.sep)[1]?.split(path.sep)[0];
     const relativeSlug = slug.replace(/^[^/]+\//u, "");
     const targetDir = path.join(blueprintsRoot, nextStatus, relativeSlug);
-    const targetPath = path.join(targetDir, "_overview.md");
+    // A flat document owns only its own file; renaming its parent directory
+    // would move the entire lifecycle state directory. Lifecycle moves are
+    // shape-preserving: flat stays flat, folder moves as a folder.
+    const isFlatDocument = resolveBlueprintDocumentIdentity(blueprintsRoot, blueprintPath)?.shape === "flat";
+    const targetPath = isFlatDocument ? `${targetDir}.md` : path.join(targetDir, "_overview.md");
+    const documentMoved = blueprintPath !== targetPath;
     const nextMarkdown = completionEvidence
         ? writeBlueprintExecutionArtifacts(result.markdown, completionEvidence)
         : result.markdown;
-    if (currentDir !== targetDir && currentStatus && currentStatus !== nextStatus) {
+    if (documentMoved && currentStatus && currentStatus !== nextStatus) {
         const { mkdir, rename } = await import("node:fs/promises");
-        await mkdir(path.dirname(targetDir), { recursive: true });
-        await rename(currentDir, targetDir);
+        if (isFlatDocument) {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await rename(blueprintPath, targetPath);
+        }
+        else {
+            await mkdir(path.dirname(targetDir), { recursive: true });
+            await rename(currentDir, targetDir);
+        }
         await writeFile(targetPath, nextMarkdown, "utf-8");
     }
     else {
         await writeFile(blueprintPath, nextMarkdown, "utf-8");
     }
     return {
-        moved: currentDir !== targetDir,
-        path: currentDir !== targetDir ? targetPath : blueprintPath,
+        moved: documentMoved,
+        path: documentMoved ? targetPath : blueprintPath,
         status: result.execution.status,
     };
 }