@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/hub-client.js

@@ -1,11 +1,52 @@
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { getActivePodConfig, getActiveWorkspaceId, getActiveWorkspaceIdForPod, findPodNameByUrl, 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 { clientHeader, 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 { PodMovedError, podFetch } from "./pod-moved.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.
  *
@@ -173,6 +214,33 @@ 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;
@@ -210,44 +278,48 @@ function hubError(method, path, status, rawBody, suffix, ctx) {
         workspaceId: ctx?.workspaceId,
     });
 }
-/** Where to send users who hit a wall. */
+/**
+ * Where to send users who hit a wall. The support door is the ONE customer
+ * support entry point shared by every Synap surface (`from=cli` tells support
+ * which surface the person came from); Discord stays as the community option.
+ */
+export const SUPPORT_URL = "https://synap.live/support?from=cli";
 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
+ * Once-per-process guard for the 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;
+let _helpShown = 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.
+ * Append a one-line "need help?" footer naming the support door (open a ticket)
+ * and the Discord invite. Prints to stderr (same stream as the error it
+ * follows, so `2>/dev/null` hides both) and only once per process. Each URL is
+ * an OSC-8 hyperlink on an interactive terminal, a plain URL when the stream is
+ * redirected/piped.
  */
-export function discordHelpLine() {
-    if (_discordHelpShown)
+export function helpFooterLine() {
+    if (_helpShown)
         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}`));
+    _helpShown = true;
+    const link = (url) => (process.stderr.isTTY ? osc8Link(url, url) : url);
+    console.error(chalk.dim(`    Need help? Open a ticket: ${link(SUPPORT_URL)} (or join our Discord: ${link(DISCORD_INVITE_URL)})`));
 }
 /**
  * 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. Always closes with the one-time Discord footer.
+ * presentation sit in one file. Always closes with the one-time help 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();
+    helpFooterLine();
 }
 function renderHubErrorBody(err) {
     // Hints use log.hint (stderr), not log.dim (stdout): a hint belongs to the
@@ -258,11 +330,70 @@ function renderHubErrorBody(err) {
         log.hint(err.hint);
         return;
     }
+    if (err instanceof PodMovedError) {
+        // One line: what happened and what to run.
+        log.error(err.message);
+        return;
+    }
     if (!(err instanceof HubError)) {
         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
@@ -284,9 +415,15 @@ function renderHubErrorBody(err) {
         // 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 likely belongs to a different pod than the one you're calling.");
-            log.hint("Fix: pass --pod <name> to target the workspace's pod, or run `synap pods use <name>` to align your active pod + workspace. See valid workspaces with `synap orient`.");
+            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");
@@ -337,14 +474,22 @@ 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,
+            // "cli": resolveUserId asks the pod who this key acts as (see HubConfig.userId).
+            userId: "cli",
+            agentUserId: podOverride.agentUserId || undefined,
+            workspaceId: safeWs,
+            projectId: resolveProjectIdForPod(podOverride.podUrl, {}),
         };
     }
     // 1. Explicit flags (escape hatch)
@@ -365,7 +510,13 @@ export async function resolveHubConfig(opts) {
         return {
             podUrl,
             apiKey: agentOverride.apiKey,
-            userId: agentOverride.podName ?? "agent",
+            // The acting user is asked of the pod ("cli" → /users/me): an agent key
+            // acts as its linked human, and the pod 403s the agent's own id.
+            userId: "cli",
+            // The AGENT's own id, recorded with its key — for `synap worker` to
+            // recognise its own room posts (resolveAgentUserId). Never the pod
+            // profile name (it once was, and the worker resumed itself on them).
+            agentUserId: agentOverride.agentUserId || undefined,
             scopes: envScopes ? envScopes.split(",") : undefined,
         };
     }
@@ -376,7 +527,13 @@ export async function resolveHubConfig(opts) {
     const envScopes = process.env.SYNAP_KEY_SCOPES;
     const envWorkspace = process.env.SYNAP_WORKSPACE_ID;
     const envProject = process.env.SYNAP_PROJECT_ID;
-    if (envPod && envKey && envUser) {
+    // Pod + key are enough. SYNAP_USER_ID used to be required too, so a shell
+    // with just the pair (`SYNAP_POD_URL=… SYNAP_HUB_API_KEY=… synap app
+    // connect`, the documented way to try another key) fell through to "No pod
+    // configured" (2026-10-20). Unset, userId is "cli" and resolveUserId asks
+    // the pod (/users/me) — the same fallback --pod and SYNAP_AGENT use. The
+    // claude-code surface-key preference below still applies.
+    if (envPod && envKey) {
         // Surface-bound resolution guard: if this pod has a `claude-code` surface
         // key pinned to it (via `synap connect --target=claude-code`) and the
         // ambient SYNAP_HUB_API_KEY doesn't match it, the session inherited a
@@ -384,28 +541,53 @@ 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;
+        const agentUserId = preferred.agentUserId;
+        // 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. The global-config
-            // fallback is resolved AGAINST THIS POD (envPod) — never send a workspace
-            // that belongs to a different pod (the "Access denied to workspace" 403).
-            workspaceId: resolveActiveLens()?.workspaceId ||
+            agentUserId,
+            // 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, threaded exactly like workspaceId.
-            projectId: resolveActiveLens()?.projectId || envProject || getActiveProjectId(),
+            // 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,
         };
     }
@@ -413,40 +595,144 @@ 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(),
+        // "cli": resolveUserId asks the pod. A profile's agentUserId is the key's
+        // principal (a computer or agent key), not who the pod acts as.
+        userId: "cli",
+        agentUserId: config.agentUserId || undefined,
+        // 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: which client calls (`synap-cli/<version>`), 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 {
+        ...clientHeader("synap-cli"),
+        ...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;
@@ -530,9 +816,11 @@ async function hubFetchWithRetry(url, init, label, timeoutMs) {
         await acquireHubSlot();
         let res;
         try {
-            res = await fetch(url, init);
+            res = await podFetch(url, init);
         }
         catch (err) {
+            if (err instanceof PodMovedError)
+                throw err;
             throw networkError(err, url, labelMethod, labelPath, timeoutMs);
         }
         if (res.status !== 429)
@@ -548,22 +836,36 @@ async function hubFetchWithRetry(url, init, label, timeoutMs) {
         await sleep(wait);
     }
 }
-export async function hubGet(path, params, cfg) {
+export async function hubGet(path, params, cfg, 
+// Default 15s suits reads. A long-poll door (`/answers/wait`) holds the
+// request open for its own `timeoutSeconds`; its caller passes more.
+timeoutMs = 15_000) {
     const url = new URL(`${cfg.podUrl}/api/hub${path}`);
     for (const [k, v] of Object.entries(params)) {
         if (v !== undefined)
             url.searchParams.set(k, String(v));
     }
     const res = await hubFetchWithRetry(url.toString(), {
-        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
-        signal: AbortSignal.timeout(15_000),
-    }, `GET ${path}`, 15_000);
+        headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
+        signal: AbortSignal.timeout(timeoutMs),
+    }, `GET ${path}`, timeoutMs);
     if (!res.ok) {
         const body = await res.text().catch(() => "");
         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
@@ -574,14 +876,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, undefined, cfg);
+        throw hubError("POST", path, res.status, bodyText, undefined, {
+            podUrl: cfg.podUrl,
+            workspaceId: errorWorkspace(body, cfg),
+        });
     }
     return res.json();
 }
@@ -595,7 +900,7 @@ 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);
@@ -617,14 +922,16 @@ export async function hubPostMultipartRetryable(path, buildForm, cfg, timeoutMs
         const url = `${cfg.podUrl}/api/hub${path}`;
         let res;
         try {
-            res = await fetch(url, {
+            res = await podFetch(url, {
                 method: "POST",
-                headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+                headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
                 body: form,
                 signal: AbortSignal.timeout(timeoutMs),
             });
         }
         catch (err) {
+            if (err instanceof PodMovedError)
+                throw err;
             throw networkError(err, url, "POST multipart", path, timeoutMs);
         }
         if (res.status !== 429) {
@@ -649,19 +956,24 @@ export async function hubPatch(path, body, cfg) {
     const url = `${cfg.podUrl}/api/hub${path}`;
     let res;
     try {
-        res = await fetch(url, {
+        res = await podFetch(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),
         });
     }
     catch (err) {
+        if (err instanceof PodMovedError)
+            throw err;
         throw networkError(err, url, "PATCH", path, 15_000);
     }
     if (!res.ok) {
         const bodyText = await res.text().catch(() => "");
-        throw hubError("PATCH", path, res.status, bodyText, undefined, cfg);
+        throw hubError("PATCH", path, res.status, bodyText, undefined, {
+            podUrl: cfg.podUrl,
+            workspaceId: errorWorkspace(body, cfg),
+        });
     }
     return res.json();
 }
@@ -669,13 +981,15 @@ export async function hubDelete(path, cfg) {
     const url = `${cfg.podUrl}/api/hub${path}`;
     let res;
     try {
-        res = await fetch(url, {
+        res = await podFetch(url, {
             method: "DELETE",
-            headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders() },
+            headers: { Authorization: `Bearer ${cfg.apiKey}`, ...sessionHeaders(cfg) },
             signal: AbortSignal.timeout(15_000),
         });
     }
     catch (err) {
+        if (err instanceof PodMovedError)
+            throw err;
         throw networkError(err, url, "DELETE", path, 15_000);
     }
     if (!res.ok) {
@@ -696,5 +1010,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