@productlobster/plob 0.1.4 → 0.1.5

package/dist/cli.js

@@ -24,10 +24,10 @@ A full analysis is asynchronous and durable. The loop is the same for every work
 
 1. **Start.** Call \`run-start\` with a \`workflow\` of \`launch\`, \`audit\`, \`focused-analysis\`, \`prototype\`, or \`refinement\`, plus its inputs. It returns a run id. For \`prototype\`, the returned id is a prototype id, not a run id: track it with \`prototype-list\` and fetch it with \`prototype-pack\`, not \`run-status\`. If your request is too thin, it returns a \`needs_sharpening\` result that lists what to add \u2014 add detail and call \`run-start\` again.
 2. **Poll.** Call \`run-status\` with the run id. It reports the current status and returns a \`since\` cursor; pass that cursor on the next poll to get only what changed. Runs take minutes \u2014 poll, do not block. Stop polling when the run's \`status\` is \`completed\`, \`failed\`, or \`cancelled\`. Do not wait for every stage to leave \`pending\`: a run that fails or is cancelled part-way leaves its unstarted stages \`pending\` permanently, and on a finished run \`pending\` means the stage never ran.
-3. **Resolve checkpoints.** When \`run-status\` reports that the run is waiting at a checkpoint, it lists the options. Pick one and call \`checkpoint-resolve\` with the run id and an \`optionId\` taken from that list. An invented or stale id is rejected.
+3. **Resolve checkpoints.** When \`run-status\` reports that the run is waiting at a checkpoint, it lists the options. Pick one and call \`checkpoint-resolve\` with the run id and an \`optionId\` taken from that list. An invented or stale id is rejected. The run resumes in the background, so the answer and the next few \`run-status\` polls (often a minute or more) can still say \`checkpoint_pending\`. \`resumePending: true\` (on the answer, or on the \`checkpoint\` block of \`run-status\`) means your selection is recorded and the run is resuming: keep polling, and do not resolve again. A successful answer with \`resumePending: false\` usually means another accept of the same decision is still being recorded, so keep polling; if \`run-status\` keeps listing the options without \`resumePending: true\`, resolving again with the same \`optionId\` is safe.
 4. **Read the result.** When the run is complete, \`run-output\` returns the structured result as generated. Its \`stageEdits\` list marks each stage whose document the user has changed since (\`hasUserEdits: true\`). When such an entry also carries a \`documentId\`, read that document with \`document-get\` rather than relying on the structured result. An entry with \`hasUserEdits: true\` and no \`documentId\` means the stage was edited but its document is not available through \`document-get\`; use \`output\` for that stage. Use \`document-list\` and \`document-get\` to read the documents the run produced, and \`prototype-list\` / \`prototype-pack\` for any prototype.
 
-Other run controls: \`run-cancel\` stops a run that is still in progress and acknowledges every call, a finished run included, so confirm the outcome with \`run-status\`; \`run-replay\` re-runs one, optionally from a stage.
+Other run controls: \`run-cancel\` stops a run that is still in progress. It answers \`cancelled: true\` for every accepted call, a finished run included, so check \`alreadyTerminal\`: \`true\` means the run had already stopped and this call changed nothing. Its \`status\` is the run's status after the call. \`run-replay\` re-runs a run, optionally from a stage.
 
 ## Reading and writing workspace context
 
@@ -53,9 +53,9 @@ Every failure is a structured object: \`{ code, message, requestId, retryHint }\
 | --- | --- | --- |
 | \`unauthorized\` | Key missing, revoked, or wrong | Ask the person to check or rotate the key |
 | \`unauthorized_scope\` | Key lacks the scope this tool needs | Ask the person to create a key with that permission |
-| \`workspace_mismatch\` | Argument points outside the bound workspace (or a fabricated id) | Use ids returned by this surface; do not invent them |
+| \`workspace_mismatch\` | Argument points outside the bound workspace | Use ids returned by this surface; do not invent them |
 | \`needs_sharpening\` | A run request was too thin | Add the detail the result lists, then retry |
-| \`invalid_arguments\` | A field was the wrong shape | Fix the named fields and retry |
+| \`invalid_arguments\` | A field was the wrong shape, or a checkpoint \`optionId\` was not one of the options offered | Fix the named fields and retry; for \`optionId\`, copy an id from the options \`run-status\` lists |
 | \`idempotency_key_reuse\` | The idempotency key was already used for a different write | Use a new key for a new write; reuse a key only to retry the same write |
 | \`conflict\` | State changed under you (e.g. a stale document token) | Re-read the current state, then retry |
 | \`rate_limited\` | Daily call budget or a short spike | Wait for the reset the result reports |
@@ -19868,7 +19868,12 @@ var checkpointResolveInputSchema = external_exports.object({
 var checkpointResolveOutputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the resolved run."),
   resolved: external_exports.literal(true).describe("The checkpoint was resolved; resume polling run-status."),
-  resumedStatus: runStatusEnum.describe("Coarse status the run resumed into."),
+  resumedStatus: runStatusEnum.describe(
+    "Coarse status at the time of the answer; usually checkpoint_pending while the resume is in flight."
+  ),
+  resumePending: external_exports.boolean().optional().describe(
+    "True when the selection is recorded and the run is resuming in the background: keep polling run-status and do not resolve again. If false, keep polling; if later polls keep listing the options without resumePending true, resolving again with the same optionId is safe."
+  ),
   schemaVersion: schemaVersionSchema
 });
 
@@ -20304,7 +20309,13 @@ var runCancelInputSchema = external_exports.object({
 });
 var runCancelOutputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the cancelled run."),
-  cancelled: external_exports.literal(true).describe("The cancel was accepted; confirm via run-status."),
+  cancelled: external_exports.literal(true).describe(
+    "The cancel was accepted, or the run is already stopped; check alreadyTerminal."
+  ),
+  alreadyTerminal: external_exports.boolean().optional().describe(
+    "True when the run had already stopped and this call changed nothing."
+  ),
+  status: runStatusEnum.optional().describe("Coarse status of the run after this call."),
   schemaVersion: schemaVersionSchema
 });
 var runReplayInputSchema = external_exports.object({
@@ -20421,7 +20432,10 @@ var checkpointPayloadSchema = external_exports.object({
   options: external_exports.array(checkpointOptionSchema).describe("The strategic options to choose between."),
   keyDifferences: external_exports.string().describe("How the options differ from one another."),
   recommendationJustification: external_exports.string().describe("Why the recommended option is recommended."),
-  refineUrl: external_exports.string().describe("Hosted-app URL to refine this checkpoint set.")
+  refineUrl: external_exports.string().describe("Hosted-app URL to refine this checkpoint set."),
+  resumePending: external_exports.boolean().optional().describe(
+    "True when a selection is recorded and the run is resuming in the background: keep polling and do not resolve again. False after a successful checkpoint-resolve: keep polling; if later polls keep listing the options without resumePending true, resolving again with the same optionId is safe."
+  )
 });
 var runStatusInputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run to poll."),
@@ -20509,12 +20523,14 @@ var API_KEY_SECRET_PATTERN = /^ak_[\x21-\x7E]+$/;
 var KeyringCredentialStore = class {
   async deleteBearerToken() {
     const keyring = await import("@napi-rs/keyring");
-    const removed = await deleteKeyringPassword(keyring, KEYCHAIN_SERVICE);
-    const legacyRemoved = await deleteKeyringPassword(
-      keyring,
-      LEGACY_KEYCHAIN_SERVICE
-    );
-    return removed || legacyRemoved;
+    const removed = [];
+    if (await deleteKeyringPassword(keyring, KEYCHAIN_SERVICE)) {
+      removed.push(keychainCredentialLocation);
+    }
+    if (await deleteKeyringPassword(keyring, LEGACY_KEYCHAIN_SERVICE)) {
+      removed.push(legacyKeychainCredentialLocation);
+    }
+    return removed;
   }
   async loadBearerToken() {
     const keyring = await import("@napi-rs/keyring");
@@ -20599,6 +20615,10 @@ var keychainCredentialLocation = {
   account: KEYCHAIN_ACCOUNT,
   service: KEYCHAIN_SERVICE
 };
+var legacyKeychainCredentialLocation = {
+  account: KEYCHAIN_ACCOUNT,
+  service: LEGACY_KEYCHAIN_SERVICE
+};
 
 // src/runtime/exit-codes.ts
 var EXIT_CODES = {
@@ -20706,11 +20726,13 @@ async function createSdkMcpClient(config2) {
 function isUnsafeTerminalCodePoint(codePoint) {
   return codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 1564 || codePoint === 8206 || codePoint === 8207 || codePoint === 8232 || codePoint === 8233 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297;
 }
-function escapeTerminalText(value, maxCodePoints) {
+var LINE_FEED_CODE_POINT = 10;
+function escapeTerminalText(value, maxCodePoints, options = {}) {
   const codePoints = Array.from(value);
   const escaped = codePoints.slice(0, maxCodePoints).map((character) => {
     const codePoint = character.codePointAt(0) ?? 0;
-    return isUnsafeTerminalCodePoint(codePoint) ? `\\u${codePoint.toString(16).padStart(4, "0")}` : character;
+    const keep = options.keepLineBreaks && codePoint === LINE_FEED_CODE_POINT;
+    return isUnsafeTerminalCodePoint(codePoint) && !keep ? `\\u${codePoint.toString(16).padStart(4, "0")}` : character;
   }).join("");
   return codePoints.length > maxCodePoints ? `${escaped}\u2026` : escaped;
 }
@@ -20734,6 +20756,9 @@ var API_KEY_IN_TEXT_PATTERN = /ak_[^\s"'\\]+/g;
 var REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 var API_KEY_MARKER_PATTERN = /ak_/i;
 var DEBUG_DIAGNOSTIC_MAX_CODE_POINTS = 300;
+var FAILURE_MESSAGE_MAX_CODE_POINTS = 1e3;
+var FAILURE_RETRY_HINT_MAX_CODE_POINTS = 500;
+var FAILURE_UPGRADE_COMMAND_MAX_CODE_POINTS = 200;
 var defaultIo = {
   stdin: process.stdin,
   stderr: process.stderr,
@@ -20865,9 +20890,11 @@ function createCliOperationalError(input2) {
     input2.diagnostic
   );
 }
-function renderCliError(document, options, io, diagnostic) {
+function renderCliError(document, options, io, diagnostic, { keepMessageLineBreaks = false } = {}) {
   const exitCode2 = exitCodeForCliError(document.code);
-  renderFailure({ diagnostic, document, exitCode: exitCode2 }, options, io);
+  renderFailure({ diagnostic, document, exitCode: exitCode2 }, options, io, {
+    keepMessageLineBreaks
+  });
   return exitCode2;
 }
 function resolveRunnerDeps(overrides, io) {
@@ -21209,21 +21236,27 @@ function renderSuccess(response, spec, options, io) {
   io.stdout.write(`${JSON.stringify(response)}
 `);
 }
-function renderFailure(failure2, options, io) {
+function renderFailure(failure2, options, io, { keepMessageLineBreaks = false } = {}) {
   if (shouldRenderJson(options, io)) {
     io.stdout.write(`${JSON.stringify(failure2.document)}
 `);
   } else {
-    io.stderr.write(`Error: ${failure2.document.message}
-`);
+    io.stderr.write(
+      `Error: ${escapeTerminalText(failure2.document.message, FAILURE_MESSAGE_MAX_CODE_POINTS, { keepLineBreaks: keepMessageLineBreaks })}
+`
+    );
     const upgradeCommand = getUpgradeCommand(failure2.document.details);
     if (upgradeCommand) {
-      io.stderr.write(`Upgrade: ${upgradeCommand}
-`);
+      io.stderr.write(
+        `Upgrade: ${escapeTerminalText(upgradeCommand, FAILURE_UPGRADE_COMMAND_MAX_CODE_POINTS)}
+`
+      );
     }
     if (failure2.document.retryHint) {
-      io.stderr.write(`${failure2.document.retryHint}
-`);
+      io.stderr.write(
+        `${escapeTerminalText(failure2.document.retryHint, FAILURE_RETRY_HINT_MAX_CODE_POINTS)}
+`
+      );
     }
   }
   printDebugRequestId(options, io, failure2.document.requestId);
@@ -21476,8 +21509,7 @@ function runCheckpointResolveCommand(options) {
   return runCommand(
     {
       outputSchema: checkpointResolveOutputSchema,
-      renderHuman: (response) => `Run ${response.runId} resumed: ${response.resumedStatus}
-`,
+      renderHuman: renderCheckpointResolve,
       toolArguments: { runId: runId.value, optionId: optionId.value },
       toolName: "checkpoint-resolve"
     },
@@ -21488,6 +21520,15 @@ function runCheckpointResolveCommand(options) {
     }
   );
 }
+function renderCheckpointResolve(response) {
+  const poll = `plob run-status ${response.runId}`;
+  if (response.resumePending === true) {
+    return `Run ${response.runId}: selection recorded; the run is resuming in the background. Keep polling \`${poll}\` and don't resolve again.
+`;
+  }
+  return `Run ${response.runId}: selection accepted. Keep polling \`${poll}\`. If later polls keep listing the options without a recorded selection, resolving again with the same option id is safe.
+`;
+}
 
 // src/commands/context-pack.ts
 function registerContextPackCommand(program, options) {
@@ -22143,11 +22184,11 @@ async function runLogoutCommand(options) {
     options.io
   );
   let existingSecret;
-  let removed = false;
+  let removedEntries = [];
   try {
     existingSecret = await deps.credentialStore.loadBearerToken();
     if (existingSecret) {
-      removed = await deps.credentialStore.deleteBearerToken();
+      removedEntries = await deps.credentialStore.deleteBearerToken();
     }
   } catch {
     return renderCliError(
@@ -22164,7 +22205,7 @@ async function runLogoutCommand(options) {
   if (!existingSecret) {
     return renderMissingCredential(options);
   }
-  if (!removed) {
+  if (removedEntries.length === 0) {
     return renderCliError(
       createCliErrorDocument({
         code: "internal",
@@ -22178,7 +22219,8 @@ async function runLogoutCommand(options) {
     {
       data: {
         keychain: keychainCredentialLocation,
-        removed: true
+        removed: true,
+        removedEntries
       },
       schemaVersion: AGENTIC_CONTRACT_SCHEMA_VERSION
     },
@@ -22211,7 +22253,11 @@ function renderLogoutSuccess(document, options, io) {
 `);
     return;
   }
-  io.stdout.write("ProductLobster API key removed from the OS keychain.\n");
+  const services = document.data.removedEntries.map((entry) => entry.service).join(", ");
+  io.stdout.write(
+    `ProductLobster API key removed from the OS keychain: ${services}.
+`
+  );
 }
 
 // src/commands/observe.ts
@@ -22604,6 +22650,19 @@ function resolveSafeTarget(root, entryName) {
 }
 
 // src/commands/prototype-pack.ts
+var SIGNED_URL_MAX_REDIRECT_HOPS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+  301,
+  302,
+  303,
+  307,
+  308
+]);
+var PACK_NETWORK_FAILURE = {
+  code: "network",
+  message: "Unable to fetch the prototype ZIP. Check the network connection and retry.",
+  retryHint: "Retry after the connection is available."
+};
 function registerPrototypePackCommand(program, options) {
   const command = program.command("prototype-pack").description("Fetch a prototype ZIP reference.").requiredOption("--prototype-id <id>", "Prototype id.").option("--out <dir>", "New output directory (parent must already exist).");
   command.action(async (commandOptions) => {
@@ -22683,22 +22742,7 @@ async function fetchAndExtractPack(input2) {
       message: "The prototype ZIP URL must use https. Retry once; if it continues, report the failure."
     });
   }
-  let response;
-  try {
-    response = await fetch(input2.pack.url, {
-      headers,
-      // With the bearer attached, never replay it to wherever a redirect
-      // points; the non-2xx check below reports the redirect status.
-      ...headers.authorization ? { redirect: "manual" } : {}
-    });
-  } catch (error62) {
-    throw createCliOperationalError({
-      code: "network",
-      diagnostic: describeThrownError(error62),
-      message: "Unable to fetch the prototype ZIP. Check the network connection and retry.",
-      retryHint: "Retry after the connection is available."
-    });
-  }
+  const response = input2.pack.delivery === "authenticated_stream" ? await fetchPack(input2.pack.url, headers) : await fetchSignedPack(input2.pack.url);
   if (!response.ok) {
     const failure2 = await normalizeHttpResponseFailure(
       response,
@@ -22710,7 +22754,15 @@ async function fetchAndExtractPack(input2) {
       failure2.diagnostic
     );
   }
-  const archive = new Uint8Array(await response.arrayBuffer());
+  let archive;
+  try {
+    archive = new Uint8Array(await response.arrayBuffer());
+  } catch (error62) {
+    throw createCliOperationalError({
+      ...PACK_NETWORK_FAILURE,
+      diagnostic: `body unreadable: ${describeThrownError(error62)}`
+    });
+  }
   try {
     return await extractZipToDirectory(archive, input2.outDir);
   } catch (error62) {
@@ -22726,6 +22778,53 @@ async function fetchAndExtractPack(input2) {
     });
   }
 }
+async function fetchPack(url2, headers) {
+  try {
+    return await fetch(url2, { headers, redirect: "manual" });
+  } catch (error62) {
+    throw createCliOperationalError({
+      ...PACK_NETWORK_FAILURE,
+      diagnostic: describeThrownError(error62)
+    });
+  }
+}
+async function fetchSignedPack(initialUrl) {
+  let url2 = initialUrl;
+  for (let hop = 0; ; hop += 1) {
+    const response = await fetchPack(url2, {});
+    if (!REDIRECT_STATUSES.has(response.status)) {
+      return response;
+    }
+    response.body?.cancel().catch(() => void 0);
+    if (hop === SIGNED_URL_MAX_REDIRECT_HOPS) {
+      throw signedRedirectFailure("redirected too many times");
+    }
+    const location = response.headers.get("location");
+    if (!location) {
+      throw signedRedirectFailure("redirected without a target URL");
+    }
+    const next = resolveRedirectUrl(location, url2);
+    if (!(next && isHttpsOrLoopbackUrl(next))) {
+      throw signedRedirectFailure(
+        "redirected to a URL that does not use https"
+      );
+    }
+    url2 = next;
+  }
+}
+function resolveRedirectUrl(location, currentUrl) {
+  try {
+    return new URL(location, currentUrl).href;
+  } catch {
+    return;
+  }
+}
+function signedRedirectFailure(reason) {
+  return createCliOperationalError({
+    code: "internal",
+    message: `The prototype ZIP download ${reason}. Retry once; if it continues, report the failure.`
+  });
+}
 function bundleRouteFailure(status) {
   if (status === 401) {
     return {
@@ -22868,8 +22967,7 @@ function runRunCancelCommand(options) {
   return runCommand(
     {
       outputSchema: runCancelOutputSchema,
-      renderHuman: (response) => `Run ${response.runId} cancel accepted.
-`,
+      renderHuman: renderRunCancel,
       toolArguments: { runId: runId.value },
       toolName: "run-cancel"
     },
@@ -22880,6 +22978,15 @@ function runRunCancelCommand(options) {
     }
   );
 }
+function renderRunCancel(response) {
+  if (response.alreadyTerminal === true) {
+    const status = response.status ? ` (status: ${response.status})` : "";
+    return `Run ${response.runId} had already stopped${status}; this call changed nothing.
+`;
+  }
+  return `Run ${response.runId} cancel accepted.
+`;
+}
 
 // src/commands/run-output.ts
 function registerRunOutputCommand(program, options) {
@@ -23069,6 +23176,9 @@ function runRunStatusCommand(options) {
     }
   );
 }
+var CHECKPOINT_QUESTION_DISPLAY_MAX = 500;
+var CHECKPOINT_OPTION_ID_DISPLAY_MAX = 200;
+var CHECKPOINT_OPTION_TITLE_DISPLAY_MAX = 200;
 function renderRunStatus(response) {
   const lines = [`Run ${response.runId}: ${response.status}`];
   if (response.stages.length > 0) {
@@ -23081,11 +23191,7 @@ function renderRunStatus(response) {
     lines.push(`Transitions: ${response.transitions.length}`);
   }
   if (response.checkpoint) {
-    lines.push(`Pending decision: ${response.checkpoint.question}`);
-    for (const option of response.checkpoint.options) {
-      const marker = option.recommended ? " recommended" : "";
-      lines.push(`- ${option.id}: ${option.title}${marker}`);
-    }
+    lines.push(...renderCheckpoint(response.checkpoint));
   }
   if (response.nextCursor) {
     lines.push(`Next cursor: ${response.nextCursor}`);
@@ -23093,6 +23199,26 @@ function renderRunStatus(response) {
   return `${lines.join("\n")}
 `;
 }
+function renderCheckpoint(checkpoint) {
+  const question = escapeTerminalText(
+    checkpoint.question,
+    CHECKPOINT_QUESTION_DISPLAY_MAX
+  );
+  if (checkpoint.resumePending === true) {
+    return [`Decision recorded; the run is resuming. Checkpoint: ${question}`];
+  }
+  const lines = [`Pending decision: ${question}`];
+  for (const option of checkpoint.options) {
+    const id = escapeTerminalText(option.id, CHECKPOINT_OPTION_ID_DISPLAY_MAX);
+    const title = escapeTerminalText(
+      option.title,
+      CHECKPOINT_OPTION_TITLE_DISPLAY_MAX
+    );
+    const marker = option.recommended ? " recommended" : "";
+    lines.push(`- ${id}: ${title}${marker}`);
+  }
+  return lines;
+}
 
 // src/commands/upload.ts
 import { readFile as readFile2, stat } from "fs/promises";
@@ -23244,11 +23370,7 @@ async function runUploadCommand(options) {
     });
   } catch (error62) {
     return renderCliError(
-      createCliErrorDocument({
-        code: "network",
-        message: "Unable to reach ProductLobster. Check the network connection and retry.",
-        retryHint: "Retry after the connection is available."
-      }),
+      createNetworkErrorDocument(),
       options.globalOptions,
       options.io,
       describeThrownError(error62)
@@ -23257,7 +23379,7 @@ async function runUploadCommand(options) {
   if (!response.ok) {
     const failure2 = await normalizeHttpResponseFailure(
       response,
-      uploadRouteFailure
+      createUploadRouteFailure(prepared.extension)
     );
     return renderCliError(
       failure2.document,
@@ -23266,12 +23388,34 @@ async function runUploadCommand(options) {
       failure2.diagnostic
     );
   }
+  let bodyText;
+  try {
+    bodyText = await response.text();
+  } catch (error62) {
+    return renderCliError(
+      createCliErrorDocument({
+        code: "network",
+        message: "The connection to ProductLobster closed before the upload was confirmed. The upload may already have been stored.",
+        retryHint: "Check the workspace's documents in the ProductLobster app before uploading again."
+      }),
+      options.globalOptions,
+      options.io,
+      `body unreadable: ${describeThrownError(error62)}`
+    );
+  }
   const uploadResponse = normalizeUploadSuccessPayload(
-    parseResponsePayload(await response.text())
+    parseResponsePayload(bodyText)
   );
   renderUploadSuccess(uploadResponse, options.globalOptions, options.io);
   return EXIT_CODES.success;
 }
+function createNetworkErrorDocument() {
+  return createCliErrorDocument({
+    code: "network",
+    message: "Unable to reach ProductLobster. Check the network connection and retry.",
+    retryHint: "Retry after the connection is available."
+  });
+}
 function resolveDocumentUploadUrl(mcpEndpoint, workspaceId) {
   const endpoint = new URL(mcpEndpoint);
   return new URL(
@@ -23301,9 +23445,8 @@ async function prepareUploadFile(filePath) {
       message: `File size ${fileStat.size} exceeds maximum of ${MAX_UPLOAD_FILE_SIZE_BYTES} bytes.`
     };
   }
-  const mimeType = MIME_TYPES_BY_EXTENSION.get(
-    path3.extname(normalizedPath).toLowerCase()
-  );
+  const extension = path3.extname(normalizedPath).toLowerCase();
+  const mimeType = MIME_TYPES_BY_EXTENSION.get(extension);
   if (!mimeType) {
     return {
       message: "Unsupported file extension. Supported extensions: .pdf, .docx, .txt, .md, .markdown, .png, .jpg, .jpeg, .webp."
@@ -23311,6 +23454,7 @@ async function prepareUploadFile(filePath) {
   }
   const bytes = await readFile2(normalizedPath);
   return {
+    extension,
     file: new File([bytes], path3.basename(normalizedPath), { type: mimeType })
   };
 }
@@ -23324,18 +23468,25 @@ function parseResponsePayload(text) {
     return text;
   }
 }
-function uploadRouteFailure(status, jsonBody) {
-  if (status >= 300 && status < 400) {
+function createUploadRouteFailure(extension) {
+  return (status, jsonBody) => {
+    if (status >= 300 && status < 400) {
+      return {
+        code: "internal",
+        message: `ProductLobster redirected the upload (HTTP ${status}) instead of accepting it. The API key was not sent on. Retry once; if it continues, report the failure.`
+      };
+    }
+    if (status === 415) {
+      return {
+        code: "invalid_arguments",
+        message: `ProductLobster did not accept the ${extension} file type. Upload the document in another supported format and retry.`
+      };
+    }
+    const byStatus = FAILURE_BY_STATUS.get(status);
     return {
-      code: "internal",
-      message: `ProductLobster redirected the upload (HTTP ${status}) instead of accepting it. The API key was not sent on. Retry once; if it continues, report the failure.`
+      code: byStatus?.code,
+      message: extractJsonErrorMessage(jsonBody) ?? byStatus?.message ?? "The upload failed. Retry once; if it continues, report the failure."
     };
-  }
-  const routeMessage = extractJsonErrorMessage(jsonBody);
-  const byStatus = FAILURE_BY_STATUS.get(status);
-  return {
-    code: byStatus?.code,
-    message: routeMessage ?? byStatus?.message ?? "The upload failed. Retry once; if it continues, report the failure."
   };
 }
 function extractJsonErrorMessage(jsonBody) {
@@ -23664,7 +23815,9 @@ function renderParseError(error62, argv, io) {
       message
     }),
     options,
-    io
+    io,
+    void 0,
+    { keepMessageLineBreaks: true }
   );
 }
 function stripCommanderPrefix(message) {

package/dist/index.d.ts

@@ -1,10 +1,23 @@
 import { Command } from 'commander';
 
+type KeychainCredentialLocation = typeof keychainCredentialLocation | typeof legacyKeychainCredentialLocation;
 interface CredentialStore {
-    deleteBearerToken(): Promise<boolean>;
+    /**
+     * Deletes the current and the legacy entry. Resolves to the entries that
+     * existed and were removed, current first; empty when neither was removed.
+     */
+    deleteBearerToken(): Promise<KeychainCredentialLocation[]>;
     loadBearerToken(): Promise<string | null>;
     saveBearerToken(secret: string): Promise<void>;
 }
+declare const keychainCredentialLocation: {
+    readonly account: "default";
+    readonly service: "productlobster.plob-cli";
+};
+declare const legacyKeychainCredentialLocation: {
+    readonly account: "default";
+    readonly service: "productlobster.pl-cli";
+};
 
 declare const EXIT_CODES: {
     readonly success: 0;
@@ -108,4 +121,4 @@ declare function createProgram(config?: CliProgramConfig): {
 };
 declare function runCli(argv?: readonly string[], config?: CliProgramConfig): Promise<number>;
 
-export { type CliExitCode, type CliIO, type CliProgramConfig, type CommandRunnerDeps, EXIT_CODES, type McpClientConfig, type McpToolClient, type RunnerGlobalOptions, createProgram, createSdkMcpClient, runCli, runCommand };
+export { type CliExitCode, type CliIO, type CliProgramConfig, type CommandRunnerDeps, type CredentialStore, EXIT_CODES, type KeychainCredentialLocation, type McpClientConfig, type McpToolClient, type RunnerGlobalOptions, createProgram, createSdkMcpClient, runCli, runCommand };

package/dist/index.js

@@ -23,10 +23,10 @@ A full analysis is asynchronous and durable. The loop is the same for every work
 
 1. **Start.** Call \`run-start\` with a \`workflow\` of \`launch\`, \`audit\`, \`focused-analysis\`, \`prototype\`, or \`refinement\`, plus its inputs. It returns a run id. For \`prototype\`, the returned id is a prototype id, not a run id: track it with \`prototype-list\` and fetch it with \`prototype-pack\`, not \`run-status\`. If your request is too thin, it returns a \`needs_sharpening\` result that lists what to add \u2014 add detail and call \`run-start\` again.
 2. **Poll.** Call \`run-status\` with the run id. It reports the current status and returns a \`since\` cursor; pass that cursor on the next poll to get only what changed. Runs take minutes \u2014 poll, do not block. Stop polling when the run's \`status\` is \`completed\`, \`failed\`, or \`cancelled\`. Do not wait for every stage to leave \`pending\`: a run that fails or is cancelled part-way leaves its unstarted stages \`pending\` permanently, and on a finished run \`pending\` means the stage never ran.
-3. **Resolve checkpoints.** When \`run-status\` reports that the run is waiting at a checkpoint, it lists the options. Pick one and call \`checkpoint-resolve\` with the run id and an \`optionId\` taken from that list. An invented or stale id is rejected.
+3. **Resolve checkpoints.** When \`run-status\` reports that the run is waiting at a checkpoint, it lists the options. Pick one and call \`checkpoint-resolve\` with the run id and an \`optionId\` taken from that list. An invented or stale id is rejected. The run resumes in the background, so the answer and the next few \`run-status\` polls (often a minute or more) can still say \`checkpoint_pending\`. \`resumePending: true\` (on the answer, or on the \`checkpoint\` block of \`run-status\`) means your selection is recorded and the run is resuming: keep polling, and do not resolve again. A successful answer with \`resumePending: false\` usually means another accept of the same decision is still being recorded, so keep polling; if \`run-status\` keeps listing the options without \`resumePending: true\`, resolving again with the same \`optionId\` is safe.
 4. **Read the result.** When the run is complete, \`run-output\` returns the structured result as generated. Its \`stageEdits\` list marks each stage whose document the user has changed since (\`hasUserEdits: true\`). When such an entry also carries a \`documentId\`, read that document with \`document-get\` rather than relying on the structured result. An entry with \`hasUserEdits: true\` and no \`documentId\` means the stage was edited but its document is not available through \`document-get\`; use \`output\` for that stage. Use \`document-list\` and \`document-get\` to read the documents the run produced, and \`prototype-list\` / \`prototype-pack\` for any prototype.
 
-Other run controls: \`run-cancel\` stops a run that is still in progress and acknowledges every call, a finished run included, so confirm the outcome with \`run-status\`; \`run-replay\` re-runs one, optionally from a stage.
+Other run controls: \`run-cancel\` stops a run that is still in progress. It answers \`cancelled: true\` for every accepted call, a finished run included, so check \`alreadyTerminal\`: \`true\` means the run had already stopped and this call changed nothing. Its \`status\` is the run's status after the call. \`run-replay\` re-runs a run, optionally from a stage.
 
 ## Reading and writing workspace context
 
@@ -52,9 +52,9 @@ Every failure is a structured object: \`{ code, message, requestId, retryHint }\
 | --- | --- | --- |
 | \`unauthorized\` | Key missing, revoked, or wrong | Ask the person to check or rotate the key |
 | \`unauthorized_scope\` | Key lacks the scope this tool needs | Ask the person to create a key with that permission |
-| \`workspace_mismatch\` | Argument points outside the bound workspace (or a fabricated id) | Use ids returned by this surface; do not invent them |
+| \`workspace_mismatch\` | Argument points outside the bound workspace | Use ids returned by this surface; do not invent them |
 | \`needs_sharpening\` | A run request was too thin | Add the detail the result lists, then retry |
-| \`invalid_arguments\` | A field was the wrong shape | Fix the named fields and retry |
+| \`invalid_arguments\` | A field was the wrong shape, or a checkpoint \`optionId\` was not one of the options offered | Fix the named fields and retry; for \`optionId\`, copy an id from the options \`run-status\` lists |
 | \`idempotency_key_reuse\` | The idempotency key was already used for a different write | Use a new key for a new write; reuse a key only to retry the same write |
 | \`conflict\` | State changed under you (e.g. a stale document token) | Re-read the current state, then retry |
 | \`rate_limited\` | Daily call budget or a short spike | Wait for the reset the result reports |
@@ -19867,7 +19867,12 @@ var checkpointResolveInputSchema = external_exports.object({
 var checkpointResolveOutputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the resolved run."),
   resolved: external_exports.literal(true).describe("The checkpoint was resolved; resume polling run-status."),
-  resumedStatus: runStatusEnum.describe("Coarse status the run resumed into."),
+  resumedStatus: runStatusEnum.describe(
+    "Coarse status at the time of the answer; usually checkpoint_pending while the resume is in flight."
+  ),
+  resumePending: external_exports.boolean().optional().describe(
+    "True when the selection is recorded and the run is resuming in the background: keep polling run-status and do not resolve again. If false, keep polling; if later polls keep listing the options without resumePending true, resolving again with the same optionId is safe."
+  ),
   schemaVersion: schemaVersionSchema
 });
 
@@ -20303,7 +20308,13 @@ var runCancelInputSchema = external_exports.object({
 });
 var runCancelOutputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the cancelled run."),
-  cancelled: external_exports.literal(true).describe("The cancel was accepted; confirm via run-status."),
+  cancelled: external_exports.literal(true).describe(
+    "The cancel was accepted, or the run is already stopped; check alreadyTerminal."
+  ),
+  alreadyTerminal: external_exports.boolean().optional().describe(
+    "True when the run had already stopped and this call changed nothing."
+  ),
+  status: runStatusEnum.optional().describe("Coarse status of the run after this call."),
   schemaVersion: schemaVersionSchema
 });
 var runReplayInputSchema = external_exports.object({
@@ -20420,7 +20431,10 @@ var checkpointPayloadSchema = external_exports.object({
   options: external_exports.array(checkpointOptionSchema).describe("The strategic options to choose between."),
   keyDifferences: external_exports.string().describe("How the options differ from one another."),
   recommendationJustification: external_exports.string().describe("Why the recommended option is recommended."),
-  refineUrl: external_exports.string().describe("Hosted-app URL to refine this checkpoint set.")
+  refineUrl: external_exports.string().describe("Hosted-app URL to refine this checkpoint set."),
+  resumePending: external_exports.boolean().optional().describe(
+    "True when a selection is recorded and the run is resuming in the background: keep polling and do not resolve again. False after a successful checkpoint-resolve: keep polling; if later polls keep listing the options without resumePending true, resolving again with the same optionId is safe."
+  )
 });
 var runStatusInputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run to poll."),
@@ -20508,12 +20522,14 @@ var API_KEY_SECRET_PATTERN = /^ak_[\x21-\x7E]+$/;
 var KeyringCredentialStore = class {
   async deleteBearerToken() {
     const keyring = await import("@napi-rs/keyring");
-    const removed = await deleteKeyringPassword(keyring, KEYCHAIN_SERVICE);
-    const legacyRemoved = await deleteKeyringPassword(
-      keyring,
-      LEGACY_KEYCHAIN_SERVICE
-    );
-    return removed || legacyRemoved;
+    const removed = [];
+    if (await deleteKeyringPassword(keyring, KEYCHAIN_SERVICE)) {
+      removed.push(keychainCredentialLocation);
+    }
+    if (await deleteKeyringPassword(keyring, LEGACY_KEYCHAIN_SERVICE)) {
+      removed.push(legacyKeychainCredentialLocation);
+    }
+    return removed;
   }
   async loadBearerToken() {
     const keyring = await import("@napi-rs/keyring");
@@ -20598,6 +20614,10 @@ var keychainCredentialLocation = {
   account: KEYCHAIN_ACCOUNT,
   service: KEYCHAIN_SERVICE
 };
+var legacyKeychainCredentialLocation = {
+  account: KEYCHAIN_ACCOUNT,
+  service: LEGACY_KEYCHAIN_SERVICE
+};
 
 // src/runtime/exit-codes.ts
 var EXIT_CODES = {
@@ -20705,11 +20725,13 @@ async function createSdkMcpClient(config2) {
 function isUnsafeTerminalCodePoint(codePoint) {
   return codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 1564 || codePoint === 8206 || codePoint === 8207 || codePoint === 8232 || codePoint === 8233 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297;
 }
-function escapeTerminalText(value, maxCodePoints) {
+var LINE_FEED_CODE_POINT = 10;
+function escapeTerminalText(value, maxCodePoints, options = {}) {
   const codePoints = Array.from(value);
   const escaped = codePoints.slice(0, maxCodePoints).map((character) => {
     const codePoint = character.codePointAt(0) ?? 0;
-    return isUnsafeTerminalCodePoint(codePoint) ? `\\u${codePoint.toString(16).padStart(4, "0")}` : character;
+    const keep = options.keepLineBreaks && codePoint === LINE_FEED_CODE_POINT;
+    return isUnsafeTerminalCodePoint(codePoint) && !keep ? `\\u${codePoint.toString(16).padStart(4, "0")}` : character;
   }).join("");
   return codePoints.length > maxCodePoints ? `${escaped}\u2026` : escaped;
 }
@@ -20733,6 +20755,9 @@ var API_KEY_IN_TEXT_PATTERN = /ak_[^\s"'\\]+/g;
 var REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 var API_KEY_MARKER_PATTERN = /ak_/i;
 var DEBUG_DIAGNOSTIC_MAX_CODE_POINTS = 300;
+var FAILURE_MESSAGE_MAX_CODE_POINTS = 1e3;
+var FAILURE_RETRY_HINT_MAX_CODE_POINTS = 500;
+var FAILURE_UPGRADE_COMMAND_MAX_CODE_POINTS = 200;
 var defaultIo = {
   stdin: process.stdin,
   stderr: process.stderr,
@@ -20864,9 +20889,11 @@ function createCliOperationalError(input2) {
     input2.diagnostic
   );
 }
-function renderCliError(document, options, io, diagnostic) {
+function renderCliError(document, options, io, diagnostic, { keepMessageLineBreaks = false } = {}) {
   const exitCode = exitCodeForCliError(document.code);
-  renderFailure({ diagnostic, document, exitCode }, options, io);
+  renderFailure({ diagnostic, document, exitCode }, options, io, {
+    keepMessageLineBreaks
+  });
   return exitCode;
 }
 function resolveRunnerDeps(overrides, io) {
@@ -21208,21 +21235,27 @@ function renderSuccess(response, spec, options, io) {
   io.stdout.write(`${JSON.stringify(response)}
 `);
 }
-function renderFailure(failure2, options, io) {
+function renderFailure(failure2, options, io, { keepMessageLineBreaks = false } = {}) {
   if (shouldRenderJson(options, io)) {
     io.stdout.write(`${JSON.stringify(failure2.document)}
 `);
   } else {
-    io.stderr.write(`Error: ${failure2.document.message}
-`);
+    io.stderr.write(
+      `Error: ${escapeTerminalText(failure2.document.message, FAILURE_MESSAGE_MAX_CODE_POINTS, { keepLineBreaks: keepMessageLineBreaks })}
+`
+    );
     const upgradeCommand = getUpgradeCommand(failure2.document.details);
     if (upgradeCommand) {
-      io.stderr.write(`Upgrade: ${upgradeCommand}
-`);
+      io.stderr.write(
+        `Upgrade: ${escapeTerminalText(upgradeCommand, FAILURE_UPGRADE_COMMAND_MAX_CODE_POINTS)}
+`
+      );
     }
     if (failure2.document.retryHint) {
-      io.stderr.write(`${failure2.document.retryHint}
-`);
+      io.stderr.write(
+        `${escapeTerminalText(failure2.document.retryHint, FAILURE_RETRY_HINT_MAX_CODE_POINTS)}
+`
+      );
     }
   }
   printDebugRequestId(options, io, failure2.document.requestId);
@@ -21475,8 +21508,7 @@ function runCheckpointResolveCommand(options) {
   return runCommand(
     {
       outputSchema: checkpointResolveOutputSchema,
-      renderHuman: (response) => `Run ${response.runId} resumed: ${response.resumedStatus}
-`,
+      renderHuman: renderCheckpointResolve,
       toolArguments: { runId: runId.value, optionId: optionId.value },
       toolName: "checkpoint-resolve"
     },
@@ -21487,6 +21519,15 @@ function runCheckpointResolveCommand(options) {
     }
   );
 }
+function renderCheckpointResolve(response) {
+  const poll = `plob run-status ${response.runId}`;
+  if (response.resumePending === true) {
+    return `Run ${response.runId}: selection recorded; the run is resuming in the background. Keep polling \`${poll}\` and don't resolve again.
+`;
+  }
+  return `Run ${response.runId}: selection accepted. Keep polling \`${poll}\`. If later polls keep listing the options without a recorded selection, resolving again with the same option id is safe.
+`;
+}
 
 // src/commands/context-pack.ts
 function registerContextPackCommand(program, options) {
@@ -22142,11 +22183,11 @@ async function runLogoutCommand(options) {
     options.io
   );
   let existingSecret;
-  let removed = false;
+  let removedEntries = [];
   try {
     existingSecret = await deps.credentialStore.loadBearerToken();
     if (existingSecret) {
-      removed = await deps.credentialStore.deleteBearerToken();
+      removedEntries = await deps.credentialStore.deleteBearerToken();
     }
   } catch {
     return renderCliError(
@@ -22163,7 +22204,7 @@ async function runLogoutCommand(options) {
   if (!existingSecret) {
     return renderMissingCredential(options);
   }
-  if (!removed) {
+  if (removedEntries.length === 0) {
     return renderCliError(
       createCliErrorDocument({
         code: "internal",
@@ -22177,7 +22218,8 @@ async function runLogoutCommand(options) {
     {
       data: {
         keychain: keychainCredentialLocation,
-        removed: true
+        removed: true,
+        removedEntries
       },
       schemaVersion: AGENTIC_CONTRACT_SCHEMA_VERSION
     },
@@ -22210,7 +22252,11 @@ function renderLogoutSuccess(document, options, io) {
 `);
     return;
   }
-  io.stdout.write("ProductLobster API key removed from the OS keychain.\n");
+  const services = document.data.removedEntries.map((entry) => entry.service).join(", ");
+  io.stdout.write(
+    `ProductLobster API key removed from the OS keychain: ${services}.
+`
+  );
 }
 
 // src/commands/observe.ts
@@ -22603,6 +22649,19 @@ function resolveSafeTarget(root, entryName) {
 }
 
 // src/commands/prototype-pack.ts
+var SIGNED_URL_MAX_REDIRECT_HOPS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+  301,
+  302,
+  303,
+  307,
+  308
+]);
+var PACK_NETWORK_FAILURE = {
+  code: "network",
+  message: "Unable to fetch the prototype ZIP. Check the network connection and retry.",
+  retryHint: "Retry after the connection is available."
+};
 function registerPrototypePackCommand(program, options) {
   const command = program.command("prototype-pack").description("Fetch a prototype ZIP reference.").requiredOption("--prototype-id <id>", "Prototype id.").option("--out <dir>", "New output directory (parent must already exist).");
   command.action(async (commandOptions) => {
@@ -22682,22 +22741,7 @@ async function fetchAndExtractPack(input2) {
       message: "The prototype ZIP URL must use https. Retry once; if it continues, report the failure."
     });
   }
-  let response;
-  try {
-    response = await fetch(input2.pack.url, {
-      headers,
-      // With the bearer attached, never replay it to wherever a redirect
-      // points; the non-2xx check below reports the redirect status.
-      ...headers.authorization ? { redirect: "manual" } : {}
-    });
-  } catch (error62) {
-    throw createCliOperationalError({
-      code: "network",
-      diagnostic: describeThrownError(error62),
-      message: "Unable to fetch the prototype ZIP. Check the network connection and retry.",
-      retryHint: "Retry after the connection is available."
-    });
-  }
+  const response = input2.pack.delivery === "authenticated_stream" ? await fetchPack(input2.pack.url, headers) : await fetchSignedPack(input2.pack.url);
   if (!response.ok) {
     const failure2 = await normalizeHttpResponseFailure(
       response,
@@ -22709,7 +22753,15 @@ async function fetchAndExtractPack(input2) {
       failure2.diagnostic
     );
   }
-  const archive = new Uint8Array(await response.arrayBuffer());
+  let archive;
+  try {
+    archive = new Uint8Array(await response.arrayBuffer());
+  } catch (error62) {
+    throw createCliOperationalError({
+      ...PACK_NETWORK_FAILURE,
+      diagnostic: `body unreadable: ${describeThrownError(error62)}`
+    });
+  }
   try {
     return await extractZipToDirectory(archive, input2.outDir);
   } catch (error62) {
@@ -22725,6 +22777,53 @@ async function fetchAndExtractPack(input2) {
     });
   }
 }
+async function fetchPack(url2, headers) {
+  try {
+    return await fetch(url2, { headers, redirect: "manual" });
+  } catch (error62) {
+    throw createCliOperationalError({
+      ...PACK_NETWORK_FAILURE,
+      diagnostic: describeThrownError(error62)
+    });
+  }
+}
+async function fetchSignedPack(initialUrl) {
+  let url2 = initialUrl;
+  for (let hop = 0; ; hop += 1) {
+    const response = await fetchPack(url2, {});
+    if (!REDIRECT_STATUSES.has(response.status)) {
+      return response;
+    }
+    response.body?.cancel().catch(() => void 0);
+    if (hop === SIGNED_URL_MAX_REDIRECT_HOPS) {
+      throw signedRedirectFailure("redirected too many times");
+    }
+    const location = response.headers.get("location");
+    if (!location) {
+      throw signedRedirectFailure("redirected without a target URL");
+    }
+    const next = resolveRedirectUrl(location, url2);
+    if (!(next && isHttpsOrLoopbackUrl(next))) {
+      throw signedRedirectFailure(
+        "redirected to a URL that does not use https"
+      );
+    }
+    url2 = next;
+  }
+}
+function resolveRedirectUrl(location, currentUrl) {
+  try {
+    return new URL(location, currentUrl).href;
+  } catch {
+    return;
+  }
+}
+function signedRedirectFailure(reason) {
+  return createCliOperationalError({
+    code: "internal",
+    message: `The prototype ZIP download ${reason}. Retry once; if it continues, report the failure.`
+  });
+}
 function bundleRouteFailure(status) {
   if (status === 401) {
     return {
@@ -22867,8 +22966,7 @@ function runRunCancelCommand(options) {
   return runCommand(
     {
       outputSchema: runCancelOutputSchema,
-      renderHuman: (response) => `Run ${response.runId} cancel accepted.
-`,
+      renderHuman: renderRunCancel,
       toolArguments: { runId: runId.value },
       toolName: "run-cancel"
     },
@@ -22879,6 +22977,15 @@ function runRunCancelCommand(options) {
     }
   );
 }
+function renderRunCancel(response) {
+  if (response.alreadyTerminal === true) {
+    const status = response.status ? ` (status: ${response.status})` : "";
+    return `Run ${response.runId} had already stopped${status}; this call changed nothing.
+`;
+  }
+  return `Run ${response.runId} cancel accepted.
+`;
+}
 
 // src/commands/run-output.ts
 function registerRunOutputCommand(program, options) {
@@ -23068,6 +23175,9 @@ function runRunStatusCommand(options) {
     }
   );
 }
+var CHECKPOINT_QUESTION_DISPLAY_MAX = 500;
+var CHECKPOINT_OPTION_ID_DISPLAY_MAX = 200;
+var CHECKPOINT_OPTION_TITLE_DISPLAY_MAX = 200;
 function renderRunStatus(response) {
   const lines = [`Run ${response.runId}: ${response.status}`];
   if (response.stages.length > 0) {
@@ -23080,11 +23190,7 @@ function renderRunStatus(response) {
     lines.push(`Transitions: ${response.transitions.length}`);
   }
   if (response.checkpoint) {
-    lines.push(`Pending decision: ${response.checkpoint.question}`);
-    for (const option of response.checkpoint.options) {
-      const marker = option.recommended ? " recommended" : "";
-      lines.push(`- ${option.id}: ${option.title}${marker}`);
-    }
+    lines.push(...renderCheckpoint(response.checkpoint));
   }
   if (response.nextCursor) {
     lines.push(`Next cursor: ${response.nextCursor}`);
@@ -23092,6 +23198,26 @@ function renderRunStatus(response) {
   return `${lines.join("\n")}
 `;
 }
+function renderCheckpoint(checkpoint) {
+  const question = escapeTerminalText(
+    checkpoint.question,
+    CHECKPOINT_QUESTION_DISPLAY_MAX
+  );
+  if (checkpoint.resumePending === true) {
+    return [`Decision recorded; the run is resuming. Checkpoint: ${question}`];
+  }
+  const lines = [`Pending decision: ${question}`];
+  for (const option of checkpoint.options) {
+    const id = escapeTerminalText(option.id, CHECKPOINT_OPTION_ID_DISPLAY_MAX);
+    const title = escapeTerminalText(
+      option.title,
+      CHECKPOINT_OPTION_TITLE_DISPLAY_MAX
+    );
+    const marker = option.recommended ? " recommended" : "";
+    lines.push(`- ${id}: ${title}${marker}`);
+  }
+  return lines;
+}
 
 // src/commands/upload.ts
 import { readFile as readFile2, stat } from "fs/promises";
@@ -23243,11 +23369,7 @@ async function runUploadCommand(options) {
     });
   } catch (error62) {
     return renderCliError(
-      createCliErrorDocument({
-        code: "network",
-        message: "Unable to reach ProductLobster. Check the network connection and retry.",
-        retryHint: "Retry after the connection is available."
-      }),
+      createNetworkErrorDocument(),
       options.globalOptions,
       options.io,
       describeThrownError(error62)
@@ -23256,7 +23378,7 @@ async function runUploadCommand(options) {
   if (!response.ok) {
     const failure2 = await normalizeHttpResponseFailure(
       response,
-      uploadRouteFailure
+      createUploadRouteFailure(prepared.extension)
     );
     return renderCliError(
       failure2.document,
@@ -23265,12 +23387,34 @@ async function runUploadCommand(options) {
       failure2.diagnostic
     );
   }
+  let bodyText;
+  try {
+    bodyText = await response.text();
+  } catch (error62) {
+    return renderCliError(
+      createCliErrorDocument({
+        code: "network",
+        message: "The connection to ProductLobster closed before the upload was confirmed. The upload may already have been stored.",
+        retryHint: "Check the workspace's documents in the ProductLobster app before uploading again."
+      }),
+      options.globalOptions,
+      options.io,
+      `body unreadable: ${describeThrownError(error62)}`
+    );
+  }
   const uploadResponse = normalizeUploadSuccessPayload(
-    parseResponsePayload(await response.text())
+    parseResponsePayload(bodyText)
   );
   renderUploadSuccess(uploadResponse, options.globalOptions, options.io);
   return EXIT_CODES.success;
 }
+function createNetworkErrorDocument() {
+  return createCliErrorDocument({
+    code: "network",
+    message: "Unable to reach ProductLobster. Check the network connection and retry.",
+    retryHint: "Retry after the connection is available."
+  });
+}
 function resolveDocumentUploadUrl(mcpEndpoint, workspaceId) {
   const endpoint = new URL(mcpEndpoint);
   return new URL(
@@ -23300,9 +23444,8 @@ async function prepareUploadFile(filePath) {
       message: `File size ${fileStat.size} exceeds maximum of ${MAX_UPLOAD_FILE_SIZE_BYTES} bytes.`
     };
   }
-  const mimeType = MIME_TYPES_BY_EXTENSION.get(
-    path3.extname(normalizedPath).toLowerCase()
-  );
+  const extension = path3.extname(normalizedPath).toLowerCase();
+  const mimeType = MIME_TYPES_BY_EXTENSION.get(extension);
   if (!mimeType) {
     return {
       message: "Unsupported file extension. Supported extensions: .pdf, .docx, .txt, .md, .markdown, .png, .jpg, .jpeg, .webp."
@@ -23310,6 +23453,7 @@ async function prepareUploadFile(filePath) {
   }
   const bytes = await readFile2(normalizedPath);
   return {
+    extension,
     file: new File([bytes], path3.basename(normalizedPath), { type: mimeType })
   };
 }
@@ -23323,18 +23467,25 @@ function parseResponsePayload(text) {
     return text;
   }
 }
-function uploadRouteFailure(status, jsonBody) {
-  if (status >= 300 && status < 400) {
+function createUploadRouteFailure(extension) {
+  return (status, jsonBody) => {
+    if (status >= 300 && status < 400) {
+      return {
+        code: "internal",
+        message: `ProductLobster redirected the upload (HTTP ${status}) instead of accepting it. The API key was not sent on. Retry once; if it continues, report the failure.`
+      };
+    }
+    if (status === 415) {
+      return {
+        code: "invalid_arguments",
+        message: `ProductLobster did not accept the ${extension} file type. Upload the document in another supported format and retry.`
+      };
+    }
+    const byStatus = FAILURE_BY_STATUS.get(status);
     return {
-      code: "internal",
-      message: `ProductLobster redirected the upload (HTTP ${status}) instead of accepting it. The API key was not sent on. Retry once; if it continues, report the failure.`
+      code: byStatus?.code,
+      message: extractJsonErrorMessage(jsonBody) ?? byStatus?.message ?? "The upload failed. Retry once; if it continues, report the failure."
     };
-  }
-  const routeMessage = extractJsonErrorMessage(jsonBody);
-  const byStatus = FAILURE_BY_STATUS.get(status);
-  return {
-    code: byStatus?.code,
-    message: routeMessage ?? byStatus?.message ?? "The upload failed. Retry once; if it continues, report the failure."
   };
 }
 function extractJsonErrorMessage(jsonBody) {
@@ -23663,7 +23814,9 @@ function renderParseError(error62, argv, io) {
       message
     }),
     options,
-    io
+    io,
+    void 0,
+    { keepMessageLineBreaks: true }
   );
 }
 function stripCommanderPrefix(message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@productlobster/plob",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "ProductLobster command-line tool — run PM analyses, manage workspaces, read run output, and upload documents from your terminal. A thin MCP client for the ProductLobster agentic surface.",
   "license": "Apache-2.0",
   "author": "ProductLobster",