@textcortex/zenocode 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textcortex/zenocode",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Secure, EU-hosted coding agent for TextCortex customers that runs in your terminal, edits files, runs scripts, and more.",
   "keywords": [
     "ai",

package/scripts/build-branded-opencode.mjs

@@ -237,6 +237,14 @@ async function packPackage(packageDir) {
   return path.join(packageDir, tarballs[tarballs.length - 1]);
 }
 
+export function buildPublishCommandArgs(tarballPath, { tag } = {}) {
+  const args = ["publish", tarballPath, "--access", "public"];
+  if (tag) {
+    args.push("--tag", tag);
+  }
+  return args;
+}
+
 async function publishTarballIfNeeded(packageName, version, tarballPath, cwd) {
   if (!publishEnabled) return { published: false, skipped: false };
 
@@ -254,11 +262,7 @@ async function publishTarballIfNeeded(packageName, version, tarballPath, cwd) {
   }
 
   const npmCommand = _command("npm");
-  await run(
-    npmCommand,
-    ["publish", tarballPath, "--access", "public", "--tag", publishTag, "--provenance"],
-    { cwd },
-  );
+  await run(npmCommand, buildPublishCommandArgs(tarballPath, { tag: publishTag }), { cwd });
   return { published: true, skipped: false };
 }
 

package/scripts/build-branded-opencode.test.mjs

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import {
+  buildPublishCommandArgs,
   buildWrapperBinMap,
   mapBrandedBinaryPackageName,
 } from "./build-branded-opencode.mjs";
@@ -23,3 +24,23 @@ test("buildWrapperBinMap includes package, opencode, and zenocode entrypoints",
     zenocode: "./bin/opencode",
   });
 });
+
+test("buildPublishCommandArgs omits npm provenance for runtime tarball publishing", () => {
+  assert.deepEqual(buildPublishCommandArgs("package.tgz", { tag: "latest" }), [
+    "publish",
+    "package.tgz",
+    "--access",
+    "public",
+    "--tag",
+    "latest",
+  ]);
+});
+
+test("buildPublishCommandArgs omits tag arguments when no tag is provided", () => {
+  assert.deepEqual(buildPublishCommandArgs("package.tgz"), [
+    "publish",
+    "package.tgz",
+    "--access",
+    "public",
+  ]);
+});

package/scripts/run-zenocode.mjs

@@ -26,10 +26,12 @@ const legacyRuntimeCredentialsPath = path.join(
   legacyRuntimeDir,
   "credentials.json",
 );
+const logoutMarkerPath = path.join(runtimeDir, "logout-marker.json");
 const modelsPath = path.join(runtimeDir, "models.json");
 const configPath = path.join(runtimeDir, "opencode.jsonc");
 const localBaseUrlDefault = "http://127.0.0.1:8080";
 const cloudBaseUrlDefault = "https://api.textcortex.com";
+const localBaseUrlFlags = new Set(["--local", "--localhost"]);
 
 const providerID = "textcortex";
 const configuredOpencodePackage =
@@ -45,8 +47,8 @@ const opencodeBinaryPath =
   process.env.ZENOCODE_OPENCODE_BIN_PATH ||
   process.env.CODECORTEX_OPENCODE_BIN_PATH ||
   "";
-const oauthInitiatePath = "/internal/v1/fastapi/codecortex/oauth2/initiate";
-const oauthTokenPath = "/internal/v1/fastapi/codecortex/oauth2/token";
+const oauthInitiatePath = "/internal/v1/fastapi/zenocode/oauth2/initiate";
+const oauthTokenPath = "/internal/v1/fastapi/zenocode/oauth2/token";
 const defaultOrder = [
   "kimi-k2-5-thinking",
   "glm-5",
@@ -63,12 +65,15 @@ const devCredentialFiles =
         path.join(process.cwd(), ".credentials.json"),
       ]
     : [];
-const credentialFiles = [
+const runtimeCredentialFiles = [
   runtimeCredentialsPath,
   legacyRuntimeCredentialsPath,
+].filter((value, index, values) => values.indexOf(value) === index);
+const fallbackCredentialFiles = [
   path.join(os.homedir(), ".credentials.json"),
   ...devCredentialFiles,
 ].filter((value, index, values) => values.indexOf(value) === index);
+const credentialFiles = [...runtimeCredentialFiles, ...fallbackCredentialFiles];
 
 function _decodeEscapedLogoLine(line) {
   return line.replace(/\\u([0-9a-fA-F]{4})/g, (_, codePoint) =>
@@ -116,6 +121,28 @@ export async function writePrivateJsonFile(filePath, payload) {
   }
 }
 
+async function clearLogoutMarker() {
+  try {
+    await fs.unlink(logoutMarkerPath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function writeLogoutMarker() {
+  await ensurePrivateDirectory(path.dirname(logoutMarkerPath));
+  await fs.writeFile(
+    logoutMarkerPath,
+    `${JSON.stringify({ logged_out_at: new Date().toISOString() }, null, 2)}\n`,
+    { encoding: "utf-8", mode: privateFileMode },
+  );
+  if (process.platform !== "win32") {
+    await fs.chmod(logoutMarkerPath, privateFileMode);
+  }
+}
+
 function extractTokenFromCredentialPayload(parsed) {
   if (!parsed) return null;
   if (typeof parsed?.access_token === "string" && parsed.access_token) {
@@ -150,13 +177,191 @@ function extractBaseUrlFromCredentialPayload(parsed) {
   return null;
 }
 
+export function resolveLoginSuccessIdentifier(tokenData) {
+  const authId =
+    typeof tokenData?.auth_id === "string" ? tokenData.auth_id.trim() : "";
+  return authId || "unknown";
+}
+
+function _isCredentialEntry(entry) {
+  return Boolean(
+    entry &&
+      typeof entry === "object" &&
+      !Array.isArray(entry) &&
+      (typeof entry.access_token === "string" ||
+        typeof entry.refresh_token === "string"),
+  );
+}
+
+function _selectCredentialEntry(parsed) {
+  if (_isCredentialEntry(parsed)) {
+    return {
+      entry: parsed,
+      apply(updatedEntry) {
+        return { ...parsed, ...updatedEntry };
+      },
+    };
+  }
+
+  if (Array.isArray(parsed?.accounts)) {
+    const index = parsed.accounts.findIndex((entry) => _isCredentialEntry(entry));
+    if (index !== -1) {
+      return {
+        entry: parsed.accounts[index],
+        apply(updatedEntry) {
+          const accounts = [...parsed.accounts];
+          accounts[index] = { ...accounts[index], ...updatedEntry };
+          return { ...parsed, accounts };
+        },
+      };
+    }
+  }
+
+  if (Array.isArray(parsed)) {
+    const index = parsed.findIndex((entry) => _isCredentialEntry(entry));
+    if (index !== -1) {
+      return {
+        entry: parsed[index],
+        apply(updatedEntry) {
+          const next = [...parsed];
+          next[index] = { ...next[index], ...updatedEntry };
+          return next;
+        },
+      };
+    }
+  }
+
+  return null;
+}
+
+async function loadStoredCredentialState(filePath) {
+  const parsed = await readJson(filePath);
+  const selected = _selectCredentialEntry(parsed);
+  if (!selected) {
+    return null;
+  }
+  return {
+    filePath,
+    parsed,
+    entry: selected.entry,
+    apply: selected.apply,
+  };
+}
+
+async function resolveCredentialFiles() {
+  if (await _pathExists(logoutMarkerPath)) {
+    return runtimeCredentialFiles;
+  }
+  return credentialFiles;
+}
+
+async function findStoredCredentialState() {
+  for (const filePath of await resolveCredentialFiles()) {
+    const state = await loadStoredCredentialState(filePath);
+    if (state) {
+      return state;
+    }
+  }
+  return null;
+}
+
+function _decodeBase64Url(value) {
+  const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padding = "=".repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(`${normalized}${padding}`, "base64").toString("utf-8");
+}
+
+function extractAccessTokenExpiry(accessToken) {
+  try {
+    const [, payloadSegment] = String(accessToken || "").split(".");
+    if (!payloadSegment) return null;
+    const payload = JSON.parse(_decodeBase64Url(payloadSegment));
+    const exp = Number(payload?.exp);
+    if (!Number.isFinite(exp) || exp <= 0) {
+      return null;
+    }
+    return new Date(exp * 1000).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+async function exchangeRefreshToken(baseUrl, refreshToken) {
+  const refreshUrl = new URL("/auth/token/refresh/", baseUrl).toString();
+  const { response, payload, text } = await requestJson(refreshUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${refreshToken}`,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const message = extractErrorMessage(payload, text || "request failed");
+    throw new Error(`Token refresh failed (${response.status}): ${message}`);
+  }
+
+  const data = unwrapData(payload);
+  if (!data?.access_token) {
+    throw new Error("Token refresh failed: invalid response payload.");
+  }
+
+  return data;
+}
+
+async function refreshStoredCredentials(baseUrl) {
+  const state = await findStoredCredentialState();
+  const refreshToken =
+    typeof state?.entry?.refresh_token === "string" && state.entry.refresh_token
+      ? state.entry.refresh_token
+      : null;
+
+  if (!state || !refreshToken) {
+    throw new Error("No refresh token available.");
+  }
+
+  const resolvedBaseUrl =
+    process.env.TEXTCORTEX_BASE_URL ||
+    (typeof state.entry.base_url === "string" && state.entry.base_url) ||
+    baseUrl;
+  if (!resolvedBaseUrl) {
+    throw new Error("Missing base URL for token refresh.");
+  }
+
+  const refreshed = await exchangeRefreshToken(resolvedBaseUrl, refreshToken);
+  const updatedEntry = {
+    ...state.entry,
+    base_url: resolvedBaseUrl,
+    access_token: refreshed.access_token,
+    refresh_token:
+      typeof refreshed.refresh_token === "string" && refreshed.refresh_token
+        ? refreshed.refresh_token
+        : refreshToken,
+    auth_id: refreshed.auth_id || state.entry.auth_id || null,
+    email: refreshed.email || state.entry.email || null,
+    expires_at:
+      refreshed.expires_at ||
+      extractAccessTokenExpiry(refreshed.access_token) ||
+      state.entry.expires_at ||
+      null,
+    updated_at: new Date().toISOString(),
+  };
+  await writePrivateJsonFile(state.filePath, state.apply(updatedEntry));
+
+  return {
+    token: updatedEntry.access_token,
+    baseUrl: resolvedBaseUrl,
+  };
+}
+
 async function resolveToken() {
   const envToken = process.env.TEXTCORTEX_API_KEY || process.env.TEXTCORTEX_API_TOKEN;
   if (envToken) return envToken;
 
-  for (const filePath of credentialFiles) {
-    const parsed = await readJson(filePath);
-    const token = extractTokenFromCredentialPayload(parsed);
+  for (const filePath of await resolveCredentialFiles()) {
+    const state = await loadStoredCredentialState(filePath);
+    const token = extractTokenFromCredentialPayload(state?.parsed);
     if (token) return token;
   }
 
@@ -195,7 +400,7 @@ export function buildOpenCodeConfig({ baseUrl, providerID, model, smallModel })
       [providerID]: {
         name: "Zenocode",
         options: {
-          baseURL: new URL("/internal/v1/fastapi/codecortex/v1", baseUrl).toString(),
+          baseURL: new URL("/internal/v1/fastapi/zenocode/v1", baseUrl).toString(),
         },
       },
       // Older fallback opencode-ai builds can load the Codex auth plugin when
@@ -249,7 +454,7 @@ async function requestJson(url, init) {
 }
 
 async function prepareRuntime(baseUrl, token) {
-  const modelsUrl = new URL("/internal/v1/fastapi/codecortex/models/api.json", baseUrl).toString();
+  const modelsUrl = new URL("/internal/v1/fastapi/zenocode/models/api.json", baseUrl).toString();
   const { response, payload, text } = await requestJson(modelsUrl, {
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
   });
@@ -288,6 +493,15 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+export function hasLocalBaseUrlFlag(args = []) {
+  const normalizedArgs = args[0] === "--" ? args.slice(1) : args;
+  return normalizedArgs.some((arg) => localBaseUrlFlags.has(arg));
+}
+
+function stripLocalBaseUrlFlags(args = []) {
+  return args.filter((arg) => !localBaseUrlFlags.has(arg));
+}
+
 async function parseLoginArgs(args) {
   const normalizedArgs = args[0] === "--" ? args.slice(1) : args;
   let emailHint = process.env.TEXTCORTEX_LOGIN_EMAIL || null;
@@ -295,6 +509,9 @@ async function parseLoginArgs(args) {
 
   for (let idx = 0; idx < normalizedArgs.length; idx += 1) {
     const arg = normalizedArgs[idx];
+    if (localBaseUrlFlags.has(arg)) {
+      continue;
+    }
     if (arg === "--no-launch-browser") {
       launchBrowser = false;
       continue;
@@ -311,6 +528,7 @@ async function parseLoginArgs(args) {
     if (arg === "--help" || arg === "-h") {
       console.log("Zenocode login options:");
       console.log("  --email <address>      Optional email hint for tenant/SSO routing");
+      console.log(`  --local                Use the local FastAPI backend at ${localBaseUrlDefault}`);
       console.log("  --no-launch-browser    Do not open browser automatically");
       process.exit(0);
     }
@@ -339,10 +557,29 @@ function isLoginRouteNotFoundError(error) {
   return message.includes("Login initiate failed (404)");
 }
 
+export function shouldFallbackLoginToCloud({ baseUrl, hasExplicitBaseUrl, error }) {
+  if (hasExplicitBaseUrl || baseUrl !== localBaseUrlDefault) {
+    return false;
+  }
+
+  return isFetchFailedError(error) || isLoginRouteNotFoundError(error);
+}
+
+export function resolveTextCortexBaseUrl({
+  envBaseUrl,
+  storedBaseUrl,
+  preferLocalhost = false,
+} = {}) {
+  if (preferLocalhost) {
+    return localBaseUrlDefault;
+  }
+  return envBaseUrl || storedBaseUrl || cloudBaseUrlDefault;
+}
+
 function _loginConnectivityHelp(baseUrl) {
   return [
     `Cannot reach Zenocode auth endpoint at ${baseUrl}.`,
-    "Run local backend FastAPI (`cd backend && uv run dev_fastapi`) or set TEXTCORTEX_BASE_URL to a reachable backend API.",
+    `Set TEXTCORTEX_BASE_URL to ${cloudBaseUrlDefault} or, for local development, run local backend FastAPI (\`cd backend && uv run dev_fastapi\`).`,
   ].join(" ");
 }
 
@@ -441,24 +678,30 @@ async function saveRuntimeCredentials(baseUrl, tokenData) {
     refresh_token: tokenData.refresh_token,
     auth_id: tokenData.auth_id || null,
     email: tokenData.email || null,
-    expires_at: tokenData.expires_at || null,
+    expires_at:
+      tokenData.expires_at ||
+      extractAccessTokenExpiry(tokenData.access_token) ||
+      null,
     updated_at: new Date().toISOString(),
   };
   await writePrivateJsonFile(runtimeCredentialsPath, payload);
+  await clearLogoutMarker();
 }
 
-async function runLoginCommand(baseUrl, args) {
+async function runLoginCommand(baseUrl, args, options = {}) {
+  const preferLocalhost = options.preferLocalhost === true;
   const { emailHint, launchBrowser } = await parseLoginArgs(args);
-  let resolvedBaseUrl = baseUrl;
+  let resolvedBaseUrl = preferLocalhost ? localBaseUrlDefault : baseUrl;
   let login;
   try {
     login = await initiateDeviceLogin(resolvedBaseUrl, emailHint);
   } catch (error) {
-    if (
-      !process.env.TEXTCORTEX_BASE_URL &&
-      resolvedBaseUrl === localBaseUrlDefault &&
-      isFetchFailedError(error)
-    ) {
+    if (shouldFallbackLoginToCloud({
+      baseUrl: resolvedBaseUrl,
+      hasExplicitBaseUrl:
+        Boolean(process.env.TEXTCORTEX_BASE_URL) || preferLocalhost,
+      error,
+    })) {
       resolvedBaseUrl = cloudBaseUrlDefault;
       console.log(
         `Local backend not reachable at ${localBaseUrlDefault}. Falling back to ${cloudBaseUrlDefault}.`,
@@ -503,17 +746,14 @@ async function runLoginCommand(baseUrl, args) {
   );
   await saveRuntimeCredentials(resolvedBaseUrl, tokenData);
 
-  const account = tokenData.email || tokenData.auth_id || "unknown";
+  const account = resolveLoginSuccessIdentifier(tokenData);
   console.log(`Login successful for ${account}.`);
   console.log(`Credentials saved to ${runtimeCredentialsPath}`);
 }
 
 async function runLogoutCommand() {
   let removedAnyCredentials = false;
-  for (const credentialsPath of [
-    runtimeCredentialsPath,
-    legacyRuntimeCredentialsPath,
-  ].filter((value, index, values) => values.indexOf(value) === index)) {
+  for (const credentialsPath of runtimeCredentialFiles) {
     try {
       await fs.unlink(credentialsPath);
       removedAnyCredentials = true;
@@ -525,8 +765,15 @@ async function runLogoutCommand() {
     }
   }
 
-  if (removedAnyCredentials) {
-    console.log("Zenocode credentials removed.");
+  const fallbackCredentialsPresent = (
+    await Promise.all(
+      fallbackCredentialFiles.map((credentialsPath) => _pathExists(credentialsPath)),
+    )
+  ).some(Boolean);
+
+  if (removedAnyCredentials || fallbackCredentialsPresent) {
+    await writeLogoutMarker();
+    console.log("Zenocode session cleared.");
     return;
   }
 
@@ -915,6 +1162,20 @@ async function _ensurePatchedOpencodeDlxBinaries(packageName, runner, options) {
   return _preparePinnedRuntimeBinary(binaryCandidates);
 }
 
+/**
+ * Mirror direct runtime launches so fallback package runners stay interactive.
+ */
+export function buildPackageLauncherChildOptions(options, pinnedRuntimePath) {
+  return {
+    ...options,
+    stdio: "inherit",
+    env: {
+      ...(options.env || {}),
+      ...(pinnedRuntimePath ? { OPENCODE_BIN_PATH: pinnedRuntimePath } : {}),
+    },
+  };
+}
+
 async function runPackageLauncher(packageName, args, options) {
   const runners = [
     { command: _runnerCommand("pnpm"), args: ["dlx", packageName, ...args] },
@@ -932,13 +1193,7 @@ async function runPackageLauncher(packageName, args, options) {
         }
       }
 
-      const childOptions = {
-        ...options,
-        env: {
-          ...(options.env || {}),
-          ...(pinnedRuntimePath ? { OPENCODE_BIN_PATH: pinnedRuntimePath } : {}),
-        },
-      };
+      const childOptions = buildPackageLauncherChildOptions(options, pinnedRuntimePath);
 
       const result = await runChild(runner.command, runner.args, childOptions);
       if (result.signal) {
@@ -1005,14 +1260,20 @@ export async function runRuntimeWithSessionRecovery({
   token,
   childOptions,
   canAutoLoginRuntime,
+  preferLocalhost = false,
+  refreshTokenFn = refreshStoredCredentials,
   runLogin = runLoginCommand,
   resolveTokenFn = resolveToken,
   resolveStoredBaseUrlFn = resolveStoredBaseUrl,
   prepareRuntimeFn = prepareRuntime,
   launchRuntimeFn,
+  maxRecoveryAttempts = 3,
+  recoveryDelayMs = 500,
+  sleepFn = sleep,
 }) {
   let activeBaseUrl = baseUrl;
   let activeToken = token;
+  let recoveryAttempts = 0;
 
   while (true) {
     const result = await launchRuntimeFn({
@@ -1031,15 +1292,51 @@ export async function runRuntimeWithSessionRecovery({
       return result;
     }
 
-    if (!canAutoLoginRuntime) {
-      return result;
+    if (recoveryAttempts >= maxRecoveryAttempts) {
+      throw new Error(
+        `Zenocode session recovery failed after ${maxRecoveryAttempts} attempts. Run \`zenocode login\` and try again.`,
+      );
+    }
+    recoveryAttempts += 1;
+
+    try {
+      const refreshed = await refreshTokenFn(activeBaseUrl);
+      activeToken = refreshed.token;
+      activeBaseUrl = refreshed.baseUrl;
+      await prepareRuntimeFn(activeBaseUrl, activeToken);
+      const retryDelayMs = Math.min(
+        Math.max(recoveryDelayMs, 0) * recoveryAttempts,
+        3_000,
+      );
+      if (retryDelayMs > 0) {
+        await sleepFn(retryDelayMs);
+      }
+      continue;
+    } catch {
+      if (!canAutoLoginRuntime) {
+        return result;
+      }
     }
 
     console.log("Zenocode session expired. Starting login flow...\n");
-    await runLogin(activeBaseUrl, buildAutoLoginArgs());
+    await runLogin(activeBaseUrl, buildAutoLoginArgs({ preferLocalhost }), {
+      preferLocalhost,
+    });
     activeToken = await resolveTokenFn();
-    activeBaseUrl = process.env.TEXTCORTEX_BASE_URL || (await resolveStoredBaseUrlFn()) || activeBaseUrl;
+    activeBaseUrl =
+      resolveTextCortexBaseUrl({
+        envBaseUrl: process.env.TEXTCORTEX_BASE_URL,
+        storedBaseUrl: await resolveStoredBaseUrlFn(),
+        preferLocalhost,
+      }) || activeBaseUrl;
     await prepareRuntimeFn(activeBaseUrl, activeToken);
+    const retryDelayMs = Math.min(
+      Math.max(recoveryDelayMs, 0) * recoveryAttempts,
+      3_000,
+    );
+    if (retryDelayMs > 0) {
+      await sleepFn(retryDelayMs);
+    }
   }
 }
 
@@ -1112,11 +1409,18 @@ function maybeRenderBanner(args) {
   console.log(`${buildZenocodeBanner()}\n`);
 }
 
-function buildAutoLoginArgs() {
-  return process.env.ZENOCODE_AUTO_LOGIN_NO_BROWSER === "1" ||
+function buildAutoLoginArgs({ preferLocalhost = false } = {}) {
+  const loginArgs = [];
+  if (preferLocalhost) {
+    loginArgs.push("--local");
+  }
+  if (
+    process.env.ZENOCODE_AUTO_LOGIN_NO_BROWSER === "1" ||
     process.env.CODECORTEX_AUTO_LOGIN_NO_BROWSER === "1"
-    ? ["--no-launch-browser"]
-    : [];
+  ) {
+    loginArgs.push("--no-launch-browser");
+  }
+  return loginArgs;
 }
 
 function isMissingTokenError(error) {
@@ -1189,7 +1493,8 @@ function shouldAttemptAutoLogin(error, args) {
   return canAutoLogin(args);
 }
 
-async function resolveTokenWithAutoLogin(baseUrl, args) {
+async function resolveTokenWithAutoLogin(baseUrl, args, options = {}) {
+  const preferLocalhost = options.preferLocalhost === true;
   try {
     const token = await resolveToken();
     return { token, baseUrl };
@@ -1199,14 +1504,21 @@ async function resolveTokenWithAutoLogin(baseUrl, args) {
     }
 
     console.log("No local Zenocode credentials found. Starting login flow...\n");
-    await runLoginCommand(baseUrl, buildAutoLoginArgs());
+    await runLoginCommand(baseUrl, buildAutoLoginArgs({ preferLocalhost }), {
+      preferLocalhost,
+    });
     const token = await resolveToken();
-    const persistedBaseUrl = process.env.TEXTCORTEX_BASE_URL || (await resolveStoredBaseUrl()) || baseUrl;
+    const persistedBaseUrl = resolveTextCortexBaseUrl({
+      envBaseUrl: process.env.TEXTCORTEX_BASE_URL,
+      storedBaseUrl: await resolveStoredBaseUrl(),
+      preferLocalhost,
+    });
     return { token, baseUrl: persistedBaseUrl };
   }
 }
 
-async function prepareRuntimeWithAutoLogin(baseUrl, token, args) {
+async function prepareRuntimeWithAutoLogin(baseUrl, token, args, options = {}) {
+  const preferLocalhost = options.preferLocalhost === true;
   try {
     const model = await prepareRuntime(baseUrl, token);
     return { model, token, baseUrl };
@@ -1214,14 +1526,31 @@ async function prepareRuntimeWithAutoLogin(baseUrl, token, args) {
     if (!isExpiredSessionError(error)) {
       throw error;
     }
-    if (!canAutoLogin(args)) {
-      throw new Error("Zenocode session expired. Run `zenocode login` and try again.");
+
+    try {
+      const refreshed = await refreshStoredCredentials(baseUrl);
+      const model = await prepareRuntime(refreshed.baseUrl, refreshed.token);
+      return {
+        model,
+        token: refreshed.token,
+        baseUrl: refreshed.baseUrl,
+      };
+    } catch {
+      if (!canAutoLogin(args)) {
+        throw new Error("Zenocode session expired. Run `zenocode login` and try again.");
+      }
     }
 
     console.log("Zenocode session expired. Starting login flow...\n");
-    await runLoginCommand(baseUrl, buildAutoLoginArgs());
+    await runLoginCommand(baseUrl, buildAutoLoginArgs({ preferLocalhost }), {
+      preferLocalhost,
+    });
     const refreshedToken = await resolveToken();
-    const refreshedBaseUrl = process.env.TEXTCORTEX_BASE_URL || (await resolveStoredBaseUrl()) || baseUrl;
+    const refreshedBaseUrl = resolveTextCortexBaseUrl({
+      envBaseUrl: process.env.TEXTCORTEX_BASE_URL,
+      storedBaseUrl: await resolveStoredBaseUrl(),
+      preferLocalhost,
+    });
     const model = await prepareRuntime(refreshedBaseUrl, refreshedToken);
     return { model, token: refreshedToken, baseUrl: refreshedBaseUrl };
   }
@@ -1238,12 +1567,18 @@ async function main() {
     passthrough.shift();
   }
 
+  const preferLocalhost = hasLocalBaseUrlFlag(passthrough);
+  const runtimeArgs = stripLocalBaseUrlFlags(passthrough);
   const storedBaseUrl = await resolveStoredBaseUrl();
-  const baseUrl = process.env.TEXTCORTEX_BASE_URL || storedBaseUrl || localBaseUrlDefault;
-  const subcommand = passthrough[0];
+  const baseUrl = resolveTextCortexBaseUrl({
+    envBaseUrl: process.env.TEXTCORTEX_BASE_URL,
+    storedBaseUrl,
+    preferLocalhost,
+  });
+  const subcommand = runtimeArgs[0];
 
   if (subcommand === "login") {
-    await runLoginCommand(baseUrl, passthrough.slice(1));
+    await runLoginCommand(baseUrl, runtimeArgs.slice(1), { preferLocalhost });
     return;
   }
 
@@ -1252,12 +1587,15 @@ async function main() {
     return;
   }
 
-  maybeRenderBanner(passthrough);
-  const tokenResolution = await resolveTokenWithAutoLogin(baseUrl, passthrough);
+  maybeRenderBanner(runtimeArgs);
+  const tokenResolution = await resolveTokenWithAutoLogin(baseUrl, runtimeArgs, {
+    preferLocalhost,
+  });
   const runtime = await prepareRuntimeWithAutoLogin(
     tokenResolution.baseUrl,
     tokenResolution.token,
-    passthrough,
+    runtimeArgs,
+    { preferLocalhost },
   );
   const token = runtime.token;
   const model = runtime.model;
@@ -1274,14 +1612,15 @@ async function main() {
       TEXTCORTEX_API_KEY: token,
     },
   };
-  const monitorRuntimeSession = canAutoLogin(passthrough);
+  const monitorRuntimeSession = canAutoLogin(runtimeArgs);
 
   if (opencodeBinaryPath) {
     const result = await runRuntimeWithSessionRecovery({
-      args: passthrough,
+      args: runtimeArgs,
       baseUrl: runtime.baseUrl,
       token,
       childOptions,
+      preferLocalhost,
       canAutoLoginRuntime: monitorRuntimeSession,
       launchRuntimeFn: ({ args, childOptions }) =>
         runRuntimeBinary(opencodeBinaryPath, args, childOptions, monitorRuntimeSession),
@@ -1294,10 +1633,11 @@ async function main() {
   const pinnedRuntimePath = await resolvePinnedRuntimeBinary(launchPackage, childOptions);
   if (pinnedRuntimePath) {
     const result = await runRuntimeWithSessionRecovery({
-      args: passthrough,
+      args: runtimeArgs,
       baseUrl: runtime.baseUrl,
       token,
       childOptions,
+      preferLocalhost,
       canAutoLoginRuntime: monitorRuntimeSession,
       launchRuntimeFn: ({ args, childOptions }) =>
         runRuntimeBinary(pinnedRuntimePath, args, childOptions, monitorRuntimeSession),
@@ -1305,7 +1645,7 @@ async function main() {
     exitWithChildResult(result);
     return;
   }
-  await runPackageLauncher(launchPackage, passthrough, childOptions);
+  await runPackageLauncher(launchPackage, runtimeArgs, childOptions);
 }
 
 const resolveExecutablePath = (value) => {

package/scripts/run-zenocode.test.mjs

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import http from "node:http";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -10,10 +11,15 @@ import {
 } from "./branding-patch.mjs";
 import {
   buildOpenCodeConfig,
+  buildPackageLauncherChildOptions,
   canRecoverRuntimeSessionFromTranscript,
   buildZenocodeBanner,
   chooseDefaults,
+  hasLocalBaseUrlFlag,
+  resolveLoginSuccessIdentifier,
+  resolveTextCortexBaseUrl,
   runRuntimeWithSessionRecovery,
+  shouldFallbackLoginToCloud,
   writePrivateJsonFile,
 } from "./run-zenocode.mjs";
 
@@ -30,6 +36,65 @@ test("chooseDefaults prefers kimi k2.5 thinking for Zenocode", () => {
   });
 });
 
+test("resolveTextCortexBaseUrl defaults to the cloud API for packaged usage", () => {
+  assert.equal(
+    resolveTextCortexBaseUrl({
+      envBaseUrl: "",
+      storedBaseUrl: null,
+    }),
+    "https://api.textcortex.com",
+  );
+});
+
+test("resolveTextCortexBaseUrl prefers the explicit env var over stored credentials", () => {
+  assert.equal(
+    resolveTextCortexBaseUrl({
+      envBaseUrl: "https://staging.textcortex.com",
+      storedBaseUrl: "http://127.0.0.1:8080",
+    }),
+    "https://staging.textcortex.com",
+  );
+});
+
+test("resolveTextCortexBaseUrl prefers localhost when the local flag is enabled", () => {
+  assert.equal(
+    resolveTextCortexBaseUrl({
+      envBaseUrl: "https://staging.textcortex.com",
+      storedBaseUrl: "https://api.textcortex.com",
+      preferLocalhost: true,
+    }),
+    "http://127.0.0.1:8080",
+  );
+});
+
+test("hasLocalBaseUrlFlag detects localhost flags", () => {
+  assert.equal(hasLocalBaseUrlFlag(["login", "--local"]), true);
+  assert.equal(hasLocalBaseUrlFlag(["--localhost", "run"]), true);
+  assert.equal(hasLocalBaseUrlFlag(["run", "--help"]), false);
+});
+
+test("shouldFallbackLoginToCloud retries the cloud API when the local auth route returns 404", () => {
+  assert.equal(
+    shouldFallbackLoginToCloud({
+      baseUrl: "http://127.0.0.1:8080",
+      hasExplicitBaseUrl: false,
+      error: new Error("Login initiate failed (404): not found"),
+    }),
+    true,
+  );
+});
+
+test("shouldFallbackLoginToCloud does not override an explicit base URL", () => {
+  assert.equal(
+    shouldFallbackLoginToCloud({
+      baseUrl: "http://127.0.0.1:8080",
+      hasExplicitBaseUrl: true,
+      error: new Error("fetch failed"),
+    }),
+    false,
+  );
+});
+
 test("buildOpenCodeConfig includes an openai stub for fallback runtime auth plugins", () => {
   const config = buildOpenCodeConfig({
     baseUrl: "http://127.0.0.1:8080",
@@ -44,6 +109,23 @@ test("buildOpenCodeConfig includes an openai stub for fallback runtime auth plug
   assert.deepEqual(config.provider.openai.models, {});
 });
 
+test("buildPackageLauncherChildOptions keeps fallback package launchers attached to the terminal", () => {
+  const childOptions = buildPackageLauncherChildOptions(
+    {
+      cwd: "/tmp/zenocode",
+      env: { TEXTCORTEX_API_KEY: "token-1" },
+    },
+    "/tmp/zenocode-runtime",
+  );
+
+  assert.equal(childOptions.stdio, "inherit");
+  assert.equal(childOptions.cwd, "/tmp/zenocode");
+  assert.deepEqual(childOptions.env, {
+    TEXTCORTEX_API_KEY: "token-1",
+    OPENCODE_BIN_PATH: "/tmp/zenocode-runtime",
+  });
+});
+
 test("buildZenocodeBanner renders block logo art instead of plain text", () => {
   const banner = buildZenocodeBanner();
 
@@ -117,6 +199,22 @@ test("canRecoverRuntimeSessionFromTranscript detects expired session output", ()
   assert.equal(canRecoverRuntimeSessionFromTranscript(transcript), true);
 });
 
+test("resolveLoginSuccessIdentifier avoids email fallback", () => {
+  assert.equal(
+    resolveLoginSuccessIdentifier({
+      auth_id: "auth_123",
+      email: "user@example.com",
+    }),
+    "auth_123",
+  );
+  assert.equal(
+    resolveLoginSuccessIdentifier({
+      email: "user@example.com",
+    }),
+    "unknown",
+  );
+});
+
 test("runRuntimeWithSessionRecovery reruns login after runtime session expiry", async () => {
   const events = [];
   let launchCount = 0;
@@ -130,6 +228,10 @@ test("runRuntimeWithSessionRecovery reruns login after runtime session expiry",
       env: {},
     },
     canAutoLoginRuntime: true,
+    refreshTokenFn: async (baseUrl) => {
+      events.push(["refresh", baseUrl]);
+      throw new Error("refresh failed");
+    },
     runLogin: async (baseUrl, loginArgs) => {
       events.push(["login", baseUrl, loginArgs]);
     },
@@ -157,6 +259,7 @@ test("runRuntimeWithSessionRecovery reruns login after runtime session expiry",
 
   assert.deepEqual(events, [
     ["launch", 1, "token-1"],
+    ["refresh", "http://127.0.0.1:8080"],
     ["login", "http://127.0.0.1:8080", []],
     ["resolve-token"],
     ["resolve-base-url"],
@@ -166,11 +269,294 @@ test("runRuntimeWithSessionRecovery reruns login after runtime session expiry",
   assert.deepEqual(result, { code: 0, signal: null, expiredSession: false });
 });
 
-test("logout removes legacy credential fallbacks as well as Zenocode credentials", async (t) => {
+test("runRuntimeWithSessionRecovery refreshes stored credentials before forcing login", async () => {
+  const events = [];
+  let launchCount = 0;
+
+  const result = await runRuntimeWithSessionRecovery({
+    args: ["run"],
+    baseUrl: "http://127.0.0.1:8080",
+    token: "token-1",
+    childOptions: {
+      cwd: process.cwd(),
+      env: {},
+    },
+    canAutoLoginRuntime: true,
+    refreshTokenFn: async (baseUrl) => {
+      events.push(["refresh", baseUrl]);
+      return {
+        token: "token-2",
+        baseUrl: "https://api.textcortex.com",
+      };
+    },
+    runLogin: async () => {
+      throw new Error("login should not be called");
+    },
+    prepareRuntimeFn: async (baseUrl, token) => {
+      events.push(["prepare", baseUrl, token]);
+      return "kimi-k2-5-thinking";
+    },
+    launchRuntimeFn: async ({ childOptions }) => {
+      launchCount += 1;
+      events.push(["launch", launchCount, childOptions.env.TEXTCORTEX_API_KEY]);
+      if (launchCount === 1) {
+        return { expiredSession: true };
+      }
+      return { code: 0, signal: null, expiredSession: false };
+    },
+  });
+
+  assert.deepEqual(events, [
+    ["launch", 1, "token-1"],
+    ["refresh", "http://127.0.0.1:8080"],
+    ["prepare", "https://api.textcortex.com", "token-2"],
+    ["launch", 2, "token-2"],
+  ]);
+  assert.deepEqual(result, { code: 0, signal: null, expiredSession: false });
+});
+
+test("runRuntimeWithSessionRecovery preserves explicit localhost preference during login recovery", async () => {
+  const events = [];
+  let launchCount = 0;
+
+  const result = await runRuntimeWithSessionRecovery({
+    args: ["run"],
+    baseUrl: "http://127.0.0.1:8080",
+    token: "token-1",
+    childOptions: {
+      cwd: process.cwd(),
+      env: {},
+    },
+    canAutoLoginRuntime: true,
+    preferLocalhost: true,
+    refreshTokenFn: async (baseUrl) => {
+      events.push(["refresh", baseUrl]);
+      throw new Error("refresh failed");
+    },
+    runLogin: async (baseUrl, loginArgs, options) => {
+      events.push(["login", baseUrl, loginArgs, options]);
+    },
+    resolveTokenFn: async () => {
+      events.push(["resolve-token"]);
+      return "token-2";
+    },
+    resolveStoredBaseUrlFn: async () => {
+      events.push(["resolve-base-url"]);
+      return "https://api.textcortex.com";
+    },
+    prepareRuntimeFn: async (baseUrl, token) => {
+      events.push(["prepare", baseUrl, token]);
+      return "kimi-k2-5-thinking";
+    },
+    launchRuntimeFn: async ({ childOptions }) => {
+      launchCount += 1;
+      events.push(["launch", launchCount, childOptions.env.TEXTCORTEX_API_KEY]);
+      if (launchCount === 1) {
+        return { expiredSession: true };
+      }
+      return { code: 0, signal: null, expiredSession: false };
+    },
+  });
+
+  assert.deepEqual(events, [
+    ["launch", 1, "token-1"],
+    ["refresh", "http://127.0.0.1:8080"],
+    ["login", "http://127.0.0.1:8080", ["--local"], { preferLocalhost: true }],
+    ["resolve-token"],
+    ["resolve-base-url"],
+    ["prepare", "http://127.0.0.1:8080", "token-2"],
+    ["launch", 2, "token-2"],
+  ]);
+  assert.deepEqual(result, { code: 0, signal: null, expiredSession: false });
+});
+
+test("runRuntimeWithSessionRecovery stops after repeated recovery failures", async () => {
+  const events = [];
+  let launchCount = 0;
+
+  await assert.rejects(
+    () =>
+      runRuntimeWithSessionRecovery({
+        args: ["run"],
+        baseUrl: "http://127.0.0.1:8080",
+        token: "token-1",
+        childOptions: {
+          cwd: process.cwd(),
+          env: {},
+        },
+        canAutoLoginRuntime: true,
+        maxRecoveryAttempts: 2,
+        sleepFn: async () => {
+          events.push(["sleep"]);
+        },
+        refreshTokenFn: async (baseUrl) => {
+          events.push(["refresh", baseUrl]);
+          throw new Error("refresh failed");
+        },
+        runLogin: async (baseUrl, loginArgs) => {
+          events.push(["login", baseUrl, loginArgs]);
+        },
+        resolveTokenFn: async () => {
+          events.push(["resolve-token"]);
+          return "token-2";
+        },
+        resolveStoredBaseUrlFn: async () => {
+          events.push(["resolve-base-url"]);
+          return "https://api.textcortex.com";
+        },
+        prepareRuntimeFn: async (baseUrl, token) => {
+          events.push(["prepare", baseUrl, token]);
+          return "kimi-k2-5-thinking";
+        },
+        launchRuntimeFn: async ({ childOptions }) => {
+          launchCount += 1;
+          events.push(["launch", launchCount, childOptions.env.TEXTCORTEX_API_KEY]);
+          return { expiredSession: true };
+        },
+      }),
+    /Zenocode session recovery failed after 2 attempts/,
+  );
+
+  assert.deepEqual(events, [
+    ["launch", 1, "token-1"],
+    ["refresh", "http://127.0.0.1:8080"],
+    ["login", "http://127.0.0.1:8080", []],
+    ["resolve-token"],
+    ["resolve-base-url"],
+    ["prepare", "https://api.textcortex.com", "token-2"],
+    ["sleep"],
+    ["launch", 2, "token-2"],
+    ["refresh", "https://api.textcortex.com"],
+    ["login", "https://api.textcortex.com", []],
+    ["resolve-token"],
+    ["resolve-base-url"],
+    ["prepare", "https://api.textcortex.com", "token-2"],
+    ["sleep"],
+    ["launch", 3, "token-2"],
+  ]);
+});
+
+test("prepare-only refreshes stored Zenocode credentials when the access token has expired", async (t) => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "zenocode-refresh-"));
+  const zenocodeHome = path.join(tempDir, ".zenocode");
+  const credentialsPath = path.join(zenocodeHome, "credentials.json");
+  const scriptPath = new URL("./run-zenocode.mjs", import.meta.url);
+  let refreshCalls = 0;
+  let refreshedAuthHeader = null;
+  let modelAuthHeader = null;
+
+  t.after(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  await fs.mkdir(zenocodeHome, { recursive: true });
+  await fs.writeFile(
+    credentialsPath,
+    JSON.stringify(
+      {
+        base_url: "http://127.0.0.1:1",
+        access_token: "expired-access",
+        refresh_token: "refresh-token",
+        expires_at: new Date(Date.now() - 60_000).toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
+
+  const server = http.createServer((req, res) => {
+    if (req.method === "POST" && req.url === "/auth/token/refresh/") {
+      refreshCalls += 1;
+      refreshedAuthHeader = req.headers.authorization || null;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          access_token: "fresh-access",
+          refresh_token: "fresh-refresh",
+        }),
+      );
+      return;
+    }
+
+    if (
+      req.method === "GET" &&
+      req.url === "/internal/v1/fastapi/zenocode/models/api.json"
+    ) {
+      modelAuthHeader = req.headers.authorization || null;
+      if (modelAuthHeader === "Bearer expired-access") {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ detail: "Token has expired" }));
+        return;
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          textcortex: {
+            models: {
+              "kimi-k2-5-thinking": {},
+              "glm-5": {},
+            },
+          },
+        }),
+      );
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ detail: "not found" }));
+  });
+
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const baseUrl = `http://127.0.0.1:${address.port}`;
+
+  t.after(async () => {
+    await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+  });
+
+  const result = await new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [scriptPath.pathname, "--prepare-only"],
+      {
+        cwd: tempDir,
+        env: {
+          ...process.env,
+          ZENOCODE_HOME: zenocodeHome,
+          TEXTCORTEX_BASE_URL: baseUrl,
+          ZENOCODE_NO_BANNER: "1",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => resolve({ code, signal, stdout, stderr }));
+  });
+
+  assert.equal(result.code, 0);
+  assert.equal(refreshCalls, 1);
+  assert.equal(refreshedAuthHeader, "Bearer refresh-token");
+  assert.equal(modelAuthHeader, "Bearer fresh-access");
+
+  const savedCredentials = JSON.parse(await fs.readFile(credentialsPath, "utf-8"));
+  assert.equal(savedCredentials.access_token, "fresh-access");
+  assert.equal(savedCredentials.refresh_token, "fresh-refresh");
+});
+
+test("logout removes runtime credentials and blocks shared fallback credentials", async (t) => {
   const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "zenocode-logout-"));
   const zenocodeHome = path.join(tempDir, ".zenocode");
   const codecortexHome = path.join(tempDir, ".codecortex");
-  const repoCredentialsPath = path.join(tempDir, ".credentials.json");
+  const homeCredentialsPath = path.join(tempDir, ".credentials.json");
   const runtimeCredentialsPath = path.join(zenocodeHome, "credentials.json");
   const legacyRuntimeCredentialsPath = path.join(codecortexHome, "credentials.json");
   const scriptPath = new URL("./run-zenocode.mjs", import.meta.url);
@@ -186,7 +572,7 @@ test("logout removes legacy credential fallbacks as well as Zenocode credentials
     legacyRuntimeCredentialsPath,
     JSON.stringify({ access_token: "legacy" }),
   );
-  await fs.writeFile(repoCredentialsPath, JSON.stringify({ access_token: "repo" }));
+  await fs.writeFile(homeCredentialsPath, JSON.stringify({ access_token: "home" }));
 
   const result = await new Promise((resolve, reject) => {
     const child = spawn(
@@ -196,6 +582,7 @@ test("logout removes legacy credential fallbacks as well as Zenocode credentials
         cwd: tempDir,
         env: {
           ...process.env,
+          HOME: tempDir,
           ZENOCODE_HOME: zenocodeHome,
           CODECORTEX_HOME: codecortexHome,
         },
@@ -218,7 +605,38 @@ test("logout removes legacy credential fallbacks as well as Zenocode credentials
   await assert.rejects(fs.stat(runtimeCredentialsPath), { code: "ENOENT" });
   await assert.rejects(fs.stat(legacyRuntimeCredentialsPath), { code: "ENOENT" });
   assert.deepEqual(
-    JSON.parse(await fs.readFile(repoCredentialsPath, "utf-8")),
-    { access_token: "repo" },
+    JSON.parse(await fs.readFile(homeCredentialsPath, "utf-8")),
+    { access_token: "home" },
   );
+
+  const prepareOnlyResult = await new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [scriptPath.pathname, "--prepare-only"],
+      {
+        cwd: tempDir,
+        env: {
+          ...process.env,
+          HOME: tempDir,
+          ZENOCODE_HOME: zenocodeHome,
+          CODECORTEX_HOME: codecortexHome,
+          ZENOCODE_NO_BANNER: "1",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => resolve({ code, signal, stdout, stderr }));
+  });
+
+  assert.equal(prepareOnlyResult.code, 1);
+  assert.match(prepareOnlyResult.stderr, /Missing API token/);
 });