@webpresso/agent-kit 3.1.30 → 3.2.0

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

@@ -10,6 +10,7 @@ import { resolveCurrentManagedWorktreeContext } from "#worktrees/current.js";
 import { canonicalizeWorktreePath, WORKTREE_PROBE_TIMEOUT_MS } from "#worktrees/identity.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
+import { canonicalizeBlueprint } from "#lifecycle/canonicalize.js";
 import { applyBlueprintLifecycleToFile, BlueprintCreationService, BlueprintService, complexitySchema, relativeBlueprintSlug, parseBlueprint, planStatusSchema, runBlueprintAudit, resolveBlueprintFile, serializeBlueprint, validateAllTasksDone, } from "#local";
 import { resolvePackageAssetPreferred } from "#utils/package-assets";
 import { resolveDraftAuthoringRoot } from "#worktrees/draft-authoring-root.js";
@@ -512,9 +513,19 @@ export async function finalizeBlueprintBySlug(slug, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     return finalizeBlueprintMutation(projectRoot, slug);
 }
+export async function canonicalizeBlueprintBySlug(slug, options = {}) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const result = await canonicalizeBlueprint(projectRoot, slug);
+    return {
+        ...result,
+        message: result.moved
+            ? `Canonicalized blueprint ${slug}: ${result.from} -> ${result.to}`
+            : `Blueprint ${slug} is already canonical: ${result.to}`,
+    };
+}
 export function registerBlueprintRouter(cli) {
     cli
-        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task)")
+        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task, trust-dossier)")
         .option("--json", "Print JSON output")
         .option("--no-tui", "Use plain terminal output")
         .option("--complexity <complexity>", "Blueprint complexity (XS|S|M|L|XL)")
@@ -535,6 +546,7 @@ export function registerBlueprintRouter(cli) {
             await executeBlueprintSubcommand(subcommand, args, options, {
                 advanceBlueprintTask,
                 auditBlueprints,
+                canonicalizeBlueprintBySlug,
                 createBlueprint,
                 controlBlueprintExec,
                 executeBlueprint,

package/dist/esm/cli/commands/ci-preflight.d.ts

@@ -31,9 +31,20 @@ export interface CiPreflightDeps {
     readonly cwd?: string;
     readonly resolveRepoRoot?: (cwd: string) => string | null;
     readonly hasNodeModules?: (repoRoot: string) => boolean;
-    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number;
+    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number | Promise<number>;
     readonly stdout?: Pick<typeof process.stdout, "write">;
     readonly stderr?: Pick<typeof process.stderr, "write">;
 }
-export declare function runCiPreflight(deps?: CiPreflightDeps): number;
+/**
+ * Re-invoke the same `wp` runtime that is currently executing so each check
+ * runs the real verb (faithful CI parity) rather than a reimplemented copy of
+ * its affected-resolution logic. Prefers the repo-local `bin/wp` launcher when
+ * present so the exact source/compiled selection and NODE_PATH wiring apply;
+ * falls back to the running runtime for consumer repos with a global `wp`.
+ */
+export declare function resolveWpLauncher(repoRoot: string): {
+    readonly command: string;
+    readonly prefixArgs: readonly string[];
+};
+export declare function runCiPreflight(deps?: CiPreflightDeps): Promise<number>;
 export declare function registerCiPreflightCommand(cli: CAC): void;

package/dist/esm/cli/commands/ci-preflight.js

@@ -57,7 +57,10 @@ function reproduceLine(check) {
  * present so the exact source/compiled selection and NODE_PATH wiring apply;
  * falls back to the running runtime for consumer repos with a global `wp`.
  */
-function resolveWpLauncher(repoRoot) {
+// Exported so `src/mcp/tools/ci-preflight.ts` can re-invoke the exact same
+// `wp` launcher when it substitutes an output-capturing `runCheck` for the
+// default `stdio: "inherit"` spawn — do not duplicate this resolution logic.
+export function resolveWpLauncher(repoRoot) {
     const localLauncher = path.join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
     if (existsSync(localLauncher))
         return { command: localLauncher, prefixArgs: [] };
@@ -82,7 +85,7 @@ function defaultRunCheck(check, repoRoot) {
     }
     return typeof result.status === "number" ? result.status : 1;
 }
-export function runCiPreflight(deps = {}) {
+export async function runCiPreflight(deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const stdout = deps.stdout ?? process.stdout;
     const stderr = deps.stderr ?? process.stderr;
@@ -100,7 +103,7 @@ export function runCiPreflight(deps = {}) {
     }
     for (const check of CI_PREFLIGHT_CHECKS) {
         stdout.write(`\nwp ci-preflight: running ${check.label} (${reproduceLine(check)})\n`);
-        const exitCode = runCheck(check, repoRoot);
+        const exitCode = await runCheck(check, repoRoot);
         if (exitCode !== 0) {
             const normalizedExit = exitCode === 0 ? 1 : exitCode;
             stderr.write(`\nwp ci-preflight: ${check.label} failed (exit ${normalizedExit}).\n` +

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

@@ -247,22 +247,10 @@ export async function runCompile(options) {
                 message: `wp compile: rulesync exited with code ${exitCode}`,
             };
         }
-        // Step 4: Emit plugin manifests in parallel
-        const skillNames = Object.keys(assets.skills);
-        const commandNames = Object.keys(assets.commands);
-        const pkgVersion = readPackageVersion(cwd);
-        const manifestOpts = {
-            agentDir,
-            outDir: cwd,
-            version: pkgVersion,
-            skills: skillNames,
-            commands: commandNames,
-        };
-        await Promise.all([
-            import("#compiler/manifests/claude").then((m) => m.emitManifest(manifestOpts)),
-            import("#compiler/manifests/codex").then((m) => m.emitManifest(manifestOpts)),
-        ]);
-        // Step 5: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // Step 4: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // (Plugin manifests are hand-maintained SSOT under packages/*-plugin/;
+        // wp compile no longer emits them — golden tests + version stamping own
+        // that surface.)
         const agentsLayers = collectAgentsLayers(agentDir);
         if (agentsLayers.length > 0) {
             const { mergeAgentsMd } = await import("#compiler/memory/merger");
@@ -278,11 +266,9 @@ export async function runCompile(options) {
                 writeFileSync(join(cwd, "AGENTS.md"), mergeResult.content);
             }
         }
-        // Step 6: Write .compile-manifest.json with content-hash sentinels
+        // Step 5: Write .compile-manifest.json with content-hash sentinels
         const outputHashes = {
             "AGENTS.md": hashFile(join(cwd, "AGENTS.md")),
-            "packages/claude-plugin/.claude-plugin/plugin.json": hashFile(join(cwd, "packages", "claude-plugin", ".claude-plugin", "plugin.json")),
-            "packages/codex-plugin/.codex-plugin/plugin.json": hashFile(join(cwd, "packages", "codex-plugin", ".codex-plugin", "plugin.json")),
         };
         const compileManifest = {
             version: COMPILE_MANIFEST_VERSION,
@@ -303,18 +289,6 @@ export async function runCompile(options) {
         cleanup();
     }
 }
-function readPackageVersion(cwd) {
-    const pkgPath = join(cwd, "package.json");
-    if (!existsSync(pkgPath))
-        return "0.0.0";
-    try {
-        const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        return typeof parsed.version === "string" ? parsed.version : "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
 function collectAgentsLayers(agentDir) {
     const agentsDir = join(agentDir, "agents");
     if (!existsSync(agentsDir))

package/dist/esm/cli/commands/dash/delivery-status.d.ts

@@ -56,3 +56,4 @@ export type DeliveryStatusOptions = {
  * prior values and expose a retryable adapter warning.
  */
 export declare function collectDeliveryStatus(options?: DeliveryStatusOptions): Promise<DeliveryStatus>;
+export declare function blueprintDocumentPath(cwd: string, state: string, slug: string): string | null;

package/dist/esm/cli/commands/dash/delivery-status.js

@@ -107,14 +107,21 @@ function checkState(value) {
         return "pending";
     return states.length > 0 ? "passing" : "unknown";
 }
+export function blueprintDocumentPath(cwd, state, slug) {
+    const folder = join(cwd, "blueprints", state, slug, "_overview.md");
+    if (existsSync(folder))
+        return folder;
+    const flat = join(cwd, "blueprints", state, `${slug}.md`);
+    return existsSync(flat) ? flat : null;
+}
 function readBlueprintDelivery(cwd) {
     const branch = run("git", ["branch", "--show-current"], cwd);
     if (!branch?.startsWith("bp/"))
         return null;
     const slug = branch.slice(3);
     for (const state of ["in-progress", "planned", "draft", "completed", "parked", "archived"]) {
-        const path = join(cwd, "blueprints", state, slug, "_overview.md");
-        if (!existsSync(path))
+        const path = blueprintDocumentPath(cwd, state, slug);
+        if (!path)
             continue;
         const raw = readFileSync(path, "utf8");
         return {
@@ -129,8 +136,8 @@ function readVerificationDelivery(cwd) {
     const blueprint = readBlueprintDelivery(cwd);
     if (!blueprint)
         return null;
-    const path = join(cwd, "blueprints", blueprint.state, blueprint.slug, "_overview.md");
-    if (!existsSync(path))
+    const path = blueprintDocumentPath(cwd, blueprint.state, blueprint.slug);
+    if (!path)
         return null;
     const raw = readFileSync(path, "utf8");
     const evidenceCount = (raw.match(/^\*\*Verification:\*\*/gmu) ?? []).length;

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

@@ -1,4 +1,5 @@
 import { auditBlueprintLifecycleSql } from "#audit/blueprint-lifecycle-sql";
+import { auditCiGuardrailsWiring } from "#audit/ci-guardrails-wiring";
 import { readConfig } from "#cli/commands/init/config";
 import { auditCatalogDrift, auditDocsFrontmatter, formatRepoAuditReport, } from "#audit/repo-guardrails";
 import { countWorktreeLifecycleScripts } from "#worktrees/lifecycle-scripts.js";
@@ -7,6 +8,9 @@ const REMEDIATIONS = {
     "Catalog drift — single package (no workspace file)": "none needed",
     "Docs frontmatter": "wp audit docs-frontmatter --fix",
     "Blueprint lifecycle": "wp audit blueprint-lifecycle",
+    // Name the missing invocation explicitly so an operator sees which CI step to
+    // restore, not just a generic "drifted" signal.
+    "CI guardrails wiring": "restore the `wp audit guardrails` CI step (run `wp setup`)",
 };
 export async function runDoctor(options = {}) {
     try {
@@ -17,6 +21,7 @@ export async function runDoctor(options = {}) {
                 docsRoot: options.docsRoot,
                 fix: options.fix,
             }),
+            auditCiGuardrailsWiring(root),
             await auditBlueprintLifecycleSql(root, { includeRuntimePlans: options.runtimePlans }),
         ];
         let failed = false;

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

@@ -1,4 +1,9 @@
 import type { CAC } from "cac";
+/**
+ * Registered GUARD_* codes emitted by the hook-command fail-closed path.
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export declare const HOOK_FALLBACK_GUARD_CODES: readonly ["GUARD_PRETOOL_FAILURE"];
 declare const HOOK_NAMES: readonly ["pretool-guard", "post-tool", "stop-qa", "stop-ultragoal", "guard-switch", "sessionstart-routing", "precompact-snapshot", "permission-request", "test-quality-check"];
 export type HookName = (typeof HOOK_NAMES)[number];
 export declare function isHookName(value: string): value is HookName;

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

@@ -2,8 +2,16 @@ import { performance } from "node:perf_hooks";
 import { reportHookDegradation, takeHookDegradation, } from "#hooks/errors/index.js";
 import { recordHookInvocation, summarizeHookText, takeRememberedHookStdin, } from "#hooks/logs/store.js";
 import { createSyntheticProcessExit, isSyntheticProcessExit, } from "#hooks/shared/synthetic-process-exit.js";
-import { writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { writeGuardStderr, writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { formatGuardReason } from "#hooks/shared/guard-outcome.js";
 import { buildDenyEnvelope } from "#hooks/shared/types.js";
+/**
+ * Registered GUARD_* codes emitted by the hook-command fail-closed path.
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export const HOOK_FALLBACK_GUARD_CODES = [
+    "GUARD_PRETOOL_FAILURE",
+];
 import { resolveHookProjectDirFromText } from "#hooks/shared/project-dir.js";
 import { createManagedHookExecutionContext, } from "#hooks/shared/session-memory-deadline.js";
 const HOOK_NAMES = [
@@ -101,13 +109,9 @@ function exitCodeFrom(value) {
 }
 function writePretoolDeny(reason) {
     writeHookOutput(`${JSON.stringify(buildDenyEnvelope({ reason }))}\n`);
-    // Best-effort stderr reason for Claude/Codex exit-2 UX (may be suppressed in some runners).
-    try {
-        process.stderr.write(`${reason}\n`);
-    }
-    catch {
-        // ignore
-    }
+    // Deliver to the REAL stderr too: Claude reads stderr on an exit-2 PreToolUse
+    // deny, and it is suppressed for decorative output.
+    writeGuardStderr(`${reason}\n`);
 }
 function emitFallback(name, error) {
     const metadata = HOOK_METADATA[name];
@@ -121,7 +125,9 @@ function emitFallback(name, error) {
         detail,
     });
     if (metadata.fallback === "fail-closed-deny") {
-        writePretoolDeny(`webpresso pretool guard failed: ${detail}`);
+        // Coded fail-closed denial so the host still sees a stable GUARD_ code even
+        // when the guard handler itself threw.
+        writePretoolDeny(formatGuardReason("GUARD_PRETOOL_FAILURE", `webpresso pretool guard failed: ${detail}`));
         // Exit 2 so Grok (and exit-code runners) treat fail-closed as an explicit deny.
         return 2;
     }

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

@@ -4,7 +4,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize } from "node:path";
-import { REQUIRED_CORE_CAPABILITIES } from "./host-visibility.js";
+import { AGENT_HOSTS, REQUIRED_CORE_CAPABILITIES } from "./host-visibility.js";
 export const CONFIG_VERSION = "1";
 export const CONFIG_FILENAME = ".webpressorc.json";
 export const LEGACY_CONFIG_FILENAME = ".agent-kitrc.json";
@@ -136,7 +136,7 @@ function parseConfigFile(path) {
             }
             : undefined;
         const selectedHosts = Array.isArray(hosts?.selected)
-            ? hosts.selected.filter((s) => ["codex", "claude", "opencode"].includes(String(s)))
+            ? hosts.selected.filter((s) => AGENT_HOSTS.includes(String(s)))
             : [];
         const requiredCapabilities = Array.isArray(hosts?.requiredCapabilities)
             ? hosts.requiredCapabilities.filter((s) => typeof s === "string")

package/dist/esm/cli/commands/init/convergence-apply.d.ts

@@ -0,0 +1,24 @@
+import { type ConvergeUnit } from "./convergence.js";
+export { resolveUntrackedCollision } from "./untracked-collision.js";
+export type AuthorCommitStatus = "committed" | "no-change" | "skipped-ci" | "failed" | "rolled-back";
+export interface AuthorCommitResult {
+    readonly status: AuthorCommitStatus;
+    readonly ok: boolean;
+    readonly commit?: string;
+    readonly allowlist: readonly string[];
+    readonly unexpectedPaths?: readonly string[];
+    readonly missingPaths?: readonly string[];
+    readonly error?: string;
+}
+export interface AuthorCommitOptions {
+    readonly repoRoot: string;
+    readonly appliedUnits: readonly ConvergeUnit[];
+    readonly message: string;
+    readonly isCi?: boolean;
+}
+export interface AppliedConvergenceCandidate {
+    readonly targetPath: string;
+    readonly reason: string;
+}
+export declare function collectAppliedConvergeUnits(repoRoot: string, candidates: readonly AppliedConvergenceCandidate[]): ConvergeUnit[];
+export declare function authorConvergenceCommit(options: AuthorCommitOptions): AuthorCommitResult;

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

@@ -0,0 +1,221 @@
+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) {
+    const result = spawnSync("git", [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        ok: result.status === 0 && !result.error,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+function lines(value) {
+    return value.length === 0 ? [] : value.split("\n").filter(Boolean).sort();
+}
+function readPorcelainStatus(repoRoot, gitPath) {
+    const result = spawnSync("git", [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+        "--ignored=matching",
+        "--",
+        gitPath,
+    ], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0 || result.error)
+        return null;
+    const fields = result.stdout.split("\0");
+    const entries = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const record = fields[index];
+        if (!record || record.length < 4)
+            continue;
+        const code = record.slice(0, 2);
+        entries.push({ code, gitPath: record.slice(3) });
+        if (code.includes("R") || code.includes("C"))
+            index += 1;
+    }
+    return entries;
+}
+function isIgnored(repoRoot, gitPath) {
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath]).ok;
+}
+export function collectAppliedConvergeUnits(repoRoot, candidates) {
+    const units = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        let candidateUnit;
+        try {
+            candidateUnit = convergeUnitFromTarget(repoRoot, candidate.targetPath, {
+                action: "modify",
+                scope: "repo-committed",
+                reason: candidate.reason,
+            });
+        }
+        catch {
+            continue;
+        }
+        const statuses = readPorcelainStatus(repoRoot, candidateUnit.gitPath);
+        if (!statuses)
+            continue;
+        for (const { code, gitPath } of statuses) {
+            if (seen.has(gitPath))
+                continue;
+            let unit;
+            try {
+                unit = convergeUnitFromTarget(repoRoot, join(repoRoot, gitPath), {
+                    action: code === "??" || code === "!!" || code.includes("A")
+                        ? "create"
+                        : code.includes("D")
+                            ? "delete"
+                            : "modify",
+                    scope: "repo-committed",
+                    reason: candidate.reason,
+                });
+            }
+            catch {
+                continue;
+            }
+            units.push({
+                ...unit,
+                scope: code === "!!" || (code === "??" && isIgnored(repoRoot, gitPath))
+                    ? "repo-ignored"
+                    : "repo-committed",
+            });
+            seen.add(gitPath);
+        }
+    }
+    return units;
+}
+export function authorConvergenceCommit(options) {
+    const allowlist = deriveCommitAllowlist(options.appliedUnits);
+    if (options.isCi)
+        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"]);
+    if (!before.ok) {
+        return { status: "failed", ok: false, allowlist, error: before.stderr || "Missing HEAD." };
+    }
+    const add = git(options.repoRoot, ["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"]);
+    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]);
+    if (!commit.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: commit.stderr || commit.stdout || "git commit failed; hook changes were preserved.",
+        };
+    }
+    const committedHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!committedHead.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: committedHead.stderr || "Unable to validate the authored commit.",
+        };
+    }
+    const committedParent = git(options.repoRoot, [
+        "rev-parse",
+        "--verify",
+        `${committedHead.stdout}^`,
+    ]);
+    if (!committedParent.ok || committedParent.stdout !== before.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            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, [
+        "diff-tree",
+        "--root",
+        "--no-commit-id",
+        "--name-only",
+        "-r",
+        committedHead.stdout,
+    ]);
+    if (!committedPathsResult.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            error: committedPathsResult.stderr || "Unable to inspect the authored commit.",
+        };
+    }
+    const committedPaths = lines(committedPathsResult.stdout);
+    const allowed = new Set(allowlist);
+    const committed = new Set(committedPaths);
+    const unexpectedPaths = committedPaths.filter((path) => !allowed.has(path));
+    const missingPaths = allowlist.filter((path) => !committed.has(path));
+    if (unexpectedPaths.length === 0 && missingPaths.length === 0) {
+        return {
+            status: "committed",
+            ok: true,
+            allowlist,
+            commit: committedHead.stdout,
+        };
+    }
+    const currentHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!currentHead.ok || currentHead.stdout !== committedHead.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            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]);
+    if (!rollback.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            error: rollback.stderr || "Failed to undo the path-invalid setup commit.",
+        };
+    }
+    return {
+        status: "rolled-back",
+        ok: false,
+        allowlist,
+        commit: committedHead.stdout,
+        unexpectedPaths,
+        missingPaths,
+        error: `A commit hook changed setup commit scope (unexpected: ${unexpectedPaths.join(", ") || "none"}; missing: ${missingPaths.join(", ") || "none"}). ` +
+            "The setup commit was undone and all worktree changes were retained. Update the hook so it does not stage unrelated paths, then stage or discard those paths and rerun wp setup.",
+    };
+}

package/dist/esm/cli/commands/init/convergence-state.d.ts

@@ -0,0 +1,13 @@
+export declare const CONVERGENCE_STATE_SCHEMA_VERSION: 1;
+export declare const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+export interface ConvergenceState {
+    readonly schemaVersion: typeof CONVERGENCE_STATE_SCHEMA_VERSION;
+    readonly agentKitVersion: string;
+    readonly host: string;
+    readonly sentinels: Readonly<Record<string, string>>;
+    readonly writtenAt: string;
+}
+export declare function parseConvergenceState(value: unknown): ConvergenceState | null;
+export declare function readConvergenceState(repoRoot: string): ConvergenceState | null;
+export declare function isConvergenceStateCurrent(state: ConvergenceState | null, expected: Pick<ConvergenceState, "agentKitVersion" | "host" | "sentinels">): boolean;
+export declare function writeConvergenceState(repoRoot: string, state: ConvergenceState): void;

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

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { writeJsonFile } from "#shared-utils/write-json-file.js";
+export const CONVERGENCE_STATE_SCHEMA_VERSION = 1;
+export const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+export function parseConvergenceState(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== CONVERGENCE_STATE_SCHEMA_VERSION ||
+        typeof record.agentKitVersion !== "string" ||
+        typeof record.host !== "string" ||
+        typeof record.writtenAt !== "string" ||
+        !isStringRecord(record.sentinels)) {
+        return null;
+    }
+    return {
+        schemaVersion: CONVERGENCE_STATE_SCHEMA_VERSION,
+        agentKitVersion: record.agentKitVersion,
+        host: record.host,
+        sentinels: record.sentinels,
+        writtenAt: record.writtenAt,
+    };
+}
+export function readConvergenceState(repoRoot) {
+    try {
+        return parseConvergenceState(JSON.parse(readFileSync(join(resolve(repoRoot), CONVERGENCE_STATE_PATH), "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function isConvergenceStateCurrent(state, expected) {
+    if (!state ||
+        state.agentKitVersion !== expected.agentKitVersion ||
+        state.host !== expected.host) {
+        return false;
+    }
+    return Object.entries(expected.sentinels).every(([name, value]) => state.sentinels[name] === value);
+}
+export function writeConvergenceState(repoRoot, state) {
+    const statePath = join(resolve(repoRoot), CONVERGENCE_STATE_PATH);
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeJsonFile(statePath, state, {
+        atomic: true,
+        indent: 2,
+    });
+}

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

@@ -0,0 +1,23 @@
+import type { WriteAction } from "./write-plan.js";
+export declare const CONVERGE_SCOPES: readonly ["repo-committed", "repo-ignored"];
+export type ConvergeScope = (typeof CONVERGE_SCOPES)[number];
+export interface ConvergeUnit {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export interface CreateConvergeUnitInput {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export declare function createConvergeUnit(input: CreateConvergeUnitInput): ConvergeUnit;
+export declare function convergeUnitFromTarget(repoRoot: string, targetPath: string, input: Pick<CreateConvergeUnitInput, "action" | "scope" | "reason">): ConvergeUnit;
+/** Applied units are the sole authority for authored commit scope. */
+export declare function deriveCommitAllowlist(appliedUnits: readonly ConvergeUnit[]): string[];