@agentbridge1/cli 0.0.3 → 0.0.5

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "builtAt": "2026-06-02T01:31:45.533Z",
-  "gitHead": "184f85c",
-  "sourceLatestMtime": "2026-06-02T01:19:37.980Z",
-  "sourceLatestFile": "src/commands/recover.ts"
+  "builtAt": "2026-06-03T09:58:38.231Z",
+  "gitHead": "6fcc74c",
+  "sourceLatestMtime": "2026-06-03T05:08:44.109Z",
+  "sourceLatestFile": "src/commands/doctor.ts"
 }

package/dist/commands/connect.js

@@ -10,35 +10,68 @@ function resolveBaseUrl(override) {
         config_1.DEFAULT_API_BASE_URL);
 }
 async function verifyCredentials(projectId, apiKey, apiBaseUrl) {
-    const url = `${apiBaseUrl}/v1/dev/projects/${projectId}/health`;
-    let res;
-    try {
-        res = await fetch(url, {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-            },
-        });
+    const summaryUrl = `${apiBaseUrl}/v1/dev/projects/${projectId}/summary`;
+    const packetUrl = `${apiBaseUrl}/v1/dev/projects/${projectId}/packet`;
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+    };
+    async function get(url) {
+        try {
+            return await fetch(url, { method: "GET", headers });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new errors_1.SafeCliError(`Could not reach AgentBridge server at ${apiBaseUrl}.\nNetwork error: ${msg}\n\nCheck your AGENTBRIDGE_BASE_URL or internet connection.`);
+        }
     }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        throw new errors_1.SafeCliError(`Could not reach AgentBridge server at ${apiBaseUrl}.\nNetwork error: ${msg}\n\nCheck your AGENTBRIDGE_BASE_URL or internet connection.`);
+    async function readBody(res) {
+        try {
+            return await res.text();
+        }
+        catch {
+            return "";
+        }
     }
-    if (res.status === 401 || res.status === 403) {
-        throw new errors_1.SafeCliError(`API key rejected (HTTP ${res.status}).\n\nGet a valid key at https://agentbridge.dev/dashboard and set AGENTBRIDGE_API_KEY.`);
+    function isRouteMissing(body) {
+        return body.toLowerCase().includes("route not found");
     }
-    if (res.status === 404) {
-        throw new errors_1.SafeCliError(`Project not found on ${apiBaseUrl}. Check project ID or backend URL.`);
+    async function throwAuthOrNotFound(res) {
+        if (res.status === 401 || res.status === 403) {
+            throw new errors_1.SafeCliError(`API key rejected (HTTP ${res.status}).\n\nGet a valid key at https://agentbridge.dev/dashboard and set AGENTBRIDGE_API_KEY.`);
+        }
+        if (res.status === 404) {
+            throw new errors_1.SafeCliError(`Project not found or key has no access on ${apiBaseUrl}.\nCheck project ID, API key, and backend URL.`);
+        }
+        const text = await readBody(res);
+        throw new http_1.CliHttpError(`GET ${summaryUrl} failed (${res.status}): ${text || "<empty>"}`, res.status, text);
     }
-    if (!res.ok) {
-        const text = await res.text();
-        throw new http_1.CliHttpError(`GET ${url} failed (${res.status}): ${text || "<empty>"}`, res.status, text);
+    let res;
+    res = await get(summaryUrl);
+    if (res.ok) {
+        const body = (await res.json());
+        return {
+            projectName: body.project_name ?? body.projectName ?? projectId,
+            agentCount: typeof body.agent_count === "number"
+                ? body.agent_count
+                : Array.isArray(body.agents)
+                    ? body.agents.length
+                    : 0,
+        };
     }
-    const body = (await res.json());
+    const summaryBody = await readBody(res);
+    if (!(res.status === 404 && isRouteMissing(summaryBody))) {
+        await throwAuthOrNotFound(res);
+    }
+    // Backward compatibility for servers that haven't shipped /summary yet.
+    const packetRes = await get(packetUrl);
+    if (!packetRes.ok) {
+        await throwAuthOrNotFound(packetRes);
+    }
+    const packetBody = (await packetRes.json());
     return {
-        projectName: body.projectName ?? projectId,
-        agentCount: Array.isArray(body.agents) ? body.agents.length : 0,
+        projectName: packetBody.project_name ?? projectId,
+        agentCount: 0,
     };
 }
 async function listAgents(projectId, apiKey, apiBaseUrl) {
@@ -51,6 +84,113 @@ async function listAgents(projectId, apiKey, apiBaseUrl) {
     const body = (await res.json());
     return Array.isArray(body.agents) ? body.agents : [];
 }
+async function resolveExecutionSurfaceFromHello(projectId, apiKey, apiBaseUrl) {
+    const url = `${apiBaseUrl}/v1/dev/projects/${projectId}/hello`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ tool_type: "cli" }),
+        });
+        if (!res.ok) {
+            return {
+                executionSurfaceId: null,
+                identityModel: "unknown",
+                status: `http_${res.status}`,
+            };
+        }
+        const body = (await res.json());
+        if (body.identity_model !== "work_identity") {
+            if (body.identity_model === "legacy") {
+                return {
+                    executionSurfaceId: null,
+                    identityModel: "legacy",
+                    status: "legacy_identity",
+                };
+            }
+            return {
+                executionSurfaceId: null,
+                identityModel: "unknown",
+                status: "unknown_identity_model",
+            };
+        }
+        const surfaceId = body.execution_surface?.id?.trim();
+        return {
+            executionSurfaceId: surfaceId || null,
+            identityModel: "work_identity",
+            status: surfaceId ? "ok" : "missing_execution_surface",
+        };
+    }
+    catch {
+        return {
+            executionSurfaceId: null,
+            identityModel: "unknown",
+            status: "network_error",
+        };
+    }
+}
+async function bootstrapDefaultConnection(projectId, apiKey, apiBaseUrl) {
+    const url = `${apiBaseUrl}/v1/dev/projects/${projectId}/connections/bootstrap-default`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+        });
+        if (!res.ok)
+            return { ok: false, status: res.status, reason: `http_${res.status}` };
+        const body = (await res.json());
+        const nextApiKey = body.api_key?.trim();
+        const executionSurfaceId = body.execution_surface_id?.trim();
+        if (!nextApiKey || !executionSurfaceId) {
+            return { ok: false, status: 200, reason: "invalid_payload" };
+        }
+        return { ok: true, apiKey: nextApiKey, executionSurfaceId };
+    }
+    catch {
+        return { ok: false, status: 0, reason: "network_error" };
+    }
+}
+async function rotateActiveConnectionKey(projectId, apiKey, apiBaseUrl) {
+    const listUrl = `${apiBaseUrl}/v1/dev/projects/${projectId}/connections`;
+    try {
+        const listRes = await fetch(listUrl, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!listRes.ok)
+            return { ok: false, reason: `list_http_${listRes.status}` };
+        const listBody = (await listRes.json());
+        const activeConnection = (listBody.connections ?? []).find((connection) => connection?.id && connection?.status === "active");
+        if (!activeConnection?.id)
+            return { ok: false, reason: "no_active_connection" };
+        const rotateUrl = `${apiBaseUrl}/v1/dev/projects/${projectId}/connections/${activeConnection.id}/rotate-key`;
+        const rotateRes = await fetch(rotateUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+        });
+        if (!rotateRes.ok)
+            return { ok: false, reason: `rotate_http_${rotateRes.status}` };
+        const rotateBody = (await rotateRes.json());
+        const rotatedApiKey = rotateBody.api_key?.trim();
+        const executionSurfaceId = rotateBody.connection?.execution_surface?.id?.trim();
+        if (!rotatedApiKey || !executionSurfaceId)
+            return { ok: false, reason: "invalid_payload" };
+        return { ok: true, apiKey: rotatedApiKey, executionSurfaceId };
+    }
+    catch {
+        return { ok: false, reason: "network_error" };
+    }
+}
 async function runConnect(options = {}) {
     process.stdout.write("AgentBridge connect\n");
     process.stdout.write("─────────────────────────────────────────\n");
@@ -109,13 +249,86 @@ async function runConnect(options = {}) {
         throw err;
     }
     process.stdout.write("OK\n");
+    let effectiveApiKey = apiKey;
+    const diagnostics = {
+        helloIdentityModel: "unknown",
+        helloStatus: "not_attempted",
+        bootstrapStatus: "not_attempted",
+        rotateStatus: "not_attempted",
+    };
+    const helloResolution = await resolveExecutionSurfaceFromHello(projectId, effectiveApiKey, apiBaseUrl);
+    diagnostics.helloIdentityModel = helloResolution.identityModel;
+    diagnostics.helloStatus = helloResolution.status;
+    let executionSurfaceId = helloResolution.executionSurfaceId;
+    let connectionUpgraded = false;
+    if (!executionSurfaceId) {
+        diagnostics.bootstrapStatus = "attempted";
+        const bootstrapAttempt = await bootstrapDefaultConnection(projectId, effectiveApiKey, apiBaseUrl);
+        if (bootstrapAttempt.ok) {
+            effectiveApiKey = bootstrapAttempt.apiKey;
+            executionSurfaceId = bootstrapAttempt.executionSurfaceId;
+            diagnostics.bootstrapStatus = "ok";
+            diagnostics.rotateStatus = "skipped";
+            connectionUpgraded = true;
+        }
+        else if (bootstrapAttempt.status === 409) {
+            diagnostics.bootstrapStatus = "http_409_existing_connection";
+            const rotated = await rotateActiveConnectionKey(projectId, effectiveApiKey, apiBaseUrl);
+            if (rotated.ok) {
+                diagnostics.rotateStatus = "ok";
+                effectiveApiKey = rotated.apiKey;
+                executionSurfaceId = rotated.executionSurfaceId;
+                connectionUpgraded = true;
+            }
+            else {
+                diagnostics.rotateStatus = rotated.reason;
+            }
+        }
+        else {
+            diagnostics.bootstrapStatus = bootstrapAttempt.reason;
+            diagnostics.rotateStatus = "skipped";
+        }
+    }
+    else {
+        diagnostics.bootstrapStatus = "skipped";
+        diagnostics.rotateStatus = "skipped";
+    }
+    if (!executionSurfaceId) {
+        (0, config_1.updateConfig)({
+            projectId,
+            apiKey: effectiveApiKey,
+            apiBaseUrl,
+        });
+        throw new errors_1.SafeCliError([
+            "Connection incomplete.",
+            "Project access was verified, but AgentBridge could not create or resolve an execution surface.",
+            "Tracked work cannot start yet.",
+            "",
+            `hello identity model: ${diagnostics.helloIdentityModel}`,
+            `hello status: ${diagnostics.helloStatus}`,
+            `bootstrap-default status: ${diagnostics.bootstrapStatus}`,
+            `rotate-key status: ${diagnostics.rotateStatus}`,
+            `backend URL: ${apiBaseUrl}`,
+        ].join("\n"));
+    }
     // Persist credentials
-    (0, config_1.updateConfig)({ projectId, apiKey, apiBaseUrl });
+    (0, config_1.updateConfig)({
+        projectId,
+        apiKey: effectiveApiKey,
+        apiBaseUrl,
+        ...(executionSurfaceId ? { executionSurfaceId } : {}),
+    });
     process.stdout.write("Credentials saved to .agentbridge/config.json\n");
+    if (connectionUpgraded) {
+        process.stdout.write("Auto-configured an AgentConnection key and execution surface for this project.\n");
+    }
+    else {
+        process.stdout.write(`Execution surface: ${executionSurfaceId}\n`);
+    }
     // Pick or auto-select an agent identity
     let activeAgentId = options.agentId ?? cfg.activeAgentId;
     if (!activeAgentId) {
-        const agents = await listAgents(projectId, apiKey, apiBaseUrl);
+        const agents = await listAgents(projectId, effectiveApiKey, apiBaseUrl);
         if (agents.length === 1 && agents[0]) {
             activeAgentId = agents[0].id;
             (0, config_1.updateConfig)({ activeAgentId });
@@ -126,7 +339,7 @@ async function runConnect(options = {}) {
             for (const a of agents) {
                 process.stdout.write(`  ${a.id}  ${a.name ?? ""}  ${a.role ?? ""}\n`.trimEnd() + "\n");
             }
-            process.stdout.write('\nRun `agentbridge use <agent-id>` to select one, then `agentbridge watch` to start.\n');
+            process.stdout.write('\nRun `agentbridge use <agent-id>` to select one.\n');
         }
     }
     else {
@@ -136,24 +349,23 @@ async function runConnect(options = {}) {
     process.stdout.write("\n");
     process.stdout.write(`Project:  ${projectName}\n`);
     process.stdout.write(`Agents:   ${agentCount}\n`);
+    process.stdout.write(`Execution surface: ${executionSurfaceId}\n`);
     process.stdout.write(`Server:   ${apiBaseUrl}\n`);
     process.stdout.write("\n");
     if (activeAgentId) {
-        process.stdout.write("✓ Connected. Next steps:\n");
+        process.stdout.write("✓ Connected and ready.\n");
         process.stdout.write([
             "",
-            "  1. Start a work session:",
-            "       agentbridge start --summary \"your task\" --scope \"src/\"",
-            "",
-            "  2. Run the watcher (keep it running in a terminal):",
-            "       agentbridge watch",
-            "",
-            "  3. Code normally — AgentBridge watches in the background.",
-            "     Approvals surface when you cross domain boundaries.",
+            "Next:",
+            "  agentbridge doctor",
+            "  agentbridge start",
             "",
         ].join("\n"));
     }
     else {
-        process.stdout.write("✓ Connected. Run `agentbridge use <agent-id>` then `agentbridge watch`.\n");
+        process.stdout.write("✓ Connected.\n");
+        process.stdout.write("Run `agentbridge use <agent-id>` and then:\n");
+        process.stdout.write("  agentbridge doctor\n");
+        process.stdout.write("  agentbridge start\n");
     }
 }

package/dist/commands/doctor.js

@@ -146,7 +146,39 @@ async function checkProjectAccess(ctx) {
 }
 async function checkIdentityAccess(ctx) {
     if (!ctx.configComplete) {
-        return { status: "skipped", reason: "config_incomplete" };
+        return {
+            status: "skipped",
+            reason: "config_incomplete",
+            identityModel: "unknown",
+            executionSurfaceId: null,
+            startCapable: false,
+        };
+    }
+    const helloUrl = `${ctx.apiBaseUrl}/v1/dev/projects/${ctx.projectId}/hello`;
+    let identityModel = "unknown";
+    let executionSurfaceId = null;
+    try {
+        const helloRes = await fetch(helloUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${ctx.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ tool_type: "cli" }),
+        });
+        if (helloRes.ok) {
+            const hello = (await helloRes.json());
+            if (hello.identity_model === "work_identity") {
+                identityModel = "work_identity";
+            }
+            else if (hello.identity_model === "legacy") {
+                identityModel = "legacy";
+            }
+            executionSurfaceId = hello.execution_surface?.id?.trim() || null;
+        }
+    }
+    catch {
+        // Keep default unknown/null and continue with identity resolution checks.
     }
     try {
         const syncCtx = {
@@ -160,14 +192,29 @@ async function checkIdentityAccess(ctx) {
             (0, server_sync_1.listWorkIdentities)(syncCtx),
         ]);
         const callerId = callerPacket?.work_identity?.id ?? null;
-        if (callerId)
-            return { status: "ok" };
-        if (identities.length === 1)
-            return { status: "ok" };
-        return { status: "failed", reason: "caller_identity_unresolved" };
+        const startCapable = Boolean(executionSurfaceId);
+        if (callerId) {
+            return { status: "ok", identityModel, executionSurfaceId, startCapable };
+        }
+        if (identities.length === 1) {
+            return { status: "ok", identityModel, executionSurfaceId, startCapable };
+        }
+        return {
+            status: "failed",
+            reason: "caller_identity_unresolved",
+            identityModel,
+            executionSurfaceId,
+            startCapable,
+        };
     }
     catch {
-        return { status: "failed", reason: "caller_identity_unresolved" };
+        return {
+            status: "failed",
+            reason: "caller_identity_unresolved",
+            identityModel,
+            executionSurfaceId,
+            startCapable: Boolean(executionSurfaceId),
+        };
     }
 }
 async function runDoctor(cliRootOverride) {
@@ -234,6 +281,9 @@ async function runDoctor(cliRootOverride) {
     if (identityAccess.reason) {
         lines.push(`Caller identity reason: ${identityAccess.reason}`);
     }
+    lines.push(`Caller identity model: ${identityAccess.identityModel}`);
+    lines.push(`Execution surface present: ${identityAccess.executionSurfaceId ? "yes" : "no"}`);
+    lines.push(`Start capable: ${identityAccess.startCapable ? "yes" : "no"}`);
     if (projectAccess.status === "failed" && projectAccess.reason) {
         const view = (0, error_catalog_1.catalogViewForDoctorReason)(projectAccess.reason, projectAccess.suggestedNextAction);
         lines.push("");
@@ -252,7 +302,9 @@ async function runDoctor(cliRootOverride) {
         lines.push("Suggested next action: run npm run dogfood:check before external dogfood.");
     }
     let productStatus = "not_ready";
-    if (projectAccess.status === "ok" && identityAccess.status === "ok") {
+    if (projectAccess.status === "ok" &&
+        identityAccess.status === "ok" &&
+        identityAccess.startCapable) {
         if (hasActiveWork) {
             productStatus = "active_work_found";
         }
@@ -281,18 +333,24 @@ async function runDoctor(cliRootOverride) {
         lines.push("- Next: agentbridge recover");
     }
     else {
-        lines.push("- Connection: required");
+        lines.push("- Connection: incomplete");
         lines.push("- Recovery: pending");
         if (!projectConfigPresent) {
             lines.push("- Note: Connection details are missing. Add credentials, then rerun agentbridge doctor.");
         }
+        else if (!identityAccess.startCapable) {
+            lines.push("- Reason: execution surface missing.");
+            lines.push("- Next: agentbridge connect");
+        }
         else if (identityAccess.status !== "ok") {
             lines.push("- Note: Caller identity is unresolved. Run agentbridge identity list and set a valid active agent.");
         }
         else {
             lines.push("- Note: Connection check failed. Verify credentials/network, then rerun agentbridge doctor.");
         }
-        lines.push("- Next: agentbridge doctor");
+        if (identityAccess.startCapable) {
+            lines.push("- Next: agentbridge doctor");
+        }
     }
     process.stdout.write(`${lines.join("\n")}\n`);
     if (freshness.state === "stale")

package/dist/commands/recover.js

@@ -7,6 +7,7 @@ const server_sync_1 = require("../server-sync");
 const node_process_1 = require("node:process");
 const gates_1 = require("../gates");
 const init_1 = require("../init");
+const http_1 = require("../http");
 function resolveNetworkContext() {
     const cfg = (0, config_1.readConfig)();
     const projectId = process.env.AGENTBRIDGE_PROJECT_ID ?? cfg.projectId ?? "";
@@ -78,6 +79,60 @@ function renderRecoveryStatusBlock(input) {
     lines.push("");
     return lines.join("\n");
 }
+function normalizeBootstrapError(error) {
+    if ((0, http_1.isCliHttpError)(error) && error.status === 422) {
+        const parsed = (0, http_1.parseCliHttpErrorBody)(error);
+        const details = [];
+        const nestedError = parsed && typeof parsed.error === "object" && parsed.error !== null
+            ? parsed.error
+            : null;
+        const fieldErrors = nestedError && typeof nestedError.fieldErrors === "object" && nestedError.fieldErrors !== null
+            ? nestedError.fieldErrors
+            : null;
+        if (fieldErrors) {
+            for (const [field, value] of Object.entries(fieldErrors)) {
+                if (Array.isArray(value) && value.length > 0) {
+                    details.push(`${field}: ${String(value[0])}`);
+                }
+            }
+        }
+        const detailText = details.length > 0 ? ` (${details.join("; ")})` : "";
+        return (0, errors_1.catalogCliError)("CONFIG_INCOMPLETE", {
+            what: `Recovery bootstrap payload was rejected by server validation${detailText}.`,
+            why: "The server cannot activate recovery until required bootstrap fields pass validation.",
+            next: "Retry `agentbridge recover`. If it fails again, run with AGENTBRIDGE_DEBUG=1 and share output.",
+        });
+    }
+    if (error instanceof Error) {
+        const message = error.message;
+        if (/does not have any commits yet/i.test(message) ||
+            /bad revision ['"]head['"]/i.test(message) ||
+            /not a git repository/i.test(message)) {
+            return new errors_1.SafeCliError({
+                code: "CONFIG_INCOMPLETE",
+                category: "CONFIG_ERROR",
+                what: "Repository has no usable git history for recovery mapping.",
+                why: "Recover infers baseline context from commit history and cannot proceed without it.",
+                next: [
+                    "Create an initial commit, then rerun recover:",
+                    "1) git add .",
+                    "2) git commit -m \"Initial commit\"",
+                    "3) agentbridge recover",
+                ].join("\n"),
+            });
+        }
+        if (/payload too large after compaction/i.test(message)) {
+            return new errors_1.SafeCliError({
+                code: "CONFIG_INCOMPLETE",
+                category: "CONFIG_ERROR",
+                what: "Repository evidence exceeded bootstrap payload limits.",
+                why: "The recovery evidence payload could not be compacted enough for server ingestion.",
+                next: "Run `agentbridge init` for an interactive baseline, or retry recover after reducing repository noise.",
+            });
+        }
+    }
+    return error;
+}
 async function runRecover(options = {}) {
     process.exitCode = 0;
     process.stdout.write([
@@ -127,8 +182,15 @@ async function runRecover(options = {}) {
             ? "build recovery baseline from repository evidence"
             : "force-refresh recovery baseline from repository evidence";
         process.stdout.write("Building recovery baseline now...\n");
-        await (0, init_1.runBootstrapRecovery)(ctx);
-        packet = await (0, server_sync_1.fetchProjectPacket)(ctx);
+        try {
+            await (0, init_1.runBootstrapRecovery)(ctx);
+            packet = await (0, server_sync_1.fetchProjectPacket)(ctx);
+        }
+        catch (error) {
+            process.stderr.write(`${(0, errors_1.renderCliError)(normalizeBootstrapError(error))}\n`);
+            process.exitCode = 1;
+            return;
+        }
     }
     const afterPacket = packet;
     if (baselineRequired(afterPacket)) {

package/dist/commands/start.js

@@ -395,6 +395,29 @@ function renderOtherSessions(lines, sessionIds) {
         ...sessionIds.map((id) => `- ${id}`),
     ];
 }
+async function resolveExecutionSurfaceIdForStart(ctx, opts, cfgExecutionSurfaceId) {
+    const explicitExecutionSurfaceId = opts.executionSurfaceId?.trim();
+    if (explicitExecutionSurfaceId) {
+        (0, config_1.updateConfig)({ executionSurfaceId: explicitExecutionSurfaceId });
+        return explicitExecutionSurfaceId;
+    }
+    const configuredExecutionSurfaceId = cfgExecutionSurfaceId?.trim();
+    if (configuredExecutionSurfaceId) {
+        return configuredExecutionSurfaceId;
+    }
+    try {
+        const callerPacket = await (0, server_sync_1.fetchCallerIdentityPacket)(ctx);
+        const discoveredExecutionSurfaceId = callerPacket?.execution_surface?.id?.trim() || null;
+        if (discoveredExecutionSurfaceId) {
+            (0, config_1.updateConfig)({ executionSurfaceId: discoveredExecutionSurfaceId });
+            return discoveredExecutionSurfaceId;
+        }
+    }
+    catch {
+        // Keep the existing catalog error path if caller identity discovery fails.
+    }
+    return null;
+}
 async function executeStartWorkSession(opts) {
     const summary = trimRequired(opts.summary ?? "", "--summary");
     const scope = trimRequired(opts.scope ?? "", "--scope");
@@ -406,7 +429,7 @@ async function executeStartWorkSession(opts) {
     if (!explicitAgentId && !configuredActiveAgentId) {
         throw (0, errors_1.catalogCliError)("START_MISSING_ACTIVE_AGENT");
     }
-    const executionSurfaceId = cfg.executionSurfaceId?.trim();
+    const executionSurfaceId = await resolveExecutionSurfaceIdForStart(ctx, opts, cfg.executionSurfaceId);
     if (!executionSurfaceId) {
         throw (0, errors_1.catalogCliError)("START_EXECUTION_SURFACE_REQUIRED");
     }
@@ -547,15 +570,16 @@ async function executeStartWorkSession(opts) {
 async function runSmartStart(opts = {}) {
     const cfg = (0, config_1.readConfig)();
     await ensureProjectAccess();
+    const ctx = (0, config_1.contextFromConfig)();
     const explicitAgentId = opts.agentId?.trim();
     const configuredActiveAgentId = cfg.activeAgentId?.trim();
     if (!explicitAgentId && !configuredActiveAgentId) {
         throw (0, errors_1.catalogCliError)("START_MISSING_ACTIVE_AGENT");
     }
-    if (!cfg.executionSurfaceId?.trim()) {
+    const executionSurfaceId = await resolveExecutionSurfaceIdForStart(ctx, opts, cfg.executionSurfaceId);
+    if (!executionSurfaceId) {
         throw (0, errors_1.catalogCliError)("START_EXECUTION_SURFACE_REQUIRED");
     }
-    const ctx = (0, config_1.contextFromConfig)();
     const resolution = await (0, work_context_resolver_1.resolveWorkContext)(ctx, {
         allowServerCurrentForCr: true,
         includeOtherActiveSessions: true,

package/dist/error-catalog.js

@@ -186,7 +186,13 @@ const CATALOG = {
         title: "Execution surface missing.",
         what: "No executionSurfaceId is saved in .agentbridge/config.json.",
         why: "The server needs a stable execution surface to open a tracked session.",
-        next: "Run `agentbridge watch --execution-surface <surface-id>` once to persist it.",
+        next: [
+            "Run:",
+            "  agentbridge connect --project <project-id> --api-key <key> --api-base-url <url>",
+            "Then:",
+            "  agentbridge doctor",
+            "If this continues, AgentBridge could not create an AgentConnection/execution surface for this project.",
+        ].join("\n"),
     },
     START_AGENT_INVALID: {
         code: "START_AGENT_INVALID",

package/dist/index.js

@@ -49,7 +49,7 @@ const COMMAND_HELP = {
     use: "  agentbridge use <agent-id>\n" +
         "    Set the active agent identity used by `watch` and `start`.\n",
     start: "  agentbridge start [\"intent\"] [\"scope\"]\n" +
-        "  Advanced: agentbridge start --summary \"<summary>\" --scope \"<path-or-glob>\" [--domain <name>] [--agent <id>] [--change-request <cr_id>] [--resume]\n" +
+        "  Advanced: agentbridge start --summary \"<summary>\" --scope \"<path-or-glob>\" [--domain <name>] [--agent <id>] [--execution-surface <es_id>] [--change-request <cr_id>] [--resume]\n" +
         "    Start supervised work. Without flags, proposes a smart work contract and asks for confirmation.\n" +
         "    --resume  Continue the active change request/session instead of creating a new one.\n",
     watch: "  agentbridge watch [--change-request <cr_id>] [--execution-surface <es_id>] [--allow-dirty] [--daemon] [--once]\n" +
@@ -350,6 +350,7 @@ async function main() {
             scopeFlagProvided,
             domain: flags["--domain"],
             agentId: flags["--agent"],
+            executionSurfaceId: flags["--execution-surface"],
             changeRequestId: flags["--change-request"],
             resume: flags["--resume"] === "true",
         });

package/dist/init.js

@@ -104,16 +104,24 @@ function assertInsideGitRepo() {
 function normalizeToken(value) {
     return value.trim().toLowerCase().replace(/[_\s]+/g, "-");
 }
-function classifyDomainKey(path) {
-    const normalized = path.replace(/\\/g, "/");
-    const srcMatch = normalized.match(/^src\/([^/]+)\//);
-    if (srcMatch) {
-        const folder = normalizeToken(srcMatch[1] ?? "");
+function normalizePath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function deriveDomainKeyFromPath(path) {
+    const normalized = normalizePath(path);
+    const packageSourcesMatch = normalized.match(/^([^/]+)\/Sources\/([^/]+)\//);
+    if (packageSourcesMatch) {
+        const folder = normalizeToken(packageSourcesMatch[2] ?? "");
         if (folder === "supabase")
             return "database";
-        if (folder)
-            return folder;
-        return null;
+        return folder || null;
+    }
+    const srcLikeMatch = normalized.match(/^(src|Sources|modules|Modules|feature|features)\/([^/]+)\//);
+    if (srcLikeMatch) {
+        const folder = normalizeToken(srcLikeMatch[2] ?? "");
+        if (folder === "supabase")
+            return "database";
+        return folder || null;
     }
     if (normalized.startsWith("db/") || normalized.startsWith("prisma/") || normalized.startsWith("supabase/")) {
         return "database";
@@ -123,6 +131,29 @@ function classifyDomainKey(path) {
     }
     return null;
 }
+function extractDomainPrefix(path) {
+    const normalized = normalizePath(path);
+    const packageSourcesMatch = normalized.match(/^([^/]+)\/Sources\/([^/]+)\//);
+    if (packageSourcesMatch) {
+        return `${packageSourcesMatch[1]}/Sources/${packageSourcesMatch[2]}/`;
+    }
+    const srcLikeMatch = normalized.match(/^(src|Sources|modules|Modules|feature|features)\/([^/]+)\//);
+    if (srcLikeMatch) {
+        return `${srcLikeMatch[1]}/${srcLikeMatch[2]}/`;
+    }
+    if (normalized.startsWith("db/"))
+        return "db/";
+    if (normalized.startsWith("prisma/"))
+        return "prisma/";
+    if (normalized.startsWith("supabase/"))
+        return "supabase/";
+    if (/^supabase_.*\.sql$/i.test(normalized))
+        return "supabase_*.sql";
+    return null;
+}
+function classifyDomainKey(path) {
+    return deriveDomainKeyFromPath(path);
+}
 function tierForDomainKey(domainKey, files) {
     if (domainKey === "sessions") {
         const highRisk = files.some((file) => /(token|auth|state|orchestrator|repository|session)/i.test(file));
@@ -148,9 +179,11 @@ function confidenceForDomain(fileCount) {
 }
 function collectWorkspaceDomainSeeds() {
     const seeds = new Set();
-    const srcPath = (0, node_path_1.resolve)(process.cwd(), "src");
-    if ((0, node_fs_1.existsSync)(srcPath)) {
-        for (const entry of (0, node_fs_1.readdirSync)(srcPath, { withFileTypes: true })) {
+    for (const root of ["src", "Sources", "modules", "Modules", "feature", "features"]) {
+        const rootPath = (0, node_path_1.resolve)(process.cwd(), root);
+        if (!(0, node_fs_1.existsSync)(rootPath))
+            continue;
+        for (const entry of (0, node_fs_1.readdirSync)(rootPath, { withFileTypes: true })) {
             if (!entry.isDirectory())
                 continue;
             const folder = normalizeToken(entry.name);
@@ -162,6 +195,24 @@ function collectWorkspaceDomainSeeds() {
             }
         }
     }
+    for (const topLevelEntry of (0, node_fs_1.readdirSync)(process.cwd(), { withFileTypes: true })) {
+        if (!topLevelEntry.isDirectory())
+            continue;
+        const packageSourcesPath = (0, node_path_1.resolve)(process.cwd(), topLevelEntry.name, "Sources");
+        if (!(0, node_fs_1.existsSync)(packageSourcesPath))
+            continue;
+        for (const sourceEntry of (0, node_fs_1.readdirSync)(packageSourcesPath, { withFileTypes: true })) {
+            if (!sourceEntry.isDirectory())
+                continue;
+            const folder = normalizeToken(sourceEntry.name);
+            if (folder === "supabase") {
+                seeds.add("database");
+            }
+            else if (folder) {
+                seeds.add(folder);
+            }
+        }
+    }
     for (const dbFolder of ["db", "prisma", "supabase"]) {
         if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), dbFolder))) {
             seeds.add("database");
@@ -171,10 +222,13 @@ function collectWorkspaceDomainSeeds() {
 }
 function refineRecoveredDomains(inferredClusters, evidence, architectureDomains) {
     const domainFiles = new Map();
+    const domainPrefixes = new Map();
     const workspaceSeeds = collectWorkspaceDomainSeeds();
     for (const seed of workspaceSeeds) {
         if (!domainFiles.has(seed))
             domainFiles.set(seed, new Set());
+        if (!domainPrefixes.has(seed))
+            domainPrefixes.set(seed, new Set());
     }
     for (const file of evidence.files) {
         const key = classifyDomainKey(file);
@@ -183,6 +237,12 @@ function refineRecoveredDomains(inferredClusters, evidence, architectureDomains)
         if (!domainFiles.has(key))
             domainFiles.set(key, new Set());
         domainFiles.get(key)?.add(file);
+        const prefix = extractDomainPrefix(file);
+        if (prefix) {
+            if (!domainPrefixes.has(key))
+                domainPrefixes.set(key, new Set());
+            domainPrefixes.get(key)?.add(prefix);
+        }
     }
     for (const cluster of inferredClusters) {
         const clusterPaths = [...cluster.files, ...cluster.path_prefixes];
@@ -207,6 +267,12 @@ function refineRecoveredDomains(inferredClusters, evidence, architectureDomains)
         for (const file of cluster.files) {
             if (classifyDomainKey(file) === chosenKey) {
                 domainFiles.get(chosenKey)?.add(file);
+                const prefix = extractDomainPrefix(file);
+                if (prefix) {
+                    if (!domainPrefixes.has(chosenKey))
+                        domainPrefixes.set(chosenKey, new Set());
+                    domainPrefixes.get(chosenKey)?.add(prefix);
+                }
             }
         }
     }
@@ -237,12 +303,14 @@ function refineRecoveredDomains(inferredClusters, evidence, architectureDomains)
     return Array.from(domainFiles.entries())
         .map(([key, filesSet]) => {
         const files = Array.from(filesSet).sort((a, b) => a.localeCompare(b));
+        const inferredPrefixes = Array.from(domainPrefixes.get(key) ?? []);
         const pathPatterns = DOMAIN_PREFIX_BY_KEY[key] ??
+            (inferredPrefixes.length > 0 ? inferredPrefixes : undefined) ??
             (key === "database"
                 ? ["db/", "prisma/", "supabase/", "supabase_*.sql"]
                 : key === "shared"
                     ? ["src/shared/"]
-                    : [`src/${key}/`]);
+                    : [`${key}/`]);
         const primaryPrefix = pathPatterns[0] ? pathPatterns[0].replace(/\/$/, "") : key;
         const protectionTier = tierForDomainKey(key, files);
         return {

package/dist/server-sync.js

@@ -132,6 +132,17 @@ async function fetchCallerIdentityPacket(ctx) {
         typeof domainCandidate.name === "string"
         ? { id: domainCandidate.id, name: domainCandidate.name }
         : null;
+    const executionSurfaceCandidate = typeof response.execution_surface === "object" && response.execution_surface !== null
+        ? response.execution_surface
+        : null;
+    const executionSurface = executionSurfaceCandidate && typeof executionSurfaceCandidate.id === "string"
+        ? {
+            id: executionSurfaceCandidate.id,
+            ...(typeof executionSurfaceCandidate.display_name === "string"
+                ? { display_name: executionSurfaceCandidate.display_name }
+                : {}),
+        }
+        : null;
     return {
         identity_model: "work_identity",
         work_identity: {
@@ -139,6 +150,7 @@ async function fetchCallerIdentityPacket(ctx) {
             name: workIdentity.name,
             domain,
         },
+        execution_surface: executionSurface,
     };
 }
 async function postObservedDiff(ctx, binding, payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentbridge1/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "CLI for AgentBridge — structured AI agent work sessions with domain authority and approval gates",
   "type": "commonjs",
   "bin": {