@hasna/mementos 0.16.0 → 0.17.0

package/dist/cli/index.js

@@ -8218,6 +8218,7 @@ __export(exports_helpers, {
   positiveIntOrDefault: () => positiveIntOrDefault,
   parseConfigValue: () => parseConfigValue,
   outputYaml: () => outputYaml,
+  outputJsonAndExit: () => outputJsonAndExit,
   outputJson: () => outputJson,
   makeHandleError: () => makeHandleError,
   importanceColor: () => importanceColor,
@@ -8298,7 +8299,30 @@ function resolveEntityArg(nameOrId, type) {
   process.exit(1);
 }
 function outputJson(data) {
-  console.log(JSON.stringify(data, null, 2));
+  process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+}
+function outputJsonAndExit(data, code) {
+  const payload = `${JSON.stringify(data, null, 2)}
+`;
+  return new Promise((resolve4) => {
+    let settled = false;
+    const finish = (exitCode) => {
+      if (settled)
+        return;
+      settled = true;
+      process.stdout.off("error", onError);
+      process.exit(exitCode);
+      resolve4(undefined);
+    };
+    const onError = () => finish(1);
+    process.stdout.once("error", onError);
+    try {
+      process.stdout.write(payload, () => finish(code));
+    } catch {
+      finish(1);
+    }
+  });
 }
 function positiveIntOrDefault(value, fallback) {
   const parsed = typeof value === "number" ? value : Number(value);
@@ -8493,9 +8517,9 @@ function makeHandleError(program2) {
   return function handleError(e) {
     const globalOpts = program2.opts();
     if (globalOpts.json || globalOpts.format === "json") {
-      outputJson({
+      return outputJsonAndExit({
         error: e instanceof Error ? e.message : String(e)
-      });
+      }, 1);
     } else {
       console.error(chalk.red(e instanceof Error ? e.message : String(e)));
     }
@@ -67748,18 +67772,20 @@ function registerCrudCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("update <id>").description("Update a memory by ID").option("--value <text>", "New value").option("--importance <n>", "New importance 1-10", parseInt).option("--tags <tags>", "New comma-separated tags").option("--summary <text>", "New summary").option("--pin", "Pin the memory").option("--unpin", "Unpin the memory").option("-c, --category <cat>", "New category").option("--scope <scope>", "New scope").option("--status <status>", "New status: active, archived, expired").action((id, opts) => {
+  program2.command("update <id>").description("Update a memory by ID").option("--value <text>", "New value").option("--importance <n>", "New importance 1-10", parseInt).option("--tags <tags>", "New comma-separated tags").option("--summary <text>", "New summary").option("--pin", "Pin the memory").option("--unpin", "Unpin the memory").option("-c, --category <cat>", "New category").option("--scope <scope>", "New scope").option("--status <status>", "New status: active, archived, expired").action(async (id, opts) => {
     try {
       const globalOpts = program2.opts();
       const resolvedId = resolveMemoryId(id);
       const existing = getMemory(resolvedId);
       if (!existing) {
         if (globalOpts.json) {
-          outputJson({ error: `Memory not found: ${id}` });
+          await outputJsonAndExit({ error: `Memory not found: ${id}` }, 1);
         } else {
           console.error(chalk2.red(`Memory not found: ${id}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       const updateInput = {
         version: existing.version
@@ -67811,7 +67837,7 @@ function registerCrudCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("forget <keyOrId>").description("Delete a memory by key or ID").option("--scope <scope>", "Filter by scope (global, shared, private)").option("--agent <agent>", "Filter by agent ID").option("--project <project>", "Filter by project ID").option("--all", "Delete ALL matching memories (no disambiguation needed)").action((keyOrId, opts) => {
+  program2.command("forget <keyOrId>").description("Delete a memory by key or ID").option("--scope <scope>", "Filter by scope (global, shared, private)").option("--agent <agent>", "Filter by agent ID").option("--project <project>", "Filter by project ID").option("--all", "Delete ALL matching memories (no disambiguation needed)").action(async (keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const idMatch = isApiMode() ? null : resolvePartialId(getDatabase(), "memories", keyOrId);
@@ -67835,11 +67861,13 @@ function registerCrudCommands(program2) {
           return;
         }
         if (globalOpts.json) {
-          outputJson({ error: `No memory found: ${keyOrId}` });
+          await outputJsonAndExit({ error: `No memory found: ${keyOrId}` }, 1);
         } else {
           console.error(chalk2.red(`No memory found: ${keyOrId}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       if (matches.length === 1) {
         deleteMemory(matches[0].id);
@@ -67862,10 +67890,10 @@ function registerCrudCommands(program2) {
         return;
       }
       if (globalOpts.json) {
-        outputJson({
+        await outputJsonAndExit({
           error: `Ambiguous key "${keyOrId}" \u2014 ${matches.length} memories found. Use --all to delete all, or specify an ID.`,
           matches: matches.map((m) => ({ id: m.id, key: redactCredentialKey(m.key), scope: m.scope, category: m.category, agent_id: m.agent_id }))
-        });
+        }, 1);
       } else {
         console.log(chalk2.yellow(`Ambiguous key "${keyOrId}" \u2014 ${matches.length} memories found:`));
         for (const m of matches) {
@@ -67874,7 +67902,8 @@ function registerCrudCommands(program2) {
         console.log(chalk2.dim(`
 Use --all to delete all, or specify an ID.`));
       }
-      process.exit(1);
+      if (!globalOpts.json)
+        process.exit(1);
     } catch (e) {
       handleError(e);
     }
@@ -67888,18 +67917,20 @@ init_redact();
 import chalk3 from "chalk";
 function registerViewCommands(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("show <id>").description("Show full detail of a memory by ID (supports partial IDs)").action((id) => {
+  program2.command("show <id>").description("Show full detail of a memory by ID (supports partial IDs)").action(async (id) => {
     try {
       const globalOpts = program2.opts();
       const resolvedId = resolveMemoryId(id);
       const memory = getMemory(resolvedId);
       if (!memory) {
         if (globalOpts.json) {
-          outputJson({ error: `Memory not found: ${id}` });
+          await outputJsonAndExit({ error: `Memory not found: ${id}` }, 1);
         } else {
           console.error(chalk3.red(`Memory not found: ${id}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       touchMemory(memory.id);
       const safe = redactMemoryForOutput(memory);
@@ -67912,17 +67943,19 @@ function registerViewCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("pin <keyOrId>").description("Pin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
+  program2.command("pin <keyOrId>").description("Pin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action(async (keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
       if (!memory) {
         if (globalOpts.json) {
-          outputJson({ error: `No memory found: ${keyOrId}` });
+          await outputJsonAndExit({ error: `No memory found: ${keyOrId}` }, 1);
         } else {
           console.error(chalk3.red(`No memory found: ${keyOrId}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       const updated = updateMemory(memory.id, {
         version: memory.version,
@@ -67937,17 +67970,19 @@ function registerViewCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("unpin <keyOrId>").description("Unpin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action((keyOrId, opts) => {
+  program2.command("unpin <keyOrId>").description("Unpin a memory by key or partial ID").option("--scope <scope>", "Scope filter for key lookup").option("--agent <name>", "Agent filter for key lookup").option("--project <path>", "Project filter for key lookup").action(async (keyOrId, opts) => {
     try {
       const globalOpts = program2.opts();
       const memory = resolveKeyOrId(keyOrId, opts, globalOpts);
       if (!memory) {
         if (globalOpts.json) {
-          outputJson({ error: `No memory found: ${keyOrId}` });
+          await outputJsonAndExit({ error: `No memory found: ${keyOrId}` }, 1);
         } else {
           console.error(chalk3.red(`No memory found: ${keyOrId}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       const updated = updateMemory(memory.id, {
         version: memory.version,
@@ -68140,14 +68175,167 @@ init_helpers();
 init_redact();
 import chalk6 from "chalk";
 import { resolve as resolve6 } from "path";
+
+// src/cli/structured-json.ts
+init_helpers();
+var STRUCTURED_PAGE_MAX_ROWS = 1000;
+var STRUCTURED_ALL_MAX_ROWS = 1e5;
+var STRUCTURED_DEFAULT_MAX_BYTES = 32 * 1024;
+var STRUCTURED_FULL_MAX_BYTES = 64 * 1024;
+var STRUCTURED_ALL_MAX_BYTES = 64 * 1024 * 1024;
+var STRUCTURED_MIN_MAX_BYTES = 1024;
+function structuredMaxBytes(value, opts) {
+  const fallback = opts.all ? STRUCTURED_ALL_MAX_BYTES : opts.detail === "full" ? STRUCTURED_FULL_MAX_BYTES : STRUCTURED_DEFAULT_MAX_BYTES;
+  if (value === undefined)
+    return fallback;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed < STRUCTURED_MIN_MAX_BYTES || parsed > STRUCTURED_ALL_MAX_BYTES) {
+    throw new Error(`--max-bytes must be an integer from ${STRUCTURED_MIN_MAX_BYTES} to ${STRUCTURED_ALL_MAX_BYTES}`);
+  }
+  return parsed;
+}
+function structuredPageLimit(value, fallback) {
+  const parsed = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > STRUCTURED_PAGE_MAX_ROWS) {
+    throw new Error(`--limit must be an integer from 1 to ${STRUCTURED_PAGE_MAX_ROWS}`);
+  }
+  return parsed;
+}
+function compactMemory(memory, opts = {}) {
+  const value = truncateText(memory.summary || memory.value, 240);
+  return {
+    id: memory.id,
+    key: memory.key,
+    value,
+    scope: memory.scope,
+    category: memory.category,
+    importance: memory.importance,
+    status: memory.status,
+    pinned: memory.pinned,
+    ...Array.isArray(memory.tags) && memory.tags.length ? { tags: memory.tags.slice(0, 10) } : {},
+    ...memory.agent_id ? { agent_id: memory.agent_id } : {},
+    ...memory.project_id ? { project_id: memory.project_id } : {},
+    ...memory.session_id ? { session_id: memory.session_id } : {},
+    ...opts.history && memory.accessed_at ? { accessed_at: memory.accessed_at } : {},
+    updated_at: memory.updated_at
+  };
+}
+function compactProject(project) {
+  return {
+    id: project.id,
+    name: project.name,
+    path: truncateText(project.path, 240),
+    ...project.description ? { description: truncateText(project.description, 240) } : {},
+    ...project.memory_prefix ? { memory_prefix: project.memory_prefix } : {},
+    updated_at: project.updated_at
+  };
+}
+function compactAgent(agent) {
+  return {
+    id: agent.id,
+    name: agent.name,
+    role: agent.role || "agent",
+    ...agent.description ? { description: truncateText(agent.description, 240) } : {},
+    ...agent.active_project_id ? { active_project_id: agent.active_project_id } : {},
+    last_seen_at: agent.last_seen_at
+  };
+}
+function compactSearchResult(result) {
+  return {
+    memory: compactMemory(result.memory),
+    score: result.score,
+    match_type: result.match_type,
+    ...result.confidence !== undefined ? { confidence: result.confidence } : {},
+    ...result.highlights?.length ? { highlights: result.highlights.slice(0, 3).map((highlight) => ({
+      field: highlight.field,
+      snippet: truncateText(highlight.snippet, 240)
+    })) } : {}
+  };
+}
+function makeEnvelope(args, items, byteTruncated, omittedFromPage) {
+  const hasMore = byteTruncated || args.sourceHasMore;
+  const complete = args.offset === 0 && !hasMore;
+  const nextCursor = hasMore ? args.offset + items.length : null;
+  const envelope = {
+    [args.collection]: items,
+    _meta: {
+      receipt: args.receipt,
+      count: items.length,
+      limit: args.all ? null : args.limit,
+      offset: args.offset,
+      next_cursor: nextCursor,
+      has_more: hasMore,
+      complete,
+      all: args.all,
+      detail: args.detail,
+      max_rows: args.all ? STRUCTURED_ALL_MAX_ROWS : STRUCTURED_PAGE_MAX_ROWS,
+      max_bytes: args.maxBytes,
+      response_bytes: 0,
+      truncated: hasMore,
+      truncation_reason: byteTruncated ? "max_bytes" : args.sourceHasMore ? "limit" : null,
+      omitted_from_page: omittedFromPage,
+      next_arguments: nextCursor === null ? null : {
+        cursor: nextCursor,
+        limit: args.limit,
+        ...args.includeDetailInNextArguments !== false && args.detail === "full" ? { full: true } : {},
+        max_bytes: args.maxBytes,
+        ...args.nextArguments
+      },
+      continuation_scope: "unchanged_snapshot"
+    }
+  };
+  for (let attempt = 0;attempt < 8; attempt += 1) {
+    const bytes = Buffer.byteLength(`${JSON.stringify(envelope)}
+`);
+    const meta = envelope["_meta"];
+    if (bytes === meta.response_bytes)
+      break;
+    meta.response_bytes = bytes;
+  }
+  return envelope;
+}
+function structuredCollectionOutput(args) {
+  const complete = makeEnvelope(args, args.items, false, 0);
+  const completeText = `${JSON.stringify(complete)}
+`;
+  if (Buffer.byteLength(completeText) <= args.maxBytes)
+    return completeText;
+  if (args.all) {
+    throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${args.maxBytes} bytes; use paginated JSON output or raise --max-bytes explicitly`);
+  }
+  for (let count = args.items.length - 1;count >= 0; count -= 1) {
+    const envelope = makeEnvelope({ ...args, sourceHasMore: true }, args.items.slice(0, count), true, args.items.length - count);
+    const text = `${JSON.stringify(envelope)}
+`;
+    if (Buffer.byteLength(text) > args.maxBytes)
+      continue;
+    if (count === 0 && args.items.length > 0) {
+      throw new Error(`One structured row exceeds --max-bytes=${args.maxBytes}; use compact detail or raise --max-bytes`);
+    }
+    return text;
+  }
+  throw new Error(`Structured output metadata exceeds --max-bytes=${args.maxBytes}`);
+}
+
+// src/cli/commands/memory-cmd-search.ts
 function registerSearchCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("search <query>").description("Full-text search across memories").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--project <path>", "Project filter (path or name)").option("--agent <name>", "Agent filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show match highlights and wider snippets").option("--history", "Show recent search queries instead of searching").option("--popular", "Show most popular search queries").action((query, opts) => {
+  program2.command("search <query>").description("Full-text search across memories").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--project <path>", "Project filter (path or name)").option("--agent <name>", "Agent filter").option("--session <id>", "Session ID filter").option("--limit <n>", "Max results", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show match highlights and wider snippets").option("--all", `Exhaust matching results in one explicit JSON receipt (hard max: ${STRUCTURED_ALL_MAX_ROWS})`).option("--full", "Return full legacy search-result objects in the bounded JSON receipt").option("--max-bytes <n>", "JSON response byte ceiling", parseInt).option("--history", "Show recent search queries instead of searching").option("--popular", "Show most popular search queries").action((query, opts) => {
     try {
       const fmt = getOutputFormat(program2, opts.format);
       const isStructured = fmt === "json" || fmt === "csv" || fmt === "yaml";
-      const limit = positiveIntOrDefault(opts.limit, isStructured ? 20 : DEFAULT_SEARCH_LIMIT);
-      const offset = cursorOrOffset(opts.cursor, opts.offset);
+      const jsonMode = fmt === "json";
+      const all = Boolean(opts.all);
+      const detail = opts.full ? "full" : "compact";
+      if (!jsonMode && (all || opts.full || opts.maxBytes !== undefined)) {
+        throw new Error("--all, --full, and --max-bytes require JSON output");
+      }
+      if (all && opts.limit !== undefined)
+        throw new Error("--all cannot be combined with --limit");
+      const limit = jsonMode ? structuredPageLimit(opts.limit, 20) : positiveIntOrDefault(opts.limit, isStructured ? 20 : DEFAULT_SEARCH_LIMIT);
+      const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
+      if (all && offset !== 0)
+        throw new Error("--all requires --cursor/--offset 0");
       if (opts.history) {
         const history = getSearchHistory(limit);
         if (fmt === "json") {
@@ -68195,16 +68383,36 @@ function registerSearchCommand(program2) {
         tags: opts.tags ? opts.tags.split(",").map((t) => t.trim()) : undefined,
         project_id: projectId,
         agent_id: agentId,
-        session_id: opts.session || globalOpts.session,
-        limit: isStructured ? limit : limit + 1,
-        offset
+        session_id: opts.session || globalOpts.session
       };
-      const fetched = searchMemories(query, filter);
+      const target = all ? STRUCTURED_ALL_MAX_ROWS : limit;
+      const { rows: fetched, hasMore } = collectPagedRows((cursor, pageLimit) => {
+        const rows = searchMemories(query, { ...filter, limit: pageLimit, offset: cursor });
+        return {
+          rows,
+          has_more: rows.length < pageLimit ? false : undefined,
+          next_cursor: cursor + rows.length
+        };
+      }, target, offset);
+      if (all && hasMore) {
+        throw new Error(`Exhaustive search output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output`);
+      }
       const sanitized = fetched.map(redactSearchResultForOutput);
-      const hasMore = !isStructured && sanitized.length > limit;
       const results = hasMore ? sanitized.slice(0, limit) : sanitized;
-      if (fmt === "json") {
-        outputJson(sanitized);
+      if (jsonMode) {
+        const items = detail === "full" ? results.map((result) => ({ ...result })) : results.map(compactSearchResult);
+        process.stdout.write(structuredCollectionOutput({
+          collection: "results",
+          receipt: "mementos.search.page.v1",
+          items,
+          offset,
+          limit,
+          sourceHasMore: hasMore,
+          all,
+          detail,
+          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail }),
+          nextArguments: { query }
+        }));
         return;
       }
       if (fmt === "csv") {
@@ -68257,18 +68465,20 @@ init_redact();
 import chalk7 from "chalk";
 function registerWhenToUseCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("when-to-use <memory_id>").description("Show the when_to_use guidance for a memory").action((memoryId) => {
+  program2.command("when-to-use <memory_id>").description("Show the when_to_use guidance for a memory").action(async (memoryId) => {
     try {
       const globalOpts = program2.opts();
       const resolvedId = resolveMemoryId(memoryId);
       const memory = getMemory(resolvedId);
       if (!memory) {
         if (globalOpts.json) {
-          outputJson({ error: `Memory not found: ${memoryId}` });
+          await outputJsonAndExit({ error: `Memory not found: ${memoryId}` }, 1);
         } else {
           console.error(chalk7.red(`Memory not found: ${memoryId}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       const safe = redactMemoryForOutput(memory);
       const whenToUse = safe.when_to_use ?? null;
@@ -68401,7 +68611,7 @@ init_memories();
 init_helpers();
 import chalk10 from "chalk";
 function registerRemoveCommand(program2) {
-  program2.command("remove <nameOrId>").description("Remove/delete a memory by name or ID (alias for memory forget)").option("--agent <id>", "Agent ID").option("--scope <scope>", "Filter by scope (when looking up by key)").action((nameOrId, opts) => {
+  program2.command("remove <nameOrId>").description("Remove/delete a memory by name or ID (alias for memory forget)").option("--agent <id>", "Agent ID").option("--scope <scope>", "Filter by scope (when looking up by key)").action(async (nameOrId, opts) => {
     const globalOpts = program2.opts();
     const agentId = opts.agent || globalOpts.agent;
     let id = isApiMode() ? null : resolvePartialId(getDatabase(), "memories", nameOrId);
@@ -68415,11 +68625,13 @@ function registerRemoveCommand(program2) {
     }
     if (!id) {
       if (globalOpts.json) {
-        outputJson({ error: `Memory not found: ${nameOrId}` });
+        await outputJsonAndExit({ error: `Memory not found: ${nameOrId}` }, 1);
       } else {
         console.error(chalk10.red(`Memory not found: ${nameOrId}`));
       }
-      process.exit(1);
+      if (!globalOpts.json)
+        process.exit(1);
+      return;
     }
     const deleted = deleteMemory(id);
     if (deleted) {
@@ -68430,11 +68642,13 @@ function registerRemoveCommand(program2) {
       }
     } else {
       if (globalOpts.json) {
-        outputJson({ error: `Memory not found: ${nameOrId}` });
+        await outputJsonAndExit({ error: `Memory not found: ${nameOrId}` }, 1);
       } else {
         console.error(chalk10.red(`Memory not found: ${nameOrId}`));
       }
-      process.exit(1);
+      if (!globalOpts.json)
+        process.exit(1);
+      return;
     }
   });
 }
@@ -68465,7 +68679,7 @@ var RECALL_EXIT_FUZZY = 2;
 // src/cli/commands/memory-cmd-recall.ts
 function registerRecallCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("recall <key>").alias("get").description("Recall a memory by exact key (use --fuzzy to fall back to the nearest match)").option("--scope <scope>", "Scope filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--fuzzy", "If the exact key is absent, return the nearest match instead (exits 2)").action((key, opts) => {
+  program2.command("recall <key>").alias("get").description("Recall a memory by exact key (use --fuzzy to fall back to the nearest match)").option("--scope <scope>", "Scope filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--fuzzy", "If the exact key is absent, return the nearest match instead (exits 2)").action(async (key, opts) => {
     try {
       const globalOpts = program2.opts();
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
@@ -68498,28 +68712,32 @@ function registerRecallCommand(program2) {
           const safeBest = redactSearchResultForOutput(results[0]);
           touchMemory(safeBest.memory.id);
           if (globalOpts.json) {
-            outputJson({
+            await outputJsonAndExit({
               fuzzy_match: true,
               requested_key: key,
               returned_key: safeBest.memory.key,
               score: safeBest.score,
               match_type: safeBest.match_type,
               memory: safeBest.memory
-            });
+            }, RECALL_EXIT_FUZZY);
           } else {
             console.error(chalk11.yellow(`No memory with key "${key}". Showing the nearest match "${safeBest.memory.key}" ` + `(score: ${safeBest.score.toFixed(2)}, match: ${safeBest.match_type}) \u2014 this is a DIFFERENT record.`));
             console.log(formatMemoryDetail(safeBest.memory));
           }
-          process.exit(RECALL_EXIT_FUZZY);
+          if (!globalOpts.json)
+            process.exit(RECALL_EXIT_FUZZY);
+          return;
         }
       }
       const message = opts.fuzzy ? `No memory found for key: ${key}` : `No memory found for key: ${key} (exact match; pass --fuzzy to return the nearest record instead)`;
       if (globalOpts.json) {
-        outputJson({ error: message, requested_key: key });
+        await outputJsonAndExit({ error: message, requested_key: key }, RECALL_EXIT_NOT_FOUND);
       } else {
         console.error(chalk11.yellow(message));
       }
-      process.exit(RECALL_EXIT_NOT_FOUND);
+      if (!globalOpts.json)
+        process.exit(RECALL_EXIT_NOT_FOUND);
+      return;
     } catch (e) {
       handleError(e);
     }
@@ -68533,19 +68751,19 @@ init_redact();
 init_helpers();
 import chalk12 from "chalk";
 import { resolve as resolve8 } from "path";
-var STRUCTURED_PAGE_MAX_ROWS = 1000;
-var STRUCTURED_ALL_MAX_ROWS = 5000;
-var STRUCTURED_DEFAULT_MAX_BYTES = 32 * 1024;
-var STRUCTURED_FULL_MAX_BYTES = 64 * 1024;
-var STRUCTURED_ALL_MAX_BYTES = 1024 * 1024;
-var STRUCTURED_MIN_MAX_BYTES = 1024;
-function structuredMaxBytes(value, opts) {
-  const fallback = opts.all ? STRUCTURED_ALL_MAX_BYTES : opts.detail === "full" ? STRUCTURED_FULL_MAX_BYTES : STRUCTURED_DEFAULT_MAX_BYTES;
+var STRUCTURED_PAGE_MAX_ROWS2 = 1000;
+var STRUCTURED_ALL_MAX_ROWS2 = 1e5;
+var STRUCTURED_DEFAULT_MAX_BYTES2 = 32 * 1024;
+var STRUCTURED_FULL_MAX_BYTES2 = 64 * 1024;
+var STRUCTURED_ALL_MAX_BYTES2 = 64 * 1024 * 1024;
+var STRUCTURED_MIN_MAX_BYTES2 = 1024;
+function structuredMaxBytes2(value, opts) {
+  const fallback = opts.all ? STRUCTURED_ALL_MAX_BYTES2 : opts.detail === "full" ? STRUCTURED_FULL_MAX_BYTES2 : STRUCTURED_DEFAULT_MAX_BYTES2;
   if (value === undefined)
     return fallback;
   const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isInteger(parsed) || parsed < STRUCTURED_MIN_MAX_BYTES || parsed > STRUCTURED_ALL_MAX_BYTES) {
-    throw new Error(`--max-bytes must be an integer from ${STRUCTURED_MIN_MAX_BYTES} to ${STRUCTURED_ALL_MAX_BYTES}`);
+  if (!Number.isInteger(parsed) || parsed < STRUCTURED_MIN_MAX_BYTES2 || parsed > STRUCTURED_ALL_MAX_BYTES2) {
+    throw new Error(`--max-bytes must be an integer from ${STRUCTURED_MIN_MAX_BYTES2} to ${STRUCTURED_ALL_MAX_BYTES2}`);
   }
   return parsed;
 }
@@ -68597,7 +68815,7 @@ function makeStructuredEnvelope(args) {
       complete,
       all: args.all,
       detail: args.detail,
-      max_rows: args.all ? STRUCTURED_ALL_MAX_ROWS : STRUCTURED_PAGE_MAX_ROWS,
+      max_rows: args.all ? STRUCTURED_ALL_MAX_ROWS2 : STRUCTURED_PAGE_MAX_ROWS2,
       max_bytes: args.maxBytes,
       response_bytes: 0,
       truncated: !complete,
@@ -68661,7 +68879,7 @@ function structuredMemoryOutput(args) {
 }
 function assertReceiptFlags(opts, receiptMode, requestedFormat) {
   if (!receiptMode && (opts.all || opts.full || opts.maxBytes !== undefined)) {
-    throw new Error("--all, --full, and --max-bytes require --agent-json receipt mode");
+    throw new Error("--all, --full, and --max-bytes require JSON receipt mode (--json, --format json, or --agent-json)");
   }
   if (receiptMode && requestedFormat !== undefined && requestedFormat !== "json") {
     throw new Error("--agent-json cannot be combined with a non-JSON --format");
@@ -68672,20 +68890,20 @@ function assertReceiptFlags(opts, receiptMode, requestedFormat) {
 }
 function registerListCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("list").description("List memories with optional filters").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--importance-min <n>", "Minimum importance", parseInt).option("--pinned", "Show only pinned").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--session <id>", "Session ID filter").option("--limit <n>", `Max results (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS})`, parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--status <status>", "Status filter: active, archived, expired").option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show wider memory snippets in human output").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES})`, parseInt).action((opts) => {
+  program2.command("list").description("List memories with optional filters").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--tags <tags>", "Comma-separated tags filter").option("--importance-min <n>", "Minimum importance", parseInt).option("--pinned", "Show only pinned").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--session <id>", "Session ID filter").option("--limit <n>", `Max results (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS2})`, parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--status <status>", "Status filter: active, archived, expired").option("--format <fmt>", "Output format: compact (default), json, csv, yaml").option("--verbose", "Show wider memory snippets in human output").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS2} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES2})`, parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
       const requestedFormat = opts.format ?? globalOpts.format;
       const fmt = getOutputFormat(program2, opts.format);
-      const receiptMode = Boolean(opts.agentJson);
+      const receiptMode = Boolean(opts.agentJson || fmt === "json");
       const isStructured = fmt === "json" || fmt === "csv" || fmt === "yaml";
       assertReceiptFlags(opts, receiptMode, requestedFormat);
       const requestedLimit = opts.limit;
       const all = Boolean(opts.all);
       const detail = opts.full ? "full" : "compact";
       const limit = requestedLimit === undefined ? receiptMode ? DEFAULT_COMPACT_LIMIT : isStructured ? undefined : DEFAULT_COMPACT_LIMIT : positiveIntOrDefault(requestedLimit, receiptMode ? DEFAULT_COMPACT_LIMIT : isStructured ? 50 : DEFAULT_COMPACT_LIMIT);
-      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS) {
-        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS}; use --all for a bounded exhaustive read`);
+      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS2) {
+        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS2}; use --all for a bounded exhaustive read`);
       }
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
       if (all && offset !== 0) {
@@ -68712,7 +68930,7 @@ function registerListCommand(program2) {
         status: opts.status,
         session_id: opts.session || globalOpts.session
       };
-      const target = all ? STRUCTURED_ALL_MAX_ROWS : limit;
+      const target = all ? STRUCTURED_ALL_MAX_ROWS2 : limit;
       const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
         const page = listMemoriesPage({
           ...filter,
@@ -68726,7 +68944,7 @@ function registerListCommand(program2) {
         };
       }, target, offset);
       if (all && hasMore) {
-        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output instead`);
+        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS2} rows; use paginated JSON output instead`);
       }
       const memories = target === undefined ? collected : collected.slice(0, target);
       const sanitized = memories.map(redactMemoryForOutput);
@@ -68739,7 +68957,7 @@ function registerListCommand(program2) {
           sourceHasMore: hasMore,
           all,
           detail,
-          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail })
+          maxBytes: structuredMaxBytes2(opts.maxBytes, { all, detail })
         }));
         return;
       }
@@ -68776,7 +68994,7 @@ function registerListCommand(program2) {
         offset,
         hasMore,
         command: "mementos list",
-        detailHint: "use mementos show <id> for full details, --json for the compatible full array, or --agent-json for a bounded receipt"
+        detailHint: "use mementos show <id> for full details; JSON output is a bounded receipt, with --full/--all as explicit compatibility escapes"
       });
     } catch (e) {
       handleError(e);
@@ -69203,7 +69421,7 @@ init_helpers();
 import chalk16 from "chalk";
 function registerHistoryCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("history").description("List memories sorted by most recently accessed").option("--limit <n>", `Max results (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS})`, parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--verbose", "Show wider memory snippets").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES})`, parseInt).action((opts) => {
+  program2.command("history").description("List memories sorted by most recently accessed").option("--limit <n>", `Max results (agent JSON page max: ${STRUCTURED_PAGE_MAX_ROWS2})`, parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--verbose", "Show wider memory snippets").option("--agent-json", "Output a bounded, receipt-bearing JSON page").option("--all", `Exhaust agent JSON results from offset zero (hard max: ${STRUCTURED_ALL_MAX_ROWS2} rows)`).option("--full", "Emit full memory objects in agent JSON instead of compact projections").option("--max-bytes <n>", `Agent JSON response byte ceiling (hard max: ${STRUCTURED_ALL_MAX_BYTES2})`, parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
       const format = getOutputFormat(program2);
@@ -69222,14 +69440,14 @@ function registerHistoryCommand(program2) {
       const all = Boolean(opts.all);
       const detail = opts.full ? "full" : "compact";
       const limit = requestedLimit === undefined ? receiptMode ? DEFAULT_SEARCH_LIMIT : isJson ? undefined : DEFAULT_SEARCH_LIMIT : positiveIntOrDefault(requestedLimit, receiptMode ? DEFAULT_SEARCH_LIMIT : isJson ? 20 : DEFAULT_SEARCH_LIMIT);
-      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS) {
-        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS}; use --all for a bounded exhaustive read`);
+      if (receiptMode && limit !== undefined && limit > STRUCTURED_PAGE_MAX_ROWS2) {
+        throw new Error(`--limit cannot exceed the agent JSON page ceiling of ${STRUCTURED_PAGE_MAX_ROWS2}; use --all for a bounded exhaustive read`);
       }
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
       if (all && offset !== 0) {
         throw new Error("--all requires --cursor/--offset 0");
       }
-      const target = all ? STRUCTURED_ALL_MAX_ROWS : limit;
+      const target = all ? STRUCTURED_ALL_MAX_ROWS2 : limit;
       const { rows: collected, hasMore } = collectPagedRows((cursor, pageLimit) => {
         const page = listMemoryHistoryPage({ limit: pageLimit, offset: cursor });
         return {
@@ -69239,7 +69457,7 @@ function registerHistoryCommand(program2) {
         };
       }, target, offset);
       if (all && hasMore) {
-        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output instead`);
+        throw new Error(`Exhaustive structured output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS2} rows; use paginated JSON output instead`);
       }
       const memories = target === undefined ? collected : collected.slice(0, target);
       const sanitized = memories.map(redactMemoryForOutput);
@@ -69252,7 +69470,7 @@ function registerHistoryCommand(program2) {
           sourceHasMore: hasMore,
           all,
           detail,
-          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail }),
+          maxBytes: structuredMaxBytes2(opts.maxBytes, { all, detail }),
           history: true
         }));
         return;
@@ -69461,7 +69679,7 @@ init_helpers();
 import { resolve as resolve12 } from "path";
 function registerExportCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("export").description("Export memories as JSON").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((opts) => {
+  program2.command("export").description("Export a truthful full-detail JSON page; use --all for the exhaustive legacy array").option("--scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--limit <n>", "Page size (default: 100, maximum: 1000)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--max-bytes <n>", "Paginated response byte ceiling (default: 65536)", parseInt).option("--all", "Exhaust the complete query and emit the legacy full JSON array").action((opts) => {
     try {
       const globalOpts = program2.opts();
       const agentId = resolveAgentFilter(opts.agent || globalOpts.agent);
@@ -69478,9 +69696,43 @@ function registerExportCommand(program2) {
         agent_id: agentId,
         project_id: projectId
       };
-      const memories = listMemoriesBounded(filter, 1e4).rows;
-      const sanitized = memories.map(redactMemoryForOutput);
-      outputJson(sanitized);
+      const exhaustive = Boolean(opts.all);
+      const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
+      if (exhaustive && opts.limit !== undefined) {
+        throw new Error("--all cannot be combined with --limit");
+      }
+      if (exhaustive && offset !== 0) {
+        throw new Error("--all requires --cursor/--offset 0");
+      }
+      if (exhaustive && opts.maxBytes !== undefined) {
+        throw new Error("--max-bytes applies to paginated exports; exhaustive --all is an explicit unbounded compatibility escape");
+      }
+      if (exhaustive) {
+        const complete = listMemoriesBounded(filter, undefined).rows.map(redactMemoryForOutput);
+        outputJson(complete);
+        return;
+      }
+      const limit = structuredPageLimit(opts.limit, 100);
+      const page = listMemoriesBounded({ ...filter, offset }, limit);
+      const sanitized = page.rows.map(redactMemoryForOutput);
+      process.stdout.write(structuredCollectionOutput({
+        collection: "memories",
+        receipt: "mementos.export.page.v1",
+        items: sanitized,
+        offset,
+        limit,
+        sourceHasMore: page.has_more,
+        all: false,
+        detail: "full",
+        maxBytes: structuredMaxBytes(opts.maxBytes, { all: false, detail: "full" }),
+        nextArguments: {
+          ...opts.scope ? { scope: opts.scope } : {},
+          ...opts.category ? { category: opts.category } : {},
+          ...agentId ? { agent: agentId } : {},
+          ...projectPath ? { project: projectPath } : {}
+        },
+        includeDetailInNextArguments: false
+      }));
     } catch (e) {
       handleError(e);
     }
@@ -69886,7 +70138,7 @@ function inspectLocalRestoreSource(source) {
 }
 function registerRestoreCommand(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("restore [file]").description("Restore the database from a backup file").option("--latest", "Restore the most recent backup from the mementos backups dir").option("--force", "Skip confirmation and perform the restore").action((filePath, opts) => {
+  program2.command("restore [file]").description("Restore the database from a backup file").option("--latest", "Restore the most recent backup from the mementos backups dir").option("--force", "Skip confirmation and perform the restore").action(async (filePath, opts) => {
     try {
       const globalOpts = program2.opts();
       const backupsDir = join11(getDataRoot(), "backups");
@@ -69947,7 +70199,7 @@ function registerRestoreCommand(program2) {
         if (result.rejected > 0) {
           const msg = `${result.rejected} of ${result.total} memories were rejected and did not persist. See errors.`;
           if (globalOpts.json) {
-            outputJson({
+            await outputJsonAndExit({
               action: "restore",
               status: "failed",
               source,
@@ -69957,11 +70209,12 @@ function registerRestoreCommand(program2) {
               rejected: result.rejected,
               total: result.total,
               error: msg
-            });
+            }, 1);
           } else {
             console.error(chalk21.red(msg));
           }
-          process.exit(1);
+          if (!globalOpts.json)
+            process.exit(1);
         }
         if (globalOpts.json) {
           outputJson({
@@ -70116,20 +70369,40 @@ function registerAgentCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("agents").description("List all registered agents").option("--limit <n>", "Max results (compact default: 20)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).action((opts) => {
+  program2.command("agents").description("List all registered agents").option("--limit <n>", "Max results (compact default: 20)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--all", `Exhaust all agents in one explicit JSON receipt (hard max: ${STRUCTURED_ALL_MAX_ROWS})`).option("--full", "Return full agent objects instead of compact projections").option("--max-bytes <n>", "JSON response byte ceiling", parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
-      const limit = positiveIntOrDefault(opts.limit, DEFAULT_COMPACT_LIMIT);
+      const jsonMode = Boolean(globalOpts.json);
+      const all = Boolean(opts.all);
+      const detail = opts.full ? "full" : "compact";
+      if (!jsonMode && (all || opts.full || opts.maxBytes !== undefined)) {
+        throw new Error("--all, --full, and --max-bytes require --json");
+      }
+      if (all && opts.limit !== undefined)
+        throw new Error("--all cannot be combined with --limit");
+      const limit = jsonMode ? structuredPageLimit(opts.limit, DEFAULT_COMPACT_LIMIT) : positiveIntOrDefault(opts.limit, DEFAULT_COMPACT_LIMIT);
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
-      const explicitPagination = opts.limit !== undefined || opts.cursor !== undefined || opts.offset !== undefined;
-      const agents = listAgents({
-        limit: globalOpts.json ? explicitPagination ? limit : undefined : limit + 1,
-        offset
-      });
-      const hasMore = !globalOpts.json && agents.length > limit;
+      if (all && offset !== 0)
+        throw new Error("--all requires --cursor/--offset 0");
+      const agents = all ? listAgents() : listAgents({ limit: limit + 1, offset });
+      if (all && agents.length > STRUCTURED_ALL_MAX_ROWS) {
+        throw new Error(`Exhaustive agent output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output`);
+      }
+      const hasMore = !all && agents.length > limit;
       const displayAgents = hasMore ? agents.slice(0, limit) : agents;
-      if (globalOpts.json) {
-        outputJson(agents);
+      if (jsonMode) {
+        const items = detail === "full" ? displayAgents.map((agent) => ({ ...agent })) : displayAgents.map(compactAgent);
+        process.stdout.write(structuredCollectionOutput({
+          collection: "agents",
+          receipt: "mementos.agents.page.v1",
+          items,
+          offset,
+          limit,
+          sourceHasMore: hasMore,
+          all,
+          detail,
+          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail })
+        }));
         return;
       }
       if (displayAgents.length === 0) {
@@ -70153,7 +70426,7 @@ function registerAgentCommands(program2) {
       handleError(e);
     }
   });
-  program2.command("agent-update <id>").description("Update an agent's name, description, or role").option("--name <name>", "New agent name").option("-d, --description <text>", "New description").option("-r, --role <role>", "New role").action((id, opts) => {
+  program2.command("agent-update <id>").description("Update an agent's name, description, or role").option("--name <name>", "New agent name").option("-d, --description <text>", "New description").option("-r, --role <role>", "New role").action(async (id, opts) => {
     try {
       const globalOpts = program2.opts();
       const updates = {};
@@ -70165,20 +70438,24 @@ function registerAgentCommands(program2) {
         updates.role = opts.role;
       if (Object.keys(updates).length === 0) {
         if (globalOpts.json) {
-          outputJson({ error: "No updates provided. Use --name, --description, or --role." });
+          await outputJsonAndExit({ error: "No updates provided. Use --name, --description, or --role." }, 1);
         } else {
           console.error(chalk22.red("No updates provided. Use --name, --description, or --role."));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       const agent = updateAgent(id, updates);
       if (!agent) {
         if (globalOpts.json) {
-          outputJson({ error: `Agent not found: ${id}` });
+          await outputJsonAndExit({ error: `Agent not found: ${id}` }, 1);
         } else {
           console.error(chalk22.red(`Agent not found: ${id}`));
         }
-        process.exit(1);
+        if (!globalOpts.json)
+          process.exit(1);
+        return;
       }
       if (globalOpts.json) {
         outputJson(agent);
@@ -70266,7 +70543,7 @@ import { resolve as resolve17 } from "path";
 init_helpers();
 function registerProjectCommands(program2) {
   const handleError = makeHandleError(program2);
-  program2.command("projects").description("Manage projects").option("--add", "Add a new project").option("--update <id>", "Update a project by its exact stable ID").option("--name <name>", "Project name").option("--path <path>", "Project path").option("--description <text>", "Project description").option("--memory-prefix <prefix>", "Project memory prefix").option("--expected-revision <revision>", "Exact updated_at revision required for compare-and-swap").option("--idempotency-key <key>", "Caller-owned key for one guarded mutation").option("--operation-id <id>", "Operation identifier (defaults to the idempotency key)").option("--step-id <id>", "Step identifier (defaults to mementos_project_update)").option("--dry-run", "Validate and preview the guarded update without writing").option("--rollback-receipt <id>", "Restore the exact before snapshot from an accepted update receipt").option("--limit <n>", "Max results (compact default: 20)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).action((opts) => {
+  program2.command("projects").description("Manage projects").option("--add", "Add a new project").option("--update <id>", "Update a project by its exact stable ID").option("--name <name>", "Project name").option("--path <path>", "Project path").option("--description <text>", "Project description").option("--memory-prefix <prefix>", "Project memory prefix").option("--expected-revision <revision>", "Exact updated_at revision required for compare-and-swap").option("--idempotency-key <key>", "Caller-owned key for one guarded mutation").option("--operation-id <id>", "Operation identifier (defaults to the idempotency key)").option("--step-id <id>", "Step identifier (defaults to mementos_project_update)").option("--dry-run", "Validate and preview the guarded update without writing").option("--rollback-receipt <id>", "Restore the exact before snapshot from an accepted update receipt").option("--limit <n>", "Max results (compact default: 20)", parseInt).option("--cursor <n>", "Cursor offset for the next page", parseInt).option("--offset <n>", "Offset for pagination", parseInt).option("--all", `Exhaust all projects in one explicit JSON receipt (hard max: ${STRUCTURED_ALL_MAX_ROWS})`).option("--full", "Return full project objects instead of compact projections").option("--max-bytes <n>", "JSON response byte ceiling", parseInt).action((opts) => {
     try {
       const globalOpts = program2.opts();
       if (opts.add && opts.update) {
@@ -70347,15 +70624,39 @@ function registerProjectCommands(program2) {
         }
         return;
       }
-      const allProjects = listProjects();
-      const limit = positiveIntOrDefault(opts.limit, DEFAULT_COMPACT_LIMIT);
+      const jsonMode = Boolean(globalOpts.json);
+      const all = Boolean(opts.all);
+      const detail = opts.full ? "full" : "compact";
+      if (!jsonMode && (all || opts.full || opts.maxBytes !== undefined)) {
+        throw new Error("--all, --full, and --max-bytes require --json");
+      }
+      if (all && opts.limit !== undefined) {
+        throw new Error("--all cannot be combined with --limit");
+      }
+      const limit = jsonMode ? structuredPageLimit(opts.limit, DEFAULT_COMPACT_LIMIT) : positiveIntOrDefault(opts.limit, DEFAULT_COMPACT_LIMIT);
       const offset = cursorOrOffset(opts.cursor, opts.offset) ?? 0;
-      const explicitPagination = opts.limit !== undefined || opts.cursor !== undefined || opts.offset !== undefined;
-      const projects = globalOpts.json ? explicitPagination ? allProjects.slice(offset, offset + limit) : allProjects : allProjects.slice(offset, offset + limit + 1);
-      const hasMore = !globalOpts.json && projects.length > limit;
-      const displayProjects = hasMore ? projects.slice(0, limit) : projects;
-      if (globalOpts.json) {
-        outputJson(projects);
+      if (all && offset !== 0)
+        throw new Error("--all requires --cursor/--offset 0");
+      const allProjects = listProjects();
+      if (all && allProjects.length > STRUCTURED_ALL_MAX_ROWS) {
+        throw new Error(`Exhaustive project output exceeds the hard safety limit of ${STRUCTURED_ALL_MAX_ROWS} rows; use paginated JSON output`);
+      }
+      const page = all ? allProjects : allProjects.slice(offset, offset + limit + 1);
+      const hasMore = !all && page.length > limit;
+      const displayProjects = hasMore ? page.slice(0, limit) : page;
+      if (jsonMode) {
+        const items = detail === "full" ? displayProjects.map((project) => ({ ...project })) : displayProjects.map(compactProject);
+        process.stdout.write(structuredCollectionOutput({
+          collection: "projects",
+          receipt: "mementos.projects.page.v1",
+          items,
+          offset,
+          limit,
+          sourceHasMore: hasMore,
+          all,
+          detail,
+          maxBytes: structuredMaxBytes(opts.maxBytes, { all, detail })
+        }));
         return;
       }
       if (displayProjects.length === 0) {
@@ -71629,7 +71930,8 @@ function resolveApiStatus(version = getPackageVersion()) {
       error = err instanceof Error ? err.message : String(err);
     }
   }
-  const validBase = error ? null : apiBase;
+  const resolvedApiUrl = error ? null : apiUrl ?? resolved?.baseUrl ?? null;
+  const validBase = error ? null : apiBase ?? resolved?.baseUrl.replace(/\/v1$/, "") ?? null;
   const apiKeyConfigured = configured?.apiKeyPresent ?? false;
   let transport;
   if (hasExplicitLocalDbPath()) {
@@ -71646,7 +71948,7 @@ function resolveApiStatus(version = getPackageVersion()) {
       app: "mementos",
       version,
       transport,
-      api_url: apiUrl,
+      api_url: resolvedApiUrl,
       api_base: validBase,
       api_key_present: apiKeyConfigured || resolved !== null
     },
@@ -74934,11 +75236,13 @@ function registerConsolidationCommands(program2) {
       }
     } catch (error40) {
       if (program2.opts().json) {
-        outputJson({ error: error40 instanceof Error ? error40.message : String(error40) });
+        await outputJsonAndExit({ error: error40 instanceof Error ? error40.message : String(error40) }, 1);
       } else {
         console.error(chalk42.red(error40 instanceof Error ? error40.message : String(error40)));
       }
-      process.exit(1);
+      if (!program2.opts().json)
+        process.exit(1);
+      return;
     }
   });
   program2.command("reflect").description("Reflect on a session, task, or range and save structured lessons").requiredOption("--on <target>", "Trajectory target: session, task, range").option("--source <idOrRange>", "Session ID, task ID, or range as since..until").option("--dry-run", "Critique without writing lesson memories").option("--project <idOrPath>", "Project ID, name, or path").option("--agent <nameOrId>", "Agent name or ID").option("--since <iso>", "Range start timestamp").option("--until <iso>", "Range end timestamp").option("--provider <name>", "Critic provider: anthropic, openai, cerebras, grok").option("--model <name>", "Critic model").option("--max-tokens <n>", "Maximum critic output tokens", parseNumber2).option("--format <fmt>", "Output format: compact, json").action(async (opts) => {
@@ -74977,11 +75281,13 @@ function registerConsolidationCommands(program2) {
       }
     } catch (error40) {
       if (program2.opts().json) {
-        outputJson({ error: error40 instanceof Error ? error40.message : String(error40) });
+        await outputJsonAndExit({ error: error40 instanceof Error ? error40.message : String(error40) }, 1);
       } else {
         console.error(chalk42.red(error40 instanceof Error ? error40.message : String(error40)));
       }
-      process.exit(1);
+      if (!program2.opts().json)
+        process.exit(1);
+      return;
     }
   });
 }