@synap-core/cli 1.10.0 → 1.12.2

package/dist/lib/hub-client.js

@@ -1,10 +1,51 @@
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { getActivePodConfig, getActiveWorkspaceId, getActiveProjectId, listPodProfiles, getPodOverride, getSurfaceAgentKey } from "./pod.js";
+import { getActivePodConfig, getActiveWorkspaceId, getActiveWorkspaceIdForPod, findPodNameByUrl, getActiveProjectBinding, getActiveProjectId, listPodProfiles, getPodOverride, getSurfaceAgentKey, } from "./pod.js";
 import { resolveAgentOverride } from "./agents-config.js";
-import { resolveActiveLens } from "./session-lens.js";
-import { HubRestClient } from "@synap/hub-rest-client";
+import { resolveActiveLensForPod, getClaudeSessionId, writeLens, clearLensField, } from "./session-lens.js";
+import { conversationHeaders } from "./conversation-headers.js";
+import { effectiveDirectoryLens, resolveDirectoryLensForPod, writeDirectoryLens, clearDirectoryLensField, } from "./directory-lens.js";
+import { preferClaudeCodeSurfaceKey } from "./key-source.js";
+import { samePodOrigin } from "./project-ref.js";
+import { HubRestClient } from "@synap-core/hub-rest-client";
 import { log } from "../utils/logger.js";
+import chalk from "chalk";
+/**
+ * Resolve a projectId safe to send to `podUrl`.
+ *
+ * Order: pod-qualified lens → directory lens → env project when co-located with
+ * this pod (trustEnvProject — same model as SYNAP_WORKSPACE_ID under env rung) →
+ * ActiveProjectBinding for this pod → legacy activeProjectId only when the
+ * active profile is this pod.
+ *
+ * Write paths should consume `resolveHubConfig().projectId` rather than bare
+ * `getActiveProjectId()` / env.
+ */
+function resolveProjectIdForPod(podUrl, opts) {
+    if (opts.lensProjectId)
+        return opts.lensProjectId;
+    if (opts.dirLensProjectId)
+        return opts.dirLensProjectId;
+    // Env pin co-located with env pod (connect --pin-project, Claude settings.env).
+    if (opts.trustEnvProject && opts.envProject)
+        return opts.envProject;
+    const profiles = listPodProfiles();
+    const binding = getActiveProjectBinding();
+    if (binding) {
+        const boundPod = profiles.find((x) => x.name === binding.podName);
+        if (boundPod && samePodOrigin(boundPod.config.podUrl, podUrl)) {
+            return binding.projectId;
+        }
+        // Binding is for another pod — do not send it.
+        return undefined;
+    }
+    // Legacy: activeProjectId with no binding — only when active profile is this pod.
+    const active = getActivePodConfig();
+    if (active && samePodOrigin(active.podUrl, podUrl)) {
+        return getActiveProjectId() || undefined;
+    }
+    return undefined;
+}
 /**
  * A failed Hub call, carrying the structured facts callers need to branch on.
  *
@@ -22,6 +63,10 @@ export class HubError extends Error {
     rawBody;
     path;
     method;
+    /** Origin of the pod this call actually hit — for cross-pod diagnostics. */
+    podUrl;
+    /** Workspace this call actually sent — for cross-pod 403 diagnostics. */
+    workspaceId;
     constructor(init) {
         super(init.message);
         this.name = "HubError";
@@ -32,6 +77,8 @@ export class HubError extends Error {
         this.rawBody = init.rawBody;
         this.path = init.path;
         this.method = init.method;
+        this.podUrl = init.podUrl;
+        this.workspaceId = init.workspaceId;
     }
 }
 /**
@@ -166,21 +213,56 @@ function readErrorBody(status, rawBody) {
         const oneLine = trimmed.replace(/\s+/g, " ");
         return { detail: oneLine.length > 200 ? `${oneLine.slice(0, 200)}…` : oneLine };
     }
+    // tRPC batch errors are array-shaped: `[{ error: { message, code, data: { httpStatus, ... } } }]`
+    // (superjson may additionally nest the real payload one level deeper under
+    // `error.json`). Unwrap to the first entry's error object before falling
+    // through to the normal object-shaped handling below, so a tRPC failure
+    // surfaces its real `message` instead of the generic status phrase.
+    if (Array.isArray(parsed)) {
+        const first = parsed[0];
+        const err = first?.error;
+        if (err && typeof err === "object") {
+            const json = err.json;
+            parsed = json ?? err;
+        }
+    }
+    else if (parsed &&
+        typeof parsed === "object" &&
+        "error" in parsed) {
+        // Single tRPC-shaped error body: `{ error: { message, ... } }` or
+        // `{ error: { json: { message, ... } } }`. Only unwrap when `error` is an
+        // OBJECT — a Hub-REST body's `error` is a plain string category
+        // (`{ error: "...", detail: "..." }`) and must fall through unchanged.
+        const errVal = parsed.error;
+        if (errVal && typeof errVal === "object") {
+            const errObj = errVal;
+            const json = errObj.json;
+            parsed = json ?? errObj;
+        }
+    }
     if (parsed && typeof parsed === "object") {
         const o = parsed;
         const code = typeof o.code === "string" ? o.code : undefined;
         const reason = typeof o.reason === "string" ? o.reason : undefined;
-        const detail = typeof o.message === "string" && o.message
-            ? o.message
-            : typeof o.error === "string" && o.error
-                ? o.error
-                : statusPhrase(status);
+        const str = (v) => typeof v === "string" && v ? v : undefined;
+        // Backend error contract for the Hub package/workspace routes is
+        // `{ error: <category>, detail: <the real underlying cause> }`. The specific
+        // cause lives in `detail` — surfacing only `error` throws away the one thing
+        // that makes a 500 actionable (e.g. "profile X targets unknown profile Y").
+        // Precedence: message (tRPC-shaped) → error+detail combined → error → detail.
+        const message = str(o.message);
+        const errorField = str(o.error);
+        const detailField = str(o.detail);
+        const detail = message ??
+            (errorField && detailField
+                ? `${errorField}: ${detailField}`
+                : errorField ?? detailField ?? statusPhrase(status));
         return { detail, code, reason, parsed };
     }
     return { detail: statusPhrase(status), parsed };
 }
 /** Build the HubError for a non-ok response body. */
-function hubError(method, path, status, rawBody, suffix) {
+function hubError(method, path, status, rawBody, suffix, ctx) {
     const { detail, code, reason, parsed } = readErrorBody(status, rawBody);
     return new HubError({
         message: `Hub ${method} ${path} failed (HTTP ${status})${suffix ? ` ${suffix}` : ""}: ${detail}`,
@@ -191,15 +273,50 @@ function hubError(method, path, status, rawBody, suffix) {
         rawBody,
         path,
         method,
+        podUrl: ctx?.podUrl ? originOf(ctx.podUrl) : undefined,
+        workspaceId: ctx?.workspaceId,
     });
 }
+/** Where to send users who hit a wall. */
+const DISCORD_INVITE_URL = "https://discord.gg/xhRdQ7hG5h";
+/** Wrap a URL in an OSC-8 terminal hyperlink so `label` is clickable. */
+function osc8Link(url, label) {
+    return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
+/**
+ * Once-per-process guard for the Discord help footer. A single CLI invocation
+ * runs one command; printing the footer at most once keeps it a footer, not a
+ * per-error/per-line spam.
+ */
+let _discordHelpShown = false;
+/**
+ * Append a one-line "need help?" footer with a clickable Discord invite. Prints
+ * to stderr (same stream as the error it follows, so `2>/dev/null` hides both)
+ * and only once per process. The invite is an OSC-8 hyperlink on an interactive
+ * terminal, a plain URL when the stream is redirected/piped.
+ */
+export function discordHelpLine() {
+    if (_discordHelpShown)
+        return;
+    _discordHelpShown = true;
+    const link = process.stderr.isTTY
+        ? osc8Link(DISCORD_INVITE_URL, DISCORD_INVITE_URL)
+        : DISCORD_INVITE_URL;
+    console.error(chalk.dim(`    Need help? Join our Discord: ${link}`));
+}
 /**
  * Print a failed Hub call: its humanized message plus a hint for the classes
  * where the cause is not obvious from the message alone. Lives here rather than
  * in utils/logger so the logger stays domain-agnostic and the taxonomy and its
- * presentation sit in one file.
+ * presentation sit in one file. Always closes with the one-time Discord footer.
  */
 export function renderHubError(err) {
+    renderHubErrorBody(err);
+    // ONE central place every failed Hub command flows through — append the help
+    // footer here so it prints once per failed command (guarded), not per line.
+    discordHelpLine();
+}
+function renderHubErrorBody(err) {
     // Hints use log.hint (stderr), not log.dim (stdout): a hint belongs to the
     // error it explains, and splitting one message across two streams means
     // `2>/dev/null` shows a bare hint with no error above it.
@@ -212,15 +329,112 @@ export function renderHubError(err) {
         log.error(err instanceof Error ? err.message : String(err));
         return;
     }
+    // Connection-class failure — the execute door returns 424 with a machine
+    // `errorClass` (+ `providerRef`) precisely so it SURVIVES the pod's 5xx egress
+    // sanitizer. This is client-ACTIONABLE (reconnect), not a server fault, so name
+    // the cause + the exact fix instead of the generic status hint. Mirrors the
+    // browser's P1 self-heal reconnect chip.
+    const errBody = err.body;
+    const errorClass = errBody?.errorClass;
+    if (errorClass === "auth" || errorClass === "no_connection") {
+        const provider = errBody?.providerRef
+            ? chalk.bold(errBody.providerRef)
+            : "this capability's";
+        log.error(`The ${provider} connection needs reconnecting — its access has expired or was revoked.`);
+        log.hint('Reconnect it:  synap cap connect "<capability>" --reconnect');
+        log.hint("Find the capability name with:  synap cap list");
+        return;
+    }
+    if (errorClass === "target_missing") {
+        log.error(err.message);
+        log.hint("The workspace or target this run needs no longer exists on this pod. Run: synap orient");
+        return;
+    }
+    // SETUP-REQUIRED failure — the APPLY door (`POST /capabilities/apply`) returns
+    // a DUCK-TYPED body (412 for `no_connection`, 400 for `missing_field`) with
+    // `failureClass` (+ `missingFields` / `connection`) so an install that needs a
+    // human before it can apply survives as an actionable message. This is a
+    // client-ACTIONABLE, NON-retryable state — name the missing step instead of the
+    // generic status phrase below (a bare 412/400 tells the user nothing to do).
+    const setupBody = err.body;
+    const failureClass = setupBody?.failureClass;
+    if (failureClass === "no_connection") {
+        const provider = setupBody?.connection?.provider;
+        log.error(provider
+            ? `The "${provider}" provider isn't connected yet — connect it first (synap cap connect "${provider}").`
+            : 'A required provider isn\'t connected yet — connect it first (synap cap connect "<provider>").');
+        return;
+    }
+    if (failureClass === "missing_field") {
+        const missingFields = Array.isArray(setupBody?.missingFields)
+            ? setupBody.missingFields.filter((field) => typeof field === "string")
+            : [];
+        log.error(missingFields.length > 0
+            ? `Missing required value(s): ${missingFields.join(", ")}`
+            : "Missing required value(s).");
+        return;
+    }
     log.error(err.message);
+    // A 500 carries an `errorId` (the egress sanitizer logs the real cause under
+    // it server-side) — surface it so "quote errorId when reporting it" is
+    // actionable rather than a dead end.
+    const errorId = typeof err.body?.errorId === "string"
+        ? err.body.errorId
+        : undefined;
+    if (err.status >= 500 && errorId) {
+        log.hint(`errorId: ${errorId}`);
+    }
+    // A 500 whose body carried a specific cause (detail/message) is already in
+    // `err.message` above — do NOT then claim "internal error, not in this
+    // command": a workspace/template creation failure is often an actionable
+    // template or data problem. Only add the generic pod-fault hint when the body
+    // gave nothing better than the status phrase.
+    const hasSpecificCause = !!err.rawBody && !err.message.endsWith("the pod hit an internal error");
+    // A 403/message naming a workspace: the real cause is almost always "that
+    // workspace doesn't exist or isn't accessible ON THIS POD" (a stale saved
+    // workspace id after a pod switch), not a scopes problem — name it + the
+    // exact next command instead of the generic "credentials" hint.
+    const namesWorkspace = /workspace/i.test(err.message);
     if (err.status >= 500) {
-        log.hint("The pod hit an internal error — this is a fault on the pod side, not in this command.");
+        if (!hasSpecificCause) {
+            log.hint("The pod hit an internal error — check the pod logs for the stack trace.");
+        }
+    }
+    else if (err.status === 403 && namesWorkspace) {
+        // Name the exact workspace + pod this call used: the usual cause is a global
+        // active workspace left over from ANOTHER pod (a stale `synap use` after a
+        // pod switch) being sent to a pod it doesn't belong to.
+        if (err.workspaceId && err.podUrl) {
+            // State the FACT (what was sent where), then the two causes WITHOUT
+            // picking one — this code cannot tell them apart, and asserting the
+            // cross-pod story is wrong whenever the saved workspace simply no longer
+            // exists on its own pod (dogfood: `pods.team.workspaceId` pointed at a
+            // deleted workspace; the hint blamed a pod mix-up that had not happened).
+            // `synap doctor` is the only thing here that actually CHECKS, so it leads.
+            log.hint(`Sent workspace ${err.workspaceId} to ${err.podUrl}.`);
+            log.hint("That workspace is not accessible on this pod — either it lives on a different pod, or it no longer exists here.");
+            log.hint("Run: synap doctor   (checks which of the two it is), then: synap orient   (see valid workspaces) and synap use <id>.");
+        }
+        else {
+            log.hint("Workspace not found or not accessible on this pod — run: synap orient   (see valid workspaces), or: synap doctor");
+        }
     }
     else if (err.status === 401 || err.status === 403) {
-        log.hint("The pod rejected this key's credentials or its scopes for this operation.");
+        log.hint("The pod rejected this key's credentials or its scopes for this operation. Run: synap doctor");
     }
     else if (err.status === 404) {
-        log.hint("The pod has no such endpoint or record — it may be running an older build.");
+        // A structured JSON body (err.body set) means THIS app answered — the
+        // endpoint just doesn't exist here (older build / wrong record). A body
+        // that failed to parse as JSON (readErrorBody's plain-text fallback — a
+        // proxy default page, an HTML error, a completely different service)
+        // means the request never reached this app at all: the classic
+        // stale/migrated-domain failure, not an old build.
+        if (err.body === undefined && err.rawBody.trim()) {
+            log.hint("This host doesn't look like a Synap pod — your saved pod URL may be stale. Run: synap doctor");
+        }
+        else {
+            log.hint("The pod has no such endpoint or record — it may be running an older build, or the id doesn't exist. Run: synap doctor");
+        }
     }
 }
 const userIdCache = new Map();
@@ -250,14 +464,21 @@ export async function resolveHubConfig(opts) {
     //    Beats the env vars deliberately — that is the whole point of the flag.
     const podOverride = getPodOverride();
     if (podOverride) {
+        // Prefer cross-pod-safe resolution (binding + "not another pod's default")
+        // over the profile's baked `workspaceId`, which can drift to a foreign UUID
+        // after dual-pod work (dogfood: perso profile held team CRM ws → 403).
+        const overrideName = findPodNameByUrl(podOverride.podUrl);
+        const safeWs = getActiveWorkspaceIdForPod(overrideName) ||
+            // Only fall back to profile default when it isn't known to belong elsewhere
+            // (getActiveWorkspaceIdForPod already applied that rule against the profile).
+            undefined;
         return {
             podUrl: podOverride.podUrl,
             apiKey: podOverride.hubApiKey,
             // A profile's agentUserId may be empty; "cli" makes resolveUserId fetch /users/me.
             userId: podOverride.agentUserId || "cli",
-            // Use the TARGET pod's own workspace — NOT this session's lens, which
-            // belongs to the default pod and would be meaningless on the target.
-            workspaceId: podOverride.workspaceId || undefined,
+            workspaceId: safeWs,
+            projectId: resolveProjectIdForPod(podOverride.podUrl, {}),
         };
     }
     // 1. Explicit flags (escape hatch)
@@ -278,7 +499,10 @@ export async function resolveHubConfig(opts) {
         return {
             podUrl,
             apiKey: agentOverride.apiKey,
-            userId: agentOverride.podName ?? "agent",
+            // The AGENT's own id, recorded with its key. Never the pod profile name
+            // (it was, so `synap worker` never recognised its own room posts and
+            // resumed itself on them). Unrecorded → "cli": resolveUserId asks the pod.
+            userId: agentOverride.agentUserId || "cli",
             scopes: envScopes ? envScopes.split(",") : undefined,
         };
     }
@@ -297,24 +521,51 @@ export async function resolveHubConfig(opts) {
         // the pinned key so a leaked/inherited env var can't silently redefine
         // which agent this session acts as. Conservative: only applies here, in
         // step 3 — steps 0-2 (--pod, explicit flags, SYNAP_AGENT) still win
-        // outright, untouched.
-        const surfaceKey = getSurfaceAgentKey("claude-code");
-        let apiKey = envKey;
-        let userId = envUser;
-        if (surfaceKey && surfaceKey.podUrl === envPod && surfaceKey.hubApiKey && surfaceKey.hubApiKey !== envKey) {
+        // outright, untouched. Preference logic lives in key-source.ts so whoami
+        // reports the same rule (no drift).
+        const preferred = preferClaudeCodeSurfaceKey({
+            envPod,
+            envKey,
+            envUser,
+            surface: getSurfaceAgentKey("claude-code", envPod),
+        });
+        if (preferred.usedSurface) {
             process.stderr.write(`[synap] warning: ambient SYNAP_HUB_API_KEY does not match the claude-code surface key pinned to ${envPod} — using the pinned key instead of the inherited one.\n`);
-            apiKey = surfaceKey.hubApiKey;
-            userId = surfaceKey.agentUserId || envUser;
         }
+        const apiKey = preferred.apiKey;
+        const userId = preferred.userId;
+        // Per-Claude-session lens wins over the global env var, so concurrent
+        // sessions can each be scoped to a different workspace — but ONLY when the
+        // lens belongs to THIS pod. A lens stamped with another pod is ignored so
+        // the pod-qualified fallback below applies (the "Access denied to
+        // workspace" 403 after `synap pods use`).
+        const lens = resolveActiveLensForPod(envPod);
+        // …and the per-DIRECTORY lens sits directly beneath it: the durable default
+        // for this working tree, overridden by the session lens when one is set.
+        // Pod-qualified through the same door, for the same reason — a directory
+        // lens outlives many `synap pods use` switches, so it is MORE exposed to
+        // the cross-pod 403 than the session lens is.
+        const dirLens = resolveDirectoryLensForPod(envPod)?.lens;
         return {
             podUrl: envPod,
             apiKey,
             userId,
-            // Per-Claude-session lens wins over the global env var, so concurrent
-            // sessions can each be scoped to a different workspace.
-            workspaceId: resolveActiveLens()?.workspaceId || envWorkspace || getActiveWorkspaceId(),
-            // Project is a peer lens, threaded exactly like workspaceId.
-            projectId: resolveActiveLens()?.projectId || envProject || getActiveProjectId(),
+            // The global-config fallback is resolved AGAINST THIS POD (envPod) —
+            // never send a workspace that belongs to a different pod.
+            workspaceId: lens?.workspaceId ||
+                dirLens?.workspaceId ||
+                envWorkspace ||
+                getActiveWorkspaceIdForPod(findPodNameByUrl(envPod)),
+            // Project is a peer lens. Lens/dir-lens are already pod-qualified;
+            // env/global active project only when ActiveProjectBinding matches this pod.
+            // Write paths must use this resolveHubConfig output — never bare
+            // getActiveProjectId() / SYNAP_PROJECT_ID without the pod check.
+            projectId: resolveProjectIdForPod(envPod, {
+                lensProjectId: lens?.projectId,
+                dirLensProjectId: dirLens?.projectId,
+                envProject,
+                trustEnvProject: true,
+            }),
             scopes: envScopes ? envScopes.split(",") : undefined,
         };
     }
@@ -322,40 +573,136 @@ export async function resolveHubConfig(opts) {
     const config = getActivePodConfig();
     if (!config)
         throw new Error("No pod configured. Run: synap pods add");
+    // Same pod-qualification as step 3: a lens stamped with another pod must not
+    // short-circuit `getActiveWorkspaceId()`, which IS cross-pod-safe.
+    const activeLens = resolveActiveLensForPod(config.podUrl);
+    const activeDirLens = resolveDirectoryLensForPod(config.podUrl)?.lens;
     return {
         podUrl: config.podUrl,
         apiKey: config.hubApiKey,
         userId: config.agentUserId,
-        workspaceId: resolveActiveLens()?.workspaceId || getActiveWorkspaceId(),
-        projectId: resolveActiveLens()?.projectId || getActiveProjectId(),
+        // session lens › directory lens › global config. (No env rung here: this
+        // branch is only reached when SYNAP_POD_URL is unset.)
+        workspaceId: activeLens?.workspaceId || activeDirLens?.workspaceId || getActiveWorkspaceId(),
+        // Project: same pod-qualification as step 3 (no bare getActiveProjectId).
+        projectId: resolveProjectIdForPod(config.podUrl, {
+            lensProjectId: activeLens?.projectId,
+            dirLensProjectId: activeDirLens?.projectId,
+        }),
     };
 }
-const SESSION_FILE = ".synap-session";
-/** Read the active session ID for this terminal from CWD or env var. */
-export function readActiveSessionId() {
+// ─── Active focus session ─────────────────────────────────────────────────────
+//
+// ONE store, two rungs of the SAME lens mechanism:
+//
+//   env SYNAP_SESSION_ID  ›  session lens (per Claude tab)  ›  directory lens
+//
+// The directory rung supplies a session only OUTSIDE a Claude Code conversation
+// (`effectiveDirectoryLens`): inside one, the session belongs to the
+// conversation, never to the working tree.
+//
+// The retired legacy store was a per-CWD `.synap-session` file that the session
+// lens already silently shadowed — two concurrent "current session" stores for
+// one concept. It is now read exactly once, to migrate (below).
+/** Legacy per-CWD session file — RETIRED as a store; read once to migrate. */
+const LEGACY_SESSION_FILE = ".synap-session";
+let legacySessionMigrationChecked = false;
+/**
+ * One-time migration of a pre-existing `.synap-session` into the DIRECTORY lens.
+ *
+ * COMPAT DECISION — read-and-migrate, not a permanent read-only fallback. A
+ * fallback would keep two stores alive indefinitely, which is exactly the
+ * divergence being removed. Migrating is faithful: `.synap-session` was
+ * per-working-tree and durable, and the directory lens has precisely that
+ * lifetime and scope — so an already-attached session survives the upgrade for
+ * every terminal in that tree. The file is deleted afterwards so it can never
+ * shadow (or be shadowed by) the lens again.
+ *
+ * No `podUrl` is stamped: the legacy file carried no pod, and stamping one here
+ * would falsely pod-qualify whatever workspace/project the lens already holds.
+ */
+function migrateLegacySessionFile() {
+    if (legacySessionMigrationChecked)
+        return;
+    legacySessionMigrationChecked = true;
+    const filePath = join(process.cwd(), LEGACY_SESSION_FILE);
+    if (!existsSync(filePath))
+        return;
+    let id;
+    try {
+        id = readFileSync(filePath, "utf8").trim() || undefined;
+    }
+    catch {
+        return;
+    }
+    try {
+        if (id)
+            writeDirectoryLens({ focusSessionId: id });
+        unlinkSync(filePath);
+    }
+    catch {
+        return; // best-effort — a read-only tree simply keeps the stale file
+    }
+    process.stderr.write(`[synap] .synap-session is deprecated${id ? ` — session ${id.slice(0, 8)}… migrated into .synap/lens.json` : " — removed (empty)"}.\n`);
+}
+/**
+ * The focus session every hub call should be tagged with.
+ *
+ * Both lens rungs are pod-qualified: a focus-session id is POD-LOCAL, so a lens
+ * stamped with another pod must not leak into `X-Session-Id`. (Lenses written
+ * before the stamp existed have no `podUrl` and match leniently — see
+ * `lensMatchesPod`.)
+ */
+export function resolveActiveSessionId(podUrl) {
     const fromEnv = process.env.SYNAP_SESSION_ID;
     if (fromEnv)
         return fromEnv;
-    const filePath = join(process.cwd(), SESSION_FILE);
-    if (existsSync(filePath)) {
-        return readFileSync(filePath, "utf8").trim() || undefined;
-    }
-    return undefined;
+    migrateLegacySessionFile();
+    const fromSessionLens = resolveActiveLensForPod(podUrl)?.focusSessionId;
+    if (fromSessionLens)
+        return fromSessionLens;
+    const dir = resolveDirectoryLensForPod(podUrl);
+    return dir ? effectiveDirectoryLens(dir.lens).focusSessionId : undefined;
 }
-/** Attach a session to this terminal — writes .synap-session in CWD. */
-export function writeActiveSessionId(sessionId) {
-    writeFileSync(join(process.cwd(), SESSION_FILE), sessionId, "utf8");
+/**
+ * Attach a focus session to this terminal.
+ *
+ * Inside Claude Code the SESSION lens wins — per-tab isolation is the point
+ * (tab A on session X, tab B on session Y, same directory). Outside it there is
+ * no `CLAUDE_CODE_SESSION_ID` to key on, so the DIRECTORY lens is the
+ * legitimate fallback: the same per-working-tree scope the retired
+ * `.synap-session` had. `attach` therefore never silently no-ops.
+ */
+export function attachActiveSessionId(sessionId) {
+    const claudeSession = getClaudeSessionId();
+    if (claudeSession) {
+        writeLens(claudeSession, { focusSessionId: sessionId });
+        return "session-lens";
+    }
+    writeDirectoryLens({ focusSessionId: sessionId });
+    return "directory-lens";
 }
-/** Detach the active session from this terminal — removes .synap-session. */
-export function clearActiveSessionId() {
-    const filePath = join(process.cwd(), SESSION_FILE);
-    if (existsSync(filePath))
-        unlinkSync(filePath);
+/**
+ * Detach — clear the focus session from BOTH lens rungs, and return whatever
+ * was active. Clearing only the top rung would "detach" into the lower one,
+ * which reads as the command failing.
+ */
+export function detachActiveSessionId(podUrl) {
+    const previous = resolveActiveSessionId(podUrl);
+    const claudeSession = getClaudeSessionId();
+    if (claudeSession)
+        clearLensField(claudeSession, "focusSessionId");
+    clearDirectoryLensField("focusSessionId");
+    return previous;
 }
-function sessionHeaders() {
-    // Per-Claude-session lens wins; fall back to the legacy per-CWD .synap-session.
-    const id = resolveActiveLens()?.focusSessionId || readActiveSessionId();
-    return id ? { "X-Session-Id": id } : {};
+/**
+ * Per-request headers: the focus session this terminal is attached to, and the
+ * Claude Code conversation the call comes from (`conversation-headers.ts`) — so
+ * the work it lands can be traced back to, and reopened in, that conversation.
+ */
+function sessionHeaders(cfg) {
+    const id = resolveActiveSessionId(cfg?.podUrl);
+    return { ...conversationHeaders(getClaudeSessionId()), ...(id ? { "X-Session-Id": id } : {}) };
 }
 /** Max 429 retries for bulk import (each waits up to the rate-limit window). */
 const HUB_429_MAX_RETRIES = 12;
@@ -464,15 +811,26 @@ export async function hubGet(path, params, cfg) {
             url.searchParams.set(k, String(v));
     }
     const res = await hubFetchWithRetry(url.toString(), {
-        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
         signal: AbortSignal.timeout(15_000),
     }, `GET ${path}`, 15_000);
     if (!res.ok) {
         const body = await res.text().catch(() => "");
-        throw hubError("GET", path, res.status, body);
+        throw hubError("GET", path, res.status, body, undefined, cfg);
     }
     return res.json();
 }
+/**
+ * The workspace a failing request ACTUALLY carried. A caller may override the
+ * configured lens per-command (e.g. `--workspace <id>`), and naming the config's
+ * workspace in that error sends the reader chasing the wrong id.
+ */
+function errorWorkspace(body, cfg) {
+    const sent = body && typeof body === "object" && "workspaceId" in body
+        ? body.workspaceId
+        : undefined;
+    return typeof sent === "string" && sent.length > 0 ? sent : cfg.workspaceId;
+}
 export async function hubPost(path, body, cfg, 
 // Default 15s suits CRUD doors. Capability runs invoke external provider APIs
 // (often several sequential calls) and legitimately take longer — callers
@@ -483,14 +841,17 @@ timeoutMs = 15_000) {
         headers: {
             Authorization: `Bearer ${cfg.apiKey}`,
             "Content-Type": "application/json",
-            ...sessionHeaders(),
+            ...sessionHeaders(cfg),
         },
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(timeoutMs),
     }, `POST ${path}`, timeoutMs);
     if (!res.ok) {
         const bodyText = await res.text().catch(() => "");
-        throw hubError("POST", path, res.status, bodyText);
+        throw hubError("POST", path, res.status, bodyText, undefined, {
+            podUrl: cfg.podUrl,
+            workspaceId: errorWorkspace(body, cfg),
+        });
     }
     return res.json();
 }
@@ -504,13 +865,13 @@ timeoutMs = 15_000) {
 export async function hubPostMultipart(path, form, cfg, timeoutMs = 120_000) {
     const res = await hubFetchWithRetry(`${cfg.podUrl}/api/hub${path}`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
         body: form,
         signal: AbortSignal.timeout(timeoutMs),
     }, `POST multipart ${path}`, timeoutMs);
     if (!res.ok) {
         const bodyText = await res.text().catch(() => "");
-        throw hubError("POST multipart", path, res.status, bodyText);
+        throw hubError("POST multipart", path, res.status, bodyText, undefined, cfg);
     }
     return res.json();
 }
@@ -528,7 +889,7 @@ export async function hubPostMultipartRetryable(path, buildForm, cfg, timeoutMs
         try {
             res = await fetch(url, {
                 method: "POST",
-                headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+                headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
                 body: form,
                 signal: AbortSignal.timeout(timeoutMs),
             });
@@ -539,7 +900,7 @@ export async function hubPostMultipartRetryable(path, buildForm, cfg, timeoutMs
         if (res.status !== 429) {
             if (!res.ok) {
                 const bodyText = await res.text().catch(() => "");
-                throw hubError("POST multipart", path, res.status, bodyText);
+                throw hubError("POST multipart", path, res.status, bodyText, undefined, cfg);
             }
             return res.json();
         }
@@ -560,7 +921,7 @@ export async function hubPatch(path, body, cfg) {
     try {
         res = await fetch(url, {
             method: "PATCH",
-            headers: { Authorization: `Bearer ${cfg.apiKey}`, "Content-Type": "application/json", ...sessionHeaders() },
+            headers: { Authorization: `Bearer ${cfg.apiKey}`, "Content-Type": "application/json", ...sessionHeaders(cfg) },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(15_000),
         });
@@ -570,7 +931,10 @@ export async function hubPatch(path, body, cfg) {
     }
     if (!res.ok) {
         const bodyText = await res.text().catch(() => "");
-        throw hubError("PATCH", path, res.status, bodyText);
+        throw hubError("PATCH", path, res.status, bodyText, undefined, {
+            podUrl: cfg.podUrl,
+            workspaceId: errorWorkspace(body, cfg),
+        });
     }
     return res.json();
 }
@@ -580,7 +944,7 @@ export async function hubDelete(path, cfg) {
     try {
         res = await fetch(url, {
             method: "DELETE",
-            headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+            headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
             signal: AbortSignal.timeout(15_000),
         });
     }
@@ -589,7 +953,7 @@ export async function hubDelete(path, cfg) {
     }
     if (!res.ok) {
         const bodyText = await res.text().catch(() => "");
-        throw hubError("DELETE", path, res.status, bodyText);
+        throw hubError("DELETE", path, res.status, bodyText, undefined, cfg);
     }
     return res.json().catch(() => ({}));
 }
@@ -605,5 +969,5 @@ export function makeHubClient(cfg) {
         workspaceId: cfg.workspaceId,
     });
 }
-export { HubRestClient } from "@synap/hub-rest-client";
+export { HubRestClient } from "@synap-core/hub-rest-client";
 //# sourceMappingURL=hub-client.js.map