@productlobster/plob 0.1.2 → 0.1.3

package/README.md

@@ -76,12 +76,31 @@ Use an explicit idempotency key for a scripted retry:
 plob observe --kind signal --content "Three users asked for CSV export" --idempotency-key "$JOB_ID"
 ```
 
-Fetch and extract a prototype pack:
+Fetch and extract a prototype pack into a new directory:
 
 ```bash
 plob prototype-pack --prototype-id proto_123 --out ./proto
 ```
 
+The output directory must not already exist, and its parent must exist. Choose a
+new name for each extraction; existing files, empty directories, and symlink
+output roots are rejected without being changed. The CLI does not merge or
+overwrite an earlier extraction. Parent path aliases are resolved to their
+canonical location, which is returned as `extraction.outDir`. Create missing
+parent directories yourself before running the command.
+
+Extraction creates a fresh tree, uses exclusive file creation, and removes that
+new tree if extraction fails. Unsafe archive paths and colliding filenames are
+rejected, including case or Unicode aliases recognized by the host filesystem.
+Directory-entry paths are validated, but empty directories are not extracted;
+parent directories are created as needed for files. Inconsistent ZIP directory
+counts, payload ranges, and decoded sizes are rejected. On POSIX the new
+directories and files use permissions 0700 and 0600; Windows inherits the
+caller's filesystem permissions. Use a trusted, stable parent directory on a
+local filesystem: this does not defend against another process replacing parent
+directories during extraction, and exclusive creation may not be reliable on
+every network filesystem.
+
 `plob upload` attaches one file to the selected workspace. Use the workspace `id` from `plob workspaces`, not the display name. The connection must include the `write:upload` scope. Supported extensions: `.pdf`, `.docx`, `.txt`, `.md`, `.markdown`, `.png`, `.jpg`, `.jpeg`, and `.webp`; files must be non-empty and at most 10 MB.
 
 ```bash

package/dist/cli.js

@@ -26,9 +26,9 @@ ProductLobster runs product analyses and keeps a product workspace's documents a
 A full analysis is asynchronous and durable. The loop is the same for every workflow:
 
 1. **Start.** Call \`run-start\` with a \`workflow\` of \`launch\`, \`audit\`, \`focused-analysis\`, \`prototype\`, or \`refinement\`, plus its inputs. It returns a run id. 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.
+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.
-4. **Read the result.** When the run is complete, \`run-output\` returns the structured result. Use \`document-list\` and \`document-get\` to read the documents the run produced, and \`prototype-list\` / \`prototype-pack\` for any prototype.
+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; \`run-replay\` re-runs one, optionally from a stage.
 
@@ -61,6 +61,7 @@ Every failure is a structured object: \`{ code, message, requestId, retryHint }\
 | \`invalid_arguments\` | A field was the wrong shape | Fix the named fields and retry |
 | \`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 |
+| \`allotment_exhausted\` | Included outcomes have been used; the key is read-only | Continue with read tools or ask the person to upgrade |
 
 Always keep \`requestId\` \u2014 it is the one join key for support.
 
@@ -14601,6 +14602,8 @@ var RUN_START_REFINEMENT_INSTRUCTION_MAX_LENGTH = 2e3;
 var runStartWorkflowSchema = external_exports.enum(["audit", "launch", "focused-analysis", "prototype", "refinement"]).describe("Which Brain action to start.");
 var runStartInputSchema = external_exports.object({
   workflow: runStartWorkflowSchema,
+  /** `audit`: deliberate acknowledgement when server-owned readiness has gaps. */
+  proceedWithGaps: external_exports.boolean().optional().describe("Proceed with server-recorded audit evidence gaps."),
   /** `launch`: the product idea to take through the launch pipeline. */
   idea: external_exports.string().optional().describe("Product idea for the launch workflow."),
   /** `focused-analysis`: the question to analyze against workspace context. */
@@ -14685,6 +14688,7 @@ var DOCUMENT_TYPE_VALUES = [
   "customer-research",
   "competitive-analysis",
   "customer-demand-analysis",
+  "kill-shot-refutation",
   "strategic-framing",
   "solution-design",
   "prd-generation",
@@ -14705,7 +14709,7 @@ var documentContentInputSchema = documentContentSchema.refine(
   "Document content must not be empty"
 ).describe("Document content to write.");
 var documentListInputSchema = external_exports.object({
-  cursor: external_exports.string().optional().describe("Opaque cursor from a previous page."),
+  cursor: external_exports.string().max(4096).optional().describe("Opaque cursor from a previous page."),
   latest: external_exports.boolean().optional().describe("Return only the newest matching document."),
   limit: external_exports.number().int().min(1).max(100).optional().describe("Maximum number of documents to return; server default is 20."),
   runId: external_exports.string().optional().describe("Identifier of the run to include."),
@@ -14753,7 +14757,7 @@ var documentPutOutputSchema = external_exports.object({
 
 // ../agentic-contract/prototype-list.ts
 var prototypeListInputSchema = external_exports.object({
-  cursor: external_exports.string().optional().describe("Opaque cursor from a previous response.")
+  cursor: external_exports.string().max(4096).optional().describe("Opaque cursor from a previous response.")
 });
 var prototypeStatusEnum = external_exports.enum(["generating", "complete", "failed"]).describe("Coarse prototype done-ness status.");
 var prototypeSummarySchema = external_exports.object({
@@ -14949,7 +14953,10 @@ var ERROR_CODES = [
   "version_revoked",
   // Appended (PRO-1484) — append-only so older clients never see a leading
   // member shift; no AGENTIC_CONTRACT_SCHEMA_VERSION bump (additive code).
-  "service_unavailable"
+  "service_unavailable",
+  // Appended (PRO-1920) — distinct from a periodic rate limit so clients can
+  // render the durable read-only conversion state without parsing prose.
+  "allotment_exhausted"
 ];
 var errorCodeSchema = external_exports.enum(ERROR_CODES);
 var agenticErrorSchema = external_exports.object({
@@ -15088,25 +15095,90 @@ var runReplayOutputSchema = external_exports.object({
 });
 
 // ../agentic-contract/run-output.ts
+var RUN_OUTPUT_MAX_OUTPUT_BYTES = 65536;
+var RUN_OUTPUT_MAX_RESPONSE_BYTES = 98304;
+var RUN_OUTPUT_ENVELOPE_RESERVE_BYTES = 1024;
+var RUN_OUTPUT_MAX_DOCUMENT_IDS = 200;
+var RUN_OUTPUT_MAX_OMITTED_KEYS = 64;
+var RUN_OUTPUT_MAX_OMITTED_KEY_BYTES = 128;
+var RUN_OUTPUT_MAX_STAGE_EDITS = 32;
+var utf8Encoder2 = new TextEncoder();
+function measureRunOutputBytes(value) {
+  const json2 = JSON.stringify(value);
+  return json2 === void 0 ? 0 : utf8Encoder2.encode(json2).byteLength;
+}
 var runOutputInputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run to read output from."),
-  stage: external_exports.string().optional().describe("Stage name to scope output to; omit for run-level output.")
+  stage: external_exports.string().trim().min(1).optional().describe("Stage name to scope output to; omit for run-level output.")
 });
-var runOutputOutputSchema = external_exports.object({
+var runOutputStageEditFields = {
+  stage: external_exports.string().describe("Stage name, as passed to run-output's stage."),
+  hasUserEdits: external_exports.boolean().describe(
+    "True when the user changed this stage's document after it was generated, so output is out of date for this stage."
+  ),
+  documentId: external_exports.string().optional().describe(
+    "The changed document, to read with document-get. Set only when hasUserEdits is true and document-get can read it; absent on an edited stage, use output."
+  )
+};
+var runOutputFieldsSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run."),
   stage: external_exports.string().nullable().describe("Stage this output is scoped to, or null for run-level."),
-  output: external_exports.record(external_exports.string(), external_exports.unknown()).describe(
-    "Structured output: summaries and IDs, never large inline bodies."
+  output: external_exports.record(external_exports.string(), external_exports.unknown()).refine(
+    (value) => measureRunOutputBytes(value) <= RUN_OUTPUT_MAX_OUTPUT_BYTES,
+    "Run output must not exceed 64 KiB"
+  ).describe(
+    "Structured output, at most 64 KiB of JSON: summaries and IDs, never large inline bodies."
+  ),
+  documentIds: external_exports.array(external_exports.string()).max(RUN_OUTPUT_MAX_DOCUMENT_IDS).describe("IDs of referenced documents to fetch via document-get."),
+  truncated: external_exports.boolean().optional().describe(
+    "True when entries were left out of output to stay within the size limit."
+  ),
+  omittedKeys: external_exports.array(
+    external_exports.string().refine(
+      (key) => measureRunOutputBytes(key) <= RUN_OUTPUT_MAX_OMITTED_KEY_BYTES,
+      "Omitted key must not exceed 128 bytes"
+    )
+  ).max(RUN_OUTPUT_MAX_OMITTED_KEYS).optional().describe(
+    "Top-level output keys left out for size, in order and at most 64: stage names for run-level output (request each by stage), field names for one stage (read the document via document-get)."
+  ),
+  omittedKeyCount: external_exports.number().int().nonnegative().optional().describe("How many top-level output keys were left out for size."),
+  omittedKeysTruncated: external_exports.boolean().optional().describe(
+    "True when omittedKeys lists fewer keys than omittedKeyCount (too many, or a key too long to list)."
+  ),
+  prototypeId: external_exports.string().optional().describe(
+    "Set when prototype content was left out for size: the run's prototype, to fetch with prototype-pack."
+  ),
+  stageEdits: external_exports.array(
+    external_exports.object({
+      ...runOutputStageEditFields,
+      stage: runOutputStageEditFields.stage.refine(
+        (stage) => measureRunOutputBytes(stage) <= RUN_OUTPUT_MAX_OMITTED_KEY_BYTES,
+        "Stage name must not exceed 128 bytes"
+      )
+    })
+  ).max(RUN_OUTPUT_MAX_STAGE_EDITS).optional().describe(
+    "One entry per stage with output, at most 32: whether the user changed that stage's document, and if so the document to read with document-get."
   ),
-  documentIds: external_exports.array(external_exports.string()).describe("IDs of referenced documents to fetch via document-get."),
   schemaVersion: schemaVersionSchema
 });
+var runOutputOutputSchema = runOutputFieldsSchema.refine(
+  (response) => measureRunOutputBytes(response) <= RUN_OUTPUT_MAX_RESPONSE_BYTES - RUN_OUTPUT_ENVELOPE_RESERVE_BYTES,
+  "Run output response must not exceed 96 KiB with its envelope"
+);
+var runOutputParseSchema = runOutputFieldsSchema.extend({
+  output: external_exports.record(external_exports.string(), external_exports.unknown()),
+  documentIds: external_exports.array(external_exports.string()),
+  omittedKeys: external_exports.array(external_exports.string()).optional(),
+  stageEdits: external_exports.array(external_exports.object(runOutputStageEditFields)).optional()
+});
 
 // ../agentic-contract/run-status.ts
 var runStageProgressSchema = external_exports.object({
   name: external_exports.string().describe("Stage identifier."),
   order: external_exports.number().int().positive().describe("1-based position in the run."),
-  status: external_exports.enum(["pending", "running", "completed", "failed"]).describe("Coarse per-stage status.")
+  status: external_exports.enum(["pending", "running", "completed", "failed"]).describe(
+    "Coarse per-stage status. On a run whose status is completed, failed, or cancelled, pending means the stage never ran; stop polling on the run status, not on stage statuses."
+  )
 });
 var runTransitionSchema = external_exports.object({
   from: runStatusEnum.nullable().describe("Prior status, or null for the first transition."),
@@ -15180,6 +15252,9 @@ var AGENTIC_TOOL_NAMES = [
 ];
 
 // ../agentic-contract/workspace-identity.ts
+var workspaceListInputSchema = external_exports.object({
+  cursor: external_exports.string().optional().describe("Opaque cursor from a previous response (reserved for Phase 2).")
+});
 var workspacePipelineTypeSchema = external_exports.enum(["LAUNCH", "AUDIT"]);
 var workspaceIdentitySchema = external_exports.object({
   id: external_exports.string().describe("Stable workspace identifier."),
@@ -15294,6 +15369,7 @@ var EXIT_CODES = {
   rateLimited: 16,
   versionRevoked: 17,
   serviceUnavailable: 18,
+  allotmentExhausted: 19,
   network: 70
 };
 var ERROR_CODE_EXIT_CODES = {
@@ -15308,7 +15384,8 @@ var ERROR_CODE_EXIT_CODES = {
   version_revoked: EXIT_CODES.versionRevoked,
   // PRO-1484: transient backend outage — its own non-zero code so scripts can
   // distinguish a retryable outage from a hard internal fault (exit 1).
-  service_unavailable: EXIT_CODES.serviceUnavailable
+  service_unavailable: EXIT_CODES.serviceUnavailable,
+  allotment_exhausted: EXIT_CODES.allotmentExhausted
 };
 function mapErrorCodeToExitCode(code) {
   return ERROR_CODE_EXIT_CODES[code];
@@ -15864,6 +15941,17 @@ function parseCommaSeparatedList(value) {
   const items = value.split(",").map((item) => item.trim()).filter(Boolean);
   return items.length > 0 ? items : void 0;
 }
+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) {
+  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;
+  }).join("");
+  return codePoints.length > maxCodePoints ? `${escaped}\u2026` : escaped;
+}
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -16811,44 +16899,86 @@ function renderPrototypeList(response) {
 }
 
 // src/runtime/zip-extract.ts
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir, realpath, rm, writeFile } from "fs/promises";
 import path2 from "path";
 import { inflateRawSync } from "zlib";
 var END_OF_CENTRAL_DIRECTORY_SIGNATURE = 101010256;
 var CENTRAL_DIRECTORY_FILE_SIGNATURE = 33639248;
+var CENTRAL_DIRECTORY_DIGITAL_SIGNATURE = 84233040;
 var LOCAL_FILE_HEADER_SIGNATURE = 67324752;
 var ZIP64_SENTINEL = 65535;
 var ZIP64_SIZE_SENTINEL = 4294967295;
+var TRAILING_WINDOWS_ALIAS = /[ .]$/;
+var RESERVED_WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i;
 var MAX_ENTRY_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
 var MAX_TOTAL_DECOMPRESSED_BYTES = 256 * 1024 * 1024;
 var MAX_ENTRY_COUNT = 4096;
+var ZipOutputDirectoryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ZipOutputDirectoryError";
+  }
+};
 async function extractZipToDirectory(bytes, outDir) {
   const archive = Buffer.from(bytes);
-  const root = path2.resolve(outDir);
-  await mkdir(root, { recursive: true });
-  const entries = readCentralDirectory(archive);
-  if (entries.length > MAX_ENTRY_COUNT) {
-    throw new Error(
-      `ZIP archive exceeds the maximum of ${MAX_ENTRY_COUNT} entries.`
-    );
+  const directory = readCentralDirectory(archive);
+  const root = await createOutputRoot(outDir);
+  try {
+    return await extractEntries(archive, directory, root);
+  } catch (error51) {
+    await rm(root, { recursive: true, force: true });
+    throw error51;
+  }
+}
+async function createOutputRoot(outDir) {
+  const requestedRoot = path2.resolve(outDir);
+  let parent;
+  try {
+    parent = await realpath(path2.dirname(requestedRoot));
+  } catch (error51) {
+    if (hasFilesystemCode(error51, "ENOENT") || hasFilesystemCode(error51, "ENOTDIR")) {
+      throw new ZipOutputDirectoryError(
+        "The output parent directory must already exist. Create the parent, then choose a new --out directory."
+      );
+    }
+    throw error51;
+  }
+  const root = path2.join(parent, path2.basename(requestedRoot));
+  try {
+    await mkdir(root, { mode: 448 });
+  } catch (error51) {
+    if (hasFilesystemCode(error51, "EEXIST")) {
+      throw new ZipOutputDirectoryError(
+        "The output directory must not already exist. Choose a new --out directory; existing files were not changed."
+      );
+    }
+    if (hasFilesystemCode(error51, "ENOTDIR")) {
+      throw new ZipOutputDirectoryError(
+        "The output parent directory must already exist. Create the parent, then choose a new --out directory."
+      );
+    }
+    throw error51;
   }
+  return root;
+}
+async function extractEntries(archive, directory, root) {
   const files = [];
   let totalDecompressedBytes = 0;
-  for (const entry of entries) {
+  for (const entry of directory.entries) {
     const normalizedName = normalizeZipEntryName(entry.name);
-    if (!normalizedName || normalizedName.endsWith("/")) {
+    const targetPath = resolveSafeTarget(root, normalizedName);
+    if (normalizedName.endsWith("/")) {
       continue;
     }
-    const targetPath = resolveSafeTarget(root, normalizedName);
-    const contents = readEntryContents(archive, entry);
+    const contents = readEntryContents(archive, entry, directory.offset);
     totalDecompressedBytes += contents.length;
     if (totalDecompressedBytes > MAX_TOTAL_DECOMPRESSED_BYTES) {
       throw new Error(
         `ZIP archive exceeds the maximum decompressed size of ${MAX_TOTAL_DECOMPRESSED_BYTES} bytes.`
       );
     }
-    await mkdir(path2.dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, contents);
+    await mkdir(path2.dirname(targetPath), { recursive: true, mode: 448 });
+    await writeFile(targetPath, contents, { flag: "wx", mode: 384 });
     files.push(normalizedName);
   }
   return {
@@ -16857,39 +16987,60 @@ async function extractZipToDirectory(bytes, outDir) {
     outDir: root
   };
 }
+function hasFilesystemCode(error51, code) {
+  return typeof error51 === "object" && error51 !== null && "code" in error51 && error51.code === code;
+}
 function readCentralDirectory(archive) {
   const eocdOffset = findEndOfCentralDirectory(archive);
   const entryCount = archive.readUInt16LE(eocdOffset + 10);
   const centralDirectorySize = archive.readUInt32LE(eocdOffset + 12);
-  let offset = archive.readUInt32LE(eocdOffset + 16);
-  if (entryCount === ZIP64_SENTINEL || centralDirectorySize === ZIP64_SIZE_SENTINEL || offset === ZIP64_SIZE_SENTINEL) {
+  const directoryOffset = archive.readUInt32LE(eocdOffset + 16);
+  if (entryCount === ZIP64_SENTINEL || centralDirectorySize === ZIP64_SIZE_SENTINEL || directoryOffset === ZIP64_SIZE_SENTINEL) {
     throw new Error("ZIP64 prototype packs are not supported.");
   }
-  const endOffset = offset + centralDirectorySize;
+  if (entryCount > MAX_ENTRY_COUNT) {
+    throw new Error(
+      `ZIP archive exceeds the maximum of ${MAX_ENTRY_COUNT} entries.`
+    );
+  }
+  const endOffset = directoryOffset + centralDirectorySize;
+  if (endOffset > eocdOffset) {
+    throw new Error("Invalid ZIP central directory.");
+  }
   const entries = [];
-  while (offset < endOffset && entries.length < entryCount) {
-    if (archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_FILE_SIGNATURE) {
+  let offset = directoryOffset;
+  while (entries.length < entryCount) {
+    if (offset + 46 > endOffset || archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_FILE_SIGNATURE) {
       throw new Error("Invalid ZIP central directory.");
     }
     const flags = archive.readUInt16LE(offset + 8);
     const compressionMethod = archive.readUInt16LE(offset + 10);
     const compressedSize = archive.readUInt32LE(offset + 20);
+    const uncompressedSize = archive.readUInt32LE(offset + 24);
     const localHeaderOffset = archive.readUInt32LE(offset + 42);
     const nameLength = archive.readUInt16LE(offset + 28);
     const extraLength = archive.readUInt16LE(offset + 30);
     const commentLength = archive.readUInt16LE(offset + 32);
     const nameStart = offset + 46;
+    const nextOffset = nameStart + nameLength + extraLength + commentLength;
+    if (nextOffset > endOffset) {
+      throw new Error("Invalid ZIP central directory.");
+    }
     const name = archive.subarray(nameStart, nameStart + nameLength).toString("utf8");
     entries.push({
       compressedSize,
       compressionMethod,
       flags,
       localHeaderOffset,
-      name
+      name,
+      uncompressedSize
     });
-    offset = nameStart + nameLength + extraLength + commentLength;
+    offset = nextOffset;
+  }
+  if (offset !== endOffset && (offset + 6 > endOffset || archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_DIGITAL_SIGNATURE || offset + 6 + archive.readUInt16LE(offset + 4) !== endOffset)) {
+    throw new Error("Invalid ZIP central directory.");
   }
-  return entries;
+  return { entries, offset: directoryOffset };
 }
 function findEndOfCentralDirectory(archive) {
   const minOffset = Math.max(0, archive.length - 65557);
@@ -16900,16 +17051,19 @@ function findEndOfCentralDirectory(archive) {
   }
   throw new Error("Invalid ZIP archive.");
 }
-function readEntryContents(archive, entry) {
+function readEntryContents(archive, entry, directoryOffset) {
   if (entry.flags % 2 === 1) {
     throw new Error("Encrypted ZIP entries are not supported.");
   }
-  if (archive.readUInt32LE(entry.localHeaderOffset) !== LOCAL_FILE_HEADER_SIGNATURE) {
+  if (entry.localHeaderOffset + 30 > directoryOffset || archive.readUInt32LE(entry.localHeaderOffset) !== LOCAL_FILE_HEADER_SIGNATURE) {
     throw new Error("Invalid ZIP local file header.");
   }
   const localNameLength = archive.readUInt16LE(entry.localHeaderOffset + 26);
   const localExtraLength = archive.readUInt16LE(entry.localHeaderOffset + 28);
   const dataStart = entry.localHeaderOffset + 30 + localNameLength + localExtraLength;
+  if (dataStart + entry.compressedSize > directoryOffset) {
+    throw new Error("Invalid ZIP entry data range.");
+  }
   const compressed = archive.subarray(
     dataStart,
     dataStart + entry.compressedSize
@@ -16920,13 +17074,20 @@ function readEntryContents(archive, entry) {
         `ZIP entry exceeds the maximum decompressed size of ${MAX_ENTRY_DECOMPRESSED_BYTES} bytes.`
       );
     }
+    if (compressed.length !== entry.uncompressedSize) {
+      throw new Error("Invalid ZIP entry decompressed size.");
+    }
     return Buffer.from(compressed);
   }
   if (entry.compressionMethod === 8) {
     try {
-      return inflateRawSync(compressed, {
+      const contents = inflateRawSync(compressed, {
         maxOutputLength: MAX_ENTRY_DECOMPRESSED_BYTES
       });
+      if (contents.length !== entry.uncompressedSize) {
+        throw new Error("Invalid ZIP entry decompressed size.");
+      }
+      return contents;
     } catch (error51) {
       if (isMaxOutputLengthError(error51)) {
         throw new Error(
@@ -16945,15 +17106,21 @@ function isMaxOutputLengthError(error51) {
 }
 function normalizeZipEntryName(name) {
   const normalized = name.replaceAll("\\", "/");
-  if (normalized.length === 0 || normalized.startsWith("/") || normalized.includes("\0")) {
-    return null;
+  if (normalized.length === 0 || normalized.startsWith("/") || normalized.includes(":") || normalized.includes("\0") || normalized.split("/").some(isUnsafeWindowsComponent)) {
+    throw new Error(`Unsafe ZIP entry path: ${name}`);
   }
   return normalized;
 }
+function isUnsafeWindowsComponent(component) {
+  if (component === "." || component === "..") {
+    return false;
+  }
+  return TRAILING_WINDOWS_ALIAS.test(component) || RESERVED_WINDOWS_DEVICE.test(component);
+}
 function resolveSafeTarget(root, entryName) {
   const targetPath = path2.resolve(root, entryName);
   const relative = path2.relative(root, targetPath);
-  if (relative.startsWith("..") || path2.isAbsolute(relative)) {
+  if (relative === "" || relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative)) {
     throw new Error(`Unsafe ZIP entry path: ${entryName}`);
   }
   return targetPath;
@@ -16961,7 +17128,7 @@ function resolveSafeTarget(root, entryName) {
 
 // src/commands/prototype-pack.ts
 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>", "Directory to extract the ZIP into.");
+  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) => {
     const exitCode2 = await runPrototypePackCommand({
       commandOptions,
@@ -17061,7 +17228,20 @@ async function fetchAndExtractPack(input) {
     });
   }
   const archive = new Uint8Array(await response.arrayBuffer());
-  return await extractZipToDirectory(archive, input.outDir);
+  try {
+    return await extractZipToDirectory(archive, input.outDir);
+  } catch (error51) {
+    if (error51 instanceof ZipOutputDirectoryError) {
+      throw createCliOperationalError({
+        code: "internal",
+        message: error51.message
+      });
+    }
+    throw createCliOperationalError({
+      code: "internal",
+      message: "The prototype ZIP could not be safely extracted. Check the output parent permissions and retry with a new --out directory; if the failure persists, report it."
+    });
+  }
 }
 function isSameOrigin(packUrl, endpoint) {
   try {
@@ -17231,7 +17411,9 @@ function runRunOutputCommand(options) {
   }
   return runCommand(
     {
-      outputSchema: runOutputOutputSchema,
+      // The tolerant consumer schema: a newer plob still reads a server that
+      // predates the run-output size bounds.
+      outputSchema: runOutputParseSchema,
       renderHuman: renderRunOutput,
       toolArguments: compactRecord({
         runId: runId.value,
@@ -17246,16 +17428,69 @@ function runRunOutputCommand(options) {
     }
   );
 }
+var OMITTED_KEY_DISPLAY_MAX = 80;
+var PROTOTYPE_ID_DISPLAY_MAX = 80;
 function renderRunOutput(response) {
   const scope = response.stage ? ` stage ${response.stage}` : "";
   const lines = [`Run ${response.runId}${scope} output`];
   lines.push(`Fields: ${Object.keys(response.output).length}`);
+  const omitted = renderOmittedKeys(response);
+  if (omitted) {
+    lines.push(`Omitted for size: ${omitted}`);
+  }
+  if (response.prototypeId !== void 0) {
+    const prototypeId = escapeTerminalText(
+      response.prototypeId,
+      PROTOTYPE_ID_DISPLAY_MAX
+    );
+    lines.push(
+      `Prototype: ${prototypeId} (fetch with \`plob prototype-pack --prototype-id ${prototypeId}\`)`
+    );
+  }
+  const edited = renderEditedStages(response);
+  if (edited) {
+    lines.push(
+      `Edited by the user (read with \`plob document-get\`): ${edited}`
+    );
+  }
   if (response.documentIds.length > 0) {
-    lines.push(`Documents: ${response.documentIds.join(", ")}`);
+    lines.push(
+      `Documents: ${response.documentIds.map((id) => escapeTerminalText(id, DOCUMENT_ID_DISPLAY_MAX)).join(", ")}`
+    );
   }
   return `${lines.join("\n")}
 `;
 }
+var DOCUMENT_ID_DISPLAY_MAX = 80;
+function renderEditedStages(response) {
+  const edited = (response.stageEdits ?? []).filter(
+    (entry) => entry.hasUserEdits
+  );
+  if (edited.length === 0) {
+    return;
+  }
+  return edited.map((entry) => {
+    const stage = escapeTerminalText(entry.stage, OMITTED_KEY_DISPLAY_MAX);
+    return entry.documentId === void 0 ? stage : `${stage} (${escapeTerminalText(entry.documentId, DOCUMENT_ID_DISPLAY_MAX)})`;
+  }).join(", ");
+}
+function renderOmittedKeys(response) {
+  if (response.truncated !== true) {
+    return;
+  }
+  const listed = (response.omittedKeys ?? []).map(
+    (key) => escapeTerminalText(key, OMITTED_KEY_DISPLAY_MAX)
+  );
+  const unlisted = Math.max(
+    0,
+    (response.omittedKeyCount ?? listed.length) - listed.length
+  );
+  if (listed.length === 0) {
+    return unlisted > 0 ? `${unlisted} ${unlisted === 1 ? "entry" : "entries"}` : void 0;
+  }
+  const names = listed.join(", ");
+  return unlisted > 0 ? `${names} (and ${unlisted} more)` : names;
+}
 
 // src/commands/run-replay.ts
 function registerRunReplayCommand(program, options) {
@@ -17368,7 +17603,7 @@ function renderRunStatus(response) {
 // src/commands/upload.ts
 import { readFile as readFile2, stat } from "fs/promises";
 import path3 from "path";
-var MAX_UPLOAD_FILE_SIZE_BYTES = 10 * 1024 * 1024;
+var MAX_UPLOAD_FILE_SIZE_BYTES = 25 * 1024 * 1024;
 var DOCUMENT_UPLOAD_FIELD_NAME = "files";
 var MIME_TYPES_BY_EXTENSION = /* @__PURE__ */ new Map([
   [

package/dist/index.d.ts

@@ -19,6 +19,7 @@ declare const EXIT_CODES: {
     readonly rateLimited: 16;
     readonly versionRevoked: 17;
     readonly serviceUnavailable: 18;
+    readonly allotmentExhausted: 19;
     readonly network: 70;
 };
 type CliExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];

package/dist/index.js

@@ -25,9 +25,9 @@ ProductLobster runs product analyses and keeps a product workspace's documents a
 A full analysis is asynchronous and durable. The loop is the same for every workflow:
 
 1. **Start.** Call \`run-start\` with a \`workflow\` of \`launch\`, \`audit\`, \`focused-analysis\`, \`prototype\`, or \`refinement\`, plus its inputs. It returns a run id. 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.
+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.
-4. **Read the result.** When the run is complete, \`run-output\` returns the structured result. Use \`document-list\` and \`document-get\` to read the documents the run produced, and \`prototype-list\` / \`prototype-pack\` for any prototype.
+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; \`run-replay\` re-runs one, optionally from a stage.
 
@@ -60,6 +60,7 @@ Every failure is a structured object: \`{ code, message, requestId, retryHint }\
 | \`invalid_arguments\` | A field was the wrong shape | Fix the named fields and retry |
 | \`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 |
+| \`allotment_exhausted\` | Included outcomes have been used; the key is read-only | Continue with read tools or ask the person to upgrade |
 
 Always keep \`requestId\` \u2014 it is the one join key for support.
 
@@ -14600,6 +14601,8 @@ var RUN_START_REFINEMENT_INSTRUCTION_MAX_LENGTH = 2e3;
 var runStartWorkflowSchema = external_exports.enum(["audit", "launch", "focused-analysis", "prototype", "refinement"]).describe("Which Brain action to start.");
 var runStartInputSchema = external_exports.object({
   workflow: runStartWorkflowSchema,
+  /** `audit`: deliberate acknowledgement when server-owned readiness has gaps. */
+  proceedWithGaps: external_exports.boolean().optional().describe("Proceed with server-recorded audit evidence gaps."),
   /** `launch`: the product idea to take through the launch pipeline. */
   idea: external_exports.string().optional().describe("Product idea for the launch workflow."),
   /** `focused-analysis`: the question to analyze against workspace context. */
@@ -14684,6 +14687,7 @@ var DOCUMENT_TYPE_VALUES = [
   "customer-research",
   "competitive-analysis",
   "customer-demand-analysis",
+  "kill-shot-refutation",
   "strategic-framing",
   "solution-design",
   "prd-generation",
@@ -14704,7 +14708,7 @@ var documentContentInputSchema = documentContentSchema.refine(
   "Document content must not be empty"
 ).describe("Document content to write.");
 var documentListInputSchema = external_exports.object({
-  cursor: external_exports.string().optional().describe("Opaque cursor from a previous page."),
+  cursor: external_exports.string().max(4096).optional().describe("Opaque cursor from a previous page."),
   latest: external_exports.boolean().optional().describe("Return only the newest matching document."),
   limit: external_exports.number().int().min(1).max(100).optional().describe("Maximum number of documents to return; server default is 20."),
   runId: external_exports.string().optional().describe("Identifier of the run to include."),
@@ -14752,7 +14756,7 @@ var documentPutOutputSchema = external_exports.object({
 
 // ../agentic-contract/prototype-list.ts
 var prototypeListInputSchema = external_exports.object({
-  cursor: external_exports.string().optional().describe("Opaque cursor from a previous response.")
+  cursor: external_exports.string().max(4096).optional().describe("Opaque cursor from a previous response.")
 });
 var prototypeStatusEnum = external_exports.enum(["generating", "complete", "failed"]).describe("Coarse prototype done-ness status.");
 var prototypeSummarySchema = external_exports.object({
@@ -14948,7 +14952,10 @@ var ERROR_CODES = [
   "version_revoked",
   // Appended (PRO-1484) — append-only so older clients never see a leading
   // member shift; no AGENTIC_CONTRACT_SCHEMA_VERSION bump (additive code).
-  "service_unavailable"
+  "service_unavailable",
+  // Appended (PRO-1920) — distinct from a periodic rate limit so clients can
+  // render the durable read-only conversion state without parsing prose.
+  "allotment_exhausted"
 ];
 var errorCodeSchema = external_exports.enum(ERROR_CODES);
 var agenticErrorSchema = external_exports.object({
@@ -15087,25 +15094,90 @@ var runReplayOutputSchema = external_exports.object({
 });
 
 // ../agentic-contract/run-output.ts
+var RUN_OUTPUT_MAX_OUTPUT_BYTES = 65536;
+var RUN_OUTPUT_MAX_RESPONSE_BYTES = 98304;
+var RUN_OUTPUT_ENVELOPE_RESERVE_BYTES = 1024;
+var RUN_OUTPUT_MAX_DOCUMENT_IDS = 200;
+var RUN_OUTPUT_MAX_OMITTED_KEYS = 64;
+var RUN_OUTPUT_MAX_OMITTED_KEY_BYTES = 128;
+var RUN_OUTPUT_MAX_STAGE_EDITS = 32;
+var utf8Encoder2 = new TextEncoder();
+function measureRunOutputBytes(value) {
+  const json2 = JSON.stringify(value);
+  return json2 === void 0 ? 0 : utf8Encoder2.encode(json2).byteLength;
+}
 var runOutputInputSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run to read output from."),
-  stage: external_exports.string().optional().describe("Stage name to scope output to; omit for run-level output.")
+  stage: external_exports.string().trim().min(1).optional().describe("Stage name to scope output to; omit for run-level output.")
 });
-var runOutputOutputSchema = external_exports.object({
+var runOutputStageEditFields = {
+  stage: external_exports.string().describe("Stage name, as passed to run-output's stage."),
+  hasUserEdits: external_exports.boolean().describe(
+    "True when the user changed this stage's document after it was generated, so output is out of date for this stage."
+  ),
+  documentId: external_exports.string().optional().describe(
+    "The changed document, to read with document-get. Set only when hasUserEdits is true and document-get can read it; absent on an edited stage, use output."
+  )
+};
+var runOutputFieldsSchema = external_exports.object({
   runId: external_exports.string().describe("Identifier of the run."),
   stage: external_exports.string().nullable().describe("Stage this output is scoped to, or null for run-level."),
-  output: external_exports.record(external_exports.string(), external_exports.unknown()).describe(
-    "Structured output: summaries and IDs, never large inline bodies."
+  output: external_exports.record(external_exports.string(), external_exports.unknown()).refine(
+    (value) => measureRunOutputBytes(value) <= RUN_OUTPUT_MAX_OUTPUT_BYTES,
+    "Run output must not exceed 64 KiB"
+  ).describe(
+    "Structured output, at most 64 KiB of JSON: summaries and IDs, never large inline bodies."
+  ),
+  documentIds: external_exports.array(external_exports.string()).max(RUN_OUTPUT_MAX_DOCUMENT_IDS).describe("IDs of referenced documents to fetch via document-get."),
+  truncated: external_exports.boolean().optional().describe(
+    "True when entries were left out of output to stay within the size limit."
+  ),
+  omittedKeys: external_exports.array(
+    external_exports.string().refine(
+      (key) => measureRunOutputBytes(key) <= RUN_OUTPUT_MAX_OMITTED_KEY_BYTES,
+      "Omitted key must not exceed 128 bytes"
+    )
+  ).max(RUN_OUTPUT_MAX_OMITTED_KEYS).optional().describe(
+    "Top-level output keys left out for size, in order and at most 64: stage names for run-level output (request each by stage), field names for one stage (read the document via document-get)."
+  ),
+  omittedKeyCount: external_exports.number().int().nonnegative().optional().describe("How many top-level output keys were left out for size."),
+  omittedKeysTruncated: external_exports.boolean().optional().describe(
+    "True when omittedKeys lists fewer keys than omittedKeyCount (too many, or a key too long to list)."
+  ),
+  prototypeId: external_exports.string().optional().describe(
+    "Set when prototype content was left out for size: the run's prototype, to fetch with prototype-pack."
+  ),
+  stageEdits: external_exports.array(
+    external_exports.object({
+      ...runOutputStageEditFields,
+      stage: runOutputStageEditFields.stage.refine(
+        (stage) => measureRunOutputBytes(stage) <= RUN_OUTPUT_MAX_OMITTED_KEY_BYTES,
+        "Stage name must not exceed 128 bytes"
+      )
+    })
+  ).max(RUN_OUTPUT_MAX_STAGE_EDITS).optional().describe(
+    "One entry per stage with output, at most 32: whether the user changed that stage's document, and if so the document to read with document-get."
   ),
-  documentIds: external_exports.array(external_exports.string()).describe("IDs of referenced documents to fetch via document-get."),
   schemaVersion: schemaVersionSchema
 });
+var runOutputOutputSchema = runOutputFieldsSchema.refine(
+  (response) => measureRunOutputBytes(response) <= RUN_OUTPUT_MAX_RESPONSE_BYTES - RUN_OUTPUT_ENVELOPE_RESERVE_BYTES,
+  "Run output response must not exceed 96 KiB with its envelope"
+);
+var runOutputParseSchema = runOutputFieldsSchema.extend({
+  output: external_exports.record(external_exports.string(), external_exports.unknown()),
+  documentIds: external_exports.array(external_exports.string()),
+  omittedKeys: external_exports.array(external_exports.string()).optional(),
+  stageEdits: external_exports.array(external_exports.object(runOutputStageEditFields)).optional()
+});
 
 // ../agentic-contract/run-status.ts
 var runStageProgressSchema = external_exports.object({
   name: external_exports.string().describe("Stage identifier."),
   order: external_exports.number().int().positive().describe("1-based position in the run."),
-  status: external_exports.enum(["pending", "running", "completed", "failed"]).describe("Coarse per-stage status.")
+  status: external_exports.enum(["pending", "running", "completed", "failed"]).describe(
+    "Coarse per-stage status. On a run whose status is completed, failed, or cancelled, pending means the stage never ran; stop polling on the run status, not on stage statuses."
+  )
 });
 var runTransitionSchema = external_exports.object({
   from: runStatusEnum.nullable().describe("Prior status, or null for the first transition."),
@@ -15179,6 +15251,9 @@ var AGENTIC_TOOL_NAMES = [
 ];
 
 // ../agentic-contract/workspace-identity.ts
+var workspaceListInputSchema = external_exports.object({
+  cursor: external_exports.string().optional().describe("Opaque cursor from a previous response (reserved for Phase 2).")
+});
 var workspacePipelineTypeSchema = external_exports.enum(["LAUNCH", "AUDIT"]);
 var workspaceIdentitySchema = external_exports.object({
   id: external_exports.string().describe("Stable workspace identifier."),
@@ -15293,6 +15368,7 @@ var EXIT_CODES = {
   rateLimited: 16,
   versionRevoked: 17,
   serviceUnavailable: 18,
+  allotmentExhausted: 19,
   network: 70
 };
 var ERROR_CODE_EXIT_CODES = {
@@ -15307,7 +15383,8 @@ var ERROR_CODE_EXIT_CODES = {
   version_revoked: EXIT_CODES.versionRevoked,
   // PRO-1484: transient backend outage — its own non-zero code so scripts can
   // distinguish a retryable outage from a hard internal fault (exit 1).
-  service_unavailable: EXIT_CODES.serviceUnavailable
+  service_unavailable: EXIT_CODES.serviceUnavailable,
+  allotment_exhausted: EXIT_CODES.allotmentExhausted
 };
 function mapErrorCodeToExitCode(code) {
   return ERROR_CODE_EXIT_CODES[code];
@@ -15863,6 +15940,17 @@ function parseCommaSeparatedList(value) {
   const items = value.split(",").map((item) => item.trim()).filter(Boolean);
   return items.length > 0 ? items : void 0;
 }
+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) {
+  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;
+  }).join("");
+  return codePoints.length > maxCodePoints ? `${escaped}\u2026` : escaped;
+}
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -16810,44 +16898,86 @@ function renderPrototypeList(response) {
 }
 
 // src/runtime/zip-extract.ts
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir, realpath, rm, writeFile } from "fs/promises";
 import path2 from "path";
 import { inflateRawSync } from "zlib";
 var END_OF_CENTRAL_DIRECTORY_SIGNATURE = 101010256;
 var CENTRAL_DIRECTORY_FILE_SIGNATURE = 33639248;
+var CENTRAL_DIRECTORY_DIGITAL_SIGNATURE = 84233040;
 var LOCAL_FILE_HEADER_SIGNATURE = 67324752;
 var ZIP64_SENTINEL = 65535;
 var ZIP64_SIZE_SENTINEL = 4294967295;
+var TRAILING_WINDOWS_ALIAS = /[ .]$/;
+var RESERVED_WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i;
 var MAX_ENTRY_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
 var MAX_TOTAL_DECOMPRESSED_BYTES = 256 * 1024 * 1024;
 var MAX_ENTRY_COUNT = 4096;
+var ZipOutputDirectoryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ZipOutputDirectoryError";
+  }
+};
 async function extractZipToDirectory(bytes, outDir) {
   const archive = Buffer.from(bytes);
-  const root = path2.resolve(outDir);
-  await mkdir(root, { recursive: true });
-  const entries = readCentralDirectory(archive);
-  if (entries.length > MAX_ENTRY_COUNT) {
-    throw new Error(
-      `ZIP archive exceeds the maximum of ${MAX_ENTRY_COUNT} entries.`
-    );
+  const directory = readCentralDirectory(archive);
+  const root = await createOutputRoot(outDir);
+  try {
+    return await extractEntries(archive, directory, root);
+  } catch (error51) {
+    await rm(root, { recursive: true, force: true });
+    throw error51;
+  }
+}
+async function createOutputRoot(outDir) {
+  const requestedRoot = path2.resolve(outDir);
+  let parent;
+  try {
+    parent = await realpath(path2.dirname(requestedRoot));
+  } catch (error51) {
+    if (hasFilesystemCode(error51, "ENOENT") || hasFilesystemCode(error51, "ENOTDIR")) {
+      throw new ZipOutputDirectoryError(
+        "The output parent directory must already exist. Create the parent, then choose a new --out directory."
+      );
+    }
+    throw error51;
+  }
+  const root = path2.join(parent, path2.basename(requestedRoot));
+  try {
+    await mkdir(root, { mode: 448 });
+  } catch (error51) {
+    if (hasFilesystemCode(error51, "EEXIST")) {
+      throw new ZipOutputDirectoryError(
+        "The output directory must not already exist. Choose a new --out directory; existing files were not changed."
+      );
+    }
+    if (hasFilesystemCode(error51, "ENOTDIR")) {
+      throw new ZipOutputDirectoryError(
+        "The output parent directory must already exist. Create the parent, then choose a new --out directory."
+      );
+    }
+    throw error51;
   }
+  return root;
+}
+async function extractEntries(archive, directory, root) {
   const files = [];
   let totalDecompressedBytes = 0;
-  for (const entry of entries) {
+  for (const entry of directory.entries) {
     const normalizedName = normalizeZipEntryName(entry.name);
-    if (!normalizedName || normalizedName.endsWith("/")) {
+    const targetPath = resolveSafeTarget(root, normalizedName);
+    if (normalizedName.endsWith("/")) {
       continue;
     }
-    const targetPath = resolveSafeTarget(root, normalizedName);
-    const contents = readEntryContents(archive, entry);
+    const contents = readEntryContents(archive, entry, directory.offset);
     totalDecompressedBytes += contents.length;
     if (totalDecompressedBytes > MAX_TOTAL_DECOMPRESSED_BYTES) {
       throw new Error(
         `ZIP archive exceeds the maximum decompressed size of ${MAX_TOTAL_DECOMPRESSED_BYTES} bytes.`
       );
     }
-    await mkdir(path2.dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, contents);
+    await mkdir(path2.dirname(targetPath), { recursive: true, mode: 448 });
+    await writeFile(targetPath, contents, { flag: "wx", mode: 384 });
     files.push(normalizedName);
   }
   return {
@@ -16856,39 +16986,60 @@ async function extractZipToDirectory(bytes, outDir) {
     outDir: root
   };
 }
+function hasFilesystemCode(error51, code) {
+  return typeof error51 === "object" && error51 !== null && "code" in error51 && error51.code === code;
+}
 function readCentralDirectory(archive) {
   const eocdOffset = findEndOfCentralDirectory(archive);
   const entryCount = archive.readUInt16LE(eocdOffset + 10);
   const centralDirectorySize = archive.readUInt32LE(eocdOffset + 12);
-  let offset = archive.readUInt32LE(eocdOffset + 16);
-  if (entryCount === ZIP64_SENTINEL || centralDirectorySize === ZIP64_SIZE_SENTINEL || offset === ZIP64_SIZE_SENTINEL) {
+  const directoryOffset = archive.readUInt32LE(eocdOffset + 16);
+  if (entryCount === ZIP64_SENTINEL || centralDirectorySize === ZIP64_SIZE_SENTINEL || directoryOffset === ZIP64_SIZE_SENTINEL) {
     throw new Error("ZIP64 prototype packs are not supported.");
   }
-  const endOffset = offset + centralDirectorySize;
+  if (entryCount > MAX_ENTRY_COUNT) {
+    throw new Error(
+      `ZIP archive exceeds the maximum of ${MAX_ENTRY_COUNT} entries.`
+    );
+  }
+  const endOffset = directoryOffset + centralDirectorySize;
+  if (endOffset > eocdOffset) {
+    throw new Error("Invalid ZIP central directory.");
+  }
   const entries = [];
-  while (offset < endOffset && entries.length < entryCount) {
-    if (archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_FILE_SIGNATURE) {
+  let offset = directoryOffset;
+  while (entries.length < entryCount) {
+    if (offset + 46 > endOffset || archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_FILE_SIGNATURE) {
       throw new Error("Invalid ZIP central directory.");
     }
     const flags = archive.readUInt16LE(offset + 8);
     const compressionMethod = archive.readUInt16LE(offset + 10);
     const compressedSize = archive.readUInt32LE(offset + 20);
+    const uncompressedSize = archive.readUInt32LE(offset + 24);
     const localHeaderOffset = archive.readUInt32LE(offset + 42);
     const nameLength = archive.readUInt16LE(offset + 28);
     const extraLength = archive.readUInt16LE(offset + 30);
     const commentLength = archive.readUInt16LE(offset + 32);
     const nameStart = offset + 46;
+    const nextOffset = nameStart + nameLength + extraLength + commentLength;
+    if (nextOffset > endOffset) {
+      throw new Error("Invalid ZIP central directory.");
+    }
     const name = archive.subarray(nameStart, nameStart + nameLength).toString("utf8");
     entries.push({
       compressedSize,
       compressionMethod,
       flags,
       localHeaderOffset,
-      name
+      name,
+      uncompressedSize
     });
-    offset = nameStart + nameLength + extraLength + commentLength;
+    offset = nextOffset;
+  }
+  if (offset !== endOffset && (offset + 6 > endOffset || archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_DIGITAL_SIGNATURE || offset + 6 + archive.readUInt16LE(offset + 4) !== endOffset)) {
+    throw new Error("Invalid ZIP central directory.");
   }
-  return entries;
+  return { entries, offset: directoryOffset };
 }
 function findEndOfCentralDirectory(archive) {
   const minOffset = Math.max(0, archive.length - 65557);
@@ -16899,16 +17050,19 @@ function findEndOfCentralDirectory(archive) {
   }
   throw new Error("Invalid ZIP archive.");
 }
-function readEntryContents(archive, entry) {
+function readEntryContents(archive, entry, directoryOffset) {
   if (entry.flags % 2 === 1) {
     throw new Error("Encrypted ZIP entries are not supported.");
   }
-  if (archive.readUInt32LE(entry.localHeaderOffset) !== LOCAL_FILE_HEADER_SIGNATURE) {
+  if (entry.localHeaderOffset + 30 > directoryOffset || archive.readUInt32LE(entry.localHeaderOffset) !== LOCAL_FILE_HEADER_SIGNATURE) {
     throw new Error("Invalid ZIP local file header.");
   }
   const localNameLength = archive.readUInt16LE(entry.localHeaderOffset + 26);
   const localExtraLength = archive.readUInt16LE(entry.localHeaderOffset + 28);
   const dataStart = entry.localHeaderOffset + 30 + localNameLength + localExtraLength;
+  if (dataStart + entry.compressedSize > directoryOffset) {
+    throw new Error("Invalid ZIP entry data range.");
+  }
   const compressed = archive.subarray(
     dataStart,
     dataStart + entry.compressedSize
@@ -16919,13 +17073,20 @@ function readEntryContents(archive, entry) {
         `ZIP entry exceeds the maximum decompressed size of ${MAX_ENTRY_DECOMPRESSED_BYTES} bytes.`
       );
     }
+    if (compressed.length !== entry.uncompressedSize) {
+      throw new Error("Invalid ZIP entry decompressed size.");
+    }
     return Buffer.from(compressed);
   }
   if (entry.compressionMethod === 8) {
     try {
-      return inflateRawSync(compressed, {
+      const contents = inflateRawSync(compressed, {
         maxOutputLength: MAX_ENTRY_DECOMPRESSED_BYTES
       });
+      if (contents.length !== entry.uncompressedSize) {
+        throw new Error("Invalid ZIP entry decompressed size.");
+      }
+      return contents;
     } catch (error51) {
       if (isMaxOutputLengthError(error51)) {
         throw new Error(
@@ -16944,15 +17105,21 @@ function isMaxOutputLengthError(error51) {
 }
 function normalizeZipEntryName(name) {
   const normalized = name.replaceAll("\\", "/");
-  if (normalized.length === 0 || normalized.startsWith("/") || normalized.includes("\0")) {
-    return null;
+  if (normalized.length === 0 || normalized.startsWith("/") || normalized.includes(":") || normalized.includes("\0") || normalized.split("/").some(isUnsafeWindowsComponent)) {
+    throw new Error(`Unsafe ZIP entry path: ${name}`);
   }
   return normalized;
 }
+function isUnsafeWindowsComponent(component) {
+  if (component === "." || component === "..") {
+    return false;
+  }
+  return TRAILING_WINDOWS_ALIAS.test(component) || RESERVED_WINDOWS_DEVICE.test(component);
+}
 function resolveSafeTarget(root, entryName) {
   const targetPath = path2.resolve(root, entryName);
   const relative = path2.relative(root, targetPath);
-  if (relative.startsWith("..") || path2.isAbsolute(relative)) {
+  if (relative === "" || relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative)) {
     throw new Error(`Unsafe ZIP entry path: ${entryName}`);
   }
   return targetPath;
@@ -16960,7 +17127,7 @@ function resolveSafeTarget(root, entryName) {
 
 // src/commands/prototype-pack.ts
 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>", "Directory to extract the ZIP into.");
+  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) => {
     const exitCode = await runPrototypePackCommand({
       commandOptions,
@@ -17060,7 +17227,20 @@ async function fetchAndExtractPack(input) {
     });
   }
   const archive = new Uint8Array(await response.arrayBuffer());
-  return await extractZipToDirectory(archive, input.outDir);
+  try {
+    return await extractZipToDirectory(archive, input.outDir);
+  } catch (error51) {
+    if (error51 instanceof ZipOutputDirectoryError) {
+      throw createCliOperationalError({
+        code: "internal",
+        message: error51.message
+      });
+    }
+    throw createCliOperationalError({
+      code: "internal",
+      message: "The prototype ZIP could not be safely extracted. Check the output parent permissions and retry with a new --out directory; if the failure persists, report it."
+    });
+  }
 }
 function isSameOrigin(packUrl, endpoint) {
   try {
@@ -17230,7 +17410,9 @@ function runRunOutputCommand(options) {
   }
   return runCommand(
     {
-      outputSchema: runOutputOutputSchema,
+      // The tolerant consumer schema: a newer plob still reads a server that
+      // predates the run-output size bounds.
+      outputSchema: runOutputParseSchema,
       renderHuman: renderRunOutput,
       toolArguments: compactRecord({
         runId: runId.value,
@@ -17245,16 +17427,69 @@ function runRunOutputCommand(options) {
     }
   );
 }
+var OMITTED_KEY_DISPLAY_MAX = 80;
+var PROTOTYPE_ID_DISPLAY_MAX = 80;
 function renderRunOutput(response) {
   const scope = response.stage ? ` stage ${response.stage}` : "";
   const lines = [`Run ${response.runId}${scope} output`];
   lines.push(`Fields: ${Object.keys(response.output).length}`);
+  const omitted = renderOmittedKeys(response);
+  if (omitted) {
+    lines.push(`Omitted for size: ${omitted}`);
+  }
+  if (response.prototypeId !== void 0) {
+    const prototypeId = escapeTerminalText(
+      response.prototypeId,
+      PROTOTYPE_ID_DISPLAY_MAX
+    );
+    lines.push(
+      `Prototype: ${prototypeId} (fetch with \`plob prototype-pack --prototype-id ${prototypeId}\`)`
+    );
+  }
+  const edited = renderEditedStages(response);
+  if (edited) {
+    lines.push(
+      `Edited by the user (read with \`plob document-get\`): ${edited}`
+    );
+  }
   if (response.documentIds.length > 0) {
-    lines.push(`Documents: ${response.documentIds.join(", ")}`);
+    lines.push(
+      `Documents: ${response.documentIds.map((id) => escapeTerminalText(id, DOCUMENT_ID_DISPLAY_MAX)).join(", ")}`
+    );
   }
   return `${lines.join("\n")}
 `;
 }
+var DOCUMENT_ID_DISPLAY_MAX = 80;
+function renderEditedStages(response) {
+  const edited = (response.stageEdits ?? []).filter(
+    (entry) => entry.hasUserEdits
+  );
+  if (edited.length === 0) {
+    return;
+  }
+  return edited.map((entry) => {
+    const stage = escapeTerminalText(entry.stage, OMITTED_KEY_DISPLAY_MAX);
+    return entry.documentId === void 0 ? stage : `${stage} (${escapeTerminalText(entry.documentId, DOCUMENT_ID_DISPLAY_MAX)})`;
+  }).join(", ");
+}
+function renderOmittedKeys(response) {
+  if (response.truncated !== true) {
+    return;
+  }
+  const listed = (response.omittedKeys ?? []).map(
+    (key) => escapeTerminalText(key, OMITTED_KEY_DISPLAY_MAX)
+  );
+  const unlisted = Math.max(
+    0,
+    (response.omittedKeyCount ?? listed.length) - listed.length
+  );
+  if (listed.length === 0) {
+    return unlisted > 0 ? `${unlisted} ${unlisted === 1 ? "entry" : "entries"}` : void 0;
+  }
+  const names = listed.join(", ");
+  return unlisted > 0 ? `${names} (and ${unlisted} more)` : names;
+}
 
 // src/commands/run-replay.ts
 function registerRunReplayCommand(program, options) {
@@ -17367,7 +17602,7 @@ function renderRunStatus(response) {
 // src/commands/upload.ts
 import { readFile as readFile2, stat } from "fs/promises";
 import path3 from "path";
-var MAX_UPLOAD_FILE_SIZE_BYTES = 10 * 1024 * 1024;
+var MAX_UPLOAD_FILE_SIZE_BYTES = 25 * 1024 * 1024;
 var DOCUMENT_UPLOAD_FIELD_NAME = "files";
 var MIME_TYPES_BY_EXTENSION = /* @__PURE__ */ new Map([
   [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@productlobster/plob",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -58,10 +58,10 @@
   "devDependencies": {
     "@repo/agentic-contract": "workspace:*",
     "@repo/typescript-config": "workspace:*",
-    "@types/node": "25.9.1",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@types/node": "26.6.3",
+    "@vitest/coverage-v8": "^5.0.3",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^5.0.3"
   }
 }