fix: resolve HIVEMIND_WORKSPACE_ID names to ids and warn on an unknown workspace

README.md

@@ -327,7 +327,7 @@ This plugin captures session activity and stores it in your Deeplake workspace:
 |---------------------------|---------------------------|--------------------------------------------|
 | `HIVEMIND_TOKEN`          | _(none)_                  | API token (auto-set by login)              |
 | `HIVEMIND_ORG_ID`         | _(none)_                  | Organization ID (auto-set by login)        |
-| `HIVEMIND_WORKSPACE_ID`   | `default`                 | Workspace name                             |
+| `HIVEMIND_WORKSPACE_ID`   | `default`                 | Workspace name or id (`hivemind workspaces`) |
 | `HIVEMIND_API_URL`        | `https://api.deeplake.ai` | API endpoint                               |
 | `HIVEMIND_TABLE`          | `memory`                  | SQL table for summaries and virtual FS     |
 | `HIVEMIND_SESSIONS_TABLE` | `sessions`                | SQL table for per-event session capture    |

harnesses/pi/extension-source/hivemind.ts

@@ -70,6 +70,20 @@ interface Creds {
   // sees `undefined !== false` and runs the update even when the user
   // has explicitly run `hivemind autoupdate off`.
   autoupdate?: boolean;
+  // Mirrors Credentials.workspaceAliases: orgId -> lower-cased name/id -> id,
+  // learned by the other harnesses' SessionStart. The API only accepts
+  // workspace ids in its URLs; see resolveWorkspaceRef in auth-creds.ts.
+  workspaceAliases?: Record<string, Record<string, string>>;
+}
+
+// Inline copy of resolveWorkspaceRef (src/commands/auth-creds.ts) — keep in
+// lockstep. Own-property lookups only; "default" is never rewritten.
+function resolveWorkspaceRef(aliases: Creds["workspaceAliases"], orgId: string, ref: string): string {
+  if (ref === "default") return ref;
+  const org = aliases && Object.prototype.hasOwnProperty.call(aliases, orgId) ? aliases[orgId] : undefined;
+  const key = ref.toLowerCase();
+  const id = org && Object.prototype.hasOwnProperty.call(org, key) ? org[key] : undefined;
+  return typeof id === "string" ? id : ref;
 }
 
 function loadCreds(): Creds | null {
@@ -87,6 +101,7 @@ function loadCreds(): Creds | null {
       workspaceId: parsed.workspaceId ?? "default",
       userName: parsed.userName ?? "unknown",
       autoupdate: parsed.autoupdate,
+      workspaceAliases: parsed.workspaceAliases,
     };
   } catch {
     return null;
@@ -135,7 +150,8 @@ function applyDirConfig(creds: Creds, cwd: string): { creds: Creds; collect: boo
   const envWs = process.env.HIVEMIND_WORKSPACE_ID;
   const baseOrgId = envOrgId || creds.orgId;
   const baseOrgName = envOrgId ? (creds.orgName ?? envOrgId) : creds.orgName;
-  const baseWs = envWs || creds.workspaceId;
+  const rawWs = envWs || creds.workspaceId;
+  const baseWs = resolveWorkspaceRef(creds.workspaceAliases, baseOrgId, rawWs);
   const withEnv: Creds = { ...creds, orgId: baseOrgId, orgName: baseOrgName, workspaceId: baseWs };
 
   const dir = findHivemindDir(cwd || process.cwd());
@@ -144,7 +160,9 @@ function applyDirConfig(creds: Creds, cwd: string): { creds: Creds; collect: boo
   // The file may fill only fields NOT pinned by an env var.
   const orgId = envOrgId ? baseOrgId : (dir.orgId ?? baseOrgId);
   const orgName = envOrgId ? baseOrgName : (dir.orgName ?? dir.orgId ?? baseOrgName);
-  const workspaceId = envWs ? baseWs : (dir.workspaceId ?? baseWs);
+  // Resolve against the FINAL org: a `.hivemind` may route the org while the
+  // env var locks the workspace reference.
+  const workspaceId = resolveWorkspaceRef(creds.workspaceAliases, orgId, envWs ? rawWs : (dir.workspaceId ?? rawWs));
   const routed = orgId !== baseOrgId || workspaceId !== baseWs; // .hivemind changed it
   return { creds: { ...withEnv, orgId, orgName, workspaceId }, collect: true, routed };
 }

src/commands/auth-creds.ts

@@ -36,9 +36,38 @@ export interface Credentials {
   workspaceId?: string;
   apiUrl?: string;
   autoupdate?: boolean;
+  // Per-org map of a workspace reference the user typed (name or id, lower-
+  // cased) to the backend id, learned by resolveWorkspaceOverride() at
+  // SessionStart. Lets the synchronous loadConfig() in every later hook turn
+  // `HIVEMIND_WORKSPACE_ID="Data Platform Dev"` into `data-platform-dev`
+  // without a network call — the API only accepts ids in its URLs.
+  workspaceAliases?: Record<string, Record<string, string>>;
   savedAt: string;
 }
 
+// "default" is the per-org sentinel the backend resolves itself. Own-property
+// lookups only: the map is user-controlled JSON, and `__proto__` /
+// `constructor` must not read as cache hits.
+export function lookupWorkspaceAlias(
+  aliases: Record<string, Record<string, string>> | undefined,
+  orgId: string,
+  ref: string,
+): string | undefined {
+  const org = aliases && Object.prototype.hasOwnProperty.call(aliases, orgId) ? aliases[orgId] : undefined;
+  const key = ref.toLowerCase();
+  const id = org && Object.prototype.hasOwnProperty.call(org, key) ? org[key] : undefined;
+  return typeof id === "string" ? id : undefined;
+}
+
+export function resolveWorkspaceRef(
+  aliases: Record<string, Record<string, string>> | undefined,
+  orgId: string,
+  ref: string,
+): string {
+  if (ref === "default") return ref;
+  return lookupWorkspaceAlias(aliases, orgId, ref) ?? ref;
+}
+
 // Each helper avoids the existsSync-before-act anti-pattern: it has both a
 // time-of-check-to-time-of-use race and extra branches that don't add real
 // safety. Letting the fs call's own error fall into a try/catch is more

src/commands/auth-login.ts

@@ -21,7 +21,7 @@
 
 import {
   login, loadCredentials, saveCredentials, deleteCredentials, listOrgs, switchOrg,
-  listWorkspaces, switchWorkspace,
+  listWorkspaces, switchWorkspace, findWorkspace,
   inviteMember, listMembers, removeMember,
 } from "./auth.js";
 import { sessionPrune } from "./session-prune.js";
@@ -76,13 +76,12 @@ export async function runAuthCommand(args: string[]): Promise<void> {
         // org switch never happens — re-running the command then succeeds
         // cleanly instead of leaving credentials half-committed.
         const prevWs = creds.workspaceId ?? "default";
-        const lcPrev = prevWs.toLowerCase();
         const wsList = await listWorkspaces(creds.token, apiUrl, match.id);
         // Resolve to the matched workspace OBJECT, not a boolean: `workspaceId`
         // is supposed to be a canonical id but legacy creds (and the post-login
         // `"default"` sentinel) can hold a name. We need the matched object so
         // we can normalize a name-only match to the canonical id.
-        const matchedWs = wsList.find(w => w.id === prevWs || (w.name && w.name.toLowerCase() === lcPrev));
+        const matchedWs = findWorkspace(wsList, prevWs);
 
         await switchOrg(match.id, match.name);
         console.log(`Switched to org: ${match.name}`);
@@ -132,8 +131,7 @@ export async function runAuthCommand(args: string[]): Promise<void> {
         const target = args[2];
         if (!target) { console.log("Usage: workspace switch <name-or-id>"); process.exit(1); }
         const wsList = await listWorkspaces(creds.token, apiUrl, creds.orgId);
-        const lcTarget = target.toLowerCase();
-        const match = wsList.find(w => w.id === target || (w.name && w.name.toLowerCase() === lcTarget));
+        const match = findWorkspace(wsList, target);
         if (!match) {
           console.log(`Workspace not found: ${target}`);
           if (wsList.length > 0) {

src/commands/auth.ts

@@ -12,7 +12,9 @@
   loadCredentials,
   saveCredentials,
   deleteCredentials,
+  lookupWorkspaceAlias,
 } from "./auth-creds.js";
+import { findDirConfig } from "../dir-config.js";
 
 // Re-export so existing importers keep working without churn.
 export { loadCredentials, saveCredentials, deleteCredentials };
@@ -55,15 +57,15 @@
 
 // ── API Helpers ──────────────────────────────────────────────────────────────
 
-async function apiGet(path: string, token: string, apiUrl: string, orgId?: string): Promise<unknown> {
+async function apiGet(path: string, token: string, apiUrl: string, orgId?: string, signal?: AbortSignal): Promise<unknown> {
   const headers: Record<string, string> = {
     Authorization: `Bearer ${token}`,
     "Content-Type": "application/json",
     ...deeplakeClientHeader(),
     ...hivemindOsHeader(),
   };
   if (orgId) headers["X-Activeloop-Org-Id"] = orgId;
-  const resp = await fetch(`${apiUrl}${path}`, { headers });
+  const resp = await fetch(`${apiUrl}${path}`, { headers, signal });
   if (!resp.ok) throw new Error(`API ${resp.status}: ${await resp.text().catch(() => "")}`);
   return resp.json();
 }
@@ -301,8 +303,7 @@
     if (currentWs !== "default") {
       try {
         const wsList = await listWorkspaces(healed.token, apiUrl, creds.orgId);
-        const lcWs = currentWs.toLowerCase();
-        const wsMatch = wsList.find(w => w.id === currentWs || (w.name && w.name.toLowerCase() === lcWs));
+        const wsMatch = findWorkspace(wsList, currentWs);
         if (!wsMatch) {
           log(`workspace '${currentWs}' not in org ${creds.orgId} — reset to default`);
           healed.workspaceId = "default";
@@ -326,8 +327,98 @@
 
 // ── Workspace Commands ───────────────────────────────────────────────────────
 
-export async function listWorkspaces(token: string, apiUrl = DEFAULT_API_URL, orgId?: string): Promise<{ id: string; name: string }[]> {
-  const raw = await apiGet("/workspaces", token, apiUrl, orgId) as { data?: { id: string; name: string }[] } | { id: string; name: string }[];
+// An exact id always wins over a name: workspace A named "build" must not
+// shadow workspace B whose id is "build".
+export function findWorkspace(
+  wsList: { id: string; name: string }[],
+  ref: string,
+): { id: string; name: string } | undefined {
+  const lc = ref.toLowerCase();
+  return wsList.find(w => w.id === ref) ?? wsList.find(w => w.name && w.name.toLowerCase() === lc);
+}
+
+export interface WorkspaceOverrideResult {
+  creds: Credentials;
+  // User-facing line when the override names a workspace the org doesn't
+  // have. Every write would 403 and capture would silently switch itself
+  // off, so SessionStart must say it out loud.
+  warning?: string;
+}
+
+// SessionStart must never hang on this lookup; the cached alias (if any)
+// keeps working when the request is cut off.
+const WORKSPACE_LOOKUP_TIMEOUT_MS = 5_000;
+
+// The warning below lands in the model's context. A `.hivemind` is committed
+// content from a cloned repo and workspace names come from the API, so
+// neither may carry newlines, control characters, or unbounded text into it.
+export function sanitizeForContext(value: string, max = 64): string {
+  const flat = value.replace(/[\p{Cc}\p{Cf}\s]+/gu, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+// `HIVEMIND_WORKSPACE_ID` (and a `.hivemind` workspaceId) are documented as
+// workspace NAMES but the API only accepts ids in `/workspaces/{id}/...` — a
+// name gets a 403 on every query. Resolve the reference against the EFFECTIVE
+// org (env > .hivemind > login, same precedence as resolveDirConfig) and
+// persist it in creds.workspaceAliases so every later (synchronous) hook maps
+// it through loadConfig() without a round-trip. Runs every session, so a
+// rename or deletion is picked up on the next start; the cache only carries
+// the answer across hooks and network failures. Never throws.
+export async function resolveWorkspaceOverride(
+  creds: Credentials,
+  log: (msg: string) => void = () => {},
+  cwd: string = process.cwd(),
+): Promise<WorkspaceOverrideResult> {
+  const found = findDirConfig(cwd);
+  const ref = process.env.HIVEMIND_WORKSPACE_ID ?? found?.raw.workspaceId;
+  const token = process.env.HIVEMIND_TOKEN ?? creds.token;
+  if (!ref || ref === "default" || !token) return { creds };
+  const orgId = process.env.HIVEMIND_ORG_ID ?? found?.raw.orgId ?? creds.orgId;
+  const apiUrl = process.env.HIVEMIND_API_URL ?? creds.apiUrl ?? DEFAULT_API_URL;
+  const cached = lookupWorkspaceAlias(creds.workspaceAliases, orgId, ref);
+  try {
+    const wsList = await listWorkspaces(token, apiUrl, orgId, AbortSignal.timeout(WORKSPACE_LOOKUP_TIMEOUT_MS));
+    const match = findWorkspace(wsList, ref);
+    if (!match) {
+      const names = wsList.map(w => sanitizeForContext(w.name || w.id)).join(", ") || "(none)";
+      const source = process.env.HIVEMIND_WORKSPACE_ID ? "HIVEMIND_WORKSPACE_ID" : "the nearest .hivemind file";
+      log(`workspace '${ref}' not found in org ${orgId} (from ${source}${found ? `: ${found.path}` : ""})`);
+      return {
+        creds: cached ? forgetWorkspaceAlias(creds, orgId, ref) : creds,
+        warning: `Workspace '${sanitizeForContext(ref)}' (from ${source}) does not match any workspace in this org (available: ${names}); ` +
+          `capture and memory search will fail until it is fixed. Prefer \`hivemind workspace switch <name>\` over the env var.`,
+      };
+    }
+    if (match.id !== ref) log(`workspace '${ref}' resolved to id '${match.id}'`);
+    return { creds: cached === match.id ? creds : rememberWorkspaceAlias(creds, orgId, ref, match.id) };
+  } catch (e) {
+    log(`workspace resolve skipped (${(e as Error).message}); ${cached ? `using cached id '${cached}'` : "no cached id"}`);
+    return { creds };
+  }
+}
+
+// Re-read credentials right before writing: many sessions start in parallel
+// and one may have just healed the token. Only the alias map is merged in,
+// so a stale in-memory snapshot can never roll back another session's write.
+function rememberWorkspaceAlias(creds: Credentials, orgId: string, ref: string, id: string): Credentials {
+  const latest = loadCredentials() ?? creds;
+  const aliases = { ...latest.workspaceAliases, [orgId]: { ...latest.workspaceAliases?.[orgId], [ref.toLowerCase()]: id } };
+  saveCredentials({ ...latest, workspaceAliases: aliases });
+  return { ...creds, workspaceAliases: aliases };
+}
+
+function forgetWorkspaceAlias(creds: Credentials, orgId: string, ref: string): Credentials {
+  const latest = loadCredentials() ?? creds;
+  const org = { ...latest.workspaceAliases?.[orgId] };
+  delete org[ref.toLowerCase()];
+  const aliases = { ...latest.workspaceAliases, [orgId]: org };
+  saveCredentials({ ...latest, workspaceAliases: aliases });
+  return { ...creds, workspaceAliases: aliases };
+}
+
+export async function listWorkspaces(token: string, apiUrl = DEFAULT_API_URL, orgId?: string, signal?: AbortSignal): Promise<{ id: string; name: string }[]> {
+  const raw = await apiGet("/workspaces", token, apiUrl, orgId, signal) as { data?: { id: string; name: string }[] } | { id: string; name: string }[];
   const data = (raw as { data?: { id: string; name: string }[] }).data ?? (raw as { id: string; name: string }[]);
   return Array.isArray(data) ? data : [];
 }

src/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, userInfo } from "node:os";
+import { resolveWorkspaceRef } from "./commands/auth-creds.js";
 
 export interface Config {
   token: string;
@@ -18,6 +19,9 @@ export interface Config {
   docsTableName: string;
   codebaseTableName: string;
   memoryPath: string;
+  // Learned workspace name → id map (see Credentials.workspaceAliases).
+  // Optional so hand-built Config fixtures in tests keep compiling.
+  workspaceAliases?: Record<string, Record<string, string>>;
 }
 
 interface Credentials {
@@ -27,6 +31,7 @@ interface Credentials {
   userName?: string;
   workspaceId?: string;
   apiUrl?: string;
+  workspaceAliases?: Record<string, Record<string, string>>;
 }
 
 export function loadConfig(): Config | null {
@@ -53,7 +58,13 @@ export function loadConfig(): Config | null {
     orgId,
     orgName: creds?.orgName ?? orgId,
     userName: creds?.userName || userInfo().username || "unknown",
-    workspaceId: process.env.HIVEMIND_WORKSPACE_ID ?? creds?.workspaceId ?? "default",
+    // The API only accepts workspace IDS in its URLs, but the env var is
+    // documented (and typed by users) as a name. Map through the aliases
+    // SessionStart learned so a name never reaches the wire.
+    workspaceId: resolveWorkspaceRef(
+      creds?.workspaceAliases, orgId,
+      process.env.HIVEMIND_WORKSPACE_ID ?? creds?.workspaceId ?? "default",
+    ),
     apiUrl: process.env.HIVEMIND_API_URL ?? creds?.apiUrl ?? "https://api.deeplake.ai",
     tableName: process.env.HIVEMIND_TABLE ?? "memory",
     sessionsTableName: process.env.HIVEMIND_SESSIONS_TABLE ?? "sessions",
@@ -79,6 +90,7 @@ export function loadConfig(): Config | null {
     // UPDATE-or-INSERT path (which is vulnerable to UPDATE-coalescing).
     docsTableName: process.env.HIVEMIND_DOCS_TABLE ?? "hivemind_docs",
     codebaseTableName: process.env.HIVEMIND_CODEBASE_TABLE ?? "codebase",
+    workspaceAliases: creds?.workspaceAliases,
     memoryPath: process.env.HIVEMIND_MEMORY_PATH ?? join(home, ".deeplake", "memory"),
   };
 }

src/dir-config.ts

@@ -30,6 +30,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { loadConfig, type Config } from "./config.js";
+import { resolveWorkspaceRef } from "./commands/auth-creds.js";
 
 /** Committed (shared) and local (personal, gitignored) filenames, local first. */
 export const DIR_CONFIG_FILENAMES = [".hivemind.local", ".hivemind"] as const;
@@ -136,12 +137,17 @@ export function resolveDirConfig(
   if (!found) return { config: base, collect: true, found: null };
 
   const orgLocked = !!(envOverride ? envOverride.HIVEMIND_ORG_ID : process.env.HIVEMIND_ORG_ID);
-  const wsLocked = !!(envOverride ? envOverride.HIVEMIND_WORKSPACE_ID : process.env.HIVEMIND_WORKSPACE_ID);
+  const envWs = envOverride ? envOverride.HIVEMIND_WORKSPACE_ID : process.env.HIVEMIND_WORKSPACE_ID;
+  const orgId = orgLocked ? base.orgId : (found.raw.orgId ?? base.orgId);
+  // Always resolve the RAW reference against the final org: `base.workspaceId`
+  // was already mapped by loadConfig() against the login org, which is the
+  // wrong map once this file routes the org elsewhere.
+  const wsRef = envWs || found.raw.workspaceId || base.workspaceId;
   const config: Config = {
     ...base,
-    orgId: orgLocked ? base.orgId : (found.raw.orgId ?? base.orgId),
+    orgId,
     orgName: orgLocked ? base.orgName : (found.raw.orgName ?? found.raw.orgId ?? base.orgName),
-    workspaceId: wsLocked ? base.workspaceId : (found.raw.workspaceId ?? base.workspaceId),
+    workspaceId: resolveWorkspaceRef(base.workspaceAliases, orgId, wsRef),
   };
   return { config, collect: found.raw.collect !== false, found };
 }