@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -23,6 +23,9 @@ import { detectRepoCollectionRoot, isInitializedWebpressoProject, } from "./repo
 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, 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";
 import { resolveTier3Selection } from "./prompts.js";
@@ -55,6 +58,7 @@ import { ensureClaudePlaywrightMcp, ensureCodexProjectMcpServers, ensureCodexWeb
 import { scaffoldExampleSkill } from "./scaffolders/example-skill/index.js";
 import { scaffoldLoreCommits } from "./scaffolders/lore-commits/index.js";
 import { ensureOpenCodeWebpressoPlugin } from "./scaffolders/opencode-plugin/index.js";
+import { ensureGrokWebpressoMcp } from "./scaffolders/grok-mcp/index.js";
 import { ensureRtk } from "./scaffolders/rtk/index.js";
 import { checkRuntimes } from "./scaffolders/runtime-check/index.js";
 import { scaffoldSubagents } from "./scaffolders/subagents/index.js";
@@ -101,6 +105,22 @@ function normalizeAllToken(rawWith, allFlag) {
         all: wantsAll,
     };
 }
+export function setupDeprecationWarnings(flags) {
+    const warnings = [];
+    if (flags.profile !== undefined) {
+        warnings.push("wp setup: `--profile` is deprecated and will be removed after this compatibility wave; use bare `wp setup` for repository convergence.");
+    }
+    if (flags.prune === true) {
+        warnings.push("wp setup: `--prune` is deprecated; use `wp update` for machine plugin/cache refresh.");
+    }
+    if (flags.yesGlobal === true ||
+        flags["yes-global"] === true ||
+        flags.skipGlobal === true ||
+        flags["skip-global"] === true) {
+        warnings.push("wp setup: global-consent flags are deprecated; use `wp setup` for repository convergence and `wp update` for machine state.");
+    }
+    return warnings;
+}
 export function resolveSetupProfile(raw) {
     if (raw === undefined)
         return DEFAULT_SETUP_PROFILE;
@@ -307,28 +327,32 @@ async function runUserOnlySetup(input) {
             console.log("  workspace config: ✓ created ~/.agent/workspace.yaml");
         }
     }
-    if (isCiEnvironment) {
-        console.log("  codex cli: - skipped (CI environment)");
-    }
-    else {
-        const codexCliResult = ensureCodexCli({ options: userScopeOptions });
-        switch (codexCliResult.kind) {
-            case "codex-cli-ok":
-                console.log(codexCliResult.installed ? "  codex cli: ✓ installed" : "  codex cli: ✓");
-                if (!userScopeOptions.dryRun) {
-                    writeToolingOwnershipState(claimUserOwnedTool(readToolingOwnershipState(), "codex"));
-                }
-                break;
-            case "codex-cli-skipped-dry-run":
-                console.log("  codex cli: skipped (--dry-run)");
-                break;
-            case "codex-cli-skipped-package-lifecycle":
-                console.log("  codex cli: - skipped (package lifecycle environment)");
-                break;
-            case "codex-cli-unavailable":
-                console.warn(`  codex cli: ⚠ ${codexCliResult.hint}`);
-                break;
+    if (selectedHosts.includes("codex")) {
+        if (isCiEnvironment) {
+            console.log("  codex cli: - skipped (CI environment)");
+        }
+        else {
+            const codexCliResult = ensureCodexCli({ options: userScopeOptions });
+            switch (codexCliResult.kind) {
+                case "codex-cli-ok":
+                    console.log(codexCliResult.installed ? "  codex cli: ✓ installed" : "  codex cli: ✓");
+                    if (!userScopeOptions.dryRun) {
+                        writeToolingOwnershipState(claimUserOwnedTool(readToolingOwnershipState(), "codex"));
+                    }
+                    break;
+                case "codex-cli-skipped-dry-run":
+                    console.log("  codex cli: skipped (--dry-run)");
+                    break;
+                case "codex-cli-skipped-package-lifecycle":
+                    console.log("  codex cli: - skipped (package lifecycle environment)");
+                    break;
+                case "codex-cli-unavailable":
+                    console.warn(`  codex cli: ⚠ ${codexCliResult.hint}`);
+                    break;
+            }
         }
+    }
+    if (selectedHosts.includes("claude") && !isCiEnvironment) {
         if (process.env.WP_SKIP_CLAUDE_PLUGIN === "1") {
             console.log("  claude cli: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
         }
@@ -356,22 +380,27 @@ async function runUserOnlySetup(input) {
     if (presets.includes("playwright-mcp")) {
         console.log("  playwright mcp: - skipped (the preset requires a project-owned .mcp.json; run setup inside the project repo)");
     }
-    const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
-    switch (webpressoMcpResult.kind) {
-        case "codex-webpresso-mcp-written":
-            console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
-            break;
-        case "codex-webpresso-mcp-unchanged":
-            console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
-            break;
-        case "codex-webpresso-mcp-skipped-dry-run":
-            console.log("  codex webpresso mcp: skipped (--dry-run)");
-            break;
-        case "codex-webpresso-mcp-not-installed":
-            console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
-            break;
+    if (selectedHosts.includes("codex")) {
+        const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
+        switch (webpressoMcpResult.kind) {
+            case "codex-webpresso-mcp-written":
+                console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
+                break;
+            case "codex-webpresso-mcp-unchanged":
+                console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
+                break;
+            case "codex-webpresso-mcp-ambiguous":
+                console.warn(`  codex webpresso mcp: ⚠ ambiguous MCP config at ${webpressoMcpResult.path}; left unchanged`);
+                break;
+            case "codex-webpresso-mcp-skipped-dry-run":
+                console.log("  codex webpresso mcp: skipped (--dry-run)");
+                break;
+            case "codex-webpresso-mcp-not-installed":
+                console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
+                break;
+        }
+        console.log("  codex project mcp: - skipped (no project .mcp.json outside a repo)");
     }
-    console.log("  codex project mcp: - skipped (no project .mcp.json outside a repo)");
     if (isCiEnvironment) {
         console.log("  agent-kit global: - skipped (CI environment)");
     }
@@ -406,33 +435,35 @@ async function runUserOnlySetup(input) {
                 break;
         }
     }
-    const claudePluginResult = ensureClaudeCodeUserPlugin({
-        options: userScopeOptions,
-        packageRoot,
-    });
-    switch (claudePluginResult.kind) {
-        case "claude-plugin-installed":
-            console.log(`  claude plugin: ✓ user-scope marketplace + plugin ensured (${claudePluginResult.pluginId})`);
-            break;
-        case "claude-plugin-skipped-dry-run":
-            console.log("  claude plugin: skipped (--dry-run)");
-            break;
-        case "claude-plugin-skipped-opt-out":
-            console.log("  claude plugin: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
-            break;
-        case "claude-plugin-skipped-package-lifecycle":
-            console.log("  claude plugin: - skipped (package lifecycle environment)");
-            break;
-        case "claude-plugin-skipped-no-cli":
-            console.log("  claude plugin: - skipped (claude not on PATH)");
-            break;
-        case "claude-plugin-unavailable":
-            console.log("  claude plugin: - skipped (plugin manifest unavailable in this install)");
-            break;
-        case "claude-plugin-failed":
-            console.warn(`  claude plugin: ⚠ ${claudePluginResult.step} exited with ${claudePluginResult.exitCode}; ` +
-                `fallback: claude plugin marketplace add --scope user webpresso/agent-kit@v$(wp --version) && claude plugin install --scope user ${claudePluginResult.pluginId}`);
-            break;
+    if (selectedHosts.includes("claude")) {
+        const claudePluginResult = ensureClaudeCodeUserPlugin({
+            options: userScopeOptions,
+            packageRoot,
+        });
+        switch (claudePluginResult.kind) {
+            case "claude-plugin-installed":
+                console.log(`  claude plugin: ✓ user-scope marketplace + plugin ensured (${claudePluginResult.pluginId})`);
+                break;
+            case "claude-plugin-skipped-dry-run":
+                console.log("  claude plugin: skipped (--dry-run)");
+                break;
+            case "claude-plugin-skipped-opt-out":
+                console.log("  claude plugin: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
+                break;
+            case "claude-plugin-skipped-package-lifecycle":
+                console.log("  claude plugin: - skipped (package lifecycle environment)");
+                break;
+            case "claude-plugin-skipped-no-cli":
+                console.log("  claude plugin: - skipped (claude not on PATH)");
+                break;
+            case "claude-plugin-unavailable":
+                console.log("  claude plugin: - skipped (plugin manifest unavailable in this install)");
+                break;
+            case "claude-plugin-failed":
+                console.warn(`  claude plugin: ⚠ ${claudePluginResult.step} exited with ${claudePluginResult.exitCode}; ` +
+                    `fallback: claude plugin marketplace add --scope user webpresso/agent-kit@v$(wp --version) && claude plugin install --scope user ${claudePluginResult.pluginId}`);
+                break;
+        }
     }
     if (selectedHosts.includes("codex") && !isCiEnvironment) {
         const codexPluginResult = ensureCodexUserPlugin({ options: userScopeOptions, packageRoot });
@@ -552,7 +583,7 @@ function enabledManagedHookVendors(manifest) {
 function disabledManagedHookVendors(manifest) {
     return ["claude", "codex"].filter((vendor) => manifest.vendorState[vendor] === "disabled");
 }
-async function runSourceRepoHookOnlyRecovery(repoRoot, options, stdout, mode = "repair-stale-only", 
+async function runSourceRepoHookOnlyRecovery(repoRoot, options, stdout, selectedHosts, mode = "repair-stale-only", 
 /**
  * User/home-scope gate for the Codex hook-trust sync leg. The repo-scope
  * `.claude`/`.codex` hook restore always runs with `options`, but the trust
@@ -571,10 +602,15 @@ trustSync) {
     }
     const nextManifest = buildManagedHooksManifest(repoRoot, previousManifest?.vendorState);
     const input = { repoRoot, options, trustCodexHooks: false };
-    const restored = restoreManagedHooksFromManifest(input, nextManifest, enabledManagedHookVendors(nextManifest));
+    const selectedManagedVendors = ["claude", "codex"].filter((vendor) => selectedHosts.includes(vendor));
+    if (selectedManagedVendors.length === 0) {
+        return null;
+    }
+    const restored = restoreManagedHooksFromManifest(input, nextManifest, enabledManagedHookVendors(nextManifest).filter((vendor) => selectedManagedVendors.includes(vendor)));
     const disabledVendors = disabledManagedHookVendors(nextManifest);
-    const disabled = disabledVendors.length > 0
-        ? disableManagedHooksFromManifest(input, nextManifest, disabledVendors)
+    const selectedDisabledVendors = disabledVendors.filter((vendor) => selectedManagedVendors.includes(vendor));
+    const disabled = selectedDisabledVendors.length > 0
+        ? disableManagedHooksFromManifest(input, nextManifest, selectedDisabledVendors)
         : {};
     if (!options.dryRun) {
         writeHooksManifest(repoRoot, nextManifest.claude, nextManifest.codex, nextManifest.vendorState);
@@ -769,7 +805,7 @@ async function runSourceRepoSafeSetup(input) {
         skipGlobal,
         explicitConsent: input.explicitConsent,
     });
-    const hookExit = await runSourceRepoHookOnlyRecovery(repoRoot, options, stdout, forceHookRepair ? "force-repair" : "repair-stale-only", {
+    const hookExit = await runSourceRepoHookOnlyRecovery(repoRoot, options, stdout, selectedHosts, forceHookRepair ? "force-repair" : "repair-stale-only", {
         options: userScopeOptions,
         consent: trustConsent,
         createCodexAppServer: input.createCodexAppServer,
@@ -881,6 +917,8 @@ function detectPlainDirectoryConsumer(startDir) {
 }
 export async function runInit(flags, deps = {}) {
     flags = normalizeInitFlagsForExecution(flags);
+    for (const warning of setupDeprecationWarnings(flags))
+        console.warn(warning);
     const stdout = deps.stdout ?? process.stdout;
     const startMs = Date.now();
     const cwd = flags.cwd ?? process.cwd();
@@ -923,6 +961,7 @@ export async function runInit(flags, deps = {}) {
     const options = {
         overwrite: flags.overwrite ?? false,
         dryRun: flags.dryRun ?? flags["dry-run"] ?? false,
+        repoRoot: consumer.repoRoot,
     };
     // Source-repo safe setup is the agent-kit maintainer's own contributor
     // workflow (running `wp setup` inside a checkout of @webpresso/agent-kit). Its
@@ -974,7 +1013,7 @@ export async function runInit(flags, deps = {}) {
             skipGlobal,
             explicitConsent: forceUserOnly,
         });
-        const hookOnlyRecoveryExit = await runSourceRepoHookOnlyRecovery(consumer.repoRoot, options, stdout, "repair-stale-only", {
+        const hookOnlyRecoveryExit = await runSourceRepoHookOnlyRecovery(consumer.repoRoot, options, stdout, recoveryHosts, "repair-stale-only", {
             options: userScopeOptions,
             consent: trustConsent,
             createCodexAppServer: deps.createCodexAppServer,
@@ -1001,6 +1040,22 @@ export async function runInit(flags, deps = {}) {
                     ? "non-webpresso-project"
                     : null;
     const userOnlySetup = userOnlyReason !== null;
+    const isCiEnvironment = process.env.CI === "true" || process.env.CI === "1";
+    if (!userOnlySetup && !options.dryRun) {
+        const gitConvergence = prepareRepositoryForConvergence({
+            repoRoot: consumer.repoRoot,
+            isCi: isCiEnvironment,
+        });
+        for (const warning of gitConvergence.warnings)
+            console.warn(`  git convergence: ⚠ ${warning}`);
+        if (!gitConvergence.ok) {
+            console.error(`wp setup: ${gitConvergence.error ?? "Git convergence preflight failed."}`);
+            return EXIT_SETUP_FAIL;
+        }
+        if (gitConvergence.shouldReplan) {
+            console.log("  git convergence: ✓ fast-forwarded upstream; recomputing setup plan");
+        }
+    }
     if (!userOnlySetup) {
         warnIfNonLocalCli(consumer.repoRoot);
     }
@@ -1159,7 +1214,7 @@ export async function runInit(flags, deps = {}) {
     // set side-effect-free, then decide once whether to apply it. On skip,
     // user-scope steps run in dry-run mode (their existing skip-branches) so only
     // repo-scope writes land; the decision is recorded for `wp hooks doctor`.
-    const isCiEnvironmentForConsent = process.env.CI === "true" || process.env.CI === "1";
+    const isCiEnvironmentForConsent = isCiEnvironment;
     const skipClaudePlugin = process.env.WP_SKIP_CLAUDE_PLUGIN === "1";
     const userScopeSteps = collectUserScopeSteps({
         isCiEnvironment: isCiEnvironmentForConsent,
@@ -1310,6 +1365,7 @@ export async function runInit(flags, deps = {}) {
             agentHooksResult = await scaffoldAgentHooks({
                 repoRoot: consumer.repoRoot,
                 options,
+                selectedHosts,
                 claudeUserOptions: userScopeOptions,
                 // Env-gate the home `~/.claude/settings.json` leg to match the preflight
                 // inventory: under WP_SKIP_CLAUDE_PLUGIN=1 the `claude-user-settings` step
@@ -1353,35 +1409,67 @@ export async function runInit(flags, deps = {}) {
         else {
             console.log(`  hooks: - skipped (profile: ${profile} omits agent + audit hooks)`);
         }
-        const opencodePluginResult = ensureOpenCodeWebpressoPlugin({
-            repoRoot: consumer.repoRoot,
-            options,
-        });
-        switch (opencodePluginResult.kind) {
-            case "opencode-webpresso-plugin-written":
-                console.log(`  opencode plugin: ✓ ${opencodePluginResult.path} ensures ${opencodePluginResult.pluginPackage}`);
-                if (opencodePluginResult.removed.length > 0) {
-                    console.log(`  opencode cleanup: removed ${opencodePluginResult.removed.join(", ")}`);
-                }
-                if (opencodePluginResult.preserved.length > 0) {
-                    console.warn(`  opencode cleanup: left ${opencodePluginResult.preserved.join(", ")} unchanged (no Webpresso ownership marker)`);
-                }
-                break;
-            case "opencode-webpresso-plugin-unchanged":
-                console.log(`  opencode plugin: already configured at ${opencodePluginResult.path}`);
-                if (opencodePluginResult.preserved.length > 0) {
-                    console.warn(`  opencode cleanup: left ${opencodePluginResult.preserved.join(", ")} unchanged (no Webpresso ownership marker)`);
-                }
-                break;
-            case "opencode-webpresso-plugin-skipped-dry-run":
-                console.log("  opencode plugin: skipped (--dry-run)");
-                break;
-            case "opencode-webpresso-plugin-invalid-json":
-                console.warn(`  opencode plugin: ⚠ ${opencodePluginResult.path} is not valid JSON; left unchanged`);
-                break;
-            case "opencode-webpresso-plugin-invalid-config":
-                console.warn(`  opencode plugin: ⚠ ${opencodePluginResult.path} has a non-string plugin config; left unchanged`);
-                break;
+        if (selectedHosts.includes("opencode")) {
+            const opencodePluginResult = ensureOpenCodeWebpressoPlugin({
+                repoRoot: consumer.repoRoot,
+                options,
+            });
+            switch (opencodePluginResult.kind) {
+                case "opencode-webpresso-plugin-written":
+                    console.log(`  opencode plugin: ✓ ${opencodePluginResult.path} ensures ${opencodePluginResult.pluginPackage}`);
+                    if (opencodePluginResult.mcpEntryPath) {
+                        console.log(`  opencode mcp: ✓ mcp.webpresso launches webpresso via ${opencodePluginResult.mcpEntryPath}`);
+                    }
+                    else {
+                        console.warn("  opencode mcp: ⚠ webpresso launcher not found; mcp.webpresso left unset");
+                    }
+                    if (opencodePluginResult.removed.length > 0) {
+                        console.log(`  opencode cleanup: removed ${opencodePluginResult.removed.join(", ")}`);
+                    }
+                    if (opencodePluginResult.preserved.length > 0) {
+                        console.warn(`  opencode cleanup: left ${opencodePluginResult.preserved.join(", ")} unchanged (no Webpresso ownership marker)`);
+                    }
+                    break;
+                case "opencode-webpresso-plugin-unchanged":
+                    console.log(`  opencode plugin: already configured at ${opencodePluginResult.path}`);
+                    if (opencodePluginResult.preserved.length > 0) {
+                        console.warn(`  opencode cleanup: left ${opencodePluginResult.preserved.join(", ")} unchanged (no Webpresso ownership marker)`);
+                    }
+                    break;
+                case "opencode-webpresso-plugin-skipped-dry-run":
+                    console.log("  opencode plugin: skipped (--dry-run)");
+                    break;
+                case "opencode-webpresso-plugin-invalid-json":
+                    console.warn(`  opencode plugin: ⚠ ${opencodePluginResult.path} is not valid JSON; left unchanged`);
+                    break;
+                case "opencode-webpresso-plugin-invalid-config":
+                    console.warn(`  opencode plugin: ⚠ ${opencodePluginResult.path} has a non-string plugin config; left unchanged`);
+                    break;
+            }
+        }
+        if (selectedHosts.includes("grok")) {
+            const grokMcpResult = ensureGrokWebpressoMcp({
+                repoRoot: consumer.repoRoot,
+                options,
+            });
+            switch (grokMcpResult.kind) {
+                case "grok-webpresso-mcp-written":
+                    console.log(`  grok mcp: ✓ ${grokMcpResult.path} launches webpresso via ${grokMcpResult.entryPath}`);
+                    console.log("  grok hooks: run /hooks-trust once in Grok to arm the managed hooks");
+                    break;
+                case "grok-webpresso-mcp-unchanged":
+                    console.log(`  grok mcp: already configured at ${grokMcpResult.path}`);
+                    break;
+                case "grok-webpresso-mcp-ambiguous":
+                    console.warn(`  grok mcp: ⚠ ambiguous MCP config at ${grokMcpResult.path}; left unchanged`);
+                    break;
+                case "grok-webpresso-mcp-skipped-dry-run":
+                    console.log("  grok mcp: skipped (--dry-run)");
+                    break;
+                case "grok-webpresso-mcp-not-installed":
+                    console.warn(`  grok mcp: ⚠ webpresso launcher not found (checked ${grokMcpResult.checked.length} location(s)); left ${grokMcpResult.path} unchanged`);
+                    break;
+            }
         }
         let claudeRulesResults = [];
         try {
@@ -1397,18 +1485,23 @@ export async function runInit(flags, deps = {}) {
         const subagentResults = scaffoldSubagents({ repoRoot: consumer.repoRoot, options });
         // Generated host instructions (AGENTS.md) are a tier-1 (guarded/full)
         // surface; the tier-0 quality profile omits them.
+        // Base-kit may have created or updated package metadata earlier in this
+        // same convergence pass. Render from that post-apply repository view so a
+        // fresh setup reaches the same fixed point as an immediate repeat.
+        const convergedConsumer = detectConsumer(consumer.repoRoot) ?? consumer;
         const agentsMdResult = surfaces.hostInstructions
             ? scaffoldAgentsMd({
                 catalogDir,
                 repoRoot: consumer.repoRoot,
-                consumer,
+                consumer: convergedConsumer,
                 config,
                 options,
             })
             : null;
+        let configuredGeneratedPathsRemoved = [];
         if (!options.dryRun) {
             writeConfig(consumer.repoRoot, config);
-            removeConfiguredGeneratedPaths(consumer.repoRoot, config);
+            configuredGeneratedPathsRemoved = removeConfiguredGeneratedPaths(consumer.repoRoot, config);
         }
         // Apply scaffolder presets
         const presetResults = [];
@@ -1450,30 +1543,34 @@ export async function runInit(flags, deps = {}) {
         // Failures from these installations must not fail the postinstall in that
         // context.
         const isCiEnvironment = process.env.CI === "true" || process.env.CI === "1";
-        if (isCiEnvironment) {
-            console.log("  codex cli: - skipped (CI environment)");
-        }
-        else {
-            const codexCliResult = ensureCodexCli({ options: userScopeOptions });
-            switch (codexCliResult.kind) {
-                case "codex-cli-ok":
-                    console.log(codexCliResult.installed ? "  codex cli: ✓ installed" : "  codex cli: ✓");
-                    recordUserScope("codex-cli");
-                    if (!userScopeOptions.dryRun) {
-                        toolingOwnership = claimUserOwnedTool(toolingOwnership, "codex");
-                        toolingOwnershipChanged = true;
-                    }
-                    break;
-                case "codex-cli-skipped-dry-run":
-                    console.log("  codex cli: skipped (--dry-run)");
-                    break;
-                case "codex-cli-skipped-package-lifecycle":
-                    console.log("  codex cli: - skipped (package lifecycle environment)");
-                    break;
-                case "codex-cli-unavailable":
-                    console.warn(`  codex cli: ⚠ ${codexCliResult.hint}`);
-                    break;
+        if (selectedHosts.includes("codex")) {
+            if (isCiEnvironment) {
+                console.log("  codex cli: - skipped (CI environment)");
             }
+            else {
+                const codexCliResult = ensureCodexCli({ options: userScopeOptions });
+                switch (codexCliResult.kind) {
+                    case "codex-cli-ok":
+                        console.log(codexCliResult.installed ? "  codex cli: ✓ installed" : "  codex cli: ✓");
+                        recordUserScope("codex-cli");
+                        if (!userScopeOptions.dryRun) {
+                            toolingOwnership = claimUserOwnedTool(toolingOwnership, "codex");
+                            toolingOwnershipChanged = true;
+                        }
+                        break;
+                    case "codex-cli-skipped-dry-run":
+                        console.log("  codex cli: skipped (--dry-run)");
+                        break;
+                    case "codex-cli-skipped-package-lifecycle":
+                        console.log("  codex cli: - skipped (package lifecycle environment)");
+                        break;
+                    case "codex-cli-unavailable":
+                        console.warn(`  codex cli: ⚠ ${codexCliResult.hint}`);
+                        break;
+                }
+            }
+        }
+        if (selectedHosts.includes("claude") && !isCiEnvironment) {
             if (process.env.WP_SKIP_CLAUDE_PLUGIN === "1") {
                 console.log("  claude cli: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
             }
@@ -1520,10 +1617,10 @@ export async function runInit(flags, deps = {}) {
                     break;
             }
         }
-        // Trusting codex hooks only matters when hooks were scaffolded (tier 1+),
-        // and even then only with resolved user-scope consent (the trust write
-        // touches $CODEX_HOME, which is user/home scope).
-        if (surfaces.hooks) {
+        // Trusting Codex hooks only matters when Codex hooks were scaffolded
+        // (tier 1+) for this host selection, and even then only with resolved
+        // user-scope consent (the trust write touches $CODEX_HOME).
+        if (surfaces.hooks && selectedHosts.includes("codex")) {
             await trustCodexWebpressoHooksForRepo({ repoRoot: consumer.repoRoot, options: userScopeOptions }, userScopeConsent
                 ? { kind: "apply" }
                 : { kind: "skip", reason: skipGlobal ? "--skip-global" : "user-scope writes declined" });
@@ -1532,23 +1629,28 @@ export async function runInit(flags, deps = {}) {
         // an install root is discoverable. Codex's config.toml is user-global, so
         // we resolve to whatever absolute install path exists today (Claude
         // plugin / bun global / pnpm global / npm global) and write that.
-        const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
-        switch (webpressoMcpResult.kind) {
-            case "codex-webpresso-mcp-written":
-                console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
-                recordUserScope("codex-config");
-                break;
-            case "codex-webpresso-mcp-unchanged":
-                console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
-                break;
-            case "codex-webpresso-mcp-skipped-dry-run":
-                console.log("  codex webpresso mcp: skipped (--dry-run)");
-                break;
-            case "codex-webpresso-mcp-not-installed":
-                console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
-                break;
+        if (selectedHosts.includes("codex")) {
+            const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
+            switch (webpressoMcpResult.kind) {
+                case "codex-webpresso-mcp-written":
+                    console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
+                    recordUserScope("codex-config");
+                    break;
+                case "codex-webpresso-mcp-unchanged":
+                    console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
+                    break;
+                case "codex-webpresso-mcp-ambiguous":
+                    console.warn(`  codex webpresso mcp: ⚠ ambiguous MCP config at ${webpressoMcpResult.path}; left unchanged`);
+                    break;
+                case "codex-webpresso-mcp-skipped-dry-run":
+                    console.log("  codex webpresso mcp: skipped (--dry-run)");
+                    break;
+                case "codex-webpresso-mcp-not-installed":
+                    console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
+                    break;
+            }
+            reconcileCodexProjectMcpServers(consumer.repoRoot, userScopeOptions);
         }
-        reconcileCodexProjectMcpServers(consumer.repoRoot, userScopeOptions);
         // Self-update the globally-distributed agent-kit install that backs PATH
         // `wp`, mirroring codex/claude. Non-fatal: a failed refresh never
         // fails consumer setup, and it skips cleanly in explicit source mode, on
@@ -1592,34 +1694,36 @@ export async function runInit(flags, deps = {}) {
             }
         }
         const successfullyInstalledPluginHosts = new Set();
-        const claudePluginResult = ensureClaudeCodeUserPlugin({
-            options: userScopeOptions,
-            packageRoot,
-        });
-        switch (claudePluginResult.kind) {
-            case "claude-plugin-installed":
-                successfullyInstalledPluginHosts.add("claude");
-                console.log(`  claude plugin: ✓ user-scope marketplace + plugin ensured (${claudePluginResult.pluginId})`);
-                break;
-            case "claude-plugin-skipped-dry-run":
-                console.log("  claude plugin: skipped (--dry-run)");
-                break;
-            case "claude-plugin-skipped-opt-out":
-                console.log("  claude plugin: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
-                break;
-            case "claude-plugin-skipped-package-lifecycle":
-                console.log("  claude plugin: - skipped (package lifecycle environment)");
-                break;
-            case "claude-plugin-skipped-no-cli":
-                console.log("  claude plugin: - skipped (claude not on PATH)");
-                break;
-            case "claude-plugin-unavailable":
-                console.log("  claude plugin: - skipped (plugin manifest unavailable in this install)");
-                break;
-            case "claude-plugin-failed":
-                console.warn(`  claude plugin: ⚠ ${claudePluginResult.step} exited with ${claudePluginResult.exitCode}; ` +
-                    `fallback: claude plugin marketplace add --scope user webpresso/agent-kit@v$(wp --version) && claude plugin install --scope user ${claudePluginResult.pluginId}`);
-                break;
+        if (selectedHosts.includes("claude")) {
+            const claudePluginResult = ensureClaudeCodeUserPlugin({
+                options: userScopeOptions,
+                packageRoot,
+            });
+            switch (claudePluginResult.kind) {
+                case "claude-plugin-installed":
+                    successfullyInstalledPluginHosts.add("claude");
+                    console.log(`  claude plugin: ✓ user-scope marketplace + plugin ensured (${claudePluginResult.pluginId})`);
+                    break;
+                case "claude-plugin-skipped-dry-run":
+                    console.log("  claude plugin: skipped (--dry-run)");
+                    break;
+                case "claude-plugin-skipped-opt-out":
+                    console.log("  claude plugin: skipped (WP_SKIP_CLAUDE_PLUGIN=1)");
+                    break;
+                case "claude-plugin-skipped-package-lifecycle":
+                    console.log("  claude plugin: - skipped (package lifecycle environment)");
+                    break;
+                case "claude-plugin-skipped-no-cli":
+                    console.log("  claude plugin: - skipped (claude not on PATH)");
+                    break;
+                case "claude-plugin-unavailable":
+                    console.log("  claude plugin: - skipped (plugin manifest unavailable in this install)");
+                    break;
+                case "claude-plugin-failed":
+                    console.warn(`  claude plugin: ⚠ ${claudePluginResult.step} exited with ${claudePluginResult.exitCode}; ` +
+                        `fallback: claude plugin marketplace add --scope user webpresso/agent-kit@v$(wp --version) && claude plugin install --scope user ${claudePluginResult.pluginId}`);
+                    break;
+            }
         }
         if (selectedHosts.includes("codex") && !isCiEnvironment) {
             const codexPluginResult = ensureCodexUserPlugin({ options: userScopeOptions, packageRoot });
@@ -1838,6 +1942,52 @@ export async function runInit(flags, deps = {}) {
                 visibility: serializeHostVisibility(visibilityAudit),
             };
             writeConfig(consumer.repoRoot, config);
+            writeConvergenceState(consumer.repoRoot, {
+                schemaVersion: 1,
+                agentKitVersion: packageVersion,
+                host: selectedHosts.join(",") || "none",
+                sentinels: {
+                    profile,
+                    selectedHosts: selectedHosts.toSorted().join(","),
+                },
+                writtenAt: new Date().toISOString(),
+            });
+            const candidates = [
+                ...all.map((result) => ({
+                    targetPath: result.targetPath,
+                    reason: result.note ?? "setup-managed surface",
+                })),
+                {
+                    targetPath: join(consumer.repoRoot, ".webpressorc.json"),
+                    reason: "setup convergence config",
+                },
+                ...configuredGeneratedPathsRemoved.map((path) => ({
+                    targetPath: join(consumer.repoRoot, path),
+                    reason: "configured generated cleanup",
+                })),
+                ...(generatedIndexCleanupResult.kind === "ok"
+                    ? generatedIndexCleanupResult.removedPaths.map((path) => ({
+                        targetPath: join(consumer.repoRoot, path),
+                        reason: "generated index cleanup",
+                    }))
+                    : []),
+            ];
+            const commitResult = authorConvergenceCommit({
+                repoRoot: consumer.repoRoot,
+                appliedUnits: collectAppliedConvergeUnits(consumer.repoRoot, candidates),
+                message: "chore: converge webpresso setup",
+                isCi: isCiEnvironment,
+            });
+            if (!commitResult.ok) {
+                console.error(formatWpSetupError(commitResult.error ?? "Unable to author convergence commit."));
+                return EXIT_WRITE_FAIL;
+            }
+            if (commitResult.status === "committed") {
+                console.log(`  git convergence: ✓ authored ${commitResult.commit?.slice(0, 12)}`);
+            }
+            else if (commitResult.status === "skipped-ci") {
+                console.log("  git convergence: - commit skipped (CI)");
+            }
             console.log("\nHost skill visibility:");
             if (visibilityAudit.selectedHosts.length === 0) {
                 console.log("  hosts: - skipped (--host none)");
@@ -1948,7 +2098,7 @@ function registerPrimaryInitOptions(command) {
         .option("--with <skills>", withHelp)
         .option("--without <skills>", withoutHelp)
         .option("--profile <profile>", `Adoption tier to scaffold: ${SETUP_PROFILES.join(", ")} (default: ${DEFAULT_SETUP_PROFILE} — bare \`wp setup\` is unchanged). quality = wp scripts + MCP + session memory; guarded = + hooks/audits/host instructions; full = + blueprint lifecycle`)
-        .option("--host <hosts>", "Comma-separated host targets: codex, claude, opencode, all, none")
+        .option("--host <hosts>", "Comma-separated host targets: codex, claude, opencode, grok, all, none")
         .option("--prune", "Widen stale agent-kit plugin-cache pruning from the default host set (claude, codex, opencode) to every supported host while retaining recent versions")
         .option("--dry-run", "Show what would change without writing anything")
         .option("--yes-global", "Apply user/home-scope writes (host config, plugin/CLI installs, agent caches) without an interactive consent prompt")
@@ -1970,6 +2120,9 @@ export function registerInitCommand(cli, commandName = "init") {
         ? "Scaffold webpresso catalog into the current repo; default runs also clean obsolete notifier state and prune stale plugin caches while retaining recent versions for claude, codex, and opencode"
         : "Compatibility alias for wp setup";
     registerPrimaryInitOptions(cli.command(commandName, description).action(async (flags) => {
+        if (commandName === "init") {
+            console.warn("wp init is deprecated; use `wp setup` for repository convergence.");
+        }
         const validationError = validatePrimarySetupFlags(commandName, flags);
         if (validationError) {
             console.error(validationError);