@apexops/cli 0.10.0-next.5 → 0.11.0-next.1

package/dist/cli.js

@@ -5,16 +5,20 @@ import { CONTRACT_VERSION, OnboardingConfigV1Schema, QualityMeasurementsV1Schema
 import { Value } from "@sinclair/typebox/value";
 import { EventJournal, ValidatorRegistry, WriterTransferStore, atomicWriteJson, sha256Json } from "@apexops/kernel";
 import { evaluateQualityScorecard, renderQualityScorecardEvaluation, } from "@apexops/renderers";
-import { basename, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { ApexError, EXIT_CODES, normalizeError } from "./errors.js";
 import { dependencyRevision as calculateDependencyRevision } from "./dependency-revision.js";
 import { resolveBundledAssets } from "./assets.js";
+import { assertTargetScope } from "./target-scope.js";
 import { serveMcp } from "./mcp.js";
 import { createFileProviderRuntime, hashTerraformConfiguration, hashTerraformLockFile } from "./provider-runtime.js";
 import { exportProviderTransfer, importProviderTransfer } from "./provider-transfer.js";
 import { ApexService } from "./service.js";
 import { exportStateTransfer, importStateTransfer } from "./state-transfer.js";
 import { APEX_VERSION } from "./version.js";
+import { interactiveBootstrap } from "./bootstrap-wizard.js";
+import { mcpWorkspaceRoot, resolveMcpWorkspace } from "./workspace-root.js";
+export { mcpWorkspaceRoot, resolveMcpWorkspace } from "./workspace-root.js";
 function addFlag(flags, name, value) {
     const current = flags[name];
     if (current === undefined)
@@ -56,48 +60,51 @@ function confirmed(flags, command) {
         throw new ApexError("APEX_USAGE", `${command} requires --yes`, EXIT_CODES.usage);
 }
 function clientId(flags) {
-    const value = flags.client ?? "github-copilot-vscode";
-    if (value !== "github-copilot-cli" && value !== "github-copilot-vscode") {
-        throw new ApexError("APEX_USAGE", "--client must be github-copilot-vscode or github-copilot-cli", EXIT_CODES.usage);
-    }
+    const value = flags.client ?? "github-copilot-cli";
+    if (value !== "github-copilot-cli")
+        throw new ApexError("APEX_USAGE", "--client must be github-copilot-cli", EXIT_CODES.usage);
     return value;
 }
-function profileClientId(flags) {
-    const value = clientId(flags);
-    if (value !== "github-copilot-vscode") {
-        throw new ApexError("APEX_USAGE", "Profile bootstrap is supported only for github-copilot-vscode", EXIT_CODES.usage);
-    }
+function riskOwner(flags) {
+    const value = required(flags, "risk-owner");
+    if (value !== "partner" && value !== "customer")
+        throw new ApexError("APEX_USAGE", "--risk-owner must be partner or customer", EXIT_CODES.usage);
     return value;
 }
 async function inputJson(flags) {
     return JSON.parse(await readFile(required(flags, "file"), "utf8"));
 }
-function defaultProjectId(root) {
-    let value = basename(resolve(root))
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-");
-    while (value.startsWith("-"))
-        value = value.slice(1);
-    while (value.endsWith("-"))
-        value = value.slice(0, -1);
-    return value.length === 0 ? "apex-project" : value;
-}
-async function onboardingConfig(flags, root) {
+async function onboardingConfig(flags, _root) {
     const config = typeof flags.file === "string"
         ? await inputJson(flags)
         : {
             schemaVersion: CONTRACT_VERSION,
-            projectId: typeof flags.project === "string" ? flags.project : defaultProjectId(root),
+            ...(typeof flags.project === "string" ? { projectId: flags.project } : {}),
             ...(typeof flags.name === "string" ? { displayName: flags.name } : {}),
             ...(typeof flags.client === "string" ? { client: flags.client } : {}),
             ...(typeof flags.environment === "string" ? { environment: flags.environment } : {}),
             ...(typeof flags.target === "string" ? { targetScope: flags.target } : {}),
             ...(flags.iac === "terraform" ? { iacTool: "terraform" } : {}),
+            ...(typeof flags["risk-owner"] === "string" ? { riskOwner: flags["risk-owner"] } : {}),
             ...(flags["create-repo"] === true ? { createRepository: true } : {}),
         };
     if (!Value.Check(OnboardingConfigV1Schema, config)) {
         throw new ApexError("APEX_VALIDATION", "Onboarding configuration is malformed", EXIT_CODES.validation);
     }
+    if (config.projectId !== undefined && config.riskOwner === undefined) {
+        throw new ApexError("APEX_VALIDATION", "Project risk owner must be partner or customer", EXIT_CODES.validation);
+    }
+    if (config.projectId !== undefined && config.targetScope === undefined) {
+        throw new ApexError("APEX_USAGE", "--project requires --target", EXIT_CODES.usage);
+    }
+    if (config.targetScope !== undefined)
+        assertTargetScope(config.targetScope);
+    if (config.projectId === undefined && config.riskOwner !== undefined) {
+        throw new ApexError("APEX_USAGE", "--risk-owner requires --project", EXIT_CODES.usage);
+    }
+    if (typeof flags.client === "string" && config.client !== undefined && flags.client !== config.client) {
+        throw new ApexError("APEX_USAGE", "--client conflicts with the onboarding configuration", EXIT_CODES.usage);
+    }
     return config;
 }
 async function configuredProviders(root, flags) {
@@ -311,11 +318,9 @@ async function qualityStatus(root) {
         throw error;
     }
 }
-export async function execute(argv, root = process.cwd(), options = {}) {
-    const { words, flags } = parse(argv);
-    const command = words.join(" ");
+export async function createApexService(root, flags = {}, command = "", options = {}) {
     const runner = new ProcessRunner();
-    const service = new ApexService(root, {
+    return new ApexService(root, {
         ...options,
         providers: { ...options.providers, ...(await configuredProviders(root, flags)) },
         azureAuthStatus: options.azureAuthStatus ??
@@ -340,7 +345,51 @@ export async function execute(argv, root = process.cwd(), options = {}) {
                 }
             }),
     });
+}
+/**
+ * One service per resolved workspace root. Every service sees the others as pending-review guard peers, so a guarded
+ * call aimed at another workspace still fails while any served workspace has a review waiting for its capture.
+ */
+export function mcpServiceResolver(defaultService, create) {
+    const cache = new Map([[defaultService.root, defaultService]]);
+    const peers = () => cache.values();
+    defaultService.setReviewGuardPeers(peers);
+    return {
+        defaultService,
+        resolve: async (workspace) => {
+            const resolved = await resolveMcpWorkspace(workspace);
+            let resolvedService = cache.get(resolved.root);
+            if (resolvedService === undefined) {
+                resolvedService = await create(resolved.root, resolved.workspace);
+                resolvedService.setReviewGuardPeers(peers);
+                cache.set(resolved.root, resolvedService);
+            }
+            return { service: resolvedService, workspace: resolved.workspace };
+        },
+    };
+}
+export async function execute(argv, root = process.cwd(), options = {}, interaction = {}) {
+    const { words, flags } = parse(argv);
+    const command = words.join(" ");
+    if (command === "mcp serve")
+        root = await realpath(await mcpWorkspaceRoot(root));
+    const service = await createApexService(root, flags, command, options);
+    const run = () => dispatch(service, command, flags, root, options, interaction);
+    if (UNSERIALIZED_COMMANDS.has(command))
+        return run();
+    // State-changing commands share the workspace lock that repeat-guarded MCP calls hold. They give it up only while
+    // they wait for interactive input, and fail stale if the workspace changed meanwhile.
+    return service.withWorkspaceWriteLock(run, undefined, { suspendable: true });
+}
+/**
+ * Commands that never write workspace state, not even by finishing a pending recovery, so they do not take the
+ * workspace lock: the long-lived MCP server and the reads that mirror the `read-only` MCP tools.
+ */
+const UNSERIALIZED_COMMANDS = new Set(["mcp serve", "version", "status", "project list"]);
+async function dispatch(service, command, flags, root, options, interaction) {
     switch (command) {
+        case "mcp serve":
+            return serveMcp(mcpServiceResolver(service, (workspaceRoot, workspacePath) => createApexService(workspaceRoot, flags, command, { ...options, workspacePath })));
         case "version": {
             const assets = await resolveBundledAssets();
             return {
@@ -350,48 +399,61 @@ export async function execute(argv, root = process.cwd(), options = {}) {
             };
         }
         case "init":
+            if (flags.client === "github-copilot-cli" && (await service.retiredProjectionInstalled()))
+                return service.replaceRetiredProjection();
             return service.init({
                 projectId: required(flags, "project"),
                 ...(typeof flags.name === "string" ? { displayName: flags.name } : {}),
                 ...(typeof flags.environment === "string" ? { environment: flags.environment } : {}),
-                ...(typeof flags.target === "string" ? { targetScope: flags.target } : {}),
+                targetScope: assertTargetScope(required(flags, "target")),
                 iacTool: flags.iac === "terraform" ? "terraform" : "bicep",
+                riskOwner: riskOwner(flags),
                 clientId: clientId(flags),
                 ...(typeof flags["customizations-source"] === "string"
                     ? { customizationsSource: flags["customizations-source"] }
                     : {}),
             });
+        case "bootstrap plan":
+            return service.planBootstrap(await onboardingConfig(flags, root));
+        case "bootstrap wizard":
+            if (flags.yes === true || flags.json === true)
+                throw new ApexError("APEX_USAGE", "The wizard requires per-plan interactive confirmation; omit --yes and --json", EXIT_CODES.usage);
+            return interactiveBootstrap(root, service, { interaction: interaction.bootstrap });
+        case "bootstrap governance-plan":
+            return service.planGovernanceSetup((await inputJson(flags)));
+        case "bootstrap governance-provision-plan":
+            return service.planGovernanceProvision((await inputJson(flags)));
+        case "bootstrap governance-provision":
+            confirmed(flags, "bootstrap governance-provision");
+            return service.provisionGovernance((await inputJson(flags)), required(flags, "expected-hash"), true);
+        case "bootstrap baseline-check":
+            return service.inspectGovernanceBaselineReadiness(required(flags, "path"));
+        case "bootstrap repository-plan":
+            return service.planRepositoryPublish((await inputJson(flags)));
+        case "bootstrap repository-publish":
+            confirmed(flags, "bootstrap repository-publish");
+            return service.publishRepository((await inputJson(flags)), required(flags, "expected-hash"), true);
+        case "bootstrap coe-plan":
+            return service.planArchetypeBatch((await inputJson(flags)));
+        case "bootstrap coe-import":
+            confirmed(flags, "bootstrap coe-import");
+            return service.importArchetypeBatch((await inputJson(flags)), required(flags, "expected-hash"), true);
         case "bootstrap": {
+            if (Object.keys(flags).length === 0)
+                return interactiveBootstrap(root, service, { interaction: interaction.bootstrap });
             confirmed(flags, "bootstrap");
             const config = await onboardingConfig(flags, root);
-            if (typeof flags.client === "string" && config.client !== undefined && flags.client !== config.client) {
-                throw new ApexError("APEX_USAGE", "--client conflicts with the onboarding configuration", EXIT_CODES.usage);
-            }
             return service.bootstrap({
-                projectId: config.projectId,
+                ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
                 ...(config.displayName === undefined ? {} : { displayName: config.displayName }),
                 ...(config.environment === undefined ? {} : { environment: config.environment }),
                 ...(config.targetScope === undefined ? {} : { targetScope: config.targetScope }),
                 ...(config.iacTool === undefined ? {} : { iacTool: config.iacTool }),
+                ...(config.riskOwner === undefined ? {} : { riskOwner: config.riskOwner }),
                 clientId: config.client ?? clientId(flags),
                 ...(config.createRepository === undefined ? {} : { createRepository: config.createRepository }),
             });
         }
-        case "profile status":
-            profileClientId(flags);
-            return service.profileStatus();
-        case "profile install":
-            confirmed(flags, "profile install");
-            profileClientId(flags);
-            return service.profileInstall();
-        case "profile update":
-            confirmed(flags, "profile update");
-            profileClientId(flags);
-            return service.profileUpdate();
-        case "profile uninstall":
-            confirmed(flags, "profile uninstall");
-            profileClientId(flags);
-            return service.profileUninstall();
         case "update":
             return service.update(typeof flags["customizations-source"] === "string" ? flags["customizations-source"] : undefined);
         case "setup":
@@ -423,8 +485,9 @@ export async function execute(argv, root = process.cwd(), options = {}) {
                 projectId: required(flags, "project"),
                 ...(typeof flags.name === "string" ? { displayName: flags.name } : {}),
                 ...(typeof flags.environment === "string" ? { environment: flags.environment } : {}),
-                ...(typeof flags.target === "string" ? { targetScope: flags.target } : {}),
+                targetScope: assertTargetScope(required(flags, "target")),
                 iacTool: flags.iac === "terraform" ? "terraform" : "bicep",
+                riskOwner: riskOwner(flags),
             });
         case "project delete":
             confirmed(flags, "project delete");
@@ -476,23 +539,73 @@ export async function execute(argv, root = process.cwd(), options = {}) {
             confirmed(flags, "provider transfer-import");
             return importProviderTransfer(root, JSON.parse(await readFile(required(flags, "file"), "utf8")), required(flags, "recipient"));
         }
+        case "archetype list":
+            return service.listArchetypes(required(flags, "repository"), required(flags, "revision"), required(flags, "path"));
+        case "archetype inspect":
+            return service.inspectArchetype(required(flags, "repository"), required(flags, "revision"), required(flags, "path"));
+        case "archetype import":
+            confirmed(flags, "archetype import");
+            return service.importArchetype({
+                repositoryPath: required(flags, "repository"),
+                revision: required(flags, "revision"),
+                selectedPath: required(flags, "path"),
+                destination: required(flags, "destination"),
+                expectedHash: required(flags, "expected-hash"),
+                confirm: true,
+            });
         case "status":
-            return service.status();
+            return service.workspaceStatus();
+        case "requirements preview-change":
+            return service.previewRequirementsChange((await inputJson(flags)), required(flags, "reason"));
+        case "requirements preview-amendment":
+            return service.previewRequirementsAmendment((await inputJson(flags)), required(flags, "reason"));
+        case "requirements amend":
+            confirmed(flags, "requirements amend");
+            return service.amendRequirements((await inputJson(flags)), {
+                reason: required(flags, "reason"),
+                expectedHash: required(flags, "expected-hash"),
+                confirm: true,
+            });
+        case "requirements preview-adoption":
+            return service.previewRequirementsChange((await inputJson(flags)), required(flags, "reason"), "adopt");
+        case "requirements adopt":
+            confirmed(flags, "requirements adopt");
+            return service.reviseRequirements((await inputJson(flags)), {
+                reason: required(flags, "reason"),
+                expectedHash: required(flags, "expected-hash"),
+                confirm: true,
+                mode: "adopt",
+            });
+        case "requirements revise":
+            confirmed(flags, "requirements revise");
+            return service.reviseRequirements((await inputJson(flags)), {
+                reason: required(flags, "reason"),
+                expectedHash: required(flags, "expected-hash"),
+                confirm: true,
+            });
+        case "governance import":
+            if (flags.reference === undefined)
+                return service.importGovernanceBaseline(required(flags, "path"));
+            if (flags.reference !== true || flags.path !== undefined)
+                throw new ApexError("APEX_USAGE", "Use exactly one of --path or --reference", EXIT_CODES.usage);
+            return service.importGovernanceReference();
+        case "governance revise": {
+            confirmed(flags, "governance revise");
+            return service.reviseGovernanceBaseline(required(flags, "path"), {
+                confirm: true,
+                reason: required(flags, "reason"),
+            });
+        }
+        case "governance select":
+            return service.selectGovernanceBaseline(required(flags, "path"), ...(flags.reopen === true ? [{ reopen: true }] : []));
         case "task next":
             return service.nextTask();
         case "task context":
             return service.taskContext(required(flags, "task"));
         case "task complete": {
             const paths = files(flags);
-            if (paths.length > 1) {
-                const outputs = await Promise.all(paths.map(async (path) => JSON.parse(await readFile(path, "utf8"))));
-                return service.completeTaskOutputs(required(flags, "task"), outputs);
-            }
-            return service.completeTask(required(flags, "task"), {
-                kind: required(flags, "kind"),
-                value: JSON.parse(await readFile(paths[0], "utf8")),
-                ...(typeof flags.summary === "string" ? { summary: flags.summary } : {}),
-            });
+            const outputs = await Promise.all(paths.map(async (path) => JSON.parse(await readFile(path, "utf8"))));
+            return service.completeTaskOutputs(required(flags, "task"), outputs);
         }
         case "task complete-bundle": {
             const bundle = (await inputJson(flags));
@@ -545,8 +658,6 @@ export async function execute(argv, root = process.cwd(), options = {}) {
             return service.diagnose();
         case "render":
             return service.render(required(flags, "kind"));
-        case "promote":
-            return service.promote(required(flags, "environment"), required(flags, "target"));
         case "customizations rollback":
             return service.rollbackCustomizations();
         case "customizations uninstall":
@@ -615,9 +726,6 @@ export async function execute(argv, root = process.cwd(), options = {}) {
         case "quality prune":
             confirmed(flags, "quality prune");
             return service.improvementPrune();
-        case "mcp serve":
-            await serveMcp(service);
-            return undefined;
         default:
             throw new ApexError("APEX_USAGE", `Unknown command: ${command || "<none>"}`, EXIT_CODES.usage);
     }
@@ -646,6 +754,8 @@ async function main() {
 export function formatHumanResult(args, result) {
     const command = args.find((argument) => !argument.startsWith("--"));
     if (command === "status" && result !== null && typeof result === "object") {
+        if ("status" in result && result.status === "needs_project")
+            return "Workspace configured. No projects yet. Open APEX to gather details and create the first project.";
         const status = result;
         const task = status.task ?? null;
         const stage = task?.startsWith("requirements")
@@ -673,14 +783,21 @@ export function formatHumanResult(args, result) {
         const passed = doctor.checks?.filter(({ ok }) => ok).length ?? 0;
         const total = doctor.checks?.length ?? 0;
         const remaining = doctor.remedies?.length ?? 0;
+        const warnings = doctor.checks?.filter(({ ok, severity }) => ok && severity === "warning") ?? [];
+        const warning = warnings[0]?.remedy ?? warnings[0]?.value;
         return [
             `Status: ${doctor.healthy ? "Ready" : "Setup incomplete"} (${passed}/${total} checks ready)`,
             `Next: ${doctor.nextAction ?? "No action required"}`,
             ...(remaining > 1 ? [`Later: ${remaining - 1} additional setup item${remaining === 2 ? "" : "s"}`] : []),
+            ...(warnings.length > 0
+                ? [`Warning: ${warning ?? "see doctor --json"}${warnings.length > 1 ? ` (+${warnings.length - 1} more)` : ""}`]
+                : []),
         ].join("\n");
     }
     return typeof result === "string" ? result : JSON.stringify(result, null, 2);
 }
-if (process.argv[1] !== undefined && (await realpath(process.argv[1])) === (await realpath(new URL(import.meta.url))))
+if (typeof __APEX_PLUGIN_BUNDLE__ === "undefined" &&
+    process.argv[1] !== undefined &&
+    (await realpath(process.argv[1])) === (await realpath(new URL(import.meta.url))))
     await main();
 //# sourceMappingURL=cli.js.map

package/dist/dependency-revision.js

@@ -1,6 +1,14 @@
 import { sha256Json } from "@apexops/kernel";
 export function dependencyRevision(run, events) {
     const artifacts = events.reduce((current, event) => {
+        if (event.type === "workflow.invalidated") {
+            const payload = event.payload;
+            for (const kind of payload.artifactKinds ?? [])
+                delete current[kind];
+            if (payload.governanceRevision?.retainedReviewHash !== undefined)
+                current["review-findings"] = payload.governanceRevision.retainedReviewHash;
+            return current;
+        }
         if (event.type !== "task.completed")
             return current;
         const hashes = event.payload.artifactHashes ?? {};

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { GovernanceBaselineError } from "@apexops/capabilities";
 export declare const EXIT_CODES: {
     readonly success: 0;
     readonly usage: 2;
@@ -8,12 +9,16 @@ export declare const EXIT_CODES: {
     readonly authorization: 7;
     readonly internal: 10;
 };
-export type ApexErrorCode = "APEX_USAGE" | "APEX_NOT_FOUND" | "APEX_CONFLICT" | "APEX_VALIDATION" | "APEX_STALE" | "APEX_AUTHORIZATION" | "APEX_INTERNAL";
+export type ApexErrorCode = "APEX_USAGE" | "APEX_NOT_FOUND" | "APEX_CONFLICT" | "APEX_WRITER_CONFLICT" | "APEX_WORKSPACE_UNSUPPORTED" | "APEX_RUNTIME_MISMATCH" | "APEX_VALIDATION" | "APEX_STALE" | "APEX_AUTHORIZATION" | "APEX_CURSOR_INVALID" | "APEX_RESULT_TOO_LARGE" | "APEX_REVIEW_PENDING" | "APEX_INTERNAL";
 export declare class ApexError extends Error {
     readonly code: ApexErrorCode;
     readonly exitCode: number;
     readonly details?: unknown;
     constructor(code: ApexErrorCode, message: string, exitCode: number, details?: unknown, options?: ErrorOptions);
 }
+export type RuntimeMismatchReason = "RUNTIME_WORKSPACE_OLDER" | "RUNTIME_WORKSPACE_NEWER" | "RUNTIME_LOCK_INVALID";
+export declare function remediationForApexError(error: ApexError): string;
 export declare function normalizeError(error: unknown): ApexError;
+export declare function governanceBaselineApexError(error: GovernanceBaselineError, source?: "baseline" | "reference"): ApexError;
+export declare function retiredProjectionError(): ApexError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -1,3 +1,6 @@
+import { GovernanceBaselineError } from "@apexops/capabilities";
+import { RunWriterConflictError } from "@apexops/kernel";
+import { APEX_VERSION } from "./version.js";
 export const EXIT_CODES = {
     success: 0,
     usage: 2,
@@ -20,9 +23,44 @@ export class ApexError extends Error {
         this.name = "ApexError";
     }
 }
+const REMEDIATION_BY_CODE = {
+    APEX_USAGE: "Fix the tool arguments to match the input schema, then call the tool again.",
+    APEX_NOT_FOUND: "Call status first, refresh the identifiers, and retry only with an existing project, run, or task.",
+    APEX_CONFLICT: "Call status and retry only if the refreshed state still requires this action; never retry mutations blindly after cancellation or timeout.",
+    APEX_WRITER_CONFLICT: "Continue from the owning worktree, release the writer lease there, or wait for the lease to expire before retrying.",
+    APEX_WORKSPACE_UNSUPPORTED: "Use the absolute path of a supported APEX checkout or git worktree, or start a workspace-aware MCP server.",
+    APEX_RUNTIME_MISMATCH: "Make this APEX runtime and the workspace runtime lock the same version: run `apex update` for an older workspace, or install the matching APEX plugin or @apexops/cli version for a newer one.",
+    APEX_VALIDATION: "Correct the validation issues against the current tool contract, then call the tool again.",
+    APEX_STALE: "Call status to refresh state and use the latest expected head, epoch, task, or cursor before retrying.",
+    APEX_AUTHORIZATION: "Call status and obtain the required human approval or decision before retrying.",
+    APEX_CURSOR_INVALID: "Discard the cursor, call the same tool again without it, and continue only from the new result; cursors do not survive an MCP server restart.",
+    APEX_RESULT_TOO_LARGE: "Request a smaller bounded result, use a paging-capable read tool, or narrow the requested document or collection.",
+    APEX_REVIEW_PENDING: "Finish the pending rubber-duck review with reviewComplete, or have the user stop any running rubber-duck and then cancel the review from a terminal with apex task cancel; then retry.",
+    APEX_INTERNAL: "Report this with the server log; retry only after checking status because side effects may have completed.",
+};
+const RUNTIME_MISMATCH_REMEDIATION = {
+    RUNTIME_WORKSPACE_OLDER: `Run \`apex update\` in the workspace with @apexops/cli@${APEX_VERSION}, the runtime this server runs, then call status again.`,
+    RUNTIME_WORKSPACE_NEWER: "Install the APEX plugin or @apexops/cli version named by the workspace runtime lock and restart the MCP server; do not downgrade the workspace with an older runtime.",
+    RUNTIME_LOCK_INVALID: `Inspect .apex/apex.lock.json; if a newer APEX runtime did not write it, run \`apex doctor --fix --yes\` in the workspace with @apexops/cli@${APEX_VERSION} to rewrite it, then call status again.`,
+};
+// Remediation is a fixed hint per stable code (and, for a runtime mismatch, per fixed reason) so error details,
+// causes, and paths never reach MCP clients.
+export function remediationForApexError(error) {
+    if (error.code === "APEX_RUNTIME_MISMATCH") {
+        const reason = error.details?.reason;
+        if (typeof reason === "string" && Object.hasOwn(RUNTIME_MISMATCH_REMEDIATION, reason))
+            return RUNTIME_MISMATCH_REMEDIATION[reason];
+    }
+    return REMEDIATION_BY_CODE[error.code];
+}
 export function normalizeError(error) {
     if (error instanceof ApexError)
         return error;
+    if (error instanceof GovernanceBaselineError)
+        return governanceBaselineApexError(error);
+    if (error instanceof RunWriterConflictError) {
+        return new ApexError("APEX_WRITER_CONFLICT", `${error.message}; retry from that worktree, release the writer lease there, or wait for it to expire`, EXIT_CODES.conflict, { ownerWorktree: error.ownerWorktree, expiresAt: error.expiresAt }, { cause: error });
+    }
     if (error instanceof Error && /expired|stale/i.test(error.message)) {
         return new ApexError("APEX_STALE", error.message, EXIT_CODES.stale, undefined, { cause: error });
     }
@@ -31,4 +69,21 @@ export function normalizeError(error) {
     }
     return new ApexError("APEX_INTERNAL", error instanceof Error ? error.message : String(error), EXIT_CODES.internal, undefined, { cause: error });
 }
+const GOVERNANCE_BASELINE_HINTS = {
+    incomplete: "the baseline does not fully cover the target scope; recollect it with tools/scripts/collect-governance-baseline.ps1 -IncludeDescendants and confirm coverage_status is COMPLETE",
+    "target-mismatch": "the baseline scope does not match the project target scope; collect it for the target subscription or its management group",
+    stale: "the baseline is too old; collect a fresh baseline",
+    "invalid-input": "the file does not match the governance baseline schema; recollect it with tools/scripts/collect-governance-baseline.ps1",
+    "invalid-options": "the project target scope cannot be checked against a baseline; check the project target scope",
+};
+export function governanceBaselineApexError(error, source = "baseline") {
+    const stale = error.code === "stale";
+    const hint = source === "reference"
+        ? "the bundled governance reference is unusable; run apex doctor --fix --yes or update APEX"
+        : GOVERNANCE_BASELINE_HINTS[error.code];
+    return new ApexError(stale ? "APEX_STALE" : "APEX_VALIDATION", `${error.message}: ${hint}`, stale ? EXIT_CODES.stale : EXIT_CODES.validation, { reason: `GOVERNANCE_${source.toUpperCase()}_${error.code.toUpperCase().replaceAll("-", "_")}` }, { cause: error });
+}
+export function retiredProjectionError() {
+    return new ApexError("APEX_VALIDATION", "The VS Code projection is retired; run `apex init --client github-copilot-cli`", EXIT_CODES.validation, { reason: "CLIENT_PROJECTION_RETIRED" });
+}
 //# sourceMappingURL=errors.js.map

package/dist/host-profile.d.ts

@@ -0,0 +1,47 @@
+/** The machine `apex doctor` inspects. Injected in tests; defaults to the running process. */
+export interface HostEnvironment {
+    readonly platform: NodeJS.Platform;
+    /** Kernel release, as `os.release()` reports it; distinguishes WSL1 from WSL2. */
+    readonly release: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly homedir: string;
+}
+/**
+ * DECISION-033 hosts. The host decides the client: native Windows (and best-effort macOS) runs VS Code with the Copilot
+ * harness or the GitHub Copilot app; Linux and WSL2 run Copilot CLI. Every workspace selects the `github-copilot-cli`
+ * projection, so the projection cannot tell the clients apart; the host can.
+ */
+export type HostKind = "windows" | "macos" | "wsl2" | "linux" | "wsl1" | "unsupported";
+export interface HostCheck {
+    id: string;
+    ok: boolean;
+    value: string;
+    remedy?: string;
+    /** Present only on advisory checks that pass but report something the user should know. */
+    severity?: "warning";
+}
+export interface HostCheckInputs {
+    host: HostEnvironment;
+    minimums: {
+        vscode?: string | undefined;
+        copilotCli?: string | undefined;
+    };
+    plugin: {
+        name: string;
+        marketplace: string;
+    };
+    apexVersion: string;
+    executableExists: (executable: string) => Promise<boolean>;
+    /** First stable `major.minor.patch` the executable reports for `args`, or undefined when it cannot be read. */
+    toolVersion: (executable: string, args: readonly string[]) => Promise<string | undefined>;
+}
+export declare function currentHostEnvironment(): HostEnvironment;
+export declare function detectHostKind(host: HostEnvironment): HostKind;
+/** Hosts whose supported client is Copilot CLI; VS Code there is not an APEX client. */
+export declare function isCopilotCliHost(kind: HostKind): boolean;
+/** Extracts the first stable release version from tool output such as `GitHub Copilot CLI 1.0.93.`. */
+export declare function firstReleaseVersion(output: string): string | undefined;
+export declare function copilotHome(host: HostEnvironment): string;
+/** Read-only host checks for the supported client on this host. Each failing or advisory check carries a remedy. */
+export declare function hostDoctorChecks(inputs: HostCheckInputs): Promise<HostCheck[]>;
+//# sourceMappingURL=host-profile.d.ts.map