@agentbridge1/cli 0.0.1

package/dist/config.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_PATH = exports.CONFIG_DIR = void 0;
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.updateConfig = updateConfig;
+exports.contextFromConfig = contextFromConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.CONFIG_DIR = ".agentbridge";
+exports.CONFIG_PATH = (0, node_path_1.resolve)(process.cwd(), exports.CONFIG_DIR, "config.json");
+function ensureConfigDir() {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.resolve)(process.cwd(), exports.CONFIG_DIR), { recursive: true });
+}
+function readConfig() {
+    if (!(0, node_fs_1.existsSync)(exports.CONFIG_PATH)) {
+        return {};
+    }
+    const raw = (0, node_fs_1.readFileSync)(exports.CONFIG_PATH, "utf8");
+    return JSON.parse(raw);
+}
+function writeConfig(next) {
+    ensureConfigDir();
+    (0, node_fs_1.writeFileSync)(exports.CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+function updateConfig(partial) {
+    const current = readConfig();
+    const next = { ...current, ...partial };
+    writeConfig(next);
+    return next;
+}
+function contextFromConfig() {
+    const cfg = readConfig();
+    const apiBaseUrl = process.env.AGENTBRIDGE_BASE_URL ??
+        cfg.apiBaseUrl ??
+        "https://agentauth-api-production.up.railway.app";
+    const apiKey = process.env.AGENTBRIDGE_API_KEY ?? cfg.apiKey;
+    const projectId = process.env.AGENTBRIDGE_PROJECT_ID ?? cfg.projectId;
+    if (!apiBaseUrl || !apiKey || !projectId) {
+        const missing = [];
+        if (!projectId)
+            missing.push("project id");
+        if (!apiKey)
+            missing.push("api key");
+        if (!apiBaseUrl)
+            missing.push("api base url");
+        throw new Error(`Missing CLI context (${missing.join(", ")}). Set flags/env or run \`agentbridge init\` to persist config.`);
+    }
+    return {
+        apiBaseUrl,
+        apiKey,
+        projectId,
+        apiKeySource: process.env.AGENTBRIDGE_API_KEY ? "env" : "config",
+    };
+}

package/dist/domain-resolution.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDomainForFile = resolveDomainForFile;
+exports.inferLaneFromFiles = inferLaneFromFiles;
+const HEURISTIC_LABELS = [
+    { domain: "auth", includes: ["auth", "oauth", "session", "token"] },
+    { domain: "billing", includes: ["billing", "stripe", "invoice", "checkout"] },
+    { domain: "database", includes: ["prisma", "migration", "schema.sql", "db/"] },
+    { domain: "api", includes: ["routes/", "api/", "controller"] },
+];
+function globToRegex(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "___GLOBSTAR___")
+        .replace(/\*/g, "[^/]*")
+        .replace(/___GLOBSTAR___/g, ".*");
+    return new RegExp(`^${escaped}$`, "i");
+}
+function matchesPattern(path, pattern) {
+    if (!pattern.includes("*")) {
+        return path === pattern || path.startsWith(pattern.replace(/\/$/, "") + "/");
+    }
+    return globToRegex(pattern).test(path);
+}
+function resolveDomainForFile(path, domains) {
+    for (const domain of domains) {
+        if (domain.pathPatterns.some((pattern) => matchesPattern(path, pattern))) {
+            return {
+                domain: domain.domain,
+                tier: domain.tier,
+                ownerAgentId: domain.ownerAgentId,
+                reason: "pattern",
+            };
+        }
+    }
+    const canonical = HEURISTIC_LABELS.find((entry) => entry.includes.some((token) => path.toLowerCase().includes(token)))?.domain;
+    if (canonical) {
+        const existing = domains.find((domain) => domain.domain.toLowerCase() === canonical);
+        if (existing) {
+            return {
+                domain: existing.domain,
+                tier: existing.tier,
+                ownerAgentId: existing.ownerAgentId,
+                reason: "heuristic_intersection",
+            };
+        }
+    }
+    return { domain: null, tier: "tier_d", reason: "unclassified" };
+}
+function inferLaneFromFiles(files, domains) {
+    const counts = new Map();
+    for (const file of files) {
+        const resolved = resolveDomainForFile(file, domains);
+        if (!resolved.domain)
+            continue;
+        counts.set(resolved.domain, (counts.get(resolved.domain) ?? 0) + 1);
+    }
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    if (sorted.length === 0) {
+        return { laneDomain: null, reason: "No confirmed domain matched initial files." };
+    }
+    return { laneDomain: sorted[0][0], reason: "Dominant domain from first changed files." };
+}

package/dist/error-catalog.js

@@ -0,0 +1,494 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapServerCodeToCatalog = mapServerCodeToCatalog;
+exports.catalogEntryForCode = catalogEntryForCode;
+exports.doctorReasonToCode = doctorReasonToCode;
+exports.catalogViewForDoctorReason = catalogViewForDoctorReason;
+exports.workContextStateToCode = workContextStateToCode;
+const CATALOG = {
+    PROJECT_ACCESS_NOT_MEMBER: {
+        code: "PROJECT_ACCESS_NOT_MEMBER",
+        category: "PROJECT_ACCESS_ERROR",
+        title: "Project access denied.",
+        what: "This API key is valid but the agent is not a member of this project.",
+        why: "AgentBridge cannot read or mutate work state without project membership.",
+        next: "Use a key for this project or add this agent to the room.",
+    },
+    PROJECT_ACCESS_UNAUTHORIZED: {
+        code: "PROJECT_ACCESS_UNAUTHORIZED",
+        category: "AUTH_ERROR",
+        title: "Authentication failed.",
+        what: "The API key was missing, invalid, or rejected by the server.",
+        why: "AgentBridge cannot reach project APIs without valid credentials.",
+        next: "Verify AGENTBRIDGE_API_KEY and rerun `agentbridge doctor`.",
+    },
+    PROJECT_ACCESS_NOT_FOUND: {
+        code: "PROJECT_ACCESS_NOT_FOUND",
+        category: "PROJECT_ACCESS_ERROR",
+        title: "Project not found.",
+        what: "The configured project ID does not exist in this API environment.",
+        why: "Commands target the wrong room or environment.",
+        next: "Verify AGENTBRIDGE_PROJECT_ID and rerun `agentbridge init --project <id>`.",
+    },
+    IDENTITY_ACTIVE_AGENT_STALE: {
+        code: "IDENTITY_ACTIVE_AGENT_STALE",
+        category: "IDENTITY_ERROR",
+        title: "Active agent could not be resolved.",
+        what: "Configured activeAgentId could not be resolved in this project.",
+        why: "Start and watch need a WorkIdentity that exists in the current room.",
+        next: "Run `agentbridge identity list` and update with `agentbridge use <agent-id>`.",
+    },
+    WORK_CONTEXT_NO_CURRENT_SESSION: {
+        code: "WORK_CONTEXT_NO_CURRENT_SESSION",
+        category: "WORK_CONTEXT_ERROR",
+        title: "No active tracked work session.",
+        what: "No active tracked work session was found for this command.",
+        why: "Proof, verify, accept, and handoff require a bound work session.",
+        next: 'Run `agentbridge start --summary "<work>" --scope "<path>"` then `agentbridge watch`.',
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_BINDING_REQUIRED: {
+        code: "WORK_CONTEXT_BINDING_REQUIRED",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Work session binding required.",
+        what: "This command needs a linked local/server work session.",
+        why: "The CLI and server must agree on the active change request and session.",
+        next: 'Run `agentbridge start --summary "<task>" --scope "<path>"` to create and bind a new session, or `agentbridge watch --change-request <id>` to bind an existing one.',
+        blocksAcceptance: true,
+    },
+    PROOF_STALE_AFTER_CHANGE: {
+        code: "PROOF_STALE_AFTER_CHANGE",
+        category: "PROOF_STALE_ERROR",
+        title: "Proof is stale.",
+        what: "Verification passed earlier, but scoped files changed afterward.",
+        why: "Acceptance requires proof that matches the current tree.",
+        next: "Rerun `agentbridge verify -- <command>`.",
+        blocksAcceptance: true,
+    },
+    SCOPE_DRIFT_OUT_OF_SCOPE_FILE: {
+        code: "SCOPE_DRIFT_OUT_OF_SCOPE_FILE",
+        category: "SCOPE_DRIFT_ERROR",
+        title: "Scope drift detected.",
+        what: "The agent changed a file outside the declared scope.",
+        why: "Out-of-scope edits block acceptance until reviewed or rescoped.",
+        next: 'Options: (1) revert the out-of-scope file, (2) restart with an expanded scope via `agentbridge start --scope "<wider-path>"`, or (3) run `agentbridge handoff` before switching to a new scoped job.',
+        blocksAcceptance: true,
+    },
+    HANDOFF_REQUIRED: {
+        code: "HANDOFF_REQUIRED",
+        category: "HANDOFF_ERROR",
+        title: "Handoff required.",
+        what: "Acceptance is blocked until a handoff is recorded for this session.",
+        why: "Cross-boundary work must be explicitly handed off before close.",
+        next: "Run `agentbridge handoff` with a summary, then retry accept.",
+        blocksAcceptance: true,
+    },
+    ACCEPTANCE_BLOCKED: {
+        code: "ACCEPTANCE_BLOCKED",
+        category: "ACCEPTANCE_ERROR",
+        title: "Acceptance blocked by protocol rules.",
+        what: "Server checks rejected acceptance due to missing handoff, proof, or scope alignment.",
+        why: "The acceptance contract was not fully satisfied.",
+        next: 'Run `agentbridge watch --once` to see current blocking issues, resolve each one, then retry `agentbridge accept`.',
+        blocksAcceptance: true,
+    },
+    MEMORY_SUGGEST_NO_SESSION: {
+        code: "MEMORY_SUGGEST_NO_SESSION",
+        category: "MEMORY_ERROR",
+        title: "No accepted session for memory suggest.",
+        what: "Memory suggest could not find an accepted session to summarize.",
+        why: "Memory packets are generated from completed, accepted work.",
+        next: "Complete and accept a session first, then rerun `agentbridge memory suggest`.",
+    },
+    CONFIG_INCOMPLETE: {
+        code: "CONFIG_INCOMPLETE",
+        category: "CONFIG_ERROR",
+        title: "Configuration incomplete.",
+        what: "Project ID, API key, or base URL is missing from config and environment.",
+        why: "AgentBridge cannot call the server without connection settings.",
+        next: "Run `agentbridge init` or set AGENTBRIDGE_PROJECT_ID / AGENTBRIDGE_API_KEY.",
+    },
+    IDENTITY_NO_ACTIVE_AGENT: {
+        code: "IDENTITY_NO_ACTIVE_AGENT",
+        category: "IDENTITY_ERROR",
+        title: "No active agent configured.",
+        what: "activeAgentId is not set in .agentbridge/config.json.",
+        why: "Watch and start need a WorkIdentity selected for this repo.",
+        next: "Run `agentbridge identity list` then `agentbridge use <agent-id>`.",
+    },
+    CONFIG_NO_DOMAIN_MAP: {
+        code: "CONFIG_NO_DOMAIN_MAP",
+        category: "CONFIG_ERROR",
+        title: "Domain map missing.",
+        what: "No recovered domain map was found in .agentbridge/config.json.",
+        why: "Watch uses domain boundaries to enforce scoped file tracking.",
+        next: "Run `agentbridge init` to recover domains for this repo.",
+    },
+    AUTH_LOGIN_FAILED: {
+        code: "AUTH_LOGIN_FAILED",
+        category: "AUTH_ERROR",
+        title: "Sign in failed.",
+        what: "Authentication could not be completed.",
+        why: "You cannot open rooms without a valid session.",
+        next: "Return to login and try again, or contact your admin if auth is disabled.",
+    },
+    NETWORK_UNREACHABLE: {
+        code: "NETWORK_UNREACHABLE",
+        category: "NETWORK_ERROR",
+        title: "Network error.",
+        what: "The CLI could not reach the AgentBridge API.",
+        why: "Without network access, local commands cannot sync work state.",
+        next: "Check AGENTBRIDGE_BASE_URL and network connectivity, then rerun `agentbridge doctor`.",
+    },
+    SERVER_ERROR: {
+        code: "SERVER_ERROR",
+        category: "SERVER_ERROR",
+        title: "Server error.",
+        what: "The AgentBridge server failed while handling the request.",
+        why: "The action could not complete until the server recovers.",
+        next: "Retry shortly. If it persists, run `agentbridge doctor` and check server logs.",
+    },
+    UNKNOWN_RUNTIME_ERROR: {
+        code: "UNKNOWN_RUNTIME_ERROR",
+        category: "UNKNOWN_ERROR",
+        title: "Command failed.",
+        what: "The command could not be completed due to an unexpected local/runtime error.",
+        why: "AgentBridge could not classify this failure.",
+        next: "Run `agentbridge doctor` with AGENTBRIDGE_DEBUG=1 and retry.",
+    },
+    START_SUMMARY_REQUIRED: {
+        code: "START_SUMMARY_REQUIRED",
+        category: "START_ERROR",
+        title: "Summary required.",
+        what: "Start requires a non-empty --summary describing the work.",
+        why: "Change requests and work sessions need a human-readable intent.",
+        next: 'Run `agentbridge start --summary "<work>" --scope "<path>"`.',
+    },
+    START_SCOPE_REQUIRED: {
+        code: "START_SCOPE_REQUIRED",
+        category: "START_ERROR",
+        title: "Scope required.",
+        what: "Start requires a non-empty --scope path or glob.",
+        why: "Scoped work must declare which files this session may touch.",
+        next: 'Run `agentbridge start --summary "<work>" --scope "<path>"`.',
+    },
+    START_MISSING_ACTIVE_AGENT: {
+        code: "START_MISSING_ACTIVE_AGENT",
+        category: "IDENTITY_ERROR",
+        title: "No active agent configured.",
+        what: "Neither activeAgentId nor --agent was provided for start.",
+        why: "Start must bind work to a WorkIdentity in this project.",
+        next: "Run `agentbridge identity list` then `agentbridge use <agent-id>`, or pass --agent.",
+    },
+    START_EXECUTION_SURFACE_REQUIRED: {
+        code: "START_EXECUTION_SURFACE_REQUIRED",
+        category: "CONFIG_ERROR",
+        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.",
+    },
+    START_AGENT_INVALID: {
+        code: "START_AGENT_INVALID",
+        category: "IDENTITY_ERROR",
+        title: "Agent could not be resolved.",
+        what: "The --agent value does not match any WorkIdentity in this project.",
+        why: "Start cannot open scoped work without a valid project agent.",
+        next: 'Run `agentbridge identity list` and retry with `--agent "<valid-agent-id>"`.',
+    },
+    START_IDENTITY_MISMATCH: {
+        code: "START_IDENTITY_MISMATCH",
+        category: "IDENTITY_ERROR",
+        title: "Agent identity mismatch.",
+        what: "The resolved agent is not authorized for this API key's WorkIdentity.",
+        why: "Start must run under the same WorkIdentity as the API key.",
+        next: "Use an API key bound to that agent, or pick an agent your key owns.",
+    },
+    START_CALLER_IDENTITY_UNRESOLVED: {
+        code: "START_CALLER_IDENTITY_UNRESOLVED",
+        category: "IDENTITY_ERROR",
+        title: "Caller identity unresolved.",
+        what: "The API key could not be mapped to a WorkIdentity in this project.",
+        why: "Start requires a resolvable caller WorkIdentity from the server.",
+        next: "Run `agentbridge doctor` and verify this key is an AgentConnection key.",
+    },
+    START_DOMAIN_UNRESOLVED: {
+        code: "START_DOMAIN_UNRESOLVED",
+        category: "START_ERROR",
+        title: "Domain could not be inferred.",
+        what: "No domain could be inferred from scope or active identity.",
+        why: "Scoped work must target a recovered domain lane.",
+        next: 'Pass `--domain "<domain>"` with start, or run `agentbridge init`.',
+    },
+    START_OWNER_UNRESOLVED: {
+        code: "START_OWNER_UNRESOLVED",
+        category: "START_ERROR",
+        title: "Domain owner unresolved.",
+        what: "The change request or session policy requires an owner WorkIdentity that is not assigned.",
+        why: "The server will not open a tracked session without domain ownership.",
+        next: "Ensure this project has a domain owner for the scope, or pass --domain.",
+    },
+    START_CR_OWNERSHIP_MISMATCH: {
+        code: "START_CR_OWNERSHIP_MISMATCH",
+        category: "START_ERROR",
+        title: "Change request ownership mismatch.",
+        what: "The change request is owned by a different WorkIdentity than this API key.",
+        why: "Start cannot reassign an existing CR to another agent without authorization.",
+        next: "Use an API key bound to the CR owner, or start a new change request.",
+    },
+    START_CR_NOT_EXECUTABLE: {
+        code: "START_CR_NOT_EXECUTABLE",
+        category: "START_ERROR",
+        title: "Change request not executable.",
+        what: "The change request is in a terminal or incompatible lifecycle state.",
+        why: "Only draft/scoped/assigned/ready_for_session CRs can start scoped work.",
+        next: "Pick another change request or create a new one with start.",
+    },
+    START_SESSION_OPEN_FAILED: {
+        code: "START_SESSION_OPEN_FAILED",
+        category: "START_ERROR",
+        title: "Session could not be opened.",
+        what: "A change request was prepared but no work session could be opened.",
+        why: "Watch and verify require a server-backed session linked to the CR.",
+        next: "Run `agentbridge watch --change-request <id>` or inspect `agentbridge session list`.",
+    },
+    START_LOCAL_SESSION_WRITE_FAILED: {
+        code: "START_LOCAL_SESSION_WRITE_FAILED",
+        category: "START_ERROR",
+        title: "Local session write failed.",
+        what: "The server session opened but local session state could not be saved.",
+        why: "Watch and verify rely on .agentbridge/session state on disk.",
+        next: "Check repo permissions under .agentbridge/ and retry start.",
+    },
+    VERIFY_COMMAND_REQUIRED: {
+        code: "VERIFY_COMMAND_REQUIRED",
+        category: "PROOF_ERROR",
+        title: "Verification command required.",
+        what: "Verify requires a shell command after `--`.",
+        why: "Proof must record the output of a concrete verification command.",
+        next: "Run `agentbridge verify -- npm test` (or your project command).",
+        blocksAcceptance: true,
+    },
+    VERIFY_COMMAND_FAILED: {
+        code: "VERIFY_COMMAND_FAILED",
+        category: "PROOF_ERROR",
+        title: "Verification command failed.",
+        what: "The verification command exited with a non-zero status.",
+        why: "Failed proof blocks acceptance until tests or checks pass.",
+        next: "Fix the command failure, then rerun `agentbridge verify -- <command>`.",
+        blocksAcceptance: true,
+    },
+    PROOF_MISSING: {
+        code: "PROOF_MISSING",
+        category: "PROOF_ERROR",
+        title: "Required proof missing.",
+        what: "Acceptance checks report missing verification evidence.",
+        why: "Acceptance requires recorded proof for this work session.",
+        next: "Run `agentbridge verify -- <command>` then `agentbridge check`.",
+        blocksAcceptance: true,
+    },
+    PROOF_EVIDENCE_NOT_RECORDED: {
+        code: "PROOF_EVIDENCE_NOT_RECORDED",
+        category: "PROOF_ERROR",
+        title: "Proof not recorded.",
+        what: "Verification could not be recorded on the server.",
+        why: "Without a verification run, acceptance cannot proceed.",
+        next: "Retry verify after confirming network access and session binding.",
+        blocksAcceptance: true,
+    },
+    SESSION_ID_REQUIRED: {
+        code: "SESSION_ID_REQUIRED",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Session id required.",
+        what: "Session inspect requires a work session id argument.",
+        why: "The command must know which server session to load.",
+        next: "Run `agentbridge session inspect <work-session-id>`.",
+    },
+    SESSION_ABANDON_REASON_REQUIRED: {
+        code: "SESSION_ABANDON_REASON_REQUIRED",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Abandon reason too short.",
+        what: "Session abandon requires --reason with at least 8 characters.",
+        why: "Abandon is audited and must explain why the session stopped.",
+        next: 'Run `agentbridge session abandon --reason "<why stopping>"`.',
+    },
+    SESSION_NO_TARGET: {
+        code: "SESSION_NO_TARGET",
+        category: "WORK_CONTEXT_ERROR",
+        title: "No session to abandon.",
+        what: "No --session id was passed and no local session is linked.",
+        why: "Abandon must target a specific work session.",
+        next: "Pass --session <id> or link a session via `agentbridge watch`.",
+    },
+    WORK_CONTEXT_SESSION_ALREADY_TERMINAL: {
+        code: "WORK_CONTEXT_SESSION_ALREADY_TERMINAL",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Session already closed.",
+        what: "The linked work session is closed or terminal.",
+        why: "Proof and acceptance cannot attach to a finished session.",
+        next: "Run `agentbridge session abandon --reason \"session closed\"` and start fresh.",
+        blocksAcceptance: true,
+    },
+    ACCEPTANCE_ALREADY_CLOSED: {
+        code: "ACCEPTANCE_ALREADY_CLOSED",
+        category: "ACCEPTANCE_ERROR",
+        title: "Work already closed.",
+        what: "This change request or session is already in a terminal acceptance state.",
+        why: "Accept and verify cannot mutate closed work.",
+        next: "Start a new scoped job with `agentbridge start`.",
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_SESSION_CR_MISMATCH: {
+        code: "WORK_CONTEXT_SESSION_CR_MISMATCH",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Session change-request mismatch.",
+        what: "Local session points at a different change request than requested.",
+        why: "Proof or acceptance could attach to the wrong work.",
+        next: "Fix activeChangeRequestId or abandon the stale local session.",
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_STALE_LOCAL_SESSION: {
+        code: "WORK_CONTEXT_STALE_LOCAL_SESSION",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Stale local session.",
+        what: "Local session id no longer exists on the server.",
+        why: "Watch and verify would track orphaned state.",
+        next: 'Local session state has been cleared. Run `agentbridge start --summary "<task>" --scope "<path>"` to begin fresh.',
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_SCOPE_MISMATCH: {
+        code: "WORK_CONTEXT_SCOPE_MISMATCH",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Session scope or task mismatch.",
+        what: "The active session was started with a different task or scope than requested.",
+        why: "Resuming the wrong session would silently corrupt proof and scope boundaries.",
+        next: 'Finish or abandon the current session (`agentbridge session abandon --reason "..."`) then rerun `agentbridge start --summary "<task>" --scope "<path>"`.',
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_AMBIGUOUS_SESSIONS: {
+        code: "WORK_CONTEXT_AMBIGUOUS_SESSIONS",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Ambiguous active sessions.",
+        what: "Multiple active sessions match this change request.",
+        why: "The CLI cannot pick a single current session safely.",
+        next: 'Run `agentbridge session abandon --session <id> --reason "duplicate"`.',
+        blocksAcceptance: true,
+    },
+    WORK_CONTEXT_OTHER_ACTIVE_SESSIONS: {
+        code: "WORK_CONTEXT_OTHER_ACTIVE_SESSIONS",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Other active sessions exist.",
+        what: "No current session is bound, but other active sessions exist on the server.",
+        why: "Verify and accept must not attach to the wrong session silently.",
+        next: 'Run `agentbridge session list --active` to identify the correct session, then `agentbridge watch --change-request <cr-id>` to bind it explicitly.',
+        blocksAcceptance: true,
+    },
+    SESSION_SERVER_MISSING: {
+        code: "SESSION_SERVER_MISSING",
+        category: "WORK_CONTEXT_ERROR",
+        title: "Session not found on server.",
+        what: "The requested work session id does not exist in this project.",
+        why: "Inspect and abandon require a valid server session.",
+        next: "Run `agentbridge session list` and pick a current id.",
+    },
+};
+const SERVER_CODE_ALIASES = {
+    not_project_member: "PROJECT_ACCESS_NOT_MEMBER",
+    unauthorized: "PROJECT_ACCESS_UNAUTHORIZED",
+    invalid_api_key: "PROJECT_ACCESS_UNAUTHORIZED",
+    forbidden: "PROJECT_ACCESS_UNAUTHORIZED",
+    project_not_found: "PROJECT_ACCESS_NOT_FOUND",
+    change_request_not_found: "WORK_CONTEXT_BINDING_REQUIRED",
+    handoff_required: "HANDOFF_REQUIRED",
+    session_has_handoff: "HANDOFF_REQUIRED",
+    pending_boundary_approval: "ACCEPTANCE_BLOCKED",
+    already_terminal: "WORK_CONTEXT_SESSION_ALREADY_TERMINAL",
+    already_closed: "ACCEPTANCE_ALREADY_CLOSED",
+    session_closed: "WORK_CONTEXT_SESSION_ALREADY_TERMINAL",
+    proof_stale: "PROOF_STALE_AFTER_CHANGE",
+    stale_evidence_after_change: "PROOF_STALE_AFTER_CHANGE",
+    evidence_missing: "PROOF_MISSING",
+    scope_drift: "SCOPE_DRIFT_OUT_OF_SCOPE_FILE",
+    out_of_scope_file: "SCOPE_DRIFT_OUT_OF_SCOPE_FILE",
+    cr_no_owner: "START_OWNER_UNRESOLVED",
+    internal_error: "SERVER_ERROR",
+    // WS2: hard session binding
+    work_context_scope_mismatch: "WORK_CONTEXT_SCOPE_MISMATCH",
+    local_session_mismatch: "WORK_CONTEXT_SCOPE_MISMATCH",
+    local_session_not_found: "WORK_CONTEXT_STALE_LOCAL_SESSION",
+};
+function mapServerCodeToCatalog(code) {
+    const normalized = code.toLowerCase();
+    return SERVER_CODE_ALIASES[normalized] ?? code;
+}
+function catalogEntryForCode(code) {
+    if (!code)
+        return null;
+    const direct = CATALOG[code];
+    if (direct)
+        return direct;
+    const alias = SERVER_CODE_ALIASES[code.toLowerCase()];
+    if (alias)
+        return CATALOG[alias] ?? null;
+    return null;
+}
+function doctorReasonToCode(reason) {
+    switch (reason) {
+        case "not_project_member":
+            return "PROJECT_ACCESS_NOT_MEMBER";
+        case "unauthorized":
+        case "invalid_api_key":
+            return "PROJECT_ACCESS_UNAUTHORIZED";
+        case "project_not_found":
+            return "PROJECT_ACCESS_NOT_FOUND";
+        case "network_error":
+        case "request_timeout":
+            return "NETWORK_UNREACHABLE";
+        case "server_error":
+            return "SERVER_ERROR";
+        case "config_incomplete":
+            return "CONFIG_INCOMPLETE";
+        default:
+            return `DOCTOR_${reason.toUpperCase()}`;
+    }
+}
+function catalogViewForDoctorReason(reason, suggestedNext) {
+    const code = doctorReasonToCode(reason);
+    const entry = catalogEntryForCode(code);
+    if (entry) {
+        return {
+            title: entry.title,
+            what: entry.what,
+            why: entry.why,
+            next: suggestedNext ?? entry.next,
+            code: entry.code,
+            category: entry.category,
+        };
+    }
+    return {
+        title: "Doctor preflight failed.",
+        what: `Project access check failed (${reason}).`,
+        why: "AgentBridge cannot verify that this machine can reach the configured room.",
+        next: suggestedNext ?? "Run `agentbridge doctor` after fixing config.",
+        code,
+        category: "PROJECT_ACCESS_ERROR",
+    };
+}
+function workContextStateToCode(state) {
+    switch (state) {
+        case "no_current_session":
+            return "WORK_CONTEXT_NO_CURRENT_SESSION";
+        case "current_session_closed":
+            return "WORK_CONTEXT_SESSION_ALREADY_TERMINAL";
+        case "mismatch":
+            return "WORK_CONTEXT_SESSION_CR_MISMATCH";
+        case "stale_orphan_session_detected":
+            return "WORK_CONTEXT_STALE_LOCAL_SESSION";
+        case "ambiguous_active_sessions":
+            return "WORK_CONTEXT_AMBIGUOUS_SESSIONS";
+        case "other_active_sessions_exist":
+            return "WORK_CONTEXT_OTHER_ACTIVE_SESSIONS";
+        default:
+            return "WORK_CONTEXT_BINDING_REQUIRED";
+    }
+}