agentplane 0.2.12 → 0.2.13

package/dist/cli/command-guide.js

@@ -244,7 +244,7 @@ export function renderQuickstart() {
         "## Global flags",
         "",
         "- `--root <path>`: treat <path> as project root",
-        "- `--json`: emit JSON-formatted errors",
+        "- `--json-errors`: emit JSON-formatted errors",
         "- `--help` / `-h`: show help",
         "- `--version`: show version",
         "- `--no-update-check`: skip checking npm for a newer CLI version",

package/dist/cli/run-cli/command-catalog.js

@@ -34,7 +34,7 @@ import { workStartSpec } from "../../commands/branch/work-start.command.js";
 import { branchBaseClearSpec, branchBaseExplainSpec, branchBaseGetSpec, branchBaseSetSpec, branchBaseSpec, } from "../../commands/branch/base.command.js";
 import { branchStatusSpec } from "../../commands/branch/status.command.js";
 import { branchRemoveSpec } from "../../commands/branch/remove.command.js";
-import { recipesInstallSpec } from "../../commands/recipes/install.command.js";
+import { recipesInstallSpec } from "../../commands/recipes/install.spec.js";
 import { recipesListSpec } from "../../commands/recipes/list.command.js";
 import { recipesListRemoteSpec } from "../../commands/recipes/list-remote.command.js";
 import { recipesInfoSpec } from "../../commands/recipes/info.command.js";
@@ -58,7 +58,7 @@ import { blockSpec } from "../../commands/block.spec.js";
 import { verifySpec } from "../../commands/verify.spec.js";
 import { finishSpec } from "../../commands/finish.spec.js";
 import { readySpec } from "../../commands/ready.command.js";
-import { doctorSpec } from "../../commands/doctor.command.js";
+import { doctorSpec } from "../../commands/doctor.spec.js";
 import { docsCliSpec } from "../../commands/docs/cli.command.js";
 import { hooksSpec } from "../../commands/hooks/hooks.command.js";
 import { hooksInstallSpec } from "../../commands/hooks/install.command.js";
@@ -147,7 +147,7 @@ export const COMMANDS = [
         needsConfig: true,
         needsTaskContext: false,
     }),
-    entry(doctorSpec, () => import("../../commands/doctor.command.js").then((m) => m.runDoctor), {
+    entry(doctorSpec, () => import("../../commands/doctor.run.js").then((m) => m.runDoctor), {
         needsProject: true,
         needsConfig: false,
         needsTaskContext: false,
@@ -189,7 +189,7 @@ export const COMMANDS = [
     entry(recipesExplainSpec, () => import("../../commands/recipes/explain.command.js").then((m) => m.runRecipesExplain)),
     entry(recipesRemoveSpec, () => import("../../commands/recipes/remove.command.js").then((m) => m.runRecipesRemove)),
     entry(recipesCachePruneSpec, () => import("../../commands/recipes/cache-prune.command.js").then((m) => m.runRecipesCachePrune)),
-    entry(recipesInstallSpec, () => import("../../commands/recipes/install.command.js").then((m) => m.runRecipesInstall)),
+    entry(recipesInstallSpec, () => import("../../commands/recipes/install.run.js").then((m) => m.runRecipesInstall)),
     entry(scenarioSpec, () => import("../../commands/scenario/scenario.command.js").then((m) => m.runScenario)),
     entry(scenarioListSpec, () => import("../../commands/scenario/list.command.js").then((m) => m.runScenarioList)),
     entry(scenarioInfoSpec, () => import("../../commands/scenario/info.command.js").then((m) => m.runScenarioInfo)),

package/dist/cli/run-cli/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/config.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAMxD,CAAC;AAiBF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAExF;AAED,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAgBtD,CAAC;AA6BF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC,CAStF;AAED,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAMlD,CAAC;AAiBF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF;AAED,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAgBlD,CAAC;AA0BF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAQlF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAMxD,CAAC;AAcF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAExF;AAED,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAgBtD,CAAC;AA6BF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC,CAStF;AAED,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAMlD,CAAC;AAcF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF;AAED,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAgBlD,CAAC;AA0BF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAQlF"}

package/dist/cli/run-cli/commands/config.js

@@ -1,8 +1,7 @@
 import path from "node:path";
 import { saveConfig, setByDottedKey } from "@agentplaneorg/core";
-import { mapCoreError } from "../../error-map.js";
 import { usageError } from "../../spec/errors.js";
-import { CliError } from "../../../shared/errors.js";
+import { wrapCommand } from "./wrap-command.js";
 export const configShowSpec = {
     id: ["config", "show"],
     group: "Config",
@@ -11,16 +10,11 @@ export const configShowSpec = {
     parse: () => ({}),
 };
 async function cmdConfigShow(opts) {
-    try {
+    return wrapCommand({ command: "config show", rootOverride: opts.rootOverride }, async () => {
         const loaded = await opts.deps.getLoadedConfig("config show");
         process.stdout.write(`${JSON.stringify(loaded.raw, null, 2)}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, { command: "config show", root: opts.rootOverride ?? null });
-    }
+    });
 }
 export function makeRunConfigShowHandler(deps) {
     return (ctx) => cmdConfigShow({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, deps });
@@ -43,7 +37,11 @@ export const configSetSpec = {
     parse: (raw) => ({ key: String(raw.args.key ?? ""), value: String(raw.args.value ?? "") }),
 };
 async function cmdConfigSet(opts) {
-    try {
+    return wrapCommand({
+        command: "config set",
+        rootOverride: opts.rootOverride,
+        context: { key: opts.key },
+    }, async () => {
         const resolved = await opts.deps.getResolvedProject("config set");
         const loaded = await opts.deps.getLoadedConfig("config set");
         const raw = { ...loaded.raw };
@@ -51,16 +49,7 @@ async function cmdConfigSet(opts) {
         await saveConfig(resolved.agentplaneDir, raw);
         process.stdout.write(`${path.relative(resolved.gitRoot, path.join(resolved.agentplaneDir, "config.json"))}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, {
-            command: "config set",
-            key: opts.key,
-            root: opts.rootOverride ?? null,
-        });
-    }
+    });
 }
 export function makeRunConfigSetHandler(deps) {
     return (ctx, p) => cmdConfigSet({
@@ -79,16 +68,11 @@ export const modeGetSpec = {
     parse: () => ({}),
 };
 async function cmdModeGet(opts) {
-    try {
+    return wrapCommand({ command: "mode get", rootOverride: opts.rootOverride }, async () => {
         const loaded = await opts.deps.getLoadedConfig("mode get");
         process.stdout.write(`${loaded.config.workflow_mode}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, { command: "mode get", root: opts.rootOverride ?? null });
-    }
+    });
 }
 export function makeRunModeGetHandler(deps) {
     return (ctx) => cmdModeGet({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, deps });
@@ -111,7 +95,11 @@ export const modeSetSpec = {
     },
 };
 async function cmdModeSet(opts) {
-    try {
+    return wrapCommand({
+        command: "mode set",
+        rootOverride: opts.rootOverride,
+        context: { mode: opts.mode },
+    }, async () => {
         const resolved = await opts.deps.getResolvedProject("mode set");
         const loaded = await opts.deps.getLoadedConfig("mode set");
         const raw = { ...loaded.raw };
@@ -119,16 +107,7 @@ async function cmdModeSet(opts) {
         await saveConfig(resolved.agentplaneDir, raw);
         process.stdout.write(`${opts.mode}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, {
-            command: "mode set",
-            root: opts.rootOverride ?? null,
-            mode: opts.mode,
-        });
-    }
+    });
 }
 export function makeRunModeSetHandler(deps) {
     return (ctx, p) => cmdModeSet({

package/dist/cli/run-cli/commands/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAOxD,CAAC;AAYF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAG1D,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAO5C,CAAC;AAgLF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA+DhF"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAOxD,CAAC;AASF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAO5C,CAAC;AAkMF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}

package/dist/cli/run-cli/commands/core.js

@@ -1,13 +1,13 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveProject } from "@agentplaneorg/core";
-import { mapCoreError } from "../../error-map.js";
 import { fileExists } from "../../fs-utils.js";
 import { CliError } from "../../../shared/errors.js";
 import { dedupeStrings } from "../../../shared/strings.js";
 import { usageError } from "../../spec/errors.js";
 import { listRoles, renderQuickstart, renderRole } from "../../command-guide.js";
 import { toStringList } from "../../spec/parse-utils.js";
+import { wrapCommand } from "./wrap-command.js";
 export const quickstartSpec = {
     id: ["quickstart"],
     group: "Core",
@@ -16,20 +16,14 @@ export const quickstartSpec = {
     examples: [{ cmd: "agentplane quickstart", why: "Show quickstart." }],
     parse: () => ({}),
 };
-function cmdQuickstart(opts) {
-    try {
+async function cmdQuickstart(opts) {
+    return wrapCommand({ command: "quickstart", rootOverride: opts.rootOverride }, () => {
         process.stdout.write(`${renderQuickstart()}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, { command: "quickstart", root: opts.rootOverride ?? null });
-    }
+    });
 }
 export const runQuickstart = (ctx) => {
-    cmdQuickstart({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });
-    return Promise.resolve(0);
+    return cmdQuickstart({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });
 };
 export const roleSpec = {
     id: ["role"],
@@ -39,6 +33,27 @@ export const roleSpec = {
     examples: [{ cmd: "agentplane role ORCHESTRATOR", why: "Show ORCHESTRATOR guide." }],
     parse: (raw) => ({ role: String(raw.args.role ?? "") }),
 };
+function parseAgentProfileJson(filePath, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Invalid agent profile JSON: ${filePath} (malformed JSON)`,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Invalid agent profile JSON: ${filePath} (expected object)`,
+        });
+    }
+    return parsed;
+}
 function normalizeRoleId(roleRaw) {
     return roleRaw.trim().toUpperCase();
 }
@@ -87,7 +102,7 @@ async function readAgentProfile(opts) {
         return null;
     const filename = `${foundId}.json`;
     const filePath = path.join(listing.agentplaneDir, "agents", filename);
-    const raw = JSON.parse(await readFile(filePath, "utf8"));
+    const raw = parseAgentProfileJson(filePath, await readFile(filePath, "utf8"));
     return { agentplaneDir: listing.agentplaneDir, filename, profile: raw };
 }
 function renderAgentProfileBlock(opts) {
@@ -112,7 +127,7 @@ function renderAgentProfileBlock(opts) {
     return lines.join("\n").trimEnd();
 }
 async function cmdRole(opts) {
-    try {
+    return wrapCommand({ command: "role", rootOverride: opts.rootOverride }, async () => {
         const roleRaw = opts.role.trim();
         if (!roleRaw) {
             throw usageError({
@@ -170,12 +185,7 @@ async function cmdRole(opts) {
         });
         process.stdout.write(`${block}\n`);
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, { command: "role", root: opts.rootOverride ?? null });
-    }
+    });
 }
 export const runRole = (ctx, p) => {
     return cmdRole({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, role: p.role });
@@ -188,64 +198,83 @@ export const agentsSpec = {
     parse: () => ({}),
 };
 export function makeRunAgentsHandler(deps) {
-    return async (ctx) => {
-        try {
-            const resolved = await deps.getResolvedProject("agents");
-            const agentsDir = path.join(resolved.agentplaneDir, "agents");
-            if (!(await fileExists(agentsDir))) {
-                throw new CliError({
-                    exitCode: 2,
-                    code: "E_USAGE",
-                    message: `Agents directory not found: ${agentsDir} (run \`agentplane init\`)`,
-                });
+    return async (ctx) => wrapCommand({ command: "agents", rootOverride: ctx.rootOverride }, async () => {
+        const resolved = await deps.getResolvedProject("agents");
+        const agentsDir = path.join(resolved.agentplaneDir, "agents");
+        if (!(await fileExists(agentsDir))) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Agents directory not found: ${agentsDir} (run \`agentplane init\`)`,
+            });
+        }
+        const entriesRaw = await readdir(agentsDir);
+        const entries = entriesRaw.filter((name) => name.endsWith(".json")).toSorted();
+        if (entries.length === 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `No agent definitions found under ${agentsDir} (expected *.json)`,
+            });
+        }
+        const rows = [];
+        const seen = new Set();
+        const duplicates = [];
+        const mismatches = [];
+        for (const entry of entries) {
+            const canonicalId = entry.replace(/\.json$/i, "");
+            const filePath = path.join(agentsDir, entry);
+            const raw = parseAgentProfileJson(filePath, await readFile(filePath, "utf8"));
+            const rawId = typeof raw.id === "string" ? raw.id : "";
+            const rawRole = typeof raw.role === "string" ? raw.role : "";
+            const normalizedRawId = rawId.trim();
+            const role = rawRole.trim() || "-";
+            if (seen.has(canonicalId)) {
+                duplicates.push(canonicalId);
             }
-            const entriesRaw = await readdir(agentsDir);
-            const entries = entriesRaw.filter((name) => name.endsWith(".json")).toSorted();
-            if (entries.length === 0) {
-                throw new CliError({
-                    exitCode: 2,
-                    code: "E_USAGE",
-                    message: `No agent definitions found under ${agentsDir} (expected *.json)`,
-                });
+            else {
+                seen.add(canonicalId);
             }
-            const rows = [];
-            const seen = new Set();
-            const duplicates = [];
-            for (const entry of entries) {
-                const filePath = path.join(agentsDir, entry);
-                const raw = JSON.parse(await readFile(filePath, "utf8"));
-                const rawId = typeof raw.id === "string" ? raw.id : "";
-                const rawRole = typeof raw.role === "string" ? raw.role : "";
-                const agentId = rawId.trim() || "<missing-id>";
-                const role = rawRole.trim() || "-";
-                if (seen.has(agentId)) {
-                    duplicates.push(agentId);
-                }
-                else {
-                    seen.add(agentId);
-                }
-                rows.push([agentId, role, entry]);
+            if (normalizedRawId.length > 0 && normalizedRawId !== canonicalId) {
+                mismatches.push({ filename: entry, canonicalId, rawId: normalizedRawId });
+            }
+            rows.push({ canonicalId, role, filename: entry, rawId: normalizedRawId });
+        }
+        const showRawIdColumn = mismatches.length > 0;
+        const widthId = Math.max(...rows.map((row) => row.canonicalId.length), "ID".length);
+        const widthFile = Math.max(...rows.map((row) => row.filename.length), "FILE".length);
+        if (showRawIdColumn) {
+            const widthRawId = Math.max(...rows.map((row) => row.rawId.length), "RAW_ID".length);
+            process.stdout.write(`${"ID".padEnd(widthId)}  ${"FILE".padEnd(widthFile)}  ${"RAW_ID".padEnd(widthRawId)}  ROLE\n`);
+            process.stdout.write(`${"-".repeat(widthId)}  ${"-".repeat(widthFile)}  ${"-".repeat(widthRawId)}  ----\n`);
+            for (const row of rows) {
+                process.stdout.write(`${row.canonicalId.padEnd(widthId)}  ${row.filename.padEnd(widthFile)}  ${row.rawId.padEnd(widthRawId)}  ${row.role}\n`);
             }
-            const widthId = Math.max(...rows.map((row) => row[0].length), "ID".length);
-            const widthFile = Math.max(...rows.map((row) => row[2].length), "FILE".length);
+        }
+        else {
             process.stdout.write(`${"ID".padEnd(widthId)}  ${"FILE".padEnd(widthFile)}  ROLE\n`);
             process.stdout.write(`${"-".repeat(widthId)}  ${"-".repeat(widthFile)}  ----\n`);
-            for (const [agentId, role, filename] of rows) {
-                process.stdout.write(`${agentId.padEnd(widthId)}  ${filename.padEnd(widthFile)}  ${role}\n`);
-            }
-            if (duplicates.length > 0) {
-                throw new CliError({
-                    exitCode: 2,
-                    code: "E_USAGE",
-                    message: `Duplicate agent ids: ${dedupeStrings(duplicates).toSorted().join(", ")}`,
-                });
+            for (const row of rows) {
+                process.stdout.write(`${row.canonicalId.padEnd(widthId)}  ${row.filename.padEnd(widthFile)}  ${row.role}\n`);
             }
-            return 0;
         }
-        catch (err) {
-            if (err instanceof CliError)
-                throw err;
-            throw mapCoreError(err, { command: "agents", root: ctx.rootOverride ?? null });
+        if (duplicates.length > 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Duplicate canonical agent ids: ${dedupeStrings(duplicates).toSorted().join(", ")}`,
+            });
+        }
+        if (mismatches.length > 0) {
+            const details = mismatches
+                .map((m) => `${m.filename}: raw id "${m.rawId}" != canonical "${m.canonicalId}"`)
+                .join("; ");
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Agent profile id mismatch: ${details}`,
+            });
         }
-    };
+        return 0;
+    });
 }

package/dist/cli/run-cli/commands/ide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}

package/dist/cli/run-cli/commands/ide.js

@@ -1,8 +1,7 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { mapCoreError } from "../../error-map.js";
 import { writeTextIfChanged } from "../../../shared/write-if-changed.js";
-import { CliError } from "../../../shared/errors.js";
+import { wrapCommand } from "./wrap-command.js";
 export const ideSyncSpec = {
     id: ["ide", "sync"],
     group: "IDE",
@@ -23,7 +22,7 @@ export const ideSyncSpec = {
     parse: (raw) => ({ ide: raw.opts.ide }),
 };
 export async function cmdIdeSync(opts) {
-    try {
+    return wrapCommand({ command: "ide sync", rootOverride: opts.rootOverride }, async () => {
         const resolved = await opts.deps.getResolvedProject("ide sync");
         const agentsPath = path.join(resolved.gitRoot, "AGENTS.md");
         const agentsText = await readFile(agentsPath, "utf8");
@@ -56,12 +55,7 @@ export async function cmdIdeSync(opts) {
             process.stdout.write(`${path.relative(resolved.gitRoot, windsurfPath)}\n`);
         }
         return 0;
-    }
-    catch (err) {
-        if (err instanceof CliError)
-            throw err;
-        throw mapCoreError(err, { command: "ide sync", root: opts.rootOverride ?? null });
-    }
+    });
 }
 export function makeRunIdeSyncHandler(deps) {
     return (ctx, p) => cmdIdeSync({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, ide: p.ide, deps });

package/dist/cli/run-cli/commands/init/write-gitignore.d.ts

@@ -1,4 +1,5 @@
-export declare function ensureGitignoreAgents(opts: {
+export declare function ensureInitGitignore(opts: {
     gitRoot: string;
+    includeAgentPromptFiles: boolean;
 }): Promise<void>;
 //# sourceMappingURL=write-gitignore.d.ts.map

package/dist/cli/run-cli/commands/init/write-gitignore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-gitignore.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-gitignore.ts"],"names":[],"mappings":"AAeA,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpF"}
+{"version":3,"file":"write-gitignore.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-gitignore.ts"],"names":[],"mappings":"AAgCA,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB,EAAE,OAAO,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhB"}

package/dist/cli/run-cli/commands/init/write-gitignore.js

@@ -12,14 +12,27 @@ async function readTextIfExists(filePath) {
         throw err;
     }
 }
-export async function ensureGitignoreAgents(opts) {
+const RUNTIME_IGNORE_LINES = [
+    "# agentplane: ignore runtime/transient workspace artifacts",
+    ".agentplane/worktrees",
+    ".agentplane/cache",
+    ".agentplane/recipes-cache",
+    ".agentplane/.upgrade",
+    ".agentplane/.release",
+    ".agentplane/upgrade",
+    ".agentplane/tasks.json",
+];
+const AGENT_PROMPT_IGNORE_LINES = [
+    "# agentplane: ignore local agent prompts/templates",
+    "AGENTS.md",
+    ".agentplane/agents/",
+];
+export async function ensureInitGitignore(opts) {
     const gitignorePath = path.join(opts.gitRoot, ".gitignore");
     const existing = (await readTextIfExists(gitignorePath)) ?? "";
-    const ensuredLines = [
-        "# agentplane: ignore local agent prompts/templates",
-        "AGENTS.md",
-        ".agentplane/agents/",
-    ];
+    const ensuredLines = opts.includeAgentPromptFiles
+        ? [...RUNTIME_IGNORE_LINES, ...AGENT_PROMPT_IGNORE_LINES]
+        : [...RUNTIME_IGNORE_LINES];
     const existingLines = existing.split(/\r?\n/);
     const existingSet = new Set(existingLines.map((line) => line.trimEnd()));
     const missing = ensuredLines.filter((line) => !existingSet.has(line));

package/dist/cli/run-cli/commands/init.js

@@ -15,7 +15,7 @@ import { maybeSyncIde } from "./init/ide-sync.js";
 import { maybeInstallBundledRecipes } from "./init/recipes.js";
 import { ensureAgentplaneDirs, writeBackendStubs, writeInitConfig } from "./init/write-config.js";
 import { ensureAgentsFiles } from "./init/write-agents.js";
-import { ensureGitignoreAgents } from "./init/write-gitignore.js";
+import { ensureInitGitignore } from "./init/write-gitignore.js";
 function parseBooleanValueForInit(flag, value) {
     const normalized = value.trim().toLowerCase();
     if (["1", "true", "yes", "y", "on"].includes(normalized))
@@ -312,8 +312,11 @@ async function cmdInit(opts) {
             configPathAbs: configPath,
             backendPathAbs: backendPath,
         });
+        await ensureInitGitignore({
+            gitRoot: resolved.gitRoot,
+            includeAgentPromptFiles: flags.gitignoreAgents === true,
+        });
         if (flags.gitignoreAgents) {
-            await ensureGitignoreAgents({ gitRoot: resolved.gitRoot });
             await setPinnedBaseBranch({
                 cwd: resolved.gitRoot,
                 rootOverride: resolved.gitRoot,

package/dist/cli/run-cli/commands/wrap-command.d.ts

@@ -0,0 +1,6 @@
+export declare function wrapCommand<T>(opts: {
+    command: string;
+    rootOverride?: string;
+    context?: Record<string, unknown>;
+}, fn: () => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=wrap-command.d.ts.map

package/dist/cli/run-cli/commands/wrap-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-command.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/wrap-command.ts"],"names":[],"mappings":"AAGA,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,EACD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/cli/run-cli/commands/wrap-command.js

@@ -0,0 +1,17 @@
+import { mapCoreError } from "../../error-map.js";
+import { CliError } from "../../../shared/errors.js";
+export async function wrapCommand(opts, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        const context = opts.context ?? {};
+        throw mapCoreError(err, {
+            command: opts.command,
+            root: opts.rootOverride ?? null,
+            ...context,
+        });
+    }
+}

package/dist/cli/run-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAmWA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqK5D"}
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAmWA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuK5D"}

package/dist/cli/run-cli.js

@@ -19,13 +19,13 @@ const GLOBAL_FLAGS = [
     { key: "version", forms: ["--version", "-v"], takesValue: false, scoped: false },
     { key: "noUpdateCheck", forms: ["--no-update-check"], takesValue: false, scoped: false },
     { key: "allowNetwork", forms: ["--allow-network"], takesValue: false, scoped: true },
-    { key: "jsonErrors", forms: ["--json-errors", "--json"], takesValue: false, scoped: true },
+    { key: "jsonErrors", forms: ["--json-errors"], takesValue: false, scoped: true },
     { key: "root", forms: ["--root"], takesValue: true, scoped: false },
 ];
 const GLOBAL_FLAG_FORMS = new Map(GLOBAL_FLAGS.flatMap((def) => def.forms.map((form) => [form, def])));
 function prescanJsonErrors(argv) {
     // If parseGlobalArgs throws (e.g. missing --root value), we still want to honor
-    // `--json` / `--json-errors` in the "scoped global" zone (before the command id).
+    // `--json-errors` in the "scoped global" zone (before the command id).
     let hasRest = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -344,7 +344,9 @@ export async function runCli(argv) {
         if (resolved) {
             await loadDotEnv(resolved.gitRoot);
         }
-        let projectPromise = null;
+        let projectPromise = resolved
+            ? Promise.resolve(resolved)
+            : null;
         const getResolvedProject = async (commandForErrorContext) => {
             projectPromise ??= resolveProject({ cwd, rootOverride: globals.root ?? null });
             try {

package/dist/commands/doctor.command.d.ts

@@ -1,8 +1,3 @@
-import type { CommandHandler, CommandSpec } from "../cli/spec/spec.js";
-type DoctorParsed = {
-    fix: boolean;
-};
-export declare const doctorSpec: CommandSpec<DoctorParsed>;
-export declare const runDoctor: CommandHandler<DoctorParsed>;
-export {};
+export { doctorSpec, type DoctorParsed } from "./doctor.spec.js";
+export { runDoctor } from "./doctor.run.js";
 //# sourceMappingURL=doctor.command.d.ts.map

package/dist/commands/doctor.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvE,KAAK,YAAY,GAAG;IAClB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAWhD,CAAC;AAkHF,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAoBlD,CAAC"}
+{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}