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

package/README.md

@@ -115,9 +115,22 @@ The CLI stores credentials and local settings in:
 - **Override**: `MEDIA_STUDIO_CONFIG_DIR=/path/to/dir`
 
 Key files:
-- `auth.json`: stores active platform credentials and user session metadata (permissions `0600`)
+- `auth.json`: stores active platform credentials and user session metadata (permissions `0600` on POSIX)
 - `config.json`: stores CLI client settings, including `lastSessionId` pointer
 
+`auth.json`'s `apiUrl` is only accepted when its host is on the CLI allowlist:
+the official hosts (which the rejection message lists) plus the local-dev
+hosts `localhost` / `127.0.0.1` / `::1`. A hand-edited URL outside that list is
+refused before any request is sent, and the CLI reports it as a rejected
+credential naming the URL — not as "not logged in", since the token itself may
+be fine. `msc login` rewrites the file with a server-supplied URL and is the
+fix; the refused URL is never used, and base-URL resolution falls back to the
+official default host.
+
+In `--json` mode the two auth states are distinguishable without reading the
+message: a rejected credential carries `"nextStep": "relogin"` (and its
+`guidance`), while no credential at all reports `status` and `message` only.
+
 ### Skills
 
 Discover what your account can reference, then reference it — the reference

package/dist/index.js

@@ -4284,7 +4284,7 @@ var consola = createConsola2();
 // package.json
 var package_default = {
   name: "@302ai/media-studio-cli",
-  version: "0.1.1-beta.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}`;
 }
@@ -10073,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)
@@ -10094,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);
@@ -16875,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(),
@@ -16891,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;
   }
@@ -16949,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.");
   }
@@ -16958,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;
@@ -16969,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({
@@ -17438,7 +17485,7 @@ class MediaStudioClient {
         const nextKey = rotatedToken.trim();
         this._apiKey = nextKey;
         try {
-          const authData = readAuthFile();
+          const authData = readAuthFileIfUsable();
           if (authData) {
             saveAuthFile({
               ...authData,
@@ -17761,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) {
@@ -17774,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)}
 `);
@@ -18003,6 +18091,16 @@ function isSessionGoneError(err) {
     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,
@@ -18010,8 +18108,7 @@ async function ensureSessionExists(options) {
   });
   if (await client.sessions.exists(options.sessionId))
     return;
-  throw new Error(`Session ${options.sessionId} does not exist.
-` + '  → Create one: `msc sessions use --new`, or `msc chat --new "<prompt>"` to also send a prompt.');
+  throw new SessionNotFoundError(options.sessionId);
 }
 function finalizeProvision(result, spinner) {
   spinner?.stop();
@@ -18032,6 +18129,7 @@ async function provisionSession(options) {
   const outcome = await client.sessions.prewarm({
     sessionId,
     source: "cli",
+    note: options.note ?? CLI_DEFAULT_SESSION_NOTE,
     onSessionReady: () => saveLastSessionId(sessionId),
     onStageChange: options.onStageChange
   });
@@ -18094,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);
@@ -18167,11 +18265,21 @@ function printTerminalMediaAssets(mediaAssets, fullText) {
   process.stdout.write(`====================
 `);
 }
+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);
@@ -18179,7 +18287,10 @@ async function provisionNewSession(options) {
 async function resolveChatSession(options) {
   if (options.newSession) {
     return {
-      sessionId: await provisionNewSession(options),
+      sessionId: await provisionNewSession({
+        ...options,
+        prompt: options.prompt
+      }),
       recreateOnGone: false
     };
   }
@@ -18192,10 +18303,22 @@ async function resolveChatSession(options) {
     return { sessionId: pointer, recreateOnGone: true };
   }
   return {
-    sessionId: await provisionNewSession(options),
+    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;
   if (!args.json) {
@@ -18215,87 +18338,103 @@ async function streamTurn(options) {
   const steps = [];
   const mediaAssets = [];
   let hasFinished = false;
-  for await (const ev of stream) {
-    if (ev.type !== "finish" && ev.type !== "error") {
-      options.progress.emitted = true;
-    }
-    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",
@@ -18321,30 +18460,48 @@ async function runTurn(options) {
     await streamTurn(options);
   } catch (err) {
     const sessionGone = isSessionGoneError(err);
-    if (sessionGone && options.progress.emitted) {
+    const ambiguousGone = err instanceof ChatUpstreamError && err.errCode === ErrCode.INVALID_PARAM_FORMAT;
+    if (!sessionGone && !ambiguousGone) {
+      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 (sessionGone && !options.recreateOnGone) {
-      throw new Error(`Session ${options.sessionId} does not exist.
-` + '  → Create one: `msc sessions use --new`, or `msc chat --new "<prompt>"` to also send a prompt.');
+    if (!options.recreateOnGone) {
+      if (sessionGone || options.args.session) {
+        throw new SessionNotFoundError(options.sessionId);
+      }
+      throw err;
     }
-    if (sessionGone) {
-      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
-      });
-      await streamTurn({
-        ...options,
-        sessionId,
-        apiKey: resolveApiKey()
-      });
-      return;
+    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;
+      }
     }
-    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({
@@ -18410,6 +18567,7 @@ var chatCommand = defineCommand({
       const resolved = await resolveChatSession({
         sessionFlag: args.session,
         newSession: args.new,
+        prompt: buildNotePrompt(promptWithAttachments, attachments),
         apiBaseUrl,
         apiKey: resolveApiKey(),
         spinner,
@@ -18477,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.
@@ -18543,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"
@@ -18619,15 +18781,82 @@ ${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" }
@@ -18636,7 +18865,8 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url}`).join(`
     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
@@ -19549,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) {
@@ -20422,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
 ` + `
@@ -20462,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!");
   }
 });
 
@@ -20509,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",
@@ -20582,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 });
     }
   }
@@ -20620,6 +20846,8 @@ var artifactsCommand = defineCommand({
       }
       consola.log(renderArtifactsTable(response.data));
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20655,7 +20883,8 @@ var useSessionCommand = defineCommand({
         }
         const result = await provisionSession({
           apiBaseUrl,
-          apiKey: resolveApiKey()
+          apiKey: resolveApiKey(),
+          note: CLI_DEFAULT_SESSION_NOTE
         });
         const created = finalizeProvision(result);
         if (args.json) {
@@ -20682,6 +20911,8 @@ var useSessionCommand = defineCommand({
       }
       consola.success(`Switched default session to ${sessionId}`);
     } catch (err) {
+      if (isTransportFailure(err))
+        throw err;
       reportCommandError(err, { json: args.json });
     }
   }
@@ -20758,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 });
     }
   }
@@ -20809,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 });
     }
   }
@@ -20840,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 });
       }
     }
@@ -20932,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)}`;
 }
@@ -20948,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);
@@ -20970,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 = [
@@ -20984,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}
-`) : ""));
   }
 });
 
@@ -21076,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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@302ai/media-studio-cli",
-  "version": "0.1.1-beta.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",