@302ai/media-studio-cli 0.1.0 → 0.1.1-beta.1

package/dist/index.js

@@ -4284,7 +4284,7 @@ var consola = createConsola2();
 // package.json
 var package_default = {
   name: "@302ai/media-studio-cli",
-  version: "0.1.0",
+  version: "0.1.1-beta.1",
   description: "CLI for AI Media Studio — let external agents drive the core media-studio features",
   author: "302.AI",
   license: "Apache-2.0",
@@ -9701,6 +9701,7 @@ var ATTACHMENT_MIME_BY_EXTENSION = {
 
 // ../media-studio-contract/src/attachments/markers.ts
 var ATTACHMENT_MARKER = "&&";
+var ATTACHMENT_MARKER_REGEX = /&&([^&\s]+)&&/g;
 function formatAttachmentMarker(remoteUrl) {
   return `${ATTACHMENT_MARKER}${remoteUrl}${ATTACHMENT_MARKER}`;
 }
@@ -9749,6 +9750,151 @@ function isString(value) {
   return typeof value === "string";
 }
 // ../media-studio-contract/src/err-codes.ts
+var ErrCode = {
+  MISSING_REQUIRED_PARAM: 10001,
+  INVALID_PARAM_FORMAT: 10002,
+  RESOURCE_NOT_FOUND: 10003,
+  METHOD_NOT_ALLOWED: 10004,
+  RATE_LIMITED: 10005,
+  PAYLOAD_TOO_LARGE: 10006,
+  UNSUPPORTED_MEDIA_TYPE: 10007,
+  INTERNAL_ERROR: 10500,
+  DEPENDENCY_UNAVAILABLE: 10501,
+  DATABASE_ERROR: 10502,
+  SERVICE_UNAVAILABLE: 10503,
+  CACHE_UNAVAILABLE: 10504,
+  UNAUTHORIZED: 20001,
+  TOKEN_MISSING: 20002,
+  TOKEN_INVALID: 20003,
+  TOKEN_EXPIRED: 20004,
+  TOKEN_REVOKED: 20005,
+  REFRESH_TOKEN_INVALID: 20006,
+  REFRESH_TOKEN_ROTATED: 20007,
+  VERIFICATION_CODE_INVALID: 20101,
+  VERIFICATION_CODE_EXPIRED: 20102,
+  CODE_SEND_RATE_LIMITED: 20103,
+  CODE_SEND_DAILY_LIMIT: 20104,
+  EMAIL_SEND_FAILED: 20105,
+  EMAIL_ALREADY_REGISTERED: 20106,
+  EMAIL_NOT_REGISTERED: 20107,
+  OAUTH_STATE_INVALID: 20201,
+  OAUTH_CALLBACK_FAILED: 20202,
+  OAUTH_ACCOUNT_ALREADY_BOUND: 20203,
+  SSO_INFO_CONFLICT: 20204,
+  FORBIDDEN: 20301,
+  ADMIN_REQUIRED: 20302,
+  ACCOUNT_DEACTIVATED: 20303,
+  INSUFFICIENT_BALANCE: 30001,
+  CREDIT_FREEZE_FAILED: 30002,
+  FREEZE_RECORD_NOT_FOUND: 30003,
+  FREEZE_ALREADY_SETTLED: 30004,
+  CREDIT_SETTLE_FAILED: 30005,
+  SETTLE_EXCEEDS_FREEZE: 30006,
+  UNFREEZE_FAILED: 30007,
+  CREDIT_BATCH_EXPIRED: 30008,
+  CREDIT_BATCH_NOT_FOUND: 30009,
+  CONCURRENT_MODIFICATION: 30010,
+  PRICING_RULE_NOT_FOUND: 30101,
+  MODEL_PRICE_MISSING: 30102,
+  USAGE_RECORD_DUPLICATED: 30103,
+  BALANCE_CACHE_REBUILD_FAILED: 30104,
+  LEDGER_WRITE_FAILED: 30105,
+  UPSTREAM_ERROR: 40001,
+  UPSTREAM_TIMEOUT: 40002,
+  UPSTREAM_RATE_LIMITED: 40003,
+  UPSTREAM_UNAVAILABLE: 40004,
+  UPSTREAM_AUTH_FAILED: 40005,
+  UPSTREAM_DATA_INVALID: 40006,
+  MODEL_UNSUPPORTED: 40101,
+  MODEL_LABEL_INVALID: 40102,
+  MODEL_PRICE_NOT_CONFIGURED: 40103,
+  MODEL_LABEL_DEPRECATED: 40104,
+  SANDBOX_TOKEN_INVALID: 40201,
+  SANDBOX_TOKEN_EXPIRED: 40202,
+  OSS_TRANSFER_FAILED: 40301,
+  OSS_URL_PRESIGN_FAILED: 40302,
+  PLAN_NOT_FOUND: 50001,
+  PLAN_UNAVAILABLE: 50002,
+  PLAN_PRICE_MISSING: 50003,
+  ORDER_NOT_FOUND: 50101,
+  ORDER_ALREADY_PAID: 50102,
+  ORDER_EXPIRED: 50103,
+  ORDER_AMOUNT_MISMATCH: 50104,
+  ORDER_STATUS_NOT_ALLOWED: 50105,
+  ORDER_CANCEL_FAILED: 50106,
+  ORDER_PENDING_EXISTS: 50107,
+  PAYMENT_FAILED: 50201,
+  PAYMENT_REJECTED: 50202,
+  PAYMENT_METHOD_NOT_FOUND: 50203,
+  WEBHOOK_SIGNATURE_INVALID: 50204,
+  WEBHOOK_EVENT_UNKNOWN: 50205,
+  STRIPE_API_ERROR: 50206,
+  SUBSCRIPTION_NOT_FOUND: 50301,
+  SUBSCRIPTION_STATUS_NOT_ALLOWED: 50302,
+  SUBSCRIPTION_CANCELED: 50303,
+  UPGRADE_PRORATION_FAILED: 50304,
+  DOWNGRADE_NOT_ALLOWED: 50305,
+  AUTO_RENEW_FAILED: 50306,
+  SAVED_CARD_INVALID: 50307,
+  REFUND_NOT_ELIGIBLE: 50401,
+  REFUND_WINDOW_EXPIRED: 50402,
+  REFUND_THRESHOLD_EXCEEDED: 50403,
+  REFUND_FAILED: 50404,
+  TOPUP_SUBSCRIPTION_ONLY: 50501,
+  TOPUP_FROZEN: 50502,
+  TOPUP_NOT_FOUND: 50503,
+  SESSION_NOT_FOUND: 60001,
+  SESSION_ALREADY_EXISTS: 60002,
+  SESSION_STATUS_NOT_ALLOWED: 60003,
+  CHAT_SESSION_EXPIRED: 60004,
+  CHAT_CONTEXT_MISSING: 60005,
+  PROMPT_SUGGESTION_FAILED: 60006,
+  TITLE_GENERATION_FAILED: 60007,
+  CHAT_TASK_NOT_FOUND: 60101,
+  CHAT_TASK_IN_PROGRESS: 60102,
+  CHAT_TASK_CANCELED: 60103,
+  CHAT_TASK_STATUS_NOT_ALLOWED: 60104,
+  SANDBOX_CREATE_FAILED: 60201,
+  SANDBOX_WARMUP_FAILED: 60202,
+  SANDBOX_TIMEOUT: 60203,
+  SANDBOX_UNAVAILABLE: 60204,
+  SANDBOX_COMMAND_FAILED: 60205,
+  SKILL_NOT_FOUND: 60301,
+  SKILL_FILE_INVALID: 60302,
+  SKILL_BUILTIN_IMMUTABLE: 60303,
+  SKILL_UPLOAD_INVALID: 60304,
+  ASSET_NOT_FOUND: 70001,
+  ASSET_GROUP_NOT_FOUND: 70002,
+  ASSET_GROUP_NAME_EXISTS: 70003,
+  ASSET_UPLOAD_FAILED: 70004,
+  ASSET_TOO_LARGE: 70005,
+  ASSET_TYPE_NOT_ALLOWED: 70006,
+  ASSET_GROUP_INVALID: 70007,
+  OSS_UPLOAD_FAILED: 70101,
+  OSS_DOWNLOAD_FAILED: 70102,
+  COVER_UPLOAD_FAILED: 70103,
+  OSS_DELETE_FAILED: 70104,
+  FILE_NOT_FOUND: 70201,
+  FILE_READ_FAILED: 70202,
+  FILE_WRITE_FAILED: 70203,
+  FILE_FORMAT_INVALID: 70204,
+  FILE_FORMAT_TEXT_FILE_ONLY: 70205,
+  FILE_OPERATION_INVALID: 70206,
+  FILE_TARGET_PATH_REQUIRED: 70207,
+  FILE_PATH_COUNT_MISMATCH: 70208,
+  FILE_RENAME_BATCH_UNSUPPORTED: 70209,
+  ADMIN_NOT_LOGGED_IN: 90001,
+  ADMIN_2FA_REQUIRED: 90002,
+  ADMIN_2FA_CODE_INVALID: 90003,
+  ADMIN_2FA_RATE_LIMITED: 90004,
+  ADMIN_FORBIDDEN: 90005,
+  ADMIN_NOT_FOUND: 90006,
+  RISK_CONTROL_TRIGGERED: 90101,
+  RISK_CONTROL_RATE_LIMITED: 90102,
+  RECONCILIATION_MISMATCH: 90103,
+  RECONCILIATION_TASK_FAILED: 90104,
+  AUDIT_LOG_WRITE_FAILED: 90105
+};
 var ERR_NEXT_STEP = {
   10001: "fix_input",
   10002: "fix_input",
@@ -9928,11 +10074,14 @@ var APP_ENV_HOSTS = {
 // ../media-studio-contract/src/skills/activation.ts
 var SKILL_ACTIVATION_MARKER = "%%";
 var SKILL_ACTIVATION_RE = /%%(\/[^%\s]+)%%/g;
+function createSkillActivationRegex() {
+  return new RegExp(SKILL_ACTIVATION_RE.source, SKILL_ACTIVATION_RE.flags);
+}
 function formatSkillActivation(command) {
   return `${SKILL_ACTIVATION_MARKER}${command}${SKILL_ACTIVATION_MARKER}`;
 }
 function findSkillActivationMatches(text) {
-  return Array.from(text.matchAll(SKILL_ACTIVATION_RE)).flatMap((match, index) => {
+  return Array.from(text.matchAll(createSkillActivationRegex())).flatMap((match, index) => {
     const start = match.index;
     const command = match[1];
     if (start === undefined || !command)
@@ -9949,6 +10098,25 @@ function findSkillActivationMatches(text) {
   });
 }
 
+// ../media-studio-contract/src/sessions/derive-first-turn-note.ts
+var DEFAULT_FALLBACK_TITLE = "Agent Task";
+var MAX_NOTE_LENGTH = 64;
+function deriveFirstTurnNote(rawText, options) {
+  const fallback = options?.fallbackTitle ?? DEFAULT_FALLBACK_TITLE;
+  if (!rawText) {
+    return fallback;
+  }
+  const unwrapped = rawText.replace(/\$--model\s+"([^"$]+)"[^$]*\$/gi, "$1 ").replace(/\$--model\s+([^$\s]+)[^$]*\$/gi, "$1 ").replace(SKILL_ACTIVATION_RE, "$1").replace(ATTACHMENT_MARKER_REGEX, "$1").replace(/\s+/g, " ").trim();
+  if (!unwrapped) {
+    return fallback;
+  }
+  const codePoints = Array.from(unwrapped);
+  if (codePoints.length > MAX_NOTE_LENGTH) {
+    return codePoints.slice(0, MAX_NOTE_LENGTH).join("");
+  }
+  return unwrapped;
+}
+
 // ../media-studio-contract/src/skills/compose-turn.ts
 function applySkillActivations(text, spans) {
   const ordered = spans.toSorted((a, b) => b.start - a.start);
@@ -10027,6 +10195,15 @@ function attempt2(func) {
     return [error, null];
   }
 }
+
+// ../../node_modules/es-toolkit/dist/util/attemptAsync.mjs
+async function attemptAsync(func) {
+  try {
+    return [null, await func()];
+  } catch (error) {
+    return [error, null];
+  }
+}
 // ../../node_modules/ts-pattern/dist/index.js
 var t2 = Symbol.for("@ts-pattern/matcher");
 var e2 = Symbol.for("@ts-pattern/isVariadic");
@@ -16721,9 +16898,7 @@ function validateApiBaseUrl(urlString) {
 }
 var AuthDataSchema = object2({
   token: string4().min(1),
-  apiUrl: string4().refine((val) => isAllowedCliApiOrigin(val), {
-    message: "Untrusted API URL in auth file"
-  }).optional(),
+  apiUrl: string4().optional(),
   uid: string4().optional(),
   username: string4().optional(),
   email: string4().optional(),
@@ -16737,11 +16912,35 @@ var ConfigFileSchema = object2({
     latest: string4().optional()
   }).optional()
 });
+
+class UntrustedCredentialError extends Error {
+  rejectedUrl;
+  constructor(rejectedUrl) {
+    super(`Untrusted apiUrl in the saved credential: "${rejectedUrl}". ` + `Allowed hosts: ${MEDIA_STUDIO_HOSTS.join(", ")}. ` + `Run \`msc login\` to sign in - it opens a browser, so a human must complete it.`);
+    this.name = "UntrustedCredentialError";
+    this.rejectedUrl = rejectedUrl;
+  }
+}
 function readAuthFile() {
+  let raw;
   try {
-    const parsed = JSON.parse(readFileSync(getAuthFilePath(), "utf8"));
-    const res = AuthDataSchema.safeParse(parsed);
-    return res.success ? res.data : null;
+    raw = JSON.parse(readFileSync(getAuthFilePath(), "utf8"));
+  } catch {
+    return null;
+  }
+  const shape = AuthDataSchema.safeParse(raw);
+  if (!shape.success || !shape.data.token.trim()) {
+    return null;
+  }
+  const savedUrl = shape.data.apiUrl?.trim();
+  if (savedUrl && !isAllowedCliApiOrigin(savedUrl)) {
+    throw new UntrustedCredentialError(savedUrl);
+  }
+  return shape.data;
+}
+function readAuthFileIfUsable() {
+  try {
+    return readAuthFile();
   } catch {
     return null;
   }
@@ -16795,7 +16994,8 @@ function saveUpdateCheck(check) {
   writeConfigFile({ updateCheck: check });
 }
 function resolveApiKey() {
-  const token = readAuthFile()?.token;
+  const auth = readAuthFile();
+  const token = auth?.token;
   if (!token?.trim()) {
     throw new Error("Missing authentication. Run `msc login` to sign in - it opens a browser, so a human " + "must complete it. Instant if that browser is already signed in to the web app.");
   }
@@ -16804,7 +17004,7 @@ function resolveApiKey() {
 function resolveApiBaseUrl(flag) {
   if (flag)
     return validateApiBaseUrl(flag);
-  const fromAuth = readAuthFile()?.apiUrl;
+  const fromAuth = readAuthFileIfUsable()?.apiUrl;
   if (typeof fromAuth === "string" && fromAuth.trim()) {
     if (isAllowedCliApiOrigin(fromAuth)) {
       return fromAuth;
@@ -16815,6 +17015,7 @@ function resolveApiBaseUrl(flag) {
 
 // src/client/session-types.ts
 var SessionSourceSchema = _enum2(["web", "cli"]);
+var CLI_DEFAULT_SESSION_NOTE = "Agent Task";
 var ApiResponseBaseSchema = object2({
   success: boolean4(),
   error: object2({
@@ -16969,6 +17170,15 @@ class ClientSessions {
     const url = `${this.baseUrl}/api/sessions${search ? `?${search}` : ""}`;
     return requestJson(this.customFetch, url, { method: "GET", headers: this.authHeaders() }, ListSessionsResponseSchema, (status) => `Failed to fetch sessions with status ${status}`);
   }
+  async exists(sessionId) {
+    const params = new URLSearchParams({ sessionId, limit: "1" });
+    const [err] = await attemptAsync(() => requestJson(this.customFetch, `${this.baseUrl}/api/sessions/detail?${params.toString()}`, { method: "GET", headers: this.authHeaders() }, unknown2(), (status) => `Failed to verify session ${sessionId} with status ${status}`));
+    if (!err)
+      return true;
+    if (err instanceof ChatUpstreamError && err.status === 404)
+      return false;
+    throw err;
+  }
   async artifacts(query) {
     const params = new URLSearchParams({ sessionId: query.sessionId });
     if (query.taskId !== undefined)
@@ -17006,12 +17216,17 @@ class ClientSessions {
             signal
           });
           if (!response.ok) {
-            await response.body?.cancel().catch(() => {
-              return;
-            });
+            const body = await response.text().catch(() => "");
             const retryable = response.status >= 500 || response.status === 429;
-            if (!retryable)
+            if (!retryable) {
+              if (!state.sessionReady) {
+                state.outcome = {
+                  status: "failed",
+                  error: new ChatUpstreamError(`Session prewarm was rejected with status ${response.status}`, response.status, body)
+                };
+              }
               break;
+            }
             continue;
           }
           await this.consumePrewarmStream(response, state, {
@@ -17030,7 +17245,10 @@ class ClientSessions {
     }
     if (state.outcome)
       return state.outcome;
-    return state.sessionReady ? { status: "fallback", session: state.sessionReady } : { status: "failed" };
+    return state.sessionReady ? { status: "fallback", session: state.sessionReady } : {
+      status: "failed",
+      error: new ChatUpstreamError("Session prewarm never completed: no session_ready event (request retries exhausted or timed out).", 0, "")
+    };
   }
   async consumePrewarmStream(response, state, callbacks) {
     if (!response.body)
@@ -17061,12 +17279,18 @@ class ClientSessions {
           }
           case "done": {
             PrewarmDoneSchema.parse(data);
-            state.outcome = state.sessionReady ? { status: "ready", session: state.sessionReady } : { status: "failed" };
+            state.outcome = state.sessionReady ? { status: "ready", session: state.sessionReady } : {
+              status: "failed",
+              error: new ChatUpstreamError("Session prewarm ended before the session was created upstream.", 0, "")
+            };
             return;
           }
           case "error": {
-            PrewarmErrorSchema.parse(data);
-            state.outcome = state.sessionReady ? { status: "fallback", session: state.sessionReady } : { status: "failed" };
+            const payload = PrewarmErrorSchema.parse(data);
+            state.outcome = state.sessionReady ? { status: "fallback", session: state.sessionReady } : {
+              status: "failed",
+              error: new ChatUpstreamError(payload.message, 0, JSON.stringify({ error: payload }))
+            };
             return;
           }
           default:
@@ -17261,7 +17485,7 @@ class MediaStudioClient {
         const nextKey = rotatedToken.trim();
         this._apiKey = nextKey;
         try {
-          const authData = readAuthFile();
+          const authData = readAuthFileIfUsable();
           if (authData) {
             saveAuthFile({
               ...authData,
@@ -17584,10 +17808,50 @@ var NEXT_STEP_GUIDANCE = {
   retry: "The failure looks transient. Retrying the same request may succeed.",
   none: ""
 };
+var TRANSPORT_CAUSE_DEPTH = 5;
+var TRANSPORT_MESSAGE = /fetch failed|Unable to connect/i;
+var ERRNO_SHAPE = /^[A-Z][A-Z0-9_]*$/;
+function isTerminalControl(codePoint) {
+  return codePoint <= 8 && codePoint !== 9 || codePoint >= 14 && codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 8206 || codePoint === 8207 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297;
+}
+function stripTerminalControls(text) {
+  let out = "";
+  for (const char of text) {
+    if (!isTerminalControl(char.codePointAt(0) ?? -1))
+      out += char;
+  }
+  return out;
+}
+function detailOf(node, code) {
+  if (!("message" in node))
+    return "";
+  const { message } = node;
+  if (typeof message !== "string")
+    return "";
+  return stripTerminalControls(message.split(code).join(" ")).replace(/\s+/g, " ").trim().replace(/^[:-]\s*/, "");
+}
+function findTransportErrno(err) {
+  let current = err;
+  for (let depth = 0;depth < TRANSPORT_CAUSE_DEPTH; depth++) {
+    if (!(current instanceof Error))
+      return null;
+    const code = "code" in current ? current.code : undefined;
+    const errno = typeof code === "string" && ERRNO_SHAPE.test(code) ? code : null;
+    if (errno)
+      return { code: errno, detail: detailOf(current, errno) };
+    current = current.cause;
+  }
+  return null;
+}
+function isTransportFailure(err) {
+  return findTransportErrno(err) !== null || err instanceof Error && TRANSPORT_MESSAGE.test(err.message);
+}
 function reportCommandError(err, options) {
-  const message = err instanceof Error ? err.message : String(err);
+  const plain = err instanceof Error ? err.message : String(err);
+  const transport = findTransportErrno(err);
+  const message = transport && !plain.includes(transport.code) ? `${plain} (${transport.code}${transport.detail ? `: ${transport.detail}` : ""})` : plain;
   const upstream = err instanceof ChatUpstreamError ? err : null;
-  const nextStep = upstream?.nextStep ?? (upstream?.status === 401 ? "relogin" : null);
+  const nextStep = upstream?.nextStep ?? (upstream?.status === 401 || err instanceof UntrustedCredentialError ? "relogin" : null);
   const status = upstream?.status !== undefined && upstream.status !== 0 ? upstream.status : null;
   const guidance = nextStep ? NEXT_STEP_GUIDANCE[nextStep] : "";
   if (options?.json) {
@@ -17597,7 +17861,8 @@ function reportCommandError(err, options) {
       ...upstream?.errCode != null ? { errCode: upstream.errCode } : {},
       ...status != null ? { httpStatus: status } : {},
       ...nextStep != null ? { nextStep } : {},
-      ...guidance ? { guidance } : {}
+      ...guidance ? { guidance } : {},
+      ...transport ? { transportCode: transport.code } : {}
     };
     process.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
@@ -17812,29 +18077,66 @@ async function resolvePromptAttachments(options) {
 }
 
 // src/services/session.ts
+var SESSION_GONE_ERR_CODES = [
+  ErrCode.SESSION_NOT_FOUND,
+  ErrCode.CHAT_SESSION_EXPIRED
+];
 function isSessionGoneError(err) {
   if (!(err instanceof ChatUpstreamError))
     return false;
+  if (err.errCode !== null) {
+    return SESSION_GONE_ERR_CODES.includes(err.errCode);
+  }
   if (err.status === 404)
     return true;
   return err.body.includes(ERR_SESSION_EXPIRED);
 }
+
+class SessionNotFoundError extends Error {
+  sessionId;
+  constructor(sessionId) {
+    super(`Session ${sessionId} does not exist.
+` + '  → Create one: `msc sessions use --new`, or `msc chat --new "<prompt>"` to also send a prompt.');
+    this.name = "SessionNotFoundError";
+    this.sessionId = sessionId;
+  }
+}
+async function ensureSessionExists(options) {
+  const client = new MediaStudioClient({
+    baseUrl: options.apiBaseUrl,
+    apiKey: options.apiKey
+  });
+  if (await client.sessions.exists(options.sessionId))
+    return;
+  throw new SessionNotFoundError(options.sessionId);
+}
+function finalizeProvision(result, spinner) {
+  spinner?.stop();
+  if (result.status === "failed") {
+    throw result.error;
+  }
+  if (result.status === "fallback") {
+    consola.warn("Session created, but sandbox/skill setup did not fully complete. Plain-text chat still works.");
+  }
+  return result.sessionId;
+}
 async function provisionSession(options) {
-  const sessionId = nanoid3();
   const client = new MediaStudioClient({
     baseUrl: options.apiBaseUrl,
     apiKey: options.apiKey
   });
+  const sessionId = nanoid3();
   const outcome = await client.sessions.prewarm({
     sessionId,
     source: "cli",
+    note: options.note ?? CLI_DEFAULT_SESSION_NOTE,
     onSessionReady: () => saveLastSessionId(sessionId),
-    ...options.onStageChange ? { onStageChange: options.onStageChange } : {}
+    onStageChange: options.onStageChange
   });
-  return M(outcome).with({ status: "ready" }, { status: "fallback" }, ({ status }) => ({
-    status,
-    sessionId
-  })).with({ status: "failed" }, () => ({ status: "failed" })).exhaustive();
+  if (outcome.status === "failed") {
+    return { status: "failed", error: outcome.error };
+  }
+  return { status: outcome.status, sessionId };
 }
 
 // src/lib/skill-refs.ts
@@ -17890,7 +18192,7 @@ async function ensureUsable(client, skill) {
   });
   if (ensured)
     return;
-  throw new SkillResolutionError(describeEnableFailure(skill, cause));
+  throw new SkillResolutionError(describeEnableFailure(skill, cause), cause ? { cause } : undefined);
 }
 async function resolvePromptSkills(options) {
   const spans = findSkillRefSpans(options.prompt);
@@ -17963,34 +18265,59 @@ function printTerminalMediaAssets(mediaAssets, fullText) {
   process.stdout.write(`====================
 `);
 }
-function finalizeProvision(result, spinner) {
-  spinner.stop();
-  if (result.status === "failed") {
-    throw new Error("Session provisioning failed before any session was created upstream. Try again.");
-  }
-  if (result.status === "fallback") {
-    consola.warn("Session created, but sandbox/skill setup did not fully complete. Continuing with chat.");
-  }
-  return result.sessionId;
+function buildNotePrompt(prompt, attachments) {
+  return prompt.replace(ATTACHMENT_MARKER_REGEX, (marker, url) => {
+    const attachment = attachments.find((a) => a.remoteUrl === url);
+    return attachment ? attachment.name || attachment.remoteUrl : marker;
+  });
+}
+async function provisionNewSession(options) {
+  const onStageChange = options.quiet ? undefined : (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage]);
+  const note = deriveFirstTurnNote(options.prompt, {
+    fallbackTitle: CLI_DEFAULT_SESSION_NOTE
+  });
+  const result = await provisionSession({
+    apiBaseUrl: options.apiBaseUrl,
+    apiKey: options.apiKey,
+    note,
+    onStageChange
+  });
+  return finalizeProvision(result, options.spinner);
 }
 async function resolveChatSession(options) {
+  if (options.newSession) {
+    return {
+      sessionId: await provisionNewSession({
+        ...options,
+        prompt: options.prompt
+      }),
+      recreateOnGone: false
+    };
+  }
   if (options.sessionFlag) {
     saveLastSessionId(options.sessionFlag);
-    return { sessionId: options.sessionFlag, recreateOnGone: true };
+    return { sessionId: options.sessionFlag, recreateOnGone: false };
   }
   const pointer = readLastSessionId();
   if (pointer) {
     return { sessionId: pointer, recreateOnGone: true };
   }
-  const result = await provisionSession({
-    apiBaseUrl: options.apiBaseUrl,
-    apiKey: options.apiKey,
-    ...options.quiet ? {} : {
-      onStageChange: (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage])
-    }
-  });
-  const sessionId = finalizeProvision(result, options.spinner);
-  return { sessionId, recreateOnGone: false };
+  return {
+    sessionId: await provisionNewSession({
+      ...options,
+      prompt: options.prompt
+    }),
+    recreateOnGone: false
+  };
+}
+function describeStreamFailure(err) {
+  if (err instanceof Error && err.name === "AbortError") {
+    return "aborted";
+  }
+  if (err instanceof Error && err.message) {
+    return err.message;
+  }
+  return String(err);
 }
 async function streamTurn(options) {
   const { args, sessionId, spinner, autoEnabled, attachments } = options;
@@ -18011,84 +18338,103 @@ async function streamTurn(options) {
   const steps = [];
   const mediaAssets = [];
   let hasFinished = false;
-  for await (const ev of stream) {
-    M(ev).with({ type: "text-delta", delta: z2.string }, ({ delta }) => {
-      isThinking = false;
-      spinner.stop();
-      fullText += delta;
-      if (!args.json) {
-        process.stdout.write(delta);
+  let emitting = false;
+  let streamFailure;
+  try {
+    for await (const ev of stream) {
+      if (ev.type !== "finish" && ev.type !== "error") {
+        options.progress.emitted = true;
       }
-    }).with({ type: "reasoning-delta", delta: z2.string }, ({ delta }) => {
-      reasoning += delta;
-      if (args["show-reasoning"] && !args.json) {
+      M(ev).with({ type: "text-delta", delta: z2.string }, ({ delta }) => {
+        isThinking = false;
         spinner.stop();
-        process.stdout.write(delta);
-      } else if (!args.json) {
-        if (!isThinking) {
-          isThinking = true;
+        fullText += delta;
+        if (!args.json) {
+          process.stdout.write(delta);
+        }
+      }).with({ type: "reasoning-delta", delta: z2.string }, ({ delta }) => {
+        reasoning += delta;
+        if (args["show-reasoning"] && !args.json) {
           spinner.stop();
-          if (fullText && !fullText.endsWith(`
+          process.stdout.write(delta);
+        } else if (!args.json) {
+          if (!isThinking) {
+            isThinking = true;
+            spinner.stop();
+            if (fullText && !fullText.endsWith(`
 `)) {
-            process.stdout.write(`
+              process.stdout.write(`
 `);
-            fullText += `
+              fullText += `
 `;
-          }
-          process.stdout.write(`[reasoning] Thinking...
+            }
+            process.stdout.write(`[reasoning] Thinking...
 `);
-          spinner.start("Thinking...");
+            spinner.start("Thinking...");
+          }
         }
-      }
-    }).with({ type: "tool-call", toolName: z2.string }, ({ toolName, args: toolArgs }) => {
-      isThinking = false;
-      spinner.stop();
-      if (fullText && !fullText.endsWith(`
+      }).with({ type: "tool-call", toolName: z2.string }, ({ toolName, args: toolArgs }) => {
+        isThinking = false;
+        spinner.stop();
+        if (fullText && !fullText.endsWith(`
 `) && !args.json) {
-        process.stdout.write(`
+          process.stdout.write(`
 `);
-        fullText += `
+          fullText += `
 `;
-      }
-      const formatted = formatToolMilestone(toolName, toolArgs);
-      steps.push(formatted.milestoneLine);
-      if (!args.json) {
-        process.stdout.write(`${formatted.milestoneLine}
+        }
+        const formatted = formatToolMilestone(toolName, toolArgs);
+        steps.push(formatted.milestoneLine);
+        if (!args.json) {
+          process.stdout.write(`${formatted.milestoneLine}
 `);
-        spinner.start(formatted.actionLabel);
-      }
-    }).with({ type: "media-result" }, ({ result }) => {
-      spinner.stop();
-      addOrMergeMediaResult(mediaAssets, result);
-    }).with({ type: "error" }, (ev) => {
-      spinner.stop();
-      const raw = ("error" in ev && typeof ev.error === "string" ? ev.error : null) ?? ("message" in ev && typeof ev.message === "string" ? ev.message : null) ?? "Upstream stream error";
-      throw new ChatUpstreamError(extractUpstreamErrorMessage(raw) || raw, 0, raw);
-    }).with({ type: "finish" }, () => {
-      hasFinished = true;
-      spinner.stop();
-      if (args.json) {
-        const output = {
-          status: "success",
-          sessionId,
-          text: fullText,
-          steps,
-          media: mediaAssets,
-          ...attachments.length > 0 ? { attachments } : {},
-          ...autoEnabled.length > 0 ? { autoEnabled } : {},
-          ...args["show-reasoning"] && reasoning ? { reasoning } : {}
-        };
-        process.stdout.write(`${JSON.stringify(output, null, 2)}
+          spinner.start(formatted.actionLabel);
+        }
+      }).with({ type: "media-result" }, ({ result }) => {
+        spinner.stop();
+        addOrMergeMediaResult(mediaAssets, result);
+      }).with({ type: "error" }, (ev) => {
+        spinner.stop();
+        const raw = ("error" in ev && typeof ev.error === "string" ? ev.error : null) ?? ("message" in ev && typeof ev.message === "string" ? ev.message : null) ?? "Upstream stream error";
+        throw new ChatUpstreamError(extractUpstreamErrorMessage(raw) || raw, 0, raw);
+      }).with({ type: "finish" }, () => {
+        emitting = true;
+        hasFinished = true;
+        spinner.stop();
+        if (args.json) {
+          const output = {
+            status: "success",
+            sessionId,
+            text: fullText,
+            steps,
+            media: mediaAssets,
+            ...attachments.length > 0 ? { attachments } : {},
+            ...autoEnabled.length > 0 ? { autoEnabled } : {},
+            ...args["show-reasoning"] && reasoning ? { reasoning } : {}
+          };
+          process.stdout.write(`${JSON.stringify(output, null, 2)}
 `);
-        return;
-      }
-      printTerminalMediaAssets(mediaAssets, fullText);
-      process.stdout.write(`session: ${sessionId}
+          emitting = false;
+          return;
+        }
+        printTerminalMediaAssets(mediaAssets, fullText);
+        process.stdout.write(`session: ${sessionId}
 `);
-    }).with(z2._, () => {}).exhaustive();
+        emitting = false;
+      }).with(z2._, () => {}).exhaustive();
+    }
+  } catch (err) {
+    if (err instanceof ChatUpstreamError)
+      throw err;
+    if (emitting)
+      throw err;
+    if (!hasFinished && !options.progress.emitted)
+      throw err;
+    streamFailure = err;
   }
   if (!hasFinished) {
     spinner.stop();
+    consola.warn(streamFailure === undefined ? "Stream ended early: no finish event" : `Stream ended early: ${describeStreamFailure(streamFailure)}`);
     if (args.json) {
       const output = {
         status: "incomplete",
@@ -18113,20 +18459,49 @@ async function runTurn(options) {
   try {
     await streamTurn(options);
   } catch (err) {
-    if (options.recreateOnGone && isSessionGoneError(err)) {
-      consola.warn(`Session ${options.sessionId} is no longer available. Provisioning a new one...`);
-      const result = await provisionSession({
-        apiBaseUrl: options.apiBaseUrl,
-        apiKey: resolveApiKey(),
-        ...options.args.json ? {} : {
-          onStageChange: (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage])
-        }
-      });
-      const sessionId = finalizeProvision(result, options.spinner);
-      await streamTurn({ ...options, sessionId, apiKey: resolveApiKey() });
-      return;
+    const sessionGone = isSessionGoneError(err);
+    const ambiguousGone = err instanceof ChatUpstreamError && err.errCode === ErrCode.INVALID_PARAM_FORMAT;
+    if (!sessionGone && !ambiguousGone) {
+      throw err;
     }
-    throw err;
+    if (options.progress.emitted) {
+      throw new Error(`Session ${options.sessionId} failed after this turn had already started.
+` + "  → The partial result above stands; re-run the same prompt to continue in a new session.");
+    }
+    if (!options.recreateOnGone) {
+      if (sessionGone || options.args.session) {
+        throw new SessionNotFoundError(options.sessionId);
+      }
+      throw err;
+    }
+    if (ambiguousGone) {
+      let confirmedGone = false;
+      try {
+        await ensureSessionExists({
+          apiBaseUrl: options.apiBaseUrl,
+          apiKey: resolveApiKey(),
+          sessionId: options.sessionId
+        });
+      } catch (checkErr) {
+        confirmedGone = checkErr instanceof SessionNotFoundError;
+      }
+      if (!confirmedGone) {
+        throw err;
+      }
+    }
+    consola.warn(`Session ${options.sessionId} is no longer available. Provisioning a new one...`);
+    const sessionId = await provisionNewSession({
+      apiBaseUrl: options.apiBaseUrl,
+      apiKey: resolveApiKey(),
+      spinner: options.spinner,
+      quiet: options.args.json === true,
+      prompt: buildNotePrompt(options.prompt, options.attachments)
+    });
+    await streamTurn({
+      ...options,
+      sessionId,
+      apiKey: resolveApiKey()
+    });
   }
 }
 var chatCommand = defineCommand({
@@ -18147,7 +18522,11 @@ var chatCommand = defineCommand({
     },
     session: {
       type: "string",
-      description: "Session id to chat with; becomes the default session for future runs"
+      description: "Chat in an existing session id (verified upstream); becomes the default session. A missing id fails — create one with --new"
+    },
+    new: {
+      type: "boolean",
+      description: "Create a new session and chat in it; becomes the default session"
     },
     "show-reasoning": {
       type: "boolean",
@@ -18159,6 +18538,16 @@ var chatCommand = defineCommand({
     const spinner = new AgentSpinner;
     try {
       const apiBaseUrl = resolveApiBaseUrl();
+      if (args.new && args.session) {
+        throw new Error("--new and --session cannot be combined: --session selects an existing session, --new creates one.");
+      }
+      if (args.session) {
+        await ensureSessionExists({
+          apiBaseUrl,
+          apiKey: resolveApiKey(),
+          sessionId: args.session
+        });
+      }
       const { text, skillUrls, autoEnabled } = await resolvePromptSkills({
         prompt: args.prompt,
         apiBaseUrl,
@@ -18177,6 +18566,8 @@ var chatCommand = defineCommand({
       });
       const resolved = await resolveChatSession({
         sessionFlag: args.session,
+        newSession: args.new,
+        prompt: buildNotePrompt(promptWithAttachments, attachments),
         apiBaseUrl,
         apiKey: resolveApiKey(),
         spinner,
@@ -18187,6 +18578,7 @@ var chatCommand = defineCommand({
         prompt: promptWithAttachments,
         sessionId: resolved.sessionId,
         recreateOnGone: resolved.recreateOnGone,
+        progress: { emitted: false },
         apiBaseUrl,
         apiKey: resolveApiKey(),
         spinner,
@@ -18243,7 +18635,11 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
 
   msc whoami
     Displays your current account information (user, email, UID, server URL).
-    Exits 0 if authenticated, 1 if unauthenticated or session expired.
+    Exits 0 only when the platform confirmed the session, and the fields it
+    prints are the platform's answer. Exits 1 otherwise - unauthenticated,
+    expired, or the request never reached the platform (DNS, refused, TLS):
+    a saved credential describes a session that was never checked, so it is
+    never printed in place of an answer.
 
   msc logout
     Removes saved credentials on this machine.
@@ -18285,8 +18681,16 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
     "no such file". Remote URLs are not attachments and there is no @url form.
 
   Session Switching:
-    Pass \`--session <id>\` to direct a prompt to a specific existing session
-    and make it your new active session.
+    Pass \`--session <id>\` to direct a prompt to an existing session and make it
+    your new active session. The id is verified against the server first: the
+    CLI only ever selects sessions that exist, so an unknown id fails with a
+    hint instead of silently starting a different conversation.
+
+    Pass \`--new\` to start a fresh session (new id, never reused) and chat in
+    it, ignoring the current default. \`--new\` and \`--session\` are mutually
+    exclusive.
+      msc chat "start over" --new      # new session, new context
+      msc sessions                     # pick an existing id for --session
 
 4. USING SKILLS
 
@@ -18301,7 +18705,7 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
     msc skills add <slug>          # add a skill from the plaza to your library
 
   Referencing Skills in Prompts:
-    Lead the prompt with your skill reference — the message must start with it
+    Lead the prompt with your skill reference - the message must start with it
     for the skill to activate:
       Slash form:     msc chat "/<name> your prompt here"
       Marker form:    msc chat "%%/<name>%% your prompt here"
@@ -18327,7 +18731,13 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
     including download URLs and model metadata.
 
   msc sessions use <session-id>
-    Switch your active session pointer without sending a prompt.
+    Switch your active session pointer to an existing session. The id is
+    verified against the server; an unknown id fails here and leaves the
+    pointer untouched.
+
+  msc sessions use --new
+    Create a new session upstream and switch the pointer to it, without sending
+    a prompt.
 
   Session deletion is not available in the CLI. Open the corresponding session
   in the Media Studio web app and delete it there manually.
@@ -18371,17 +18781,92 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url}`).join(`
   Extracting the result URL (e.g. with jq):
     url=$(msc chat "a red balloon" --json | jq -r '.media[0].resultUrl')
 
+  Exit codes: 0 = the turn ran to completion OR its stream ended early; 1 =
+  \`status: "error"\`, a usage error, or any other failure. Only what the parser
+  itself rejects (unknown flag, missing \`<prompt>\`) exits 1 before the command
+  runs with an empty stdout; argument conflicts checked inside the command --
+  \`--new\` with \`--session\`, \`sessions use --new <id>\` -- do print the error
+  payload below. Either way, check the exit code first, then branch on
+  \`.status\`.
+  Exit code 1 does not imply a payload. A bare transport failure -- the host
+  does not resolve, the port is refused, TLS fails -- is printed by the runtime
+  with its \`cause\` chain instead, so \`--json\` stdout stays empty there: to
+  tell "could not reach the platform" from "the platform answered with a
+  failure", read the exit code, then check whether stdout has a payload at all.
+  \`"success" | "incomplete" | "error"\` are \`chat\`-envelope values: \`chat\` is
+  the only command whose *success* payload carries a \`status\`, and every
+  command that supports \`--json\` puts \`"status": "error"\` on its failure
+  payload. \`login\`, \`logout\` and \`whoami\` define no \`--json\` and emit no
+  payload at all -- their failures are prose on stderr with exit 1. Do not
+  reuse that vocabulary elsewhere -- \`sessions --json\` items carry
+  \`status: { chat, task }\` (a boolean pair) and \`sessions artifacts <id> --json\`
+  items carry the task lifecycle
+  (\`pending | running | processing | completed | failed | cancelled\`).
+  Human stdout carries no status marker -- an early end only warns on
+  stderr -- so never parse it in scripts.
+
   Error schema on failure (exit code 1):
     {
       "status": "error",
       "message": "string",         // human-readable error description
       "errCode": 12345,            // optional platform error code
       "httpStatus": 401,           // optional HTTP status code
-      "nextStep": "relogin"        // recommended action keyword
+      "nextStep": "relogin",       // recommended action keyword
+      "guidance": "string?",       // present when nextStep names an action;
+                                   // absent for nextStep "none"
+      "transportCode": "ECONNREFUSED" // optional: errno of a transport failure
+                                   // the error wraps, when it had one
+    }
+
+  Classifying a failure (branch on these fields, not on message prose):
+    A consumer reads \`errCode\`, \`httpStatus\`, \`nextStep\` and
+    \`transportCode\` - never the prose in \`message\`, which is written for a
+    human and may change between versions.
+    \`errCode\`, \`httpStatus\`, \`nextStep\` and \`transportCode\` are optional
+    on *every* failure. All four absent means unclassified: nothing structured
+    to act on, so report the payload as-is.
+    \`transportCode\` is diagnostic, not a branch: it names the errno a
+    transport failure left on the error's cause chain when a wrapper copied
+    only the constant message. A bare transport failure does not reach this
+    reporter at all - the runtime prints it with its cause chain and the
+    command exits 1.
+
+  A rejected saved credential (auth.json's apiUrl is off the CLI allowlist)
+  reports the same error shape with no errCode/httpStatus - nothing came from
+  the platform - and nextStep "relogin", because \`msc login\` rewrites the file:
+    {
+      "status": "error",
+      "message": "Untrusted apiUrl in the saved credential: ...",
+      "nextStep": "relogin",
+      "guidance": "Run \`msc login\` to re-authenticate; ..."
     }
+  With no credential at all the payload stays minimal (status + message only),
+  so an agent can tell "credential file rejected" from "not logged in" without
+  reading the message.
+
+  A chat turn whose stream is open and then ends before the finish event --
+  the connection dropped, or the response was truncated -- is not a failure: it
+  exits 0 with \`status: "incomplete"\` and whatever
+  \`text\`/\`steps\`/\`media\` had arrived. An early end may therefore carry an
+  empty \`text\` and an empty \`media\` array, so do not treat \`incomplete\` as
+  proof that a partial result exists. This applies once the turn has observed
+  any frame at all; a stream request that fails before that -- the host does not
+  resolve, the port is refused, TLS fails, and no event ever arrived -- never
+  reaches \`incomplete\`: it is \`status: "error"\` with exit 1, carrying the
+  errno in \`transportCode\` (and naming it in \`message\`). A
+  platform error (an upstream \`error\` frame, or a non-2xx response) is likewise
+  \`status: "error"\` with exit 1.
+
+  Session commands:
+    msc sessions --json              # list: [{ sessionId, note, ... }]
+    msc sessions use <id> --json     # { "sessionId": "string" }
+    msc sessions use --new --json    # { "sessionId": "string" } (newly created)
+    \`--session\`/\`use <id>\` verify the id upstream; an unknown id exits 1 with
+    the \`--new\` hint and leaves the default session untouched.
 
   Recommended next steps:
-    relogin          Session expired or missing; run \`msc login\`
+    relogin          Session expired or missing, or a saved credential was
+                     rejected (its apiUrl is off the allowlist); run \`msc login\`
     retry_later      Rate limit reached; wait before re-sending
     top_up_balance   Insufficient balance; top up your account
     fix_input        Invalid parameters or prompt; adjust input
@@ -19294,7 +19779,7 @@ function applyForHost(urlString) {
   return true;
 }
 function applyInsecureTlsIfRequested() {
-  const target = readAuthFile()?.apiUrl || getDefaultApiBaseUrl();
+  const target = readAuthFileIfUsable()?.apiUrl || getDefaultApiBaseUrl();
   return applyForHost(target);
 }
 function applyInsecureTlsForUrl(urlString) {
@@ -20167,37 +20652,36 @@ var loginCommand = defineCommand({
     }
   },
   run: async ({ args }) => {
-    try {
-      if (process.env.CI || process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
-        throw new Error(`Browser sign-in needs a graphical session on this machine, so it cannot complete here.
+    if (process.env.CI || process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+      throw new Error(`Browser sign-in needs a graphical session on this machine, so it cannot complete here.
 ` + "Run `msc login` from a terminal on a machine whose browser is signed in to Media Studio.\n" + "See `msc guide` for the full authentication flow.");
+    }
+    let targetApiUrl;
+    if (args.region) {
+      targetApiUrl = matchRegionUrl(args.region);
+    } else if (process.env.CI || false || !process.stdin.isTTY) {
+      targetApiUrl = SERVERS.default.url;
+    } else {
+      const answer = await select({
+        message: "Select server:",
+        options: getAvailableRegions().map((opt) => ({
+          label: opt.label,
+          value: opt.url
+        })),
+        initialValue: SERVERS.default.url
+      });
+      if (isCancel(answer)) {
+        process.exit(130);
       }
-      let targetApiUrl;
-      if (args.region) {
-        targetApiUrl = matchRegionUrl(args.region);
-      } else if (process.env.CI || false || !process.stdin.isTTY) {
-        targetApiUrl = SERVERS.default.url;
-      } else {
-        const answer = await select({
-          message: "Select server:",
-          options: getAvailableRegions().map((opt) => ({
-            label: opt.label,
-            value: opt.url
-          })),
-          initialValue: SERVERS.default.url
-        });
-        if (isCancel(answer)) {
-          process.exit(130);
-        }
-        targetApiUrl = String(answer);
-      }
-      applyInsecureTlsForUrl(targetApiUrl);
-      const apiUrl = resolveApiBaseUrl(targetApiUrl);
-      consola.info("Opening browser for sign-in...");
-      if (!process.stdin.isTTY) {
-        const regionList = getAvailableRegions().map((r) => `  - ${r.key.padEnd(8)}: ${r.url} (${r.description})`).join(`
+      targetApiUrl = String(answer);
+    }
+    applyInsecureTlsForUrl(targetApiUrl);
+    const apiUrl = resolveApiBaseUrl(targetApiUrl);
+    consola.info("Opening browser for sign-in...");
+    if (!process.stdin.isTTY) {
+      const regionList = getAvailableRegions().map((r) => `  - ${r.key.padEnd(8)}: ${r.url} (${r.description})`).join(`
 `);
-        process.stdout.write(`Sign-in needs a human at a browser on this machine:
+      process.stdout.write(`Sign-in needs a human at a browser on this machine:
 ` + `  1. already signed in to the Media Studio web app there -> completes at once
 ` + `  2. not signed in -> a browser opens; a human finishes it within 120s
 ` + `
@@ -20207,29 +20691,24 @@ ${regionList}
 ` + `
 ` + `If you are an agent, ask the user to sign in to the web app in their browser first
 ` + "or ask the user to run `msc login` in their own terminal,\n" + "then poll `msc whoami` until it succeeds.\n");
-      }
-      const result = await runLoopbackLogin({
-        apiUrl,
-        onUrl: (url) => {
-          consola.info(`If your browser does not open automatically, visit:
+    }
+    const result = await runLoopbackLogin({
+      apiUrl,
+      onUrl: (url) => {
+        consola.info(`If your browser does not open automatically, visit:
   ${url}
 ` + "Signed in to the Media Studio web app in that browser already? This completes without a prompt.");
-        }
-      });
-      saveAuthFile({
-        token: result.token,
-        apiUrl,
-        uid: result.uid,
-        username: result.username,
-        email: result.email,
-        updated_at: new Date().toISOString()
-      });
-      consola.success("Successfully logged in!");
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      consola.error(message);
-      process.exit(1);
-    }
+      }
+    });
+    saveAuthFile({
+      token: result.token,
+      apiUrl,
+      uid: result.uid,
+      username: result.username,
+      email: result.email,
+      updated_at: new Date().toISOString()
+    });
+    consola.success("Successfully logged in!");
   }
 });
 
@@ -20254,7 +20733,7 @@ function renderSessionsTable(sessions, currentSessionId) {
     id: s.id === currentSessionId ? `${s.id} (current)` : s.id,
     source: s.source,
     lastActive: formatLastActive(s.lastActiveAt),
-    note: s.note ? s.note.replace(/\r?\n/g, " ").trim() : "-"
+    note: s.note ? s.note.replace(/\r?\n/g, " ").trim() || CLI_DEFAULT_SESSION_NOTE : CLI_DEFAULT_SESSION_NOTE
   }));
   const headers = {
     id: "ID",
@@ -20327,6 +20806,8 @@ var listSessionsCommand = defineCommand({
       const currentId = readLastSessionId();
       consola.log(renderSessionsTable(response.data, currentId));
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20365,6 +20846,8 @@ var artifactsCommand = defineCommand({
       }
       consola.log(renderArtifactsTable(response.data));
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20372,18 +20855,66 @@ var artifactsCommand = defineCommand({
 var useSessionCommand = defineCommand({
   meta: {
     name: "use",
-    description: "Switch default session (local pointer only, no network request)"
+    description: "Switch the default session to an existing session, or create a fresh one with --new"
   },
   args: {
     sessionId: {
       type: "positional",
-      required: true,
-      description: "Session id to set as default"
+      required: false,
+      description: "Existing session id to set as default"
+    },
+    new: {
+      type: "boolean",
+      description: "Create a new session and make it the default"
+    },
+    json: {
+      type: "boolean",
+      alias: "j",
+      description: "Output machine-readable JSON: { sessionId }"
     }
   },
-  run: ({ args }) => {
-    saveLastSessionId(args.sessionId);
-    consola.success(`Switched default session to ${args.sessionId}`);
+  run: async ({ args }) => {
+    try {
+      const sessionId = args.sessionId;
+      const apiBaseUrl = resolveApiBaseUrl();
+      if (args.new) {
+        if (sessionId) {
+          throw new Error("--new and <session-id> cannot be combined: pass one, not both.");
+        }
+        const result = await provisionSession({
+          apiBaseUrl,
+          apiKey: resolveApiKey(),
+          note: CLI_DEFAULT_SESSION_NOTE
+        });
+        const created = finalizeProvision(result);
+        if (args.json) {
+          process.stdout.write(`${JSON.stringify({ sessionId: created })}
+`);
+          return;
+        }
+        consola.success(`Created and switched to session ${created}`);
+        return;
+      }
+      if (!sessionId) {
+        throw new Error("Pass the session id to switch to, or --new to create a new session.");
+      }
+      await ensureSessionExists({
+        apiBaseUrl,
+        apiKey: resolveApiKey(),
+        sessionId
+      });
+      saveLastSessionId(sessionId);
+      if (args.json) {
+        process.stdout.write(`${JSON.stringify({ sessionId })}
+`);
+        return;
+      }
+      consola.success(`Switched default session to ${sessionId}`);
+    } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
+      reportCommandError(err, { json: args.json });
+    }
   }
 });
 var sessionsCommand = defineCommand({
@@ -20458,6 +20989,8 @@ var addSkillCommand = defineCommand({
       }
       consola.success(`Installed ${stripControlChars(skill.command)} (${stripControlChars(skill.name)}).`);
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20509,6 +21042,8 @@ var rmSkillCommand = defineCommand({
       }
       consola.success(`Skill "${args["skill-command"]}" removed from your library.`);
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20540,6 +21075,8 @@ function makeSetEnabledCommand(name, enabled, description) {
         }
         consola.success(`${enabled ? "Enabled" : "Disabled"} ${stripControlChars(skill.command)}.`);
       } catch (err) {
+        if (isTransportFailure(err))
+          throw err;
         reportCommandError(err, { json: args.json });
       }
     }
@@ -20632,13 +21169,14 @@ var skillsCommand = defineCommand({
       ].join(`
 `));
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
 });
 
 // src/commands/whoami.ts
-var import_picocolors3 = __toESM(require_picocolors(), 1);
 function maskToken(token) {
   return `${token.slice(0, 10)}...${token.slice(-6)}`;
 }
@@ -20648,7 +21186,16 @@ var whoamiCommand = defineCommand({
     description: "Display current authentication status"
   },
   run: async () => {
-    const auth = readAuthFile();
+    let auth;
+    try {
+      auth = readAuthFile();
+    } catch (err) {
+      consola.error(err instanceof Error ? err.message : String(err));
+      consola.error(`
+  → ${NEXT_STEP_GUIDANCE.relogin}`);
+      process.exit(1);
+      return;
+    }
     if (!auth) {
       consola.error("Not logged in. Run `msc login` to authenticate - it opens a browser, so a human must complete it.");
       process.exit(1);
@@ -20670,13 +21217,17 @@ var whoamiCommand = defineCommand({
       const updatedUid = data.uid ?? auth.uid;
       const updatedEmail = data.email ?? auth.email;
       if (updatedName !== auth.username || updatedUid !== auth.uid || updatedEmail !== auth.email) {
-        saveAuthFile({
-          ...auth,
-          token: client.apiKey,
-          username: updatedName,
-          uid: updatedUid,
-          email: updatedEmail
-        });
+        try {
+          saveAuthFile({
+            ...auth,
+            token: client.apiKey,
+            username: updatedName,
+            uid: updatedUid,
+            email: updatedEmail
+          });
+        } catch (err) {
+          consola.warn(err instanceof Error ? err.message : String(err));
+        }
       }
       consola.success("Authenticated");
       const lines = [
@@ -20684,27 +21235,16 @@ var whoamiCommand = defineCommand({
         updatedUid ? `  UID:      ${updatedUid}` : null,
         updatedEmail ? `  Email:    ${updatedEmail}` : null,
         data.apiKeyMasked ? `  API Key:  ${data.apiKeyMasked}` : null,
-        `  Token:    ${maskToken(auth.token)}`,
-        auth.updated_at ? import_picocolors3.gray(`  Saved:    ${auth.updated_at}`) : null
+        `  Token:    ${maskToken(client.apiKey)}`
       ].filter(Boolean);
       consola.log(`${lines.join(`
 `)}
 `);
-      return;
     } catch (err) {
-      const isNetworkError = err instanceof TypeError && /fetch failed|failed to fetch/i.test(err.message) || isObject2(err) && "code" in err && isString(err.code) && (err.code === "ECONNREFUSED" || err.code === "ENOTFOUND" || err.code === "ETIMEDOUT" || err.code === "EHOSTUNREACH");
-      if (!isNetworkError) {
-        reportCommandError(err);
-        return;
-      }
+      if (isTransportFailure(err))
+        throw err;
+      reportCommandError(err);
     }
-    consola.info("Authentication Status (Cached)");
-    consola.log(`  Token:  ${maskToken(auth.token)}
-` + (auth.username ? `  User:   ${auth.username}
-` : "") + (auth.uid ? `  UID:    ${auth.uid}
-` : "") + (auth.email ? `  Email:  ${auth.email}
-` : "") + (auth.updated_at ? import_picocolors3.gray(`  Saved:  ${auth.updated_at}
-`) : ""));
   }
 });
 
@@ -20763,6 +21303,8 @@ AGENT QUICKSTART
   1. msc login                   # a human must finish this in a browser; instant if
                                  # that browser is already signed in to the web app
   2. msc chat "a red car" --json # one turn; the conversation continues across runs
+                                 # (--new starts a fresh session, --session <id> picks
+                                 #  an existing one; both are verified)
   3. msc skills --plaza --json   # find a skill, then reference it by leading the
                                  # prompt with /name or %%/name%%
 
@@ -20774,6 +21316,10 @@ AGENT QUICKSTART
   Failure exits 1 with a JSON error carrying message, errCode, httpStatus and
   nextStep, which is the action to take:
   relogin | retry_later | top_up_balance | fix_input | retry | none.
+  A rejected saved credential (auth.json's apiUrl is off the allowlist) reports
+  no errCode/httpStatus - nothing came from the platform - and nextStep
+  "relogin", since \`msc login\` rewrites the file. No credential at all reports
+  no nextStep, so the two states differ without parsing the message.
   A turn reports status "success", or "incomplete" if the stream ended early.
 `;
 await runMain({