aui-agent-builder 0.4.16 → 0.4.17

package/dist/commands/agents.js

@@ -7,13 +7,13 @@ import chalk from "chalk";
 import { getAuthenticatedSession, listAgents as listAgentsSvc, listVersions as listVersionsSvc, switchToAgent, } from "../services/agents.service.js";
 import { AgentsMenuView, AgentsListView, AgentSwitchView, VersionsListView, AgentDeletePreviewView, AgentDeleteResultView, } from "../ui/views/AgentsView.js";
 import { Spinner, ErrorDisplay, StatusLine } from "../ui/components/index.js";
-import { AUIClient } from "../api-client/index.js";
+import { AUIClient, AUIAPIError } from "../api-client/index.js";
 import { ApolloClient } from "../api-client/apollo-client.js";
 import { isJsonMode, outputJson, stderrLog } from "../utils/json-output.js";
 import { searchableSelect } from "../utils/select-prompt.js";
 import { getConfig, loadSession, saveSession, loadProjectConfig, findProjectRoot } from "../config/index.js";
 import { resolveAgentManagementInfo } from "./util/agent-resolve.js";
-import { ConfigError } from "../errors/index.js";
+import { CLIError, ConfigError, ValidationError } from "../errors/index.js";
 import { getTracer, SpanStatusCode, setUserContext } from "../telemetry.js";
 function renderView(element) {
     const instance = render(element);
@@ -44,6 +44,147 @@ async function deleteNetworkBestEffort(client, networkId) {
         return { deleted: false, errorMessage: formatApiErrorBody(err) };
     }
 }
+/**
+ * A MongoDB ObjectId string — the only shape the provisioning endpoint
+ * accepts for `network_category_id` (it 422s on anything else with
+ * `network_category_id must match ^[0-9a-f]{24}$`). We use this to decide
+ * whether a raw `--category` value can be forwarded as-is when the
+ * categories endpoint is unavailable to resolve names/keys.
+ */
+const OBJECT_ID_RE = /^[0-9a-f]{24}$/i;
+/**
+ * Resolve a `--category` value (id, key, or name) to its category id,
+ * defaulting to the "General" category when nothing is passed.
+ *
+ * This replaces the old per-call resolution blocks that silently swallowed
+ * a failed `categories.list()` (CTS-16872): when the lookup failed they
+ * kept the raw value (e.g. the literal "General"), which then 422'd at the
+ * provisioning endpoint, and the announced "default General" was never
+ * actually applied. Instead we now:
+ *   - resolve id / key / name against the live category list,
+ *   - forward an already-valid ObjectId unchanged (server decides),
+ *   - throw a clear, actionable error otherwise (instead of a downstream
+ *     422 / "needs a category").
+ */
+async function resolveCategoryId(client, raw) {
+    let categories;
+    try {
+        categories = (await client.categories.list()).data ?? [];
+    }
+    catch (error) {
+        // Couldn't reach the categories endpoint. The only safe thing to do is
+        // forward a value that's already a valid ObjectId; anything else (a
+        // name/key we can't resolve, or the default) must fail loudly.
+        if (raw && OBJECT_ID_RE.test(raw))
+            return { id: raw, label: raw };
+        throw new CLIError(`Could not load categories to resolve --category${raw ? ` "${raw}"` : ""}.`, {
+            code: "API_SERVER_ERROR",
+            suggestion: "List available categories with `aui agents --categories`, then pass --category <id>. Retry shortly if this is transient.",
+            cause: error,
+        });
+    }
+    if (raw) {
+        const up = raw.toUpperCase();
+        const match = categories.find((c) => c._id === raw ||
+            c.key?.toUpperCase() === up ||
+            c.name?.toUpperCase() === up);
+        if (match)
+            return { id: match._id, label: `${match.name} (${match.key})` };
+        // Unknown to us but a structurally valid id — let the server decide.
+        if (OBJECT_ID_RE.test(raw))
+            return { id: raw, label: raw };
+        throw new ValidationError(`Category "${raw}" not found.`, {
+            suggestion: `List categories with \`aui agents --categories\`.${categories.length
+                ? ` Available: ${categories.map((c) => `${c.name} (${c.key})`).slice(0, 10).join(", ")}${categories.length > 10 ? `, … (${categories.length} total)` : ""}`
+                : ""}`,
+        });
+    }
+    // No --category passed: apply the real "General" default.
+    const general = categories.find((c) => c.name?.toUpperCase() === "GENERAL" || c.key?.toUpperCase() === "GENERAL");
+    if (general)
+        return { id: general._id, label: `${general.name} (${general.key})` };
+    if (categories[0]) {
+        return { id: categories[0]._id, label: `${categories[0].name} (${categories[0].key})` };
+    }
+    throw new CLIError("No categories are available to default to.", {
+        code: "API_CLIENT_ERROR",
+        suggestion: "Pass an explicit --category <id>. List the ids with `aui agents --categories`.",
+    });
+}
+/**
+ * Fetch ALL organizations the user can see (following pagination). Returns
+ * `[]` on any error — callers treat "couldn't list" the same as "none" and
+ * fall back to flags/session. Used by the non-interactive-safe `--create`
+ * scope resolver (CTS-16852).
+ */
+async function fetchAllOrganizations(client) {
+    try {
+        const first = await client.organizations.listMy(1, 50);
+        const docs = [...first.data.docs];
+        const totalPages = first.data.totalPages ?? 1;
+        if (totalPages > 1) {
+            const rest = await Promise.all(Array.from({ length: totalPages - 1 }, (_, i) => i + 2).map((p) => client.organizations.listMy(p, 50)));
+            for (const r of rest)
+                docs.push(...r.data.docs);
+        }
+        return docs.map((o) => ({ id: o._id || o.id || "", name: o.name }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Fetch ALL accounts in the current org scope (following pagination).
+ * Returns `[]` on any error. See `fetchAllOrganizations`.
+ */
+async function fetchAllAccounts(client) {
+    try {
+        const first = await client.accounts.list(1, 50);
+        const docs = [...first.data.docs];
+        const totalPages = first.data.totalPages ?? 1;
+        if (totalPages > 1) {
+            const rest = await Promise.all(Array.from({ length: totalPages - 1 }, (_, i) => i + 2).map((p) => client.accounts.list(p, 50)));
+            for (const r of rest)
+                docs.push(...r.data.docs);
+        }
+        return docs.map((a) => ({
+            id: a._id || a.id || "",
+            name: a.name,
+            niceName: a.niceName,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Whether an error from the provisioning endpoint means the agent/network
+ * name is already taken (HTTP 409, or a backend message to that effect).
+ * Used by `--if-not-exists` to import the existing agent instead of failing.
+ */
+function isAlreadyExistsError(error) {
+    if (error instanceof AUIAPIError && error.status === 409)
+        return true;
+    const msg = error instanceof Error ? error.message : String(error);
+    return /already exists|name already|already in use/i.test(msg);
+}
+/**
+ * Find a regular (NETWORK-scoped) agent by exact name in the current
+ * account. Used by `--if-not-exists` to recover from a 409 (name reserved)
+ * — including the parallel-create orphan case (CTS-16874) where the agent
+ * was provisioned server-side but the local import never ran.
+ */
+async function findExistingAgentByName(client, name, accountId) {
+    try {
+        const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { account_id: accountId || undefined, name });
+        const wanted = name.trim().toLowerCase();
+        return (resp.items.find((a) => (a.name ?? "").trim().toLowerCase() === wanted) ??
+            null);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build a human-readable summary from an API error.
  *
@@ -140,6 +281,10 @@ async function runAgents(options = {}) {
         await handleListAgents();
         return;
     }
+    if (options.categories) {
+        await handleListCategories();
+        return;
+    }
     if (options.versions !== undefined) {
         const agentId = typeof options.versions === "string" ? options.versions : undefined;
         await handleListVersions(agentId);
@@ -221,6 +366,49 @@ async function runAgents(options = {}) {
             await importFromOtherOrg();
         }
     }
+    async function handleListCategories() {
+        // Network categories are org-scoped; their ids are required by
+        // `aui agents --create --category <id>` (the provisioning endpoint only
+        // accepts a 24-hex ObjectId). Before this there was no way to discover
+        // them from the CLI — users had to GET an existing agent to read its
+        // `network_category_id` (CTS-16872).
+        const config = getConfig();
+        const client = new AUIClient({
+            baseUrl: config.apiUrl,
+            authToken: config.authToken,
+            accountId: config.accountId,
+            organizationId: config.organizationId,
+            environment: config.environment,
+        });
+        if (isJsonMode()) {
+            stderrLog("Fetching categories...");
+            const resp = await client.categories.list();
+            outputJson({
+                categories: (resp.data ?? []).map((c) => ({
+                    id: c._id,
+                    key: c.key,
+                    name: c.name,
+                    status: c.status,
+                })),
+            });
+            return;
+        }
+        const spinnerInstance = render(_jsx(Spinner, { label: "Fetching categories..." }));
+        try {
+            const resp = await client.categories.list();
+            spinnerInstance.unmount();
+            const cats = resp.data ?? [];
+            if (cats.length === 0) {
+                logView(_jsx(StatusLine, { kind: "warning", label: "No categories found for this organization." }));
+                return;
+            }
+            renderView(_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: [_jsx(StatusLine, { kind: "info", label: `Categories (${cats.length}) — pass the id to --category` }), cats.map((c) => (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: c._id }), _jsx(Text, { color: "gray", children: "  " }), _jsx(Text, { children: c.name }), _jsx(Text, { color: "gray", children: c.key ? ` (${c.key})` : "" })] }, c._id)))] }));
+        }
+        catch (error) {
+            spinnerInstance.unmount();
+            renderView(_jsx(ErrorDisplay, { error: error, message: "Failed to fetch categories." }));
+        }
+    }
     async function handleListAgents() {
         // Account scope for listing comes from, in priority:
         //   1. --account-id (explicit; wins anywhere, in or out of a folder)
@@ -987,7 +1175,7 @@ async function runAgents(options = {}) {
                 logView(_jsx(StatusLine, { kind: "warning", label: `Network shell could not be removed automatically: ${networkResult.errorMessage}. The agent may still appear in some legacy listings.` }));
             }
             const cleared = clearSessionIfMatchesAgent(networkId, agentManagementId);
-            renderView(_jsx(AgentDeleteResultView, { scope: "agent", agentName: agentName, cleared: cleared }));
+            renderView(_jsx(AgentDeleteResultView, { scope: "agent", agentName: agentName, cleared: cleared, networkOrphaned: !networkResult.deleted, networkId: networkId }));
         }
         catch (error) {
             deleteSpinner.unmount();
@@ -1235,32 +1423,30 @@ async function runAgents(options = {}) {
         });
         let networkId = opts.networkId;
         let categoryId = opts.category;
+        let categoryLabel;
         let agentName = opts.name;
-        // Resolve category early — supports ID, key, or name
+        // Resolve an explicit `--category` early — supports ID, key, or name.
+        // Unlike the old block this NO LONGER silently swallows a failed lookup
+        // (which used to forward the raw "General" and 422 downstream — CTS-16872):
+        // `resolveCategoryId` throws a clear error instead. The default-category
+        // resolution for the no-`--category` case happens later, once the org is
+        // selected (interactive flow), so we only resolve here when one was passed.
         if (categoryId) {
-            try {
-                const catResp = await client.categories.list();
-                const catUpper = categoryId.toUpperCase();
-                const match = catResp.data.find((c) => c._id === categoryId ||
-                    c.key?.toUpperCase() === catUpper ||
-                    c.name?.toUpperCase() === catUpper);
-                if (match) {
-                    categoryId = match._id;
-                }
-                else {
-                    const available = catResp.data
-                        .map((c) => `${c.name} (${c.key})`)
-                        .slice(0, 10)
-                        .join(", ");
-                    renderView(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "error", label: `Category "${opts.category}" not found.` }), _jsxs(Text, { color: "gray", children: ["  Available: ", available, catResp.data.length > 10 ? `, ... (${catResp.data.length} total)` : ""] }), _jsx(Text, { children: " " })] }));
-                    return;
-                }
-            }
-            catch {
-                // keep raw value — categories endpoint might be unavailable
-            }
+            const resolved = await resolveCategoryId(client, categoryId);
+            categoryId = resolved.id;
+            categoryLabel = resolved.label;
+        }
+        // Pin explicit scope from flags up-front so the interactive flow can
+        // skip the matching picker. `--account-id` pins both org+account (it's
+        // account-unique); `--organization-id` pins only the org so a
+        // non-interactive create can skip the org picker without also choosing
+        // an account (CTS-16852).
+        if (opts.organizationId) {
+            client.setScope({ organizationId: opts.organizationId });
+            const currentSession = loadSession();
+            currentSession.organization_id = opts.organizationId;
+            saveSession(currentSession);
         }
-        // If --account-id is passed, set scope directly (skip org/account prompts)
         if (opts.accountId) {
             client.setScope({ accountId: opts.accountId });
             const currentSession = loadSession();
@@ -1286,8 +1472,14 @@ async function runAgents(options = {}) {
             }
             // Prompt for name if it wasn't passed on the CLI. Same prompt as
             // the regular interactive flow (kept consistent so users don't
-            // have to learn a separate template UX).
+            // have to learn a separate template UX). Fail clearly instead of
+            // hanging when there's no TTY (CTS-16852).
             if (!agentName) {
+                if (!canPrompt()) {
+                    throw new ValidationError("A template name is required.", {
+                        suggestion: "Pass --name <name> for non-interactive create.",
+                    });
+                }
                 const { name: inputName } = await inquirer.prompt([
                     {
                         type: "input",
@@ -1337,14 +1529,14 @@ async function runAgents(options = {}) {
         // Direct single-command: aui agents --create --name X --category Y (new network)
         if (agentName && categoryId && !networkId) {
             // Bundle-mode: hand the whole flow (network → agent → version →
-            // publish → activate) to the Apollo provisioning endpoint.
-            const created = await createBundledAgentViaApollo({
+            // publish → activate) to the Apollo provisioning endpoint. The helper
+            // exits non-zero on provision failure and supports --if-not-exists.
+            await createRegularAgentAndImport(client, {
                 name: agentName,
                 networkCategoryId: categoryId,
                 organizationId: client.getOrganizationId(),
                 accountId: client.getAccountId(),
-            });
-            await autoImportAndEnter(created, opts.dir, agentName);
+            }, { dir: opts.dir, ifNotExists: opts.ifNotExists });
             return;
             // ─── RECORDS-MODE CREATION RETIRED — moved to bundle-mode creation ──
             // The legacy per-step records path (network create → createAgentOnBackend
@@ -1370,75 +1562,85 @@ async function runAgents(options = {}) {
             // return;
         }
         // ─── Interactive flow with step indicators ───
-        logView(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u25C6 " }), _jsx(Text, { bold: true, children: "Create a New Agent" })] }), !categoryId && (_jsxs(_Fragment, { children: [_jsx(Box, { children: _jsx(Text, { color: "gray", children: "  Using default category (General). To use a specific one:" }) }), _jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "  aui agents --create --category " }), _jsx(Text, { color: "gray", italic: true, children: "<name or key>" })] })] })), categoryId && (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "  Category: " }), _jsx(Text, { children: opts.category })] }))] }));
+        logView(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u25C6 " }), _jsx(Text, { bold: true, children: "Create a New Agent" })] }), !categoryId && (_jsxs(_Fragment, { children: [_jsx(Box, { children: _jsx(Text, { color: "gray", children: "  No --category passed; will use the default (General) if available." }) }), _jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "  Override with  aui agents --create --category " }), _jsx(Text, { color: "gray", italic: true, children: "<name or key>" }), _jsx(Text, { color: "gray", children: "  (list ids: aui agents --categories)" })] })] })), categoryId && (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "  Category: " }), _jsx(Text, { children: categoryLabel ?? opts.category })] }))] }));
         if (!opts.accountId) {
-            // Step 1: Select organization
+            // Resolve org + account scope. This used to ALWAYS render a picker when
+            // there was >1 option, which hangs a non-interactive create (no TTY)
+            // — `aui agents --create --name X --dir .` would block on "Select
+            // organization" forever (CTS-16852). Now we only prompt when we can
+            // (`canPrompt`); otherwise we resolve from `--organization-id` / the
+            // session, and fail with a clear, actionable error if it's still
+            // ambiguous rather than hanging.
+            const sessionForScope = loadSession();
+            // Step 1: Organization
             logView(_jsx(Text, { color: "gray", children: "  \u250C Step 1 \u2192 Select Organization" }));
-            {
+            if (opts.organizationId) {
+                // Already pinned above from the flag — nothing to choose.
+                logView(_jsx(StatusLine, { kind: "success", label: `Organization: ${opts.organizationId}` }));
+            }
+            else {
                 const orgSpinner = render(_jsx(Spinner, { label: "Fetching organizations..." }));
-                try {
-                    // Fetch page 1 to learn totalPages, then fetch the rest in parallel
-                    // so orgs beyond the first 50 are not silently dropped.
-                    const orgFirst = await client.organizations.listMy(1, 50);
-                    const orgs = [...orgFirst.data.docs];
-                    const orgTotalPages = orgFirst.data.totalPages ?? 1;
-                    if (orgTotalPages > 1) {
-                        const restPages = Array.from({ length: orgTotalPages - 1 }, (_, i) => i + 2);
-                        const rest = await Promise.all(restPages.map((p) => client.organizations.listMy(p, 50)));
-                        for (const r of rest)
-                            orgs.push(...r.data.docs);
-                    }
-                    orgSpinner.unmount();
-                    if (orgs.length === 1) {
-                        client.setScope({ organizationId: orgs[0]._id || orgs[0].id });
-                        logView(_jsx(StatusLine, { kind: "success", label: `Organization: ${orgs[0].name}` }));
-                    }
-                    else if (orgs.length > 1) {
+                const orgs = await fetchAllOrganizations(client);
+                orgSpinner.unmount();
+                if (orgs.length === 1) {
+                    client.setScope({ organizationId: orgs[0].id });
+                    logView(_jsx(StatusLine, { kind: "success", label: `Organization: ${orgs[0].name}` }));
+                }
+                else if (orgs.length > 1) {
+                    if (canPrompt()) {
                         const chosen = await searchableSelect({
                             message: "Select organization:",
-                            choices: orgs.map((o) => ({ name: o.name, value: o._id || o.id })),
+                            choices: orgs.map((o) => ({ name: o.name, value: o.id })),
                         });
                         client.setScope({ organizationId: chosen });
                     }
+                    else if (sessionForScope?.organization_id) {
+                        client.setScope({ organizationId: sessionForScope.organization_id });
+                        logView(_jsx(StatusLine, { kind: "muted", label: `Organization: ${sessionForScope.organization_id} (from session)` }));
+                    }
+                    else {
+                        throw new ValidationError("Multiple organizations available and no TTY to choose one.", {
+                            suggestion: "Pass --organization-id <id> (or --account-id <id> to pin both) for non-interactive create. List them with `aui account --list`.",
+                        });
+                    }
                 }
-                catch {
-                    orgSpinner.unmount();
-                }
+                // 0 orgs (e.g. listing failed): leave scope as-is; downstream calls
+                // surface the real error.
             }
-            // Step 2: Select account
+            // Step 2: Account
             logView(_jsx(Text, { color: "gray", children: "  \u251C Step 2 \u2192 Select Account" }));
             {
                 const accSpinner = render(_jsx(Spinner, { label: "Fetching accounts..." }));
-                try {
-                    // Fetch page 1 to learn totalPages, then fetch the rest in parallel
-                    // so accounts beyond the first 50 are not silently dropped.
-                    const accFirst = await client.accounts.list(1, 50);
-                    const accounts = [...accFirst.data.docs];
-                    const accTotalPages = accFirst.data.totalPages ?? 1;
-                    if (accTotalPages > 1) {
-                        const restPages = Array.from({ length: accTotalPages - 1 }, (_, i) => i + 2);
-                        const rest = await Promise.all(restPages.map((p) => client.accounts.list(p, 50)));
-                        for (const r of rest)
-                            accounts.push(...r.data.docs);
-                    }
-                    accSpinner.unmount();
-                    if (accounts.length === 1) {
-                        client.setScope({ accountId: accounts[0]._id || accounts[0].id });
-                        logView(_jsx(StatusLine, { kind: "success", label: `Account: ${accounts[0].name}` }));
-                    }
-                    else if (accounts.length > 1) {
+                const accounts = await fetchAllAccounts(client);
+                accSpinner.unmount();
+                if (accounts.length === 1) {
+                    client.setScope({ accountId: accounts[0].id });
+                    logView(_jsx(StatusLine, { kind: "success", label: `Account: ${accounts[0].name}` }));
+                }
+                else if (accounts.length > 1) {
+                    if (canPrompt()) {
                         const chosen = await searchableSelect({
                             message: "Select account:",
-                            choices: accounts.map((a) => ({ name: `${a.name} (${a.niceName})`, value: a._id || a.id })),
+                            choices: accounts.map((a) => ({
+                                name: a.niceName ? `${a.name} (${a.niceName})` : a.name,
+                                value: a.id,
+                            })),
                         });
                         client.setScope({ accountId: chosen });
                     }
+                    else if (sessionForScope?.account_id) {
+                        client.setScope({ accountId: sessionForScope.account_id });
+                        logView(_jsx(StatusLine, { kind: "muted", label: `Account: ${sessionForScope.account_id} (from session)` }));
+                    }
+                    else {
+                        throw new ValidationError("Multiple accounts available and no TTY to choose one.", {
+                            suggestion: "Pass --account-id <id> for non-interactive create. List them with `aui account --list`.",
+                        });
+                    }
                 }
-                catch {
-                    accSpinner.unmount();
-                }
+                // 0 accounts: leave scope as-is.
             }
-            // Persist selected org/account to session
+            // Persist resolved org/account to session.
             {
                 const currentSession = loadSession();
                 currentSession.organization_id = client.getOrganizationId();
@@ -1449,6 +1651,13 @@ async function runAgents(options = {}) {
         // Step 3: Agent name
         logView(_jsx(Text, { color: "gray", children: "  \u251C Step 3 \u2192 Name Your Agent" }));
         if (!agentName) {
+            // Don't render a blocking prompt with no TTY — fail clearly instead of
+            // hanging (CTS-16852).
+            if (!canPrompt()) {
+                throw new ValidationError("An agent name is required.", {
+                    suggestion: "Pass --name <name> for non-interactive create.",
+                });
+            }
             const { name: inputName } = await inquirer.prompt([
                 {
                     type: "input",
@@ -1461,35 +1670,26 @@ async function runAgents(options = {}) {
         }
         // Step 4: Creating the agent
         logView(_jsx(Text, { color: "gray", children: "  \u2514 Step 4 \u2192 Creating Agent" }));
-        // Resolve category: supports ID, key, or name. Defaults to General.
-        try {
-            const catResp = await client.categories.list();
-            if (categoryId) {
-                const catUpper = categoryId.toUpperCase();
-                const match = catResp.data.find((c) => c._id === categoryId ||
-                    c.key?.toUpperCase() === catUpper ||
-                    c.name?.toUpperCase() === catUpper);
-                if (match)
-                    categoryId = match._id;
-            }
-            else {
-                const general = catResp.data.find((c) => c.name?.toUpperCase() === "GENERAL");
-                categoryId = general?._id || catResp.data[0]?._id || "";
-            }
-        }
-        catch {
-            // proceed with whatever categoryId we have
+        // Resolve category now that the org is selected: supports ID, key, or
+        // name, and applies a REAL "General" default when none was passed. Throws
+        // a clear error (instead of silently sending an empty / raw value that
+        // 422s) when it can't resolve — CTS-16872.
+        {
+            const resolved = await resolveCategoryId(client, categoryId);
+            categoryId = resolved.id;
+            categoryLabel = resolved.label;
+            logView(_jsx(StatusLine, { kind: "muted", label: `Category: ${resolved.label}` }));
         }
         // Bundle-mode: the Apollo provisioning endpoint runs the whole flow
         // (network → agent → version-from-template → publish → activate) in a
-        // single call. This is the only creation path now.
-        const created = await createBundledAgentViaApollo({
+        // single call. This is the only creation path now. The helper exits
+        // non-zero on provision failure and supports --if-not-exists.
+        await createRegularAgentAndImport(client, {
             name: agentName,
-            networkCategoryId: categoryId || "",
+            networkCategoryId: categoryId,
             organizationId: client.getOrganizationId(),
             accountId: client.getAccountId(),
-        });
-        await autoImportAndEnter(created, opts.dir, agentName);
+        }, { dir: opts.dir, ifNotExists: opts.ifNotExists });
         return;
         // ─── RECORDS-MODE CREATION RETIRED — moved to bundle-mode creation ──
         // The legacy interactive records path (create network → createAgentOnBackend
@@ -1626,10 +1826,63 @@ async function autoImportAndEnter(created, dir, agentName) {
         tag,
         dir,
         agentName,
+        // A failed import after a successful provision is an orphan, not a
+        // best-effort miss — fail the create so scripts don't see success then
+        // crash on the missing dir (CTS-16874).
+        strict: true,
     });
     if (importedDir)
         enterProjectShell(importedDir);
 }
+/**
+ * Create a regular (runtime) bundle agent and import it, with optional
+ * `--if-not-exists` recovery.
+ *
+ * Shared by the two regular create paths (direct single-command and the
+ * interactive fall-through). On a name conflict (HTTP 409) — including the
+ * parallel-create orphan case where the agent was provisioned but never
+ * imported locally (CTS-16874) — `--if-not-exists` resolves the existing
+ * agent by name and imports it instead of failing. Without the flag the
+ * 409 propagates and the command exits non-zero.
+ */
+async function createRegularAgentAndImport(client, input, opts) {
+    try {
+        const created = await createBundledAgentViaApollo(input);
+        await autoImportAndEnter(created, opts.dir, input.name);
+    }
+    catch (error) {
+        if (!opts.ifNotExists || !isAlreadyExistsError(error))
+            throw error;
+        const existing = await findExistingAgentByName(client, input.name, input.accountId);
+        if (!existing) {
+            // Name is taken but we can't see the agent (different account/org, or
+            // a half-provisioned orphan the listing doesn't return yet). Surface
+            // the conflict rather than pretend it resolved.
+            throw new CLIError(`Agent "${input.name}" already exists but could not be found to import.`, {
+                code: "API_CLIENT_ERROR",
+                suggestion: "Check the agent's account/org with `aui agents --list --account-id <id>`, then import it with `aui import-agent <agent-id>`.",
+                cause: error,
+            });
+        }
+        logView(_jsx(StatusLine, { kind: "info", label: `Agent "${input.name}" already exists (${existing.id}) — importing the existing agent (--if-not-exists).` }));
+        // Repoint the session at the existing agent, mirroring a fresh create.
+        const session = loadSession();
+        session.agent_management_id = existing.id;
+        const existingNetworkId = existing.scope?.network_id ?? undefined;
+        if (existingNetworkId) {
+            session.network_id = existingNetworkId;
+            session.network_name = input.name;
+        }
+        delete session.version_id;
+        delete session.version_number;
+        delete session.version_revision_number;
+        saveSession(session);
+        await autoImportAndEnter({
+            agentId: existing.id,
+            activeVersionId: existing.active_version_id ?? undefined,
+        }, opts.dir, input.name);
+    }
+}
 /**
  * Resolve the id of the latest DRAFT version for a freshly provisioned bundle
  * agent. Apollo creates a draft after publishing the first version; this finds
@@ -1667,6 +1920,21 @@ async function resolveLatestDraftId(agentId) {
  *   2. AUI_AUTO_IMPORT=1 / =0 → explicit opt-in / opt-out (automation + tests).
  *   3. otherwise             → only when BOTH stdin and stdout are TTYs.
  */
+/**
+ * Whether the CLI may render a blocking interactive prompt right now.
+ *
+ * Stricter than `isInteractiveSession` (which honors `AUI_AUTO_IMPORT` and
+ * is about the post-create conveniences): a prompt is only safe when BOTH
+ * std streams are real TTYs and we're not in JSON mode. Used to gate the
+ * `--create` org/account pickers so a non-interactive run resolves scope
+ * from flags/session or fails with a clear message instead of hanging on a
+ * picker with no TTY (CTS-16852).
+ */
+function canPrompt() {
+    if (isJsonMode())
+        return false;
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
 function isInteractiveSession() {
     if (isJsonMode())
         return false;
@@ -1751,6 +2019,15 @@ async function autoImportLatestDraft(agentId, opts) {
         return resolvedDir;
     }
     catch (error) {
+        if (opts.strict) {
+            // The agent exists server-side but the local project was never
+            // written — surface the orphan + an exact reclaim path, and fail.
+            throw new CLIError(`Agent "${opts.agentName ?? agentId}" was provisioned but the local import failed: ${error instanceof Error ? error.message : String(error)}`, {
+                code: "API_CLIENT_ERROR",
+                suggestion: `The agent exists server-side (name reserved). Import it with \`aui import-agent ${agentId} --dir ${targetDir}\`, or re-run create with \`--if-not-exists\` to import the existing agent.`,
+                cause: error,
+            });
+        }
         logView(_jsxs(Box, { flexDirection: "column", paddingX: 1, marginTop: 1, children: [_jsx(StatusLine, { kind: "warning", label: `Auto-import failed: ${error instanceof Error ? error.message : String(error)}` }), _jsx(Text, { color: "gray", children: `  Import it manually with:  aui import-agent --dir ${targetDir}` })] }));
         return null;
     }
@@ -1827,8 +2104,11 @@ async function createBundledAgentViaApollo(input) {
     const isTemplate = input.kind === "template";
     const noun = isTemplate ? "template" : "bundle agent";
     if (!input.networkCategoryId) {
-        logView(_jsx(StatusLine, { kind: "error", label: `Bundle-mode ${noun} create needs a category — pass --category <name-or-key>.` }));
-        return null;
+        // Throw (not return null) so the command exits non-zero — a missing
+        // category is a hard failure, never a silent success (CTS-16872).
+        throw new ValidationError(`Bundle-mode ${noun} create needs a category — pass --category <name-or-key>.`, {
+            suggestion: "List available categories with `aui agents --categories`.",
+        });
     }
     const apollo = new ApolloClient({
         authToken: config.authToken,
@@ -1879,14 +2159,26 @@ async function createBundledAgentViaApollo(input) {
         const activeVersionTag = typeof res.active_version_tag === "string" ? res.active_version_tag : undefined;
         const activeVersion = activeVersionTag || activeVersionId || "";
         logView(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "success", label: `${isTemplate ? "Template" : "Bundle agent"} created: ${res.name || input.name}${agentId ? ` (${agentId})` : ""}` }), isTemplate ? (_jsx(Text, { color: "gray", children: `  Use it as a clone source:  aui version create --source template --from-template ${agentId || "<templateId>"}` })) : (_jsx(Text, { color: "gray", children: "  Apollo provisioned it end-to-end: network → agent → version (from template) → published → activated." })), activeVersion ? (_jsx(StatusLine, { kind: "muted", label: `Active version: ${activeVersion}` })) : null, !isTemplate && agentId ? (_jsx(StatusLine, { kind: "muted", label: "Session updated to this agent." })) : null] }));
-        return agentId
-            ? { agentId, activeVersionId, activeVersionTag }
-            : null;
+        // A 2xx that somehow carries no agent id is still a failure — the
+        // caller can't import/repoint to a nameless agent. Throw rather than
+        // return null so the command exits non-zero (CTS-16874).
+        if (!agentId) {
+            throw new CLIError(`Provisioning ${noun} "${input.name}" returned no agent id.`, {
+                code: "API_SERVER_ERROR",
+                suggestion: "Re-run with AUI_DEBUG=1 to see the raw response, or inspect it with `aui curl --failed`.",
+            });
+        }
+        return { agentId, activeVersionId, activeVersionTag };
     }
     catch (error) {
         spinner.unmount();
-        renderView(_jsx(ErrorDisplay, { error: error, message: `Failed to provision ${noun}: ${error instanceof Error ? error.message : String(error)}` }));
-        return null;
+        // Re-throw so the command exits non-zero. Previously this swallowed the
+        // error and returned null, so `aui agents --create` printed "✗ Failed…"
+        // but still exited 0 — scripted fleet creation then treated the failure
+        // as success and crashed on the missing dir / looped re-creating
+        // (CTS-16874). `handleError` (the action wrapper) renders the same rich
+        // error display this used to render inline.
+        throw error;
     }
 }
 export async function createAgentOnBackend(name, networkId, networkCategoryId, modeOpts = {}) {