nolo-cli 0.84.0-alpha.1 → 0.84.0

package/{chunk-3VPDELAP.js → chunk-FP76KI2Y.js}

@@ -9,7 +9,10 @@ import {
   resolveRawAgentInput,
   resolveServerUrl,
   writeUsage
-} from "./chunk-JYYZCK2Z.js";
+} from "./chunk-V7E4PXQD.js";
+import {
+  resolveMachineId
+} from "./chunk-ESHYE7WU.js";
 import {
   agentRunCardLabels,
   createCliLocalRuntimeAdapter,
@@ -26,8 +29,9 @@ import {
   resolveFileWriteGateEnabled,
   resolveLocalUserId,
   t,
-  toolLabel
-} from "./chunk-GHEJJGJI.js";
+  toolLabel,
+  toolLabelVariants
+} from "./chunk-LMREEBWT.js";
 import {
   createRunActivityTracker,
   popSingleQueueMessage,
@@ -35,38 +39,36 @@ import {
   resolveRunQueuePath,
   settleRunTerminalAuthoritatively,
   spawnLocalBackgroundRun
-} from "./chunk-HH65VA5U.js";
+} from "./chunk-I3TQJXQ7.js";
 import {
+  clearCredentialAvailability,
   readCredentialEntry,
   recordCredentialProbe,
   resolveCredentialKeyWithFallback
-} from "./chunk-DWUCB2A3.js";
+} from "./chunk-42V6BK2E.js";
 import {
   getReadableCliDb
-} from "./chunk-RXX4GDIH.js";
+} from "./chunk-LS2ZANRJ.js";
 import {
   readDbRecord,
   resolveAgentRecordFromHybridStore
-} from "./chunk-NRALD3CC.js";
+} from "./chunk-QSHEEA5N.js";
 import {
   isLocalCliAgentKey
-} from "./chunk-SPAQ4PVV.js";
+} from "./chunk-SV5IJK6K.js";
 import {
   CliProviderQuotaError
 } from "./chunk-MP64VFGD.js";
-import {
-  resolveMachineId
-} from "./chunk-ESHYE7WU.js";
 import {
   applyModelLayerOverride,
   buildModelLayerOverride
 } from "./chunk-LTRXGFMS.js";
 import {
   formatAgentListCard
-} from "./chunk-RZOJRTKR.js";
+} from "./chunk-3BGIKIPF.js";
 import {
   isTransientFetchError
-} from "./chunk-5XTOKQLW.js";
+} from "./chunk-5UTFL4QJ.js";
 import {
   isGatewayHttpStatus
 } from "./chunk-NF64D32W.js";
@@ -78,17 +80,20 @@ import {
   formatStatusRunCard,
   formatStopRunCard,
   isAgentRunTerminalStatus
-} from "./chunk-NTW5GWDM.js";
+} from "./chunk-3VNWWVKB.js";
+import {
+  extractGoogleValidationLink
+} from "./chunk-BMQ2MJUK.js";
 import {
   buildMemorySubjectsForAgent,
   chooseMemoryOwners,
   loadMemoryCandidatesFromDb,
   resolveAgentMemoryPolicy
-} from "./chunk-KEZNSFGD.js";
+} from "./chunk-MZYBSTMH.js";
 import {
   API_REPORTED_COST_MULTIPLIER,
   parseUiAskChoiceContent
-} from "./chunk-IDGYOD2O.js";
+} from "./chunk-XP3VVAPG.js";
 import {
   isOAuthApiKeyRef
 } from "./chunk-YYLHWIW6.js";
@@ -99,50 +104,51 @@ import {
 } from "./chunk-TRV2MIDW.js";
 import {
   getDefaultCliLocalRuntimeDb
-} from "./chunk-C3FZR5EC.js";
+} from "./chunk-2F7RJC6L.js";
 import {
   buildSkillDiscoveryContextLayer
 } from "./chunk-E4MARS3Q.js";
 import {
   parseExternalSkillMarkdown,
   parseSkillDocProtocol
-} from "./chunk-AETZ7AD6.js";
+} from "./chunk-Q554LLSI.js";
 import {
   LOCAL_AGENT_CONFIG_MISSING_CODE,
   LOCAL_TURN_ABORTED_CODE,
   readActionGate
-} from "./chunk-PF6O3GR3.js";
+} from "./chunk-52Q2IW2X.js";
 import {
   resolveAgentRuntimeConfigFromRecord
-} from "./chunk-AX7RMXSH.js";
+} from "./chunk-4MK3I7Y4.js";
 import {
   createThinkParserState,
   flushThinkParser,
   processThinkChunk
 } from "./chunk-N7J63Q6C.js";
 import {
+  QUOTA_ERROR_PATTERNS,
   isQuotaExhaustedError,
   isQuotaLimited403Body,
   mergeAvailabilityDeadline,
   resolveCooldownGate
-} from "./chunk-CJCJF5XB.js";
+} from "./chunk-FDTR4QJ6.js";
 import {
   isAntigravityOAuthAgent
-} from "./chunk-LHDV2QUI.js";
+} from "./chunk-GNCCNNZD.js";
 import {
   resolveClientVersion
-} from "./chunk-TMPLPCVX.js";
+} from "./chunk-6OZ36FXI.js";
 import {
   DEFAULT_CONTEXT_WINDOW,
   getModelContextWindow,
   normalizeUsage
-} from "./chunk-7QVPPOEC.js";
+} from "./chunk-HKNXJGEC.js";
 import {
   clipCompactText
-} from "./chunk-E36HZARC.js";
+} from "./chunk-P5EVSOPA.js";
 import {
   findModelConfig
-} from "./chunk-MXUSPS2N.js";
+} from "./chunk-OIVSQH2O.js";
 import {
   compactWhitespace
 } from "./chunk-DWLEOOGR.js";
@@ -167,13 +173,14 @@ import {
   CLIENT_VERSION_TOO_OLD_CODE,
   NOLO_CLIENT_VERSION_HEADER,
   buildClientVersionUpgradeMessage
-} from "./chunk-AJHEFRGJ.js";
+} from "./chunk-Q67DOFOO.js";
 import {
   parsePositiveFiniteNumberOrFallback
 } from "./chunk-Y5GCAMGP.js";
 import {
-  createMemoryKey
-} from "./chunk-NHRQCXIQ.js";
+  createMemoryKey,
+  ulid
+} from "./chunk-VMFTFOWF.js";
 import {
   asTrimmedLowercaseString
 } from "./chunk-QSJ3HFEF.js";
@@ -181,10 +188,13 @@ import {
   BUILTIN_NOLO_AGENT_KEY,
   BUILTIN_NOLO_AGENT_NAME,
   builtinAgentCatalogEntryById
-} from "./chunk-5J7W2VWW.js";
+} from "./chunk-BNGW5ASC.js";
 import {
   parsePublicAgentId
-} from "./chunk-BJIRLHJR.js";
+} from "./chunk-M2EJHDJP.js";
+import {
+  isLevelNotFoundError
+} from "./chunk-OW765XBU.js";
 import {
   asTrimmedString
 } from "./chunk-3EUW3WEO.js";
@@ -380,6 +390,24 @@ function styleCliText(text, style, enabled = resolveCliColorEnabled()) {
 function dimCliText(text, enabled = resolveCliColorEnabled()) {
   return styleCliText(text, "dim", enabled);
 }
+var OSC8_OPEN = "\x1B]8;;";
+var OSC8_CLOSE = "\x1B\\";
+function sanitizeHyperlinkLabel(label) {
+  return label.replace(/[\u0000-\u001f\u007f]/g, "");
+}
+function resolveCliHyperlinkEnabled(env = process.env, isTTY = Boolean(process.stdout.isTTY)) {
+  const setting = asTrimmedLowercaseString(env.NOLO_CLI_HYPERLINKS);
+  if (setting === "0" || setting === "false" || setting === "off") return false;
+  if (setting === "1" || setting === "true" || setting === "on") return true;
+  return isTTY;
+}
+function formatCliHyperlink(url, label, enabled = resolveCliHyperlinkEnabled()) {
+  if (!url) return label;
+  const safeLabel = sanitizeHyperlinkLabel(label);
+  if (!enabled) return `${safeLabel} (${url})`;
+  if (!safeLabel) return url;
+  return `${OSC8_OPEN}${url}${OSC8_CLOSE}${safeLabel}${OSC8_OPEN}${OSC8_CLOSE}`;
+}
 
 // node_modules/ansi-regex/index.js
 function ansiRegex({ onlyFirst = false } = {}) {
@@ -614,8 +642,12 @@ function stringWidth(input, options = {}) {
 
 // packages/cli/tui/tuiAnsi.ts
 var ANSI_ESCAPE_REGEX = /\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+var OSC8_HYPERLINK_REGEX = /\x1b\]8;;[^\x1b]*\x1b\\/g;
 var ALL_ANSI_ESCAPE_REGEX = ansiRegex();
 var FIRST_ANSI_ESCAPE_REGEX = ansiRegex({ onlyFirst: true });
+function stripOsc8Hyperlinks(text) {
+  return text.replace(OSC8_HYPERLINK_REGEX, "");
+}
 function stripAnsi2(text) {
   return text.replace(ANSI_ESCAPE_REGEX, "").replace(ALL_ANSI_ESCAPE_REGEX, "");
 }
@@ -777,6 +809,7 @@ function visibleWidth(str) {
 }
 function truncateAnsi(text, maxWidth) {
   if (maxWidth <= 0) return "";
+  text = stripOsc8Hyperlinks(text);
   if (visibleWidth(text) <= maxWidth) return text;
   let width = 0;
   let out = "";
@@ -817,7 +850,7 @@ function countPhysicalLines(text, columns) {
   const lines = text.split("\n");
   let total = 0;
   for (const line of lines) {
-    const width = displayWidth(line);
+    const width = visibleWidth(stripOsc8Hyperlinks(line));
     total += Math.max(1, Math.ceil(width / columns));
   }
   return Math.max(total, 1);
@@ -8190,12 +8223,79 @@ function normalizeListLine(line) {
   }
   return line;
 }
+var TOOL_TREE_HEADER_RE = /^•\s+(.+?)\s+\((\d+)\)$/;
+var TOOL_TREE_LEAF_RE = /^([├└]──\s+)(.*?)\s{2}(✓|✗|!)(?:\s+(.*))?$/;
+var TOOL_SINGLE_RE = /^▸\s+(.+?)(?:\s+·\s+(.*?))?(?:\s{2}(✓|✗|!)(?:\s+(.*))?)$/;
+function plainToolLine(line) {
+  return stripAnsi2(line);
+}
+var TOOL_TREE_GROUP_LABELS = new Set(
+  ["execShell", "readFile", "fetchWebpage", "exa_search"].flatMap(toolLabelVariants)
+);
+function isKnownToolGroupLabel(label) {
+  return TOOL_TREE_GROUP_LABELS.has(label);
+}
+function toolTreeHeaderMatch(line) {
+  const match = plainToolLine(line).match(TOOL_TREE_HEADER_RE);
+  return match && isKnownToolGroupLabel(match[1]) ? match : null;
+}
+function isToolTreeHeaderLine(line) {
+  return toolTreeHeaderMatch(line) !== null;
+}
+function isToolTreeLeafLine(line) {
+  return TOOL_TREE_LEAF_RE.test(plainToolLine(line));
+}
+function isToolSingleLine(line) {
+  return TOOL_SINGLE_RE.test(plainToolLine(line));
+}
+function isToolGroupBoundary(cur, next) {
+  return isToolTreeLeafLine(cur) && isToolTreeHeaderLine(next);
+}
+function statusColorSeq(marker, brightness) {
+  if (marker === "\u2713") return colorSeq("success", brightness);
+  if (marker === "\u2717") return colorSeq("danger", brightness);
+  return colorSeq("warning", brightness);
+}
+function styleTuiToolLine(line, brightness) {
+  const plain = plainToolLine(line);
+  const chrome = colorSeq("chrome", brightness);
+  const muted = colorSeq("muted", brightness);
+  const header = toolTreeHeaderMatch(plain);
+  if (header) {
+    return `${chrome}\u2022${STYLE.reset} ${STYLE.bold}${muted}${header[1]}${STYLE.reset} ${chrome}${STYLE.dim}(${header[2]})${STYLE.reset}`;
+  }
+  const leaf = plain.match(TOOL_TREE_LEAF_RE);
+  if (leaf) {
+    const [, connector, detail, marker, statusDetail] = leaf;
+    let rendered = `${chrome}${connector}${STYLE.reset}${chrome}${detail}${STYLE.reset}`;
+    rendered += `  ${statusColorSeq(marker, brightness)}${marker}${STYLE.reset}`;
+    if (statusDetail) {
+      const metaSeq = marker === "\u2713" ? chrome : statusColorSeq(marker, brightness);
+      rendered += ` ${metaSeq}${STYLE.dim}${statusDetail}${STYLE.reset}`;
+    }
+    return rendered;
+  }
+  const single = plain.match(TOOL_SINGLE_RE);
+  if (single) {
+    const [, label, detail, marker, statusDetail] = single;
+    let rendered = `${chrome}\u25B8${STYLE.reset} ${STYLE.bold}${muted}${label}${STYLE.reset}`;
+    if (detail) rendered += ` ${chrome}\xB7 ${detail}${STYLE.reset}`;
+    rendered += `  ${statusColorSeq(marker, brightness)}${marker}${STYLE.reset}`;
+    if (statusDetail) {
+      const metaSeq = marker === "\u2713" ? chrome : statusColorSeq(marker, brightness);
+      rendered += ` ${metaSeq}${STYLE.dim}${statusDetail}${STYLE.reset}`;
+    }
+    return rendered;
+  }
+  return null;
+}
 function isPolishListLikeLine(line) {
-  return LIST_LIKE_RE_FOR_GUARD.test(normalizeListLine(line));
+  return LIST_LIKE_RE_FOR_GUARD.test(normalizeListLine(plainToolLine(line)));
 }
-var LIST_LIKE_RE_FOR_GUARD = /^\s*(?:•|☐|☑|\d+\.)\s|^\s*[\u2460-\u2473]|^\s*[├└]──\s/;
+var LIST_LIKE_RE_FOR_GUARD = /^\s*(?:•|☐|☑|\d+\.)\s|^\s*[\u2460-\u2473]|^\s*[├└]──\s|^\s*▸\s/;
 function polishBreathInsertsBlankBetween(cur, next) {
   if (cur === "" || next === "") return false;
+  if (isToolGroupBoundary(cur, next)) return true;
   return isPolishListLikeLine(cur) !== isPolishListLikeLine(next);
 }
 function convertMarkdownTablesForTerminal(text) {
@@ -8265,16 +8365,14 @@ function polishAssistantStructure(text, options = {}) {
     return line;
   });
   const afterHeading = maskedLines.join("\n").replace(/([^\n])\n(#{1,3} )/g, "$1\n\n$2").replace(/^(#{1,3} .+)\n(?!\n)/gm, "$1\n\n").replace(/\n{4,}/g, "\n\n\n");
-  const LIST_LIKE = /^\s*(?:•|☐|☑|\d+\.)\s|^\s*[\u2460-\u2473]|^\s*[├└]──\s/;
   const headingLines = afterHeading.split("\n");
   const breathed = [];
   for (let i = 0; i < headingLines.length; i++) {
     breathed.push(headingLines[i]);
     const cur = headingLines[i];
     const next = headingLines[i + 1];
-    if (cur === "" || next === void 0 || next === "") continue;
-    if (LIST_LIKE.test(cur) === LIST_LIKE.test(next)) continue;
-    breathed.push("");
+    if (next === void 0) continue;
+    if (polishBreathInsertsBlankBetween(cur, next)) breathed.push("");
   }
   const polishedMasked = breathed.join("\n");
   const polished = polishedMasked.replace(
@@ -8284,6 +8382,8 @@ function polishAssistantStructure(text, options = {}) {
   return options.trimEdges === false ? polished : polished.trim();
 }
 function styleRichMarkdownLine(line, brightness) {
+  const toolLine = styleTuiToolLine(line, brightness);
+  if (toolLine !== null) return toolLine;
   const heading = line.match(/^(#{1,3})\s+(.+)$/);
   if (heading) {
     const level = heading[1].length;
@@ -8435,16 +8535,23 @@ function emitFormattedAssistantBlock(write, text, trailingNewline = false) {
 }
 function classifyStreamLine(line) {
   if (line === "") return "blank";
-  if (TASK_LIST_RE.test(line) || UNORDERED_LIST_RE.test(line) || ORDERED_LIST_RE.test(line) || /^\s*(?:•|☐|☑)\s/.test(line) || /^\s*[\u2460-\u2473]/.test(line)) {
+  const plain = plainToolLine(line);
+  if (isToolTreeHeaderLine(plain)) return "tool-header";
+  if (isToolTreeLeafLine(plain)) return "tool-leaf";
+  if (isToolSingleLine(plain)) return "tool";
+  if (TASK_LIST_RE.test(plain) || UNORDERED_LIST_RE.test(plain) || ORDERED_LIST_RE.test(plain) || /^\s*(?:•|☐|☑)\s/.test(plain) || /^\s*[\u2460-\u2473]/.test(plain)) {
     return "list";
   }
+  if (isPolishListLikeLine(plain)) return "list";
   return "prose";
 }
+function isStreamListLike(kind) {
+  return kind === "list" || kind === "tool-header" || kind === "tool-leaf" || kind === "tool";
+}
 function needsListProseBreath(prev, next) {
   if (prev === null || prev === "blank" || next === "blank") return false;
-  const prevList = prev === "list";
-  const nextList = next === "list";
-  return prevList !== nextList;
+  if (prev === "tool-leaf" && next === "tool-header") return true;
+  return isStreamListLike(prev) !== isStreamListLike(next);
 }
 function createRenderAwareStreamWriter(args) {
   const brightness = resolveTuiBrightness();
@@ -9802,6 +9909,7 @@ ${this.text}
 // packages/cli/client/agentRunOutput.ts
 var IDENTITY_LABEL_SEPARATOR = " > ";
 var THINKING_PREVIEW_BUFFER_LIMIT = 512;
+var TUI_PROGRESS_BUFFER_LIMIT = 1200;
 function appendThinkingPreview(current, chunk, limit = THINKING_PREVIEW_BUFFER_LIMIT) {
   if (limit <= 0) return "";
   const combined = current + chunk;
@@ -9815,6 +9923,14 @@ function formatCompactionSummaryLine(event) {
     return `${STYLE.dim}\u81EA\u52A8\u4E0A\u4E0B\u6587\u538B\u7F29\u5931\u8D25${reason}\uFF0C\u672C\u8F6E\u4EE5\u672A\u538B\u7F29\u4E0A\u4E0B\u6587\u7EE7\u7EED\u3002\u82E5\u53CD\u590D\u51FA\u73B0\u53EF\u624B\u52A8 /compact\u3002${STYLE.reset}
 `;
   }
+  if (event.skipped) {
+    if (event.skipReason === "adapter-missing-summary-methods" || event.skipReason === "load-summary-failed") {
+      return `${STYLE.dim}\u81EA\u52A8\u4E0A\u4E0B\u6587\u538B\u7F29\u4E0D\u53EF\u7528\uFF08${event.skipReason}\uFF09\uFF0C\u672C\u8F6E\u4E0D\u538B\u7F29\u3002${STYLE.reset}
+`;
+    }
+    return "";
+  }
+  if (!event.summaryGenerated) return "";
   let detail = "\u751F\u6210\u5386\u53F2\u6458\u8981";
   const saved = typeof event.savedTokens === "number" ? event.savedTokens : void 0;
   let line = `\u5DF2\u538B\u7F29\u4E0A\u4E0B\u6587\uFF1A${detail}`;
@@ -9855,6 +9971,14 @@ function formatToolJsonEvent(event) {
   })}
 `;
 }
+function shouldPromoteTuiNarration(text) {
+  if (text.length >= TUI_PROGRESS_BUFFER_LIMIT) return true;
+  return /(^|\n)\s*(?:#{1,3}\s|```|[-*+]\s|\d+[.)]\s)/.test(text);
+}
+function narrationActivityLabel(text) {
+  const oneLine = stripAnsi2(text).replace(/[`*_#>]/g, "").replace(/\s+/g, " ").trim();
+  return truncateThinkingHint(oneLine, 60);
+}
 function createCliTurnOutput(params) {
   const { options } = params;
   const workingLabel = params.workingLabel ?? `${options.agentName} -> working`;
@@ -9863,7 +9987,8 @@ function createCliTurnOutput(params) {
     tuiTrees: options.output.tuiTrees === true
   });
   const eventMode = resolveAgentEventMode(options);
-  const showThinking = options.showThinking !== false;
+  const assistantLabelManaged = options.output.assistantLabelManaged === true;
+  const showThinking = !assistantLabelManaged && options.showThinking !== false;
   let streamedAssistantText = false;
   let everStreamedAnyText = false;
   let printedAssistantLabel = false;
@@ -9900,7 +10025,6 @@ function createCliTurnOutput(params) {
     }
   };
   let compactionEvent = null;
-  const assistantLabelManaged = options.output.assistantLabelManaged === true;
   const writeToolOutput = (chunk) => {
     if (!chunk) return;
     if (typeof options.output.writeToolBlock === "function") {
@@ -9912,9 +10036,25 @@ function createCliTurnOutput(params) {
   const renderWriter = createRenderAwareStreamWriter({
     write: (chunk) => options.output.write(chunk)
   });
+  let pendingTuiNarration = "";
+  let tuiNarrationPromoted = false;
+  const flushPendingTuiNarration = () => {
+    if (!pendingTuiNarration) return;
+    formatToolEvent.reset?.();
+    renderWriter.push(pendingTuiNarration);
+    pendingTuiNarration = "";
+    tuiNarrationPromoted = true;
+    streamedAssistantText = true;
+    options.activityReporter?.(null);
+  };
+  const dropPendingTuiProgress = () => {
+    pendingTuiNarration = "";
+    tuiNarrationPromoted = false;
+    options.activityReporter?.(null);
+  };
   const writeVisibleAssistantChunk = (chunk) => {
     if (!chunk) return;
-    formatToolEvent.reset?.();
+    if (!assistantLabelManaged) formatToolEvent.reset?.();
     const parsed = processThinkChunk(chunk, thinkState);
     thinkState = parsed.state;
     if (!parsed.content && !parsed.reasoning) return;
@@ -9930,8 +10070,23 @@ ${options.agentName}${IDENTITY_LABEL_SEPARATOR}`);
       }
       printedAssistantLabel = true;
     }
-    streamedAssistantText = true;
     everStreamedAnyText = true;
+    if (assistantLabelManaged) {
+      if (tuiNarrationPromoted) {
+        renderWriter.push(parsed.content);
+        streamedAssistantText = true;
+        return;
+      }
+      pendingTuiNarration += parsed.content;
+      if (shouldPromoteTuiNarration(pendingTuiNarration)) {
+        flushPendingTuiNarration();
+      } else {
+        const label = narrationActivityLabel(pendingTuiNarration);
+        if (label) options.activityReporter?.(label);
+      }
+      return;
+    }
+    streamedAssistantText = true;
     renderWriter.push(parsed.content);
   };
   const handleToolEvent = (event) => {
@@ -9947,6 +10102,9 @@ ${options.agentName}${IDENTITY_LABEL_SEPARATOR}`);
       return;
     }
     if (event.type === "tool-call") {
+      if (assistantLabelManaged && pendingTuiNarration) {
+        dropPendingTuiProgress();
+      }
       renderWriter.flush();
       formatToolEvent(event);
       endThinkingPhase();
@@ -9954,6 +10112,7 @@ ${options.agentName}${IDENTITY_LABEL_SEPARATOR}`);
         options.output.write("\n");
         streamedAssistantText = false;
       }
+      if (assistantLabelManaged) tuiNarrationPromoted = false;
       const activeLabel = formatConservativeActiveToolLabel(event);
       spinner.show(activeLabel);
       options.activityReporter?.(activeLabel);
@@ -9977,6 +10136,26 @@ ${options.agentName}${IDENTITY_LABEL_SEPARATOR}`);
   return {
     spinner,
     eventMode,
+    /**
+     * Terminal cleanup for abort/error paths that never reach `finish()`.
+     *
+     * A user abort discards the transient TUI progress buffer: the user stopped
+     * on purpose and the dock already showed that text as activity. A genuine
+     * failure must not swallow prose that never got the chance to be *proven*
+     * durable (only a following tool call proves "progress"), so it promotes the
+     * pending buffer and flushes what was already promoted — otherwise a short
+     * final answer followed by a transport error disappears from the transcript.
+     */
+    cancel(cleanup) {
+      if (assistantLabelManaged && cleanup?.preservePendingNarration) {
+        flushPendingTuiNarration();
+        if (streamedAssistantText) {
+          renderWriter.flush();
+          options.output.write("\n");
+        }
+      }
+      dropPendingTuiProgress();
+    },
     pushText(chunk) {
       writeVisibleAssistantChunk(chunk);
     },
@@ -9984,21 +10163,39 @@ ${options.agentName}${IDENTITY_LABEL_SEPARATOR}`);
       markThinkingDelta(chunk);
     },
     handleToolEvent,
-    /** 记录一条 compaction 观测事件（TUI 在 turn 结束时渲染一行 dim 摘要）。 */
     recordCompaction(event) {
-      compactionEvent = event;
+      const significance = (e) => e.failed ? 4 : e.summaryGenerated ? 3 : e.compressed ? 2 : 1;
+      if (!compactionEvent || significance(event) >= significance(compactionEvent)) {
+        compactionEvent = event;
+      }
     },
     showWorking(label) {
       const activeLabel = label ?? workingLabel;
       spinner.show(activeLabel);
       options.activityReporter?.(activeLabel);
     },
+    /**
+     * Pre-delta turn phase label (ctx-overflow-feedback batch 3).
+     *
+     * localLoop 在首个 provider delta 之前依次发出 turn-phase 事件
+     * （validating-context → compacting → waiting-provider）；此前 CLI 只有
+     * llm-start 才进入明确 working 状态，压缩期间 spinner 停在通用
+     * working 文案上，用户无法区分「卡在检查上下文 / 压缩 / 等模型」。
+     * 两个显示面（bare CLI 的 spinner 与 TUI 的 dock activityReporter）与
+     * showWorking 走同一条投影，保证两端文案不漂移。
+     */
+    showPhase(phase) {
+      const label = phase === "validating-context" ? t("contextChecking") : phase === "compacting" ? t("contextCompacting") : t("waitingForModel");
+      spinner.show(label);
+      options.activityReporter?.(label);
+    },
     finish(fallbackContent) {
       const flushedThink = flushThinkParser(thinkState);
       thinkState = flushedThink.state;
       if (flushedThink.content) {
         writeVisibleAssistantChunk(flushedThink.content);
       }
+      if (assistantLabelManaged) flushPendingTuiNarration();
       endThinkingPhase();
       spinner.stop();
       options.activityReporter?.(null);
@@ -10103,6 +10300,7 @@ async function readStreamingAgentRun(options, res, existingSpinner) {
   let content = "";
   let dialogId;
   let usage;
+  let sawDone = false;
   const handlePayload = (payload) => {
     if (typeof payload?.dialogId === "string" && payload.dialogId.trim()) {
       dialogId = payload.dialogId;
@@ -10115,6 +10313,7 @@ async function readStreamingAgentRun(options, res, existingSpinner) {
     }
     if (payload?.type === "done") {
       usage = payload.usage;
+      sawDone = true;
       return;
     }
     if (payload?.type === "dialog" || payload?.type === "status") {
@@ -10168,6 +10367,9 @@ async function readStreamingAgentRun(options, res, existingSpinner) {
     }
   } catch (error) {
     turnOutput.spinner.stop();
+    turnOutput.cancel({
+      preservePendingNarration: !options.abortSignal?.aborted
+    });
     if (options.abortSignal?.aborted) {
       return {
         exitCode: 0,
@@ -10197,6 +10399,15 @@ ${describeClientVersionTooOldFailure(message, error)}`);
 `);
     return { exitCode: 1 };
   }
+  if (options.abortSignal?.aborted && !sawDone) {
+    turnOutput.spinner.stop();
+    turnOutput.cancel();
+    return {
+      exitCode: 0,
+      ...dialogId ? { dialogId } : {},
+      streamInterrupted: true
+    };
+  }
   turnOutput.finish(content);
   const usageText = formatUsage(usage, dialogId);
   if (usageText && shouldShowUsage(options.env))
@@ -10411,9 +10622,9 @@ function findCollapsedPasteSpanAt(buffer, pos, opts = {}) {
 }
 
 // packages/cli/client/agentRun.ts
-import { ulid } from "ulid";
+import { ulid as ulid2 } from "ulid";
 async function loadRunLocalAgentTurn() {
-  const { runLocalAgentTurn } = await import("./agentRuntimeLocal-YRONTDLM.js");
+  const { runLocalAgentTurn } = await import("./agentRuntimeLocal-3WTYYIT2.js");
   return runLocalAgentTurn;
 }
 var stripDebugNoise = (s) => s.replace(/\s*raw="[\s\S]*"/g, "").replace(/\s*raw=\S+/g, "").replace(/\s*headers=\[[^\]]*\]/g, "").replace(/\s*headers=\S+/g, "").trim();
@@ -10676,27 +10887,62 @@ function isMissingLocalAgentConfigError(error, agentRef) {
 }
 var PROVIDER_HTTP_FAILED_RE = /(.+?) provider failed:\s*HTTP\s+(\d+)\b/i;
 var PLATFORM_TRANSPORT_RE = /\bplatform provider failed\b/i;
+var EXTRA_RATE_LIMIT_TEXT_RE = /\brate[\s_-]?limit(?:ed|ing|s)?\b|\bresource[_\s-]?exhausted\b|\bmax_concurrent_reached\b/i;
+function looksLikeRateLimitedText(message) {
+  return EXTRA_RATE_LIMIT_TEXT_RE.test(message) || QUOTA_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+var AUTH_TEXT_SIGNAL_RE = /\b401\b|unauthori[sz]ed|invalid[_\s-]?(?:api[_\s-]?key|token|credential)s?|(?:api[_\s-]?key|token|credential)s?[_\s-](?:invalid|expired|rejected|missing|not[_\s-]?found)|authentication[_\s-]?(?:error|failed|required)/i;
+var QUOTA_EXHAUSTED_EXTRA_RE = /insufficient[_\s-]?(?:quota|balance|credits?)|余额不足|额度已?用尽/i;
+function looksLikeQuotaExhaustedText(message) {
+  return isQuotaLimited403Body(message) || QUOTA_EXHAUSTED_EXTRA_RE.test(message);
+}
+var BARE_UPSTREAM_5XX_RE = /\bHTTP[:\s]+(5\d\d)\b|\bstatus[:\s=]+(5\d\d)\b|\breturned error\s+(5\d\d)\b/i;
 function classifyLocalRunError(message) {
   const m = message.match(PROVIDER_HTTP_FAILED_RE);
-  if (!m) return { kind: "generic" };
-  const status = Number(m[2]);
-  const transport = PLATFORM_TRANSPORT_RE.test(message) ? "platform" : "local";
-  if (status === 401) {
-    return { kind: "auth", transport, status };
-  }
-  if (status === 403) {
-    return isQuotaLimited403Body(message) ? { kind: "rate-limit", transport, status } : { kind: "auth", transport, status };
-  }
-  if (status === 400 || status === 422) {
-    return { kind: "rejected-payload", transport, status };
+  if (m) {
+    const status = Number(m[2]);
+    const transport2 = PLATFORM_TRANSPORT_RE.test(message) ? "platform" : "local";
+    const quotaExhausted = looksLikeQuotaExhaustedText(message);
+    if (status === 401) {
+      return { kind: "auth", transport: transport2, status };
+    }
+    if (status === 403) {
+      return quotaExhausted ? { kind: "rate-limit", transport: transport2, status, quotaExhausted: true } : { kind: "auth", transport: transport2, status };
+    }
+    if (status === 400 || status === 422) {
+      return { kind: "rejected-payload", transport: transport2, status };
+    }
+    if (status === 429) {
+      return {
+        kind: "rate-limit",
+        transport: transport2,
+        status,
+        ...quotaExhausted ? { quotaExhausted: true } : {}
+      };
+    }
+    if (status >= 500 && status <= 599) {
+      return { kind: "transient", transport: transport2, status };
+    }
+    return { kind: "upstream", transport: transport2, status };
   }
-  if (status === 429) {
-    return { kind: "rate-limit", transport, status };
+  const transport = PLATFORM_TRANSPORT_RE.test(message) ? "platform" : "local";
+  if (AUTH_TEXT_SIGNAL_RE.test(message)) return { kind: "generic" };
+  if (looksLikeRateLimitedText(message)) {
+    const quotaExhausted = looksLikeQuotaExhaustedText(message);
+    return {
+      kind: "rate-limit",
+      transport,
+      status: 429,
+      statusInferred: true,
+      ...quotaExhausted ? { quotaExhausted: true } : {}
+    };
   }
-  if (status >= 500 && status <= 599) {
+  const bare5xx = message.match(BARE_UPSTREAM_5XX_RE);
+  if (bare5xx) {
+    const status = Number(bare5xx[1] ?? bare5xx[2] ?? bare5xx[3]);
     return { kind: "transient", transport, status };
   }
-  return { kind: "upstream", transport, status };
+  return { kind: "generic" };
 }
 var HISTORY_REPLAY_REJECTION_RE = /invalid_request_error|invalid\s+tool\s+call\s+arguments?/i;
 var RUN_UNAVAILABLE_PREFIX = "[nolo] auto runtime: local run unavailable";
@@ -10705,6 +10951,22 @@ var SERVER_FALLBACK_HINT = "or use --server to run on the server explicitly.";
 function buildAuthFailure(ctx) {
   const platformNoToken = ctx.where === "server chat proxy" && isAuthNoTokenBody(ctx.message);
   const fix = platformNoToken ? `This install is not logged in \u2014 run \`nolo login\`, or set AUTH_TOKEN / NOLO_SERVER` : ctx.where === "server chat proxy" ? `Check the agent's provider/api-key settings on nolo.chat` : `Fix the local credential/config and retry`;
+  const { url: validationUrl, text: validationText } = extractGoogleValidationLink(ctx.message);
+  const validationLabel = validationText || "Verify your account";
+  if (validationUrl) {
+    const linkLine = `
+    ${formatCliHyperlink(validationUrl, validationLabel)}`;
+    const rawLine = resolveCliHyperlinkEnabled() ? `
+    \u70B9\u4E0D\u4E86\u5C31\u590D\u5236\u8FD9\u884C: ${validationUrl}` : "";
+    const verifyHint = `
+  \u24D8 \u60F3\u4E00\u952E\u6253\u5F00\uFF1F\u8DD1 \`nolo auth antigravity --verify\` \u2014\u2014 \u5B83\u4F1A\u7528\u672C\u5730\u51ED\u8BC1\u62FF\u5230\u5F53\u524D\u9A8C\u8BC1\u94FE\u63A5\u5E76\u76F4\u63A5\u62C9\u8D77\u6D4F\u89C8\u5668\u3002`;
+    const retryLine = `
+  \u9A8C\u8BC1\u5B8C\u6210\u540E\u76F4\u63A5\u91CD\u8BD5\u521A\u624D\u7684\u547D\u4EE4\u5373\u53EF\uFF0Ctoken \u4E0D\u7528\u91CD\u65B0\u767B\u5F55\u3002`;
+    return `${RUN_UNAVAILABLE_PREFIX} (${ctx.where} returned HTTP ${ctx.status}: Google requires a one-time account verification \u2014 your credential is fine).
+  Open this link in a browser signed into ${ctx.credentialAccountId ? `\`${ctx.credentialAccountId}\`` : "the Google account behind this credential"}:${linkLine}${rawLine}${verifyHint}${retryLine}
+  Detail: ${ctx.message} ${NO_FALLBACK} Use --server to run on the server explicitly.
+`;
+  }
   return `${RUN_UNAVAILABLE_PREFIX} (${ctx.where} returned HTTP ${ctx.status}, auth rejected). Detail: ${ctx.message} ${NO_FALLBACK} ${fix}, ${SERVER_FALLBACK_HINT}.
 `;
 }
@@ -10717,9 +10979,18 @@ function buildRejectedPayloadFailure(ctx) {
   return `${RUN_UNAVAILABLE_PREFIX} (${ctx.where} returned HTTP ${ctx.status}, the provider rejected the request body \u2014 this is NOT a local credential/config issue). Detail: ${ctx.message}${cause} ${NO_FALLBACK} Use --server to run on the server explicitly, or start a fresh dialog.
 `;
 }
+var RATE_LIMIT_RESET_HINT_RE = /retry[-_\s]?after\s*[:=]?\s*\d[\w:-]*|resets?\s+(?:in|at)\s+\d[\w:-]*(?:[ T]\d[\w:-]*)?/i;
+function extractRateLimitResetHint(message) {
+  const match = message.match(RATE_LIMIT_RESET_HINT_RE);
+  return match ? match[0].trim() : void 0;
+}
 function buildRateLimitFailure(ctx) {
   const cooldownNote = ctx.cooldownUntil ? ` \u5DF2\u6807\u8BB0\u51B7\u5374\u81F3 ${ctx.cooldownUntil}\uFF0C\u5230\u671F\u524D\u6D3E\u53D1\u4F1A\u88AB\u51B7\u5374\u95E8\u63A7\u62E6\u622A\uFF08\u5230\u671F\u81EA\u52A8 probe \u6062\u590D\uFF09\u3002` : "";
-  return `${RUN_UNAVAILABLE_PREFIX} (${ctx.where} returned HTTP ${ctx.status}, rate limited). Detail: ${ctx.message} ${NO_FALLBACK} Retry shortly, ${SERVER_FALLBACK_HINT}.${cooldownNote}
+  const headline = ctx.statusInferred ? `${ctx.where} hit an upstream rate-limit/quota error` : `${ctx.where} returned HTTP ${ctx.status}, rate limited`;
+  const cause = ctx.quotaExhausted ? "The upstream quota/balance for this agent is exhausted \u2014 NOT a local credential/config issue" : "This agent is being throttled by the upstream provider \u2014 NOT a local credential/config issue";
+  const reset = extractRateLimitResetHint(ctx.message);
+  const advice = ctx.quotaExhausted ? `Retry after the upstream quota resets${reset ? ` (${reset})` : ""}` : `Retry shortly${reset ? ` (${reset})` : ""}`;
+  return `${RUN_UNAVAILABLE_PREFIX} (${headline}). Detail: ${ctx.message} ${NO_FALLBACK} ${cause}. ${advice}, switch to another agent (\`nolo agent list\`), ${SERVER_FALLBACK_HINT}${cooldownNote}
 `;
 }
 function buildTransientFailure(ctx) {
@@ -10731,6 +11002,17 @@ function buildUpstreamFailure(ctx) {
   return `${RUN_UNAVAILABLE_PREFIX} (${ctx.where} returned HTTP ${ctx.status}). Detail: ${ctx.message} ${NO_FALLBACK} ${fix}, ${SERVER_FALLBACK_HINT}.
 `;
 }
+function formatLocalTurnFailureLine(error) {
+  const message = toErrorMessage(error);
+  if (error?.code === "LLM_REQUEST_TIMEOUT") {
+    const msMatch = /after (\d+)ms/.exec(message);
+    const deadline = msMatch && Number.isFinite(Number(msMatch[1])) ? formatElapsed(Math.round(Number(msMatch[1]) / 1e3)) : "the configured window";
+    return `[nolo] ${t("llmRequestTimedOut", deadline)}
+`;
+  }
+  return `[nolo] Local agent run failed: ${message}
+`;
+}
 var FAILURE_BUILDERS = {
   auth: buildAuthFailure,
   "rejected-payload": buildRejectedPayloadFailure,
@@ -10739,6 +11021,7 @@ var FAILURE_BUILDERS = {
   upstream: buildUpstreamFailure
 };
 function describeLocalRunFailure(message, rawError) {
+  const credentialAccountId = rawError && typeof rawError === "object" && typeof rawError.credentialAccountId === "string" ? rawError.credentialAccountId.trim() || void 0 : void 0;
   if (rawError && typeof rawError === "object" && "code" in rawError && rawError.code === "PLATFORM_STREAM_INTERRUPTED") {
     return "[nolo] The platform LLM stream was interrupted before the turn completed. Your conversation was preserved. Send another message to continue.\n";
   }
@@ -10814,7 +11097,10 @@ function describeLocalRunFailure(message, rawError) {
     message,
     where: cls.transport === "platform" ? "server chat proxy" : "local provider",
     status: cls.status,
-    ...cooldownUntil ? { cooldownUntil } : {}
+    ...cls.statusInferred ? { statusInferred: true } : {},
+    ...cls.quotaExhausted ? { quotaExhausted: true } : {},
+    ...cooldownUntil ? { cooldownUntil } : {},
+    ...credentialAccountId ? { credentialAccountId } : {}
   };
   return FAILURE_BUILDERS[cls.kind](ctx);
 }
@@ -11078,8 +11364,8 @@ async function runLocalAgentTurnForCli(options, settings) {
     ...options.parentWakeOnTerminal ? { parentWakeOnTerminal: true } : {},
     ...options.parentDialogId ? { parentThreadId: options.parentDialogId } : {}
   } : void 0;
-  const currentDialogId = options.continueDialogId ?? ulid();
-  const turnId = `turn-${ulid()}`;
+  const currentDialogId = options.continueDialogId ?? ulid2();
+  const turnId = `turn-${ulid2()}`;
   const runtimeContextWithOwnership = {
     ...runtimeContext ?? {},
     dialogId: currentDialogId,
@@ -11131,6 +11417,18 @@ async function runLocalAgentTurnForCli(options, settings) {
         if (event.kind === "llm-start") {
           turnOutput.showWorking();
         }
+        if (event.kind === "turn-phase") {
+          turnOutput.showPhase(event.phase);
+        }
+        if (event.kind === "compaction-start") {
+          turnOutput.showPhase("compacting");
+        }
+        if (event.kind === "compaction-end" || // 压缩失败（timeout/provider-error）时 localLoop 按失败原子性语义
+        // 带着裁剪后的历史继续本轮，切回等待模型文案；aborted 时 turn 随即
+        // 结束，不再切文案（终态由 abort 路径收尾）。
+        event.kind === "compaction-failed" && event.reason !== "aborted") {
+          turnOutput.showPhase("waiting-provider");
+        }
         if (event.kind === "image-downgraded") {
           options.output.write(
             "[nolo] \u5F53\u524D agent \u88AB\u914D\u7F6E\u4E3A\u4E0D\u652F\u6301\u56FE\u7247\u8F93\u5165\uFF0C\u56FE\u7247\u5DF2\u7528\u5360\u4F4D\u6587\u672C\u66FF\u4EE3\u3002\u8BF7\u68C0\u67E5\u6A21\u578B\u7684\u56FE\u7247\u80FD\u529B\u914D\u7F6E\uFF0C\u6216\u7528 /switch \u9009\u62E9\u652F\u6301\u56FE\u7247\u7684 agent \u540E\u91CD\u65B0\u53D1\u9001\u56FE\u7247\u3002\n"
@@ -11176,6 +11474,9 @@ async function runLocalAgentTurnForCli(options, settings) {
     };
   } catch (error) {
     turnOutput.spinner.stop();
+    turnOutput.cancel({
+      preservePendingNarration: error?.code !== LOCAL_TURN_ABORTED_CODE && !options.abortSignal?.aborted
+    });
     const savedDialogId = error?.dialogId;
     const abortedUsageRecords = error?.usageRecords;
     const abortedTurnCredits = sumPlatformCredits(abortedUsageRecords);
@@ -11199,10 +11500,12 @@ async function runLocalAgentTurnForCli(options, settings) {
       error.cooldownUntil = cooldownUntil;
     }
     if (settings.reportFailure) {
-      options.output.write(
-        `[nolo] Local agent run failed: ${toErrorMessage(error)}
-`
-      );
+      const failureLine = formatLocalTurnFailureLine(error);
+      if (typeof options.output.writeErr === "function") {
+        options.output.writeErr(failureLine);
+      } else {
+        options.output.write(failureLine);
+      }
       if (cooldownUntil) {
         options.output.write(
           `[nolo] \u5DF2\u6807\u8BB0\u51B7\u5374\u81F3 ${cooldownUntil}\uFF0C\u5230\u671F\u524D\u6D3E\u53D1\u8BE5 agent \u4F1A\u88AB\u51B7\u5374\u95E8\u63A7\u62E6\u622A\u3002
@@ -11239,22 +11542,24 @@ async function checkLocalAvailabilityBeforeHttpDispatch(options) {
   }
   const agentLevelAt = baseRecord.nextAvailableAt;
   const agentLevelNextAvailableAt = typeof agentLevelAt === "number" && Number.isFinite(agentLevelAt) ? agentLevelAt : void 0;
-  if (!credentialKey && agentLevelNextAvailableAt === void 0) return null;
+  if (!credentialKey && agentLevelNextAvailableAt === void 0) {
+    return { credentialKey };
+  }
   const env = options.env;
   const now = Date.now();
   const entry = credentialKey ? await readCredentialEntry(credentialKey, env, now).catch(() => void 0) : void 0;
   const entryAt = entry?.nextAvailableAt;
   const effectiveNextAvailableAt = typeof entryAt === "number" ? mergeAvailabilityDeadline(agentLevelNextAvailableAt, entryAt) : agentLevelNextAvailableAt;
-  if (typeof effectiveNextAvailableAt !== "number") return null;
+  if (typeof effectiveNextAvailableAt !== "number") return { credentialKey };
   const gateDecision = resolveCooldownGate(
     { nextAvailableAt: effectiveNextAvailableAt, lastProbeAt: entry?.lastProbeAt },
     now
   );
   if (gateDecision === "probe" && credentialKey) {
     await recordCredentialProbe(credentialKey, env, now).catch(() => void 0);
-    return null;
+    return { credentialKey };
   }
-  if (gateDecision !== "blocked") return null;
+  if (gateDecision !== "blocked") return { credentialKey };
   options.output.write(
     `[nolo] Agent ${options.agentName || options.agentKey} is temporarily unavailable (429 cooldown) until ${new Date(Number(effectiveNextAvailableAt)).toISOString()}.
 Dispatch aborted before reaching the server. Pick another agent via listAgents, or retry after the cooldown.
@@ -11337,11 +11642,18 @@ async function runAgentTurn(options) {
     );
     return { exitCode: 1 };
   }
-  const localBlock = await checkLocalAvailabilityBeforeHttpDispatch(options);
-  if (localBlock) {
-    return { exitCode: localBlock.exitCode };
+  const localAvailability = await checkLocalAvailabilityBeforeHttpDispatch(options);
+  if (localAvailability?.exitCode) {
+    return { exitCode: localAvailability.exitCode };
+  }
+  const httpResult = await runHttpAgentTurn(options, authToken);
+  if (httpResult.exitCode === 0 && !httpResult.streamInterrupted && localAvailability?.credentialKey) {
+    await clearCredentialAvailability(
+      localAvailability.credentialKey,
+      options.env
+    ).catch(() => void 0);
   }
-  return runHttpAgentTurn(options, authToken);
+  return httpResult;
 }
 
 // packages/cli/agentRunCommand.ts
@@ -12073,6 +12385,1078 @@ var rankMemoryCandidates = (items, query, context) => {
   });
 };
 
+// packages/ai/memory/vnext/store.ts
+var enc = (value) => encodeURIComponent(value).replace(/-/g, "%2D");
+var rangeOf = (prefix) => ({ gte: prefix, lte: `${prefix}\uFFFF` });
+var entityKey = (ownerId, id) => `mem2-e-${enc(ownerId)}-${enc(id)}`;
+var entityOwnerPrefix = (ownerId) => `mem2-e-${enc(ownerId)}-`;
+var stateKey = (ownerId, id) => `mem2-s-${enc(ownerId)}-${enc(id)}`;
+var stateEntityIndexKey = (ownerId, entityId, stateId) => `mem2-si-${enc(ownerId)}-${enc(entityId)}-${enc(stateId)}`;
+var stateEntityIndexPrefix = (ownerId, entityId) => `mem2-si-${enc(ownerId)}-${enc(entityId)}-`;
+var evidenceKey = (ownerId, id) => `mem2-v-${enc(ownerId)}-${enc(id)}`;
+var relationKey = (ownerId, id) => `mem2-r-${enc(ownerId)}-${enc(id)}`;
+var relationFromIndexKey = (ownerId, from, relationId) => `mem2-rf-${enc(ownerId)}-${enc(from)}-${enc(relationId)}`;
+var relationToIndexKey = (ownerId, to, relationId) => `mem2-rt-${enc(ownerId)}-${enc(to)}-${enc(relationId)}`;
+var readIndexed = async (db, prefix) => {
+  const refs = [];
+  for await (const [, value] of db.iterator({ ...rangeOf(prefix), reverse: false })) {
+    if (typeof value?.key === "string") refs.push(value.key);
+  }
+  const rows = await Promise.all(refs.map((key) => db.get(key).catch(() => null)));
+  return rows.filter((row) => !!row);
+};
+var getMemoryEntityVNext = async (db, ownerId, entityId) => db.get(entityKey(ownerId, entityId)).catch(() => null);
+var listMemoryEntitiesVNext = async (db, ownerId) => {
+  const rows = [];
+  for await (const [, value] of db.iterator({
+    ...rangeOf(entityOwnerPrefix(ownerId)),
+    reverse: false
+  })) {
+    if (value) rows.push(value);
+  }
+  return rows;
+};
+var getMemoryStateVNext = async (db, ownerId, stateId) => db.get(stateKey(ownerId, stateId)).catch(() => null);
+var listMemoryStatesForEntityVNext = (db, ownerId, entityId) => readIndexed(db, stateEntityIndexPrefix(ownerId, entityId));
+var putMemoryEvidenceVNext = async (db, evidence) => {
+  await db.put(evidenceKey(evidence.ownerId, evidence.id), evidence);
+};
+var getMemoryEvidenceVNext = async (db, ownerId, evidenceId) => db.get(evidenceKey(ownerId, evidenceId)).catch(() => null);
+var getMemoryEvidenceVNextStrict = async (db, ownerId, evidenceId) => {
+  try {
+    return await db.get(evidenceKey(ownerId, evidenceId));
+  } catch (error) {
+    if (isLevelNotFoundError(error)) return null;
+    throw error;
+  }
+};
+var _appendEntityBatch = (batch, entity) => {
+  batch.put(entityKey(entity.ownerId, entity.id), entity);
+};
+var _appendEvidenceBatch = (batch, evidence) => {
+  batch.put(evidenceKey(evidence.ownerId, evidence.id), evidence);
+};
+var _appendStateBatch = (batch, state2) => {
+  const key = stateKey(state2.ownerId, state2.id);
+  batch.put(key, state2);
+  batch.put(stateEntityIndexKey(state2.ownerId, state2.entityId, state2.id), { key });
+};
+var _appendRetiredStateBatch = (batch, state2) => {
+  batch.put(stateKey(state2.ownerId, state2.id), state2);
+};
+var _appendRelationBatch = (batch, relation) => {
+  const key = relationKey(relation.ownerId, relation.id);
+  batch.put(key, relation);
+  batch.put(relationFromIndexKey(relation.ownerId, relation.from, relation.id), { key });
+  batch.put(relationToIndexKey(relation.ownerId, relation.to, relation.id), { key });
+};
+
+// packages/ai/memory/vnext/recall.ts
+var MAX_RECALL_REFS = 6;
+var stripFence = (raw) => {
+  const trimmed = raw.trim();
+  const match = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return match ? match[1].trim() : trimmed;
+};
+var parseSelection = (raw) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(stripFence(raw));
+  } catch {
+    throw new Error("memory recall selector output is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("memory recall selector output must be an object");
+  }
+  const obj = parsed;
+  if (!Array.isArray(obj.refs) || !obj.refs.every((item) => typeof item === "string")) {
+    throw new Error("memory recall selector refs must be string[]");
+  }
+  if (typeof obj.reason !== "string") {
+    throw new Error("memory recall selector reason must be string");
+  }
+  return {
+    refs: [...new Set(obj.refs)].slice(0, MAX_RECALL_REFS),
+    reason: obj.reason
+  };
+};
+var buildCatalog = async (db, ownerId) => {
+  const entities = await listMemoryEntitiesVNext(db, ownerId);
+  const states = [];
+  for (const entity of entities) {
+    states.push(...await listMemoryStatesForEntityVNext(db, ownerId, entity.id));
+  }
+  return { entities, states };
+};
+var catalogText = (entities, states) => JSON.stringify(
+  {
+    entities: entities.map((entity) => ({
+      id: entity.id,
+      type: entity.type,
+      name: entity.name,
+      ...entity.subtype ? { subtype: entity.subtype } : {},
+      ...entity.aliases?.length ? { aliases: entity.aliases } : {}
+    })),
+    states: states.map((state2) => ({
+      id: state2.id,
+      entityId: state2.entityId,
+      facet: state2.facet,
+      text: state2.text,
+      // Retired (superseded) States stay listed as recoverable history; the
+      // boolean — not the retiredAt timestamp — enters the prompt so no
+      // timestamps reach LLM text.
+      ...state2.retiredAt ? { retired: true } : {}
+    }))
+  },
+  null,
+  2
+);
+var createMemoryVNextRecall = (input) => async (query) => {
+  const startedAt = performance.now();
+  const { entities, states } = await buildCatalog(input.db, input.ownerId);
+  if (entities.length === 0 && states.length === 0) {
+    return {
+      query,
+      refs: [],
+      entities: [],
+      states: [],
+      reason: "memory catalog is empty",
+      trace: {
+        candidateEntities: 0,
+        candidateStates: 0,
+        selectedRefs: 0,
+        elapsedMs: Math.round((performance.now() - startedAt) * 10) / 10
+      }
+    };
+  }
+  const result = await input.provider.complete(
+    [
+      {
+        role: "system",
+        content: [
+          "Select the smallest useful set of long-lived memory entrances for the user query.",
+          'Return ONLY JSON: {"refs":["exact-id"],"reason":"short explanation"}.',
+          `Select at most ${MAX_RECALL_REFS} exact ids from the supplied catalog.`,
+          "Prefer State ids when current durable understanding answers the query.",
+          "Select an Entity id when it is a useful navigation anchor and no single State is enough.",
+          "Do not select unrelated memories merely because they are personal or interesting.",
+          "Historical-detail questions may select the relevant current State/Entity as an entrance; deeper evidence is handled by inspect, not here."
+        ].join("\n")
+      },
+      {
+        role: "user",
+        content: `Query:
+${query}
+
+Memory catalog:
+${catalogText(entities, states)}`
+      }
+    ],
+    input.timeoutMs ? { timeoutMs: input.timeoutMs } : void 0
+  );
+  const selected = parseSelection(result.content);
+  const entityById = new Map(entities.map((entity) => [entity.id, entity]));
+  const stateById = new Map(states.map((state2) => [state2.id, state2]));
+  const validRefs = selected.refs.filter((ref) => entityById.has(ref) || stateById.has(ref));
+  return {
+    query,
+    refs: validRefs,
+    entities: validRefs.flatMap((ref) => {
+      const entity = entityById.get(ref);
+      return entity ? [entity] : [];
+    }),
+    states: validRefs.flatMap((ref) => {
+      const state2 = stateById.get(ref);
+      return state2 ? [state2] : [];
+    }),
+    reason: selected.reason,
+    trace: {
+      candidateEntities: entities.length,
+      candidateStates: states.length,
+      selectedRefs: validRefs.length,
+      elapsedMs: Math.round((performance.now() - startedAt) * 10) / 10
+    }
+  };
+};
+
+// packages/ai/memory/vnext/legacyMigration.ts
+import { createHash } from "crypto";
+var LEGACY_MEMORY_SOURCE_REF_PREFIX = "legacy-memory";
+var LEGACY_MEMORY_EVIDENCE_ID_PREFIX = "mem-legacy-";
+var resolveLegacyMemoryPrincipal = (item) => ({
+  ownerType: item.ownerType,
+  ownerId: item.ownerId,
+  principalId: `${item.ownerType}:${encodeURIComponent(item.ownerId)}`
+});
+var buildLegacyMemorySourceRef = (item) => {
+  const { principalId } = resolveLegacyMemoryPrincipal(item);
+  return `${LEGACY_MEMORY_SOURCE_REF_PREFIX}:${principalId}:${encodeURIComponent(item.id)}`;
+};
+var legacyEvidenceSeed = (principalId, itemId) => JSON.stringify([principalId, itemId]);
+var buildLegacyEvidenceId = (item) => {
+  const { principalId } = resolveLegacyMemoryPrincipal(item);
+  const digest = createHash("sha256").update(legacyEvidenceSeed(principalId, item.id)).digest("hex");
+  return `${LEGACY_MEMORY_EVIDENCE_ID_PREFIX}${digest.slice(0, 32)}`;
+};
+var clampLegacyConfidence = (value) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+};
+var buildLegacyMemoryEvidence = (item) => {
+  const { principalId } = resolveLegacyMemoryPrincipal(item);
+  return {
+    id: buildLegacyEvidenceId(item),
+    ownerId: principalId,
+    text: item.content,
+    sourceRef: buildLegacyMemorySourceRef(item),
+    confidence: clampLegacyConfidence(item.confidence),
+    createdAt: item.createdAt
+  };
+};
+
+// packages/ai/memory/vnext/shadowRead.ts
+var SHADOW_TIMEOUT_MS = 2e4;
+var ERROR_MESSAGE_MAX = 120;
+var normalizeTextKey = (text) => text.trim().replace(/\s+/g, " ").toLowerCase();
+var legacyItemKeys = (item) => {
+  const keys = [normalizeTextKey(item.content ?? "")];
+  return keys.filter((key) => key.length > 0);
+};
+var vnextResultKeys = (result) => {
+  const keys = [];
+  for (const entity of result.entities) {
+    if (entity.name) keys.push(normalizeTextKey(entity.name));
+  }
+  for (const state2 of result.states) {
+    if (state2.text) keys.push(normalizeTextKey(state2.text));
+  }
+  return keys.filter((key) => key.length > 0);
+};
+var vnextContextChars = (result) => result.entities.reduce(
+  (sum, entity) => sum + (entity.name?.length ?? 0),
+  result.states.reduce((sum, state2) => sum + (state2.text?.length ?? 0), 0)
+);
+var shortError = (error) => {
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return message.length > ERROR_MESSAGE_MAX ? `${message.slice(0, ERROR_MESSAGE_MAX)}\u2026` : message;
+};
+var withTimeout = async (promise, timeoutMs, label) => {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(label)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+};
+var runMemoryVNextShadowRead = async (input) => {
+  const now = input.ctx.now ?? (() => performance.now());
+  const defaultEmit = (observation2) => {
+    const payload = {
+      event: "memory_vnext_shadow_read",
+      ...observation2
+    };
+    console.info("[memory] vnext shadow read", payload);
+  };
+  const emit = input.emit ?? defaultEmit;
+  const legacyKeys = new Set(
+    input.legacyItems.flatMap((item) => legacyItemKeys(item))
+  );
+  const vnextStartedAt = now();
+  let vnextHitCount = 0;
+  let vnextChars = 0;
+  const vnextKeys = /* @__PURE__ */ new Set();
+  let vnextError;
+  try {
+    const shadowTimeoutMs = input.ctx.shadowTimeoutMs ?? SHADOW_TIMEOUT_MS;
+    const perOwner = async (owner) => {
+      const principal = resolveLegacyMemoryPrincipal({
+        ownerType: owner.ownerType,
+        ownerId: owner.ownerId
+      });
+      const recall = createMemoryVNextRecall({
+        db: input.ctx.db,
+        ownerId: principal.principalId,
+        provider: input.ctx.provider,
+        timeoutMs: input.ctx.timeoutMs
+      });
+      return recall(input.ctx.query);
+    };
+    const results = await withTimeout(
+      Promise.all(input.ctx.owners.map((owner) => perOwner(owner))),
+      shadowTimeoutMs,
+      `memory vnext shadow read timed out after ${shadowTimeoutMs}ms`
+    );
+    for (const result of results) {
+      vnextHitCount += result.refs.length;
+      vnextChars += vnextContextChars(result);
+      for (const key of vnextResultKeys(result)) vnextKeys.add(key);
+    }
+  } catch (error) {
+    vnextError = shortError(error);
+  }
+  const vnextLatencyMs = Math.round((now() - vnextStartedAt) * 10) / 10;
+  let overlapCount = null;
+  let legacyOnlyCount = null;
+  let vnextOnlyCount = null;
+  if (!vnextError) {
+    let overlap = 0;
+    for (const key of vnextKeys) if (legacyKeys.has(key)) overlap += 1;
+    overlapCount = overlap;
+    legacyOnlyCount = Math.max(0, legacyKeys.size - overlap);
+    vnextOnlyCount = Math.max(0, vnextKeys.size - overlap);
+  }
+  const observation = {
+    legacyHitCount: input.legacyItems.length,
+    vnextHitCount,
+    overlapCount,
+    legacyOnlyCount,
+    vnextOnlyCount,
+    legacyLatencyMs: input.legacyLatencyMs,
+    vnextLatencyMs,
+    legacyContextChars: input.legacyContextChars,
+    vnextContextChars: vnextChars,
+    ...vnextError ? { vnextError } : {}
+  };
+  emit(observation);
+  return observation;
+};
+var isMemoryVNextShadowReadEnabled = (env = typeof process !== "undefined" ? process.env : {}) => env.NOLO_MEMORY_VNEXT_SHADOW_READ === "1" || env.NOLO_MEMORY_VNEXT_SHADOW_READ === "true";
+
+// packages/ai/memory/vnext/applyMutation.ts
+async function validateMutation(db, ownerId, mutation) {
+  const pending = {
+    evidenceIds: /* @__PURE__ */ new Set(),
+    entityIds: /* @__PURE__ */ new Set(),
+    stateIds: /* @__PURE__ */ new Set(),
+    relationIds: /* @__PURE__ */ new Set()
+  };
+  for (const ev of mutation.evidence ?? []) {
+    if (!ev.id || typeof ev.id !== "string") {
+      throw new Error("evidence id must be a non-empty string");
+    }
+    if (pending.evidenceIds.has(ev.id)) {
+      throw new Error(`duplicate evidence id in mutation: ${ev.id}`);
+    }
+    pending.evidenceIds.add(ev.id);
+  }
+  for (const ent of mutation.entities ?? []) {
+    if (!ent.id || typeof ent.id !== "string") {
+      throw new Error("entity id must be a non-empty string");
+    }
+    if (pending.entityIds.has(ent.id)) {
+      throw new Error(`duplicate entity id in mutation: ${ent.id}`);
+    }
+    pending.entityIds.add(ent.id);
+  }
+  for (const st of mutation.states ?? []) {
+    if (!st.id || typeof st.id !== "string") {
+      throw new Error("state id must be a non-empty string");
+    }
+    if (pending.stateIds.has(st.id)) {
+      throw new Error(`duplicate state id in mutation: ${st.id}`);
+    }
+    pending.stateIds.add(st.id);
+  }
+  for (const rel of mutation.relations ?? []) {
+    if (!rel.id || typeof rel.id !== "string") {
+      throw new Error("relation id must be a non-empty string");
+    }
+    if (pending.relationIds.has(rel.id)) {
+      throw new Error(`duplicate relation id in mutation: ${rel.id}`);
+    }
+    pending.relationIds.add(rel.id);
+  }
+  const supersededIds = /* @__PURE__ */ new Set();
+  for (const sid of mutation.supersededStateIds ?? []) {
+    if (supersededIds.has(sid)) {
+      throw new Error(`duplicate supersededStateId in mutation: ${sid}`);
+    }
+    supersededIds.add(sid);
+  }
+  for (const ev of mutation.evidence ?? []) {
+    if (ev.ownerId !== ownerId) {
+      throw new Error(
+        `evidence ${ev.id} has ownerId ${ev.ownerId}, expected ${ownerId}`
+      );
+    }
+  }
+  for (const ent of mutation.entities ?? []) {
+    if (ent.ownerId !== ownerId) {
+      throw new Error(
+        `entity ${ent.id} has ownerId ${ent.ownerId}, expected ${ownerId}`
+      );
+    }
+  }
+  for (const st of mutation.states ?? []) {
+    if (st.ownerId !== ownerId) {
+      throw new Error(
+        `state ${st.id} has ownerId ${st.ownerId}, expected ${ownerId}`
+      );
+    }
+  }
+  for (const rel of mutation.relations ?? []) {
+    if (rel.ownerId !== ownerId) {
+      throw new Error(
+        `relation ${rel.id} has ownerId ${rel.ownerId}, expected ${ownerId}`
+      );
+    }
+  }
+  for (const st of mutation.states ?? []) {
+    if (supersededIds.has(st.id)) {
+      throw new Error(
+        `state ${st.id} appears in both states and supersededStateIds; a record cannot be created and retired in the same mutation`
+      );
+    }
+  }
+  const facetSlots = /* @__PURE__ */ new Set();
+  for (const st of mutation.states ?? []) {
+    const slot = `${st.entityId} ${st.facet}`;
+    if (facetSlots.has(slot)) {
+      throw new Error(
+        `mutation writes parallel current states for entity ${st.entityId} facet ${st.facet}`
+      );
+    }
+    facetSlots.add(slot);
+  }
+  for (const ev of mutation.evidence ?? []) {
+    const existing = await getMemoryEvidenceVNext(db, ownerId, ev.id);
+    if (existing) {
+      throw new Error(
+        `evidence ${ev.id} already exists (owner ${ownerId}); use a unique id`
+      );
+    }
+  }
+  for (const ent of mutation.entities ?? []) {
+    const existing = await getMemoryEntityVNext(db, ownerId, ent.id);
+    if (existing) {
+      throw new Error(
+        `entity ${ent.id} already exists (owner ${ownerId}); use a unique id`
+      );
+    }
+  }
+  for (const st of mutation.states ?? []) {
+    if (!pending.entityIds.has(st.entityId)) {
+      const entity = await getMemoryEntityVNext(db, ownerId, st.entityId);
+      if (!entity) {
+        throw new Error(
+          `memory state ${st.id} references missing entity ${st.entityId} (owner ${ownerId})`
+        );
+      }
+    }
+    for (const evidenceId of st.evidenceIds) {
+      if (!pending.evidenceIds.has(evidenceId)) {
+        const ev = await getMemoryEvidenceVNext(db, ownerId, evidenceId);
+        if (!ev) {
+          throw new Error(
+            `memory state ${st.id} references missing evidence ${evidenceId} (owner ${ownerId})`
+          );
+        }
+      }
+    }
+    const existing = await getMemoryStateVNext(db, ownerId, st.id);
+    if (existing) {
+      if (existing.retiredAt) {
+        throw new Error(
+          `cannot update retired memory state ${st.id} (owner ${ownerId})`
+        );
+      }
+      if (existing.entityId !== st.entityId || existing.facet !== st.facet) {
+        throw new Error(
+          `state ${st.id} already exists with different entity/facet (${existing.entityId}/${existing.facet} vs ${st.entityId}/${st.facet}); use supersede instead`
+        );
+      }
+    }
+    if (!existing) {
+      const existingStates = await listMemoryStatesForEntityVNext(db, ownerId, st.entityId);
+      for (const es of existingStates) {
+        if (es.facet === st.facet && !es.retiredAt) {
+          if (!supersededIds.has(es.id)) {
+            throw new Error(
+              `entity ${st.entityId} facet ${st.facet} already has current state ${es.id}; supersede it or use a different facet`
+            );
+          }
+        }
+      }
+    }
+  }
+  for (const sid of mutation.supersededStateIds ?? []) {
+    const existing = await getMemoryStateVNext(db, ownerId, sid);
+    if (!existing) {
+      throw new Error(
+        `cannot supersede missing memory state: ${sid} (owner ${ownerId})`
+      );
+    }
+    if (existing.retiredAt) {
+      throw new Error(
+        `cannot supersede already retired memory state: ${sid} (owner ${ownerId})`
+      );
+    }
+    const replacement = (mutation.states ?? []).find(
+      (st) => st.entityId === existing.entityId && st.facet === existing.facet
+    );
+    if (!replacement) {
+      throw new Error(
+        `superseded state ${sid} (entity ${existing.entityId} facet ${existing.facet}) has no replacement in this mutation`
+      );
+    }
+  }
+  for (const rel of mutation.relations ?? []) {
+    for (const [side, ref] of [
+      ["from", rel.from],
+      ["to", rel.to]
+    ]) {
+      if (pending.entityIds.has(ref) || pending.stateIds.has(ref) || pending.evidenceIds.has(ref)) {
+        continue;
+      }
+      const resolved = await getMemoryEntityVNext(db, ownerId, ref) ?? await getMemoryStateVNext(db, ownerId, ref) ?? await getMemoryEvidenceVNext(db, ownerId, ref);
+      if (!resolved) {
+        throw new Error(
+          `memory relation ${rel.id} references missing ${side} ${ref} (owner ${ownerId})`
+        );
+      }
+    }
+  }
+}
+var applyMemoryInterpreterMutation = async (db, ownerId, mutation) => {
+  await validateMutation(db, ownerId, mutation);
+  const batch = db.batch();
+  for (const ev of mutation.evidence ?? []) {
+    _appendEvidenceBatch(batch, ev);
+  }
+  for (const ent of mutation.entities ?? []) {
+    _appendEntityBatch(batch, ent);
+  }
+  for (const st of mutation.states ?? []) {
+    _appendStateBatch(batch, st);
+  }
+  for (const sid of mutation.supersededStateIds ?? []) {
+    const existing = await getMemoryStateVNext(db, ownerId, sid);
+    if (!existing) {
+      throw new Error(
+        `cannot supersede missing memory state: ${sid} (owner ${ownerId})`
+      );
+    }
+    const replacement = (mutation.states ?? []).find(
+      (st) => st.entityId === existing.entityId && st.facet === existing.facet
+    );
+    const retired = {
+      ...existing,
+      retiredAt: replacement?.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    _appendRetiredStateBatch(batch, retired);
+  }
+  for (const rel of mutation.relations ?? []) {
+    _appendRelationBatch(batch, rel);
+  }
+  await batch.write();
+};
+
+// packages/ai/memory/vnext/legacyMigrationApply.ts
+var isSameLegacyMemoryEvidence = (left, right) => left.id === right.id && left.ownerId === right.ownerId && left.text === right.text && left.sourceRef === right.sourceRef && left.confidence === right.confidence && left.createdAt === right.createdAt;
+var applyLegacyMemoryEvidence = async (db, item) => {
+  const incoming = buildLegacyMemoryEvidence(item);
+  const existing = await getMemoryEvidenceVNextStrict(db, incoming.ownerId, incoming.id);
+  if (existing) {
+    return isSameLegacyMemoryEvidence(existing, incoming) ? { status: "already_exists", evidence: existing } : { status: "conflict", existing, incoming };
+  }
+  await putMemoryEvidenceVNext(db, incoming);
+  return { status: "created", evidence: incoming };
+};
+
+// packages/ai/memory/vnext/types.ts
+var MEMORY_ENTITY_TYPES = [
+  "person",
+  "organization",
+  "project",
+  "place",
+  "object",
+  "activity",
+  "concept"
+];
+var MEMORY_RELATION_TYPES = [
+  "related_to",
+  "part_of",
+  "uses",
+  "involves",
+  "supersedes"
+];
+
+// packages/ai/memory/vnext/interpreterWireProtocol.ts
+var isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+var isString = (value) => typeof value === "string" && value.trim().length > 0;
+var isStringArray = (value) => Array.isArray(value) && value.every(isString);
+var optionalArray = (value, validate2) => value === void 0 || Array.isArray(value) && value.every(validate2);
+var ACTIONS = /* @__PURE__ */ new Set([
+  "no_op",
+  "create",
+  "update",
+  "specialize",
+  "supersede",
+  "ambiguous"
+]);
+var validateEvidence = (value) => {
+  if (!isObject(value)) return false;
+  return isString(value.key) && isString(value.text) && typeof value.confidence === "number" && Number.isFinite(value.confidence) && value.confidence >= 0 && value.confidence <= 1 && (value.sourceRef === void 0 || isString(value.sourceRef));
+};
+var validateEntity = (value) => {
+  if (!isObject(value)) return false;
+  return isString(value.key) && MEMORY_ENTITY_TYPES.includes(value.type) && isString(value.name) && (value.subtype === void 0 || isString(value.subtype)) && (value.aliases === void 0 || isStringArray(value.aliases));
+};
+var validateState = (value) => {
+  if (!isObject(value)) return false;
+  return (value.stateId === void 0 || isString(value.stateId)) && (value.supersedes === void 0 || isString(value.supersedes)) && isString(value.entityRef) && isString(value.facet) && "value" in value && isString(value.text) && isStringArray(value.evidenceRefs);
+};
+var validateRelation = (value) => {
+  if (!isObject(value)) return false;
+  return isString(value.fromRef) && MEMORY_RELATION_TYPES.includes(value.type) && isString(value.toRef);
+};
+var stripJsonFence = (raw) => {
+  const trimmed = raw.trim();
+  const match = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return match ? match[1].trim() : trimmed;
+};
+var parseMemoryInterpreterWireMutation = (raw) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(stripJsonFence(raw));
+  } catch {
+    return { ok: false, error: "interpreter output is not valid JSON" };
+  }
+  if (!isObject(parsed)) return { ok: false, error: "interpreter output must be an object" };
+  if (!isString(parsed.action) || !ACTIONS.has(parsed.action)) {
+    return { ok: false, error: "invalid reconciliation action" };
+  }
+  if (!isString(parsed.reason)) return { ok: false, error: "reason is required" };
+  if (!optionalArray(parsed.evidence, validateEvidence)) return { ok: false, error: "invalid evidence array" };
+  if (!optionalArray(parsed.entities, validateEntity)) return { ok: false, error: "invalid entities array" };
+  if (!optionalArray(parsed.states, validateState)) return { ok: false, error: "invalid states array" };
+  if (!optionalArray(parsed.relations, validateRelation)) return { ok: false, error: "invalid relations array" };
+  return { ok: true, value: parsed };
+};
+var buildMemoryInterpreterWireContract = () => `
+Return ONLY one JSON object:
+{
+  "action": "no_op|create|update|specialize|supersede|ambiguous",
+  "reason": "short explanation",
+  "evidence": [{ "key": "e1", "text": "...", "confidence": 0.9, "sourceRef": "optional" }],
+  "entities": [{ "key": "n1", "type": "person|organization|project|place|object|activity|concept", "name": "...", "subtype": "optional", "aliases": [] }],
+  "states": [{ "stateId": "optional-existing-state-id", "supersedes": "optional-existing-state-id-this-statement-replaces", "entityRef": "existing-entity-id-or-new-entity-key", "facet": "...", "value": {}, "text": "...", "evidenceRefs": ["e1"] }],
+  "relations": [{ "fromRef": "existing-id-or-local-key", "type": "related_to|part_of|uses|involves|supersedes", "toRef": "existing-id-or-local-key" }]
+}
+
+Do not generate persistent ids, owner ids, timestamps or storage keys. Runtime owns identity and time.
+Use short local keys only to connect records created in the SAME response. Every local key must be unique across evidence/entities.
+State evidenceRefs may reference Evidence emitted in this response. Evidence ids marked referenceable in the supplied memory context may be referenced directly. Do not reference any other prior Evidence id.
+When updating an existing State, reuse its exact stateId, exact entityRef and exact facet. Runtime preserves that State's original entity/facet/createdAt and appends new Evidence provenance.
+When creating a new State, omit stateId.
+For supersede: emit the replacing statement as a NEW State (omit stateId) and set supersedes to the exact id of the replaced current State. Runtime retires the replaced State \u2014 it stays recoverable as history but is no longer current, and the new State becomes the only current one for that facet. Never update or supersede an already retired State.
+supersedes and stateId are mutually exclusive on one State.
+Do not emit an existing Entity again merely to update its State; reference its exact id in entityRef.
+Relations may reference only known persisted Entity/State/Evidence ids or local Entity/Evidence keys emitted in the same response.
+Do not invent new Entity or Relation types. Keep expressive detail in subtype/facet/value/text.
+`.trim();
+var assertUniqueLocalKeys = (wire) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of [...wire.evidence ?? [], ...wire.entities ?? []]) {
+    if (seen.has(item.key)) throw new Error(`duplicate local key: ${item.key}`);
+    seen.add(item.key);
+  }
+};
+var materializeMemoryInterpreterMutation = (input) => {
+  assertUniqueLocalKeys(input.wire);
+  const now = input.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const nextId = input.nextId ?? ulid;
+  const existingStates = new Map((input.existingStates ?? []).map((state2) => [state2.id, state2]));
+  const existingStateIds = new Set(existingStates.keys());
+  const existingEvidenceIds = new Set(
+    [...existingStates.values()].flatMap((state2) => state2.evidenceIds)
+  );
+  const existingEntityIds = new Set(input.existingEntityIds ?? []);
+  const entityRefs = /* @__PURE__ */ new Map();
+  const evidenceRefs = /* @__PURE__ */ new Map();
+  const evidence = (input.wire.evidence ?? []).map((item) => {
+    const id = nextId();
+    evidenceRefs.set(item.key, id);
+    return {
+      id,
+      ownerId: input.ownerId,
+      text: item.text,
+      ...item.sourceRef ? { sourceRef: item.sourceRef } : {},
+      confidence: item.confidence,
+      createdAt: now
+    };
+  });
+  const entities = (input.wire.entities ?? []).map((item) => {
+    const id = nextId();
+    entityRefs.set(item.key, id);
+    return {
+      id,
+      ownerId: input.ownerId,
+      type: item.type,
+      name: item.name,
+      ...item.subtype ? { subtype: item.subtype } : {},
+      ...item.aliases ? { aliases: item.aliases } : {},
+      createdAt: now,
+      updatedAt: now
+    };
+  });
+  const resolveEntityRef = (ref) => {
+    const created = entityRefs.get(ref);
+    if (created) return created;
+    if (existingEntityIds.has(ref)) return ref;
+    throw new Error(`unknown entity ref: ${ref}`);
+  };
+  const supersededStateIds = [];
+  const referenceableEvidenceIds = new Set(input.referenceableEvidenceIds ?? []);
+  const resolveEvidenceRef = (ref) => {
+    const created = evidenceRefs.get(ref);
+    if (created) return created;
+    if (referenceableEvidenceIds.has(ref)) return ref;
+    throw new Error(`unknown evidence ref: ${ref}`);
+  };
+  const states = (input.wire.states ?? []).map((item) => {
+    const prior = item.stateId ? existingStates.get(item.stateId) : void 0;
+    if (item.stateId && !prior) {
+      throw new Error(`unknown existing state: ${item.stateId}`);
+    }
+    if (prior?.retiredAt) {
+      throw new Error(`retired state cannot be updated: ${item.stateId}`);
+    }
+    if (prior && item.entityRef !== prior.entityId) {
+      throw new Error(`existing state entityRef changed: ${item.stateId}`);
+    }
+    if (prior && item.facet !== prior.facet) {
+      throw new Error(`existing state facet changed: ${item.stateId}`);
+    }
+    let supersededStateId;
+    if (item.supersedes !== void 0) {
+      if (input.wire.action !== "supersede") {
+        throw new Error(
+          `supersedes is only valid for the supersede action, got ${input.wire.action}`
+        );
+      }
+      if (item.stateId !== void 0) {
+        throw new Error("supersedes and stateId are mutually exclusive on one state");
+      }
+      const superseded = existingStates.get(item.supersedes);
+      if (!superseded) {
+        throw new Error(`unknown superseded state id: ${item.supersedes}`);
+      }
+      if (superseded.retiredAt) {
+        throw new Error(`retired state cannot be superseded: ${item.supersedes}`);
+      }
+      if (supersededStateIds.includes(item.supersedes)) {
+        throw new Error(`duplicate superseded state id: ${item.supersedes}`);
+      }
+      supersededStateId = item.supersedes;
+    }
+    const newEvidenceIds = item.evidenceRefs.map(resolveEvidenceRef);
+    const id = prior?.id ?? nextId();
+    if (supersededStateId !== void 0) supersededStateIds.push(supersededStateId);
+    return {
+      id,
+      ownerId: input.ownerId,
+      entityId: prior?.entityId ?? resolveEntityRef(item.entityRef),
+      facet: prior?.facet ?? item.facet,
+      value: item.value,
+      text: item.text,
+      evidenceIds: [.../* @__PURE__ */ new Set([...prior?.evidenceIds ?? [], ...newEvidenceIds])],
+      createdAt: prior?.createdAt ?? now,
+      updatedAt: now
+    };
+  });
+  const resolveRelationRef = (ref) => {
+    const createdEntity = entityRefs.get(ref);
+    if (createdEntity) return createdEntity;
+    const createdEvidence = evidenceRefs.get(ref);
+    if (createdEvidence) return createdEvidence;
+    if (existingEntityIds.has(ref) || existingStateIds.has(ref) || existingEvidenceIds.has(ref)) {
+      return ref;
+    }
+    throw new Error(`unknown relation ref: ${ref}`);
+  };
+  const relations = (input.wire.relations ?? []).map((item) => ({
+    id: nextId(),
+    ownerId: input.ownerId,
+    from: resolveRelationRef(item.fromRef),
+    type: item.type,
+    to: resolveRelationRef(item.toRef),
+    createdAt: now
+  }));
+  return {
+    action: input.wire.action,
+    reason: input.wire.reason,
+    ...evidence.length ? { evidence } : {},
+    ...entities.length ? { entities } : {},
+    ...states.length ? { states } : {},
+    ...supersededStateIds.length ? { supersededStateIds } : {},
+    ...relations.length ? { relations } : {}
+  };
+};
+
+// packages/ai/memory/vnext/interpreterPrompt.ts
+var MEMORY_VNEXT_ENTITY_CREATION_CONTRACT = `
+Entity creation is NOT named-entity recognition.
+
+Create a new long-lived Entity only when the subject has future continuity value.
+A mention alone is insufficient.
+
+Prefer leaving information as Evidence until at least one strong continuity signal exists:
+1. The subject recurs across independent dialogs, or the user explicitly describes it as enduring.
+2. The user connects it to their own preferences, relationships, goals, identity, worldview, ongoing work, or repeated activity.
+3. Future conversations are likely to refer back to it under different wording, so a stable anchor materially improves cross-dialog continuity.
+4. Creating the anchor is necessary to update or relate existing long-lived State.
+
+Do NOT create an Entity merely because the text contains a named person, product, place, historical event, book, philosopher, food, device, or concept.
+When uncertain, keep Evidence and defer Entity creation.
+
+Concept-specific rule:
+- concept is for abstract subjects that become part of the user's personal meaning world, such as freedom, absurdism, privacy, modernity, beauty, loneliness, safety, or maintainability.
+- Do not create a Concept Entity for every topic discussed or external fact queried.
+- Promote a concept only when it recurs, carries a durable user stance/interest/tension, connects multiple memories, or is likely to become a future recall/navigation anchor.
+- A one-off question such as "when was Kant born?" should normally create no long-lived Concept or Person Entity. Repeated discussion about Kant, freedom, and the user's own values may justify them.
+`.trim();
+var MEMORY_VNEXT_THIRD_PARTY_RELEVANCE_CONTRACT = `
+Third-party relevance test:
+- A fact about another person is durable only when it concerns the user's own world. Observation-only third-party facts \u2014 someone's appearance, news, habits, or the doings of a person the user merely encounters \u2014 stay Evidence, no matter how often they recur.
+- Closeness of that person, and repeated mentions across independent dialogs, do not by themselves make such an observation durable: never invent a user-world consequence to justify promotion (for example "the user keeps watching this person").
+- Matters that are part of the user's own shared life \u2014 household or family arrangements the user takes part in, a family member's health, or what the user relies on someone for \u2014 do belong to the user's world: state the user-world side (caregiving, changed time, changed plans, a sustained constraint) instead of a chronicle of the other person's doings.
+`.trim();
+var MEMORY_VNEXT_RECONCILIATION_CONTRACT = `
+When durable understanding changes, choose the smallest correct reconciliation:
+- no_op: no durable change.
+- create: genuinely new durable state/entity.
+- update: advance an existing state without changing its scope.
+- specialize: add a scoped exception/qualification; do not replace the broader state.
+- supersede: a newer statement explicitly replaces old current state. Emit the replacement as a NEW State and name the replaced current State in its supersedes field; runtime retires the old one (kept as recoverable history, no longer current).
+- ambiguous: evidence conflicts with current state, but replacement vs exception cannot be determined reliably.
+
+Examples:
+- "\u56DE\u7B54\u7B80\u5355" then "\u5B89\u5168\u548C bug \u6392\u67E5\u8BE6\u7EC6" => specialize, not supersede.
+- "\u6211\u6709 Ollama Pro" then "\u6211\u5DF2\u7ECF\u4E0D\u7528 Ollama Pro \u4E86" => supersede.
+- Repeatedly choosing thin noodles without explicitly rejecting thick noodles => update or ambiguous, not automatic supersession.
+
+Preserve ambiguity. Do not ask the user merely to clean memory. A later task may ask only if the unresolved state materially changes the answer.
+`.trim();
+var buildMemoryVNextInterpreterPrompt = () => [
+  "You maintain long-lived adaptive relationship memory backed by evidence.",
+  "External dialogs/files/web facts remain authoritative outside memory.",
+  "Prefer a small stable set of Entities and updateable States over an ever-growing bag of facts.",
+  MEMORY_VNEXT_ENTITY_CREATION_CONTRACT,
+  MEMORY_VNEXT_THIRD_PARTY_RELEVANCE_CONTRACT,
+  MEMORY_VNEXT_RECONCILIATION_CONTRACT,
+  buildMemoryInterpreterWireContract()
+].join("\n\n");
+
+// packages/ai/memory/vnext/legacyMigrationShadow.ts
+var LEGACY_MIGRATION_SHADOW_INSTRUCTION = `
+This Evidence came from a legacy memory record.
+Legacy kind and subject metadata are advisory hints only.
+Re-evaluate it under the current vNext contract.
+Do not mechanically map:
+- semantic -> State
+- procedural -> procedure State
+- subjectType=agent -> agent Entity
+- visibility -> scope
+Prefer Evidence-only when durable semantic value is unclear.
+`.trim();
+var serializeExisting = (existing) => JSON.stringify({
+  entityIds: existing?.entityIds ?? [],
+  states: (existing?.states ?? []).map((state2) => ({
+    stateId: state2.id,
+    entityId: state2.entityId,
+    facet: state2.facet,
+    text: state2.text
+  }))
+});
+var buildLegacyMigrationInterpreterInput = (input) => [
+  LEGACY_MIGRATION_SHADOW_INSTRUCTION,
+  `The legacy record's Evidence is marked referenceable with id "${input.evidence.id}" and sourceRef "${input.evidence.sourceRef}". Evidence ids marked referenceable in the supplied memory context may be referenced directly. When a State cites it, reference that exact id in evidenceRefs. Do not emit another Evidence for this legacy record.`,
+  `Imported Evidence (text is the authoritative legacy content, referenceable directly):
+${JSON.stringify(
+    {
+      ...input.evidence,
+      referenceable: true
+    },
+    null,
+    2
+  )}`,
+  `Legacy metadata (advisory hints only, NOT vNext semantics):
+${JSON.stringify(
+    {
+      kind: input.item.kind,
+      visibility: input.item.visibility,
+      subjectType: input.item.subjectType,
+      subjectId: input.item.subjectId,
+      facet: input.item.facet,
+      importance: input.item.importance,
+      resident: input.item.resident
+    },
+    null,
+    2
+  )}`,
+  `Existing vNext context for this principal (caller-supplied shadow snapshot):
+${serializeExisting(
+    input.existing
+  )}`
+].join("\n\n");
+var mergeImportedEvidence = (mutation, imported) => {
+  const emitted = mutation.evidence ?? [];
+  const duplicatedIds = new Set(
+    emitted.filter(
+      (item) => item.sourceRef === imported.sourceRef || // A re-emitted copy that drops sourceRef is still the same legacy record:
+      // text equality is the only identity left on the wire to catch it.
+      item.sourceRef === void 0 && item.text === imported.text
+    ).map((item) => item.id)
+  );
+  const rewrite = (id) => duplicatedIds.has(id) ? imported.id : id;
+  return {
+    ...mutation,
+    evidence: [imported, ...emitted.filter((item) => !duplicatedIds.has(item.id))],
+    ...mutation.states ? {
+      states: mutation.states.map((state2) => ({
+        ...state2,
+        evidenceIds: [...new Set(state2.evidenceIds.map(rewrite))]
+      }))
+    } : {},
+    ...mutation.relations ? {
+      relations: mutation.relations.map((relation) => ({
+        ...relation,
+        from: rewrite(relation.from),
+        to: rewrite(relation.to)
+      }))
+    } : {}
+  };
+};
+var runLegacyMemoryMigrationShadow = async (input) => {
+  const principal = resolveLegacyMemoryPrincipal(input.item);
+  const evidence = buildLegacyMemoryEvidence(input.item);
+  const completion = await input.provider.complete(
+    [
+      { role: "system", content: buildMemoryVNextInterpreterPrompt() },
+      {
+        role: "user",
+        content: buildLegacyMigrationInterpreterInput({
+          item: input.item,
+          evidence,
+          ...input.existing ? { existing: input.existing } : {}
+        })
+      }
+    ],
+    input.timeoutMs === void 0 ? void 0 : { timeoutMs: input.timeoutMs }
+  );
+  const parsed = parseMemoryInterpreterWireMutation(completion.content);
+  if (!parsed.ok) {
+    throw new Error(`legacy migration shadow: unparsable interpreter response (${parsed.error})`);
+  }
+  const candidate = materializeMemoryInterpreterMutation({
+    // The principal identity (user:/space:/system:<id>) is the migration owner
+    // space, so a space migration can never land in a user space.
+    ownerId: evidence.ownerId,
+    wire: parsed.value,
+    ...input.existing?.states ? { existingStates: [...input.existing.states] } : {},
+    ...input.existing?.entityIds ? { existingEntityIds: [...input.existing.entityIds] } : {},
+    referenceableEvidenceIds: [evidence.id],
+    ...input.now === void 0 ? {} : { now: input.now },
+    ...input.nextId ? { nextId: input.nextId } : {}
+  });
+  const mutation = mergeImportedEvidence(candidate, evidence);
+  return {
+    principal,
+    evidence,
+    wire: parsed.value,
+    mutation,
+    action: mutation.action,
+    reason: mutation.reason
+  };
+};
+
+// packages/ai/memory/vnext/lazyPromotion.ts
+var ERROR_MESSAGE_MAX2 = 120;
+var inFlight = /* @__PURE__ */ new Set();
+var shortError2 = (error) => {
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return message.length > ERROR_MESSAGE_MAX2 ? `${message.slice(0, ERROR_MESSAGE_MAX2)}\u2026` : message;
+};
+var loadExistingContext = async (db, ownerId) => {
+  const entities = await listMemoryEntitiesVNext(db, ownerId);
+  const states = (await Promise.all(
+    entities.map((entity) => listMemoryStatesForEntityVNext(db, ownerId, entity.id))
+  )).flat();
+  return {
+    entityIds: entities.map((entity) => entity.id),
+    states
+  };
+};
+var withoutImportedEvidence = (mutation, importedEvidenceId) => ({
+  ...mutation,
+  evidence: (mutation.evidence ?? []).filter((evidence) => evidence.id !== importedEvidenceId)
+});
+var hasWrites = (mutation) => (mutation.evidence?.length ?? 0) > 0 || (mutation.entities?.length ?? 0) > 0 || (mutation.states?.length ?? 0) > 0 || (mutation.supersededStateIds?.length ?? 0) > 0 || (mutation.relations?.length ?? 0) > 0;
+var runMemoryVNextLazyPromotion = async (input) => {
+  const clock = input.clock ?? (() => performance.now());
+  const startedAt = clock();
+  const emit = input.emit ?? ((observation) => console.info("[memory] vnext lazy promotion", {
+    event: "memory_vnext_lazy_promotion",
+    ...observation
+  }));
+  const finish = (partial) => {
+    const observation = {
+      ...partial,
+      latencyMs: Math.round((clock() - startedAt) * 10) / 10
+    };
+    try {
+      emit(observation);
+    } catch {
+    }
+    return observation;
+  };
+  const deterministicEvidence = buildLegacyMemoryEvidence(input.item);
+  const flightKey = `${deterministicEvidence.ownerId}\0${deterministicEvidence.id}`;
+  if (inFlight.has(flightKey)) {
+    return finish({ status: "in_flight" });
+  }
+  inFlight.add(flightKey);
+  try {
+    const evidenceResult = await applyLegacyMemoryEvidence(input.db, input.item);
+    if (evidenceResult.status === "conflict") {
+      return finish({ status: "conflict" });
+    }
+    const evidence = evidenceResult.evidence;
+    const existing = await loadExistingContext(input.db, evidence.ownerId);
+    const alreadyCovered = (existing.states ?? []).some(
+      (state2) => !state2.retiredAt && state2.evidenceIds.includes(evidence.id)
+    );
+    if (alreadyCovered) {
+      return finish({ status: "already_covered" });
+    }
+    const interpreted = await runLegacyMemoryMigrationShadow({
+      item: input.item,
+      provider: input.provider,
+      existing,
+      ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+      ...input.now === void 0 ? {} : { now: input.now },
+      ...input.nextId ? { nextId: input.nextId } : {}
+    });
+    const semanticMutation = withoutImportedEvidence(interpreted.mutation, evidence.id);
+    if (!hasWrites(semanticMutation)) {
+      return finish({ status: "no_op", action: semanticMutation.action });
+    }
+    await applyMemoryInterpreterMutation(input.db, evidence.ownerId, semanticMutation);
+    return finish({ status: "promoted", action: semanticMutation.action });
+  } catch (error) {
+    return finish({ status: "error", error: shortError2(error) });
+  } finally {
+    inFlight.delete(flightKey);
+  }
+};
+var isMemoryVNextLazyPromotionEnabled = (env = typeof process !== "undefined" ? process.env : {}) => env.NOLO_MEMORY_VNEXT_LAZY_PROMOTION === "1" || env.NOLO_MEMORY_VNEXT_LAZY_PROMOTION === "true";
+
 // packages/ai/memory/runtime.ts
 var COLD_STORAGE_CONFIDENCE = 0.3;
 var MEMORY_OVERLAY_TOKEN_BUDGET = DEFAULT_MEMORY_OVERLAY_TOKEN_BUDGET;
@@ -12196,6 +13580,7 @@ var resolveMemoryRuntime = async (input) => {
     return { selectedItems: [], promptBlock: null };
   }
   const policy = resolveAgentMemoryPolicy({ agentKey: input.agentKey });
+  const legacyStartedAt = performance.now();
   const candidates = await loadMemoryCandidatesFromDb(input.db, {
     owners,
     subjects: buildMemorySubjectsForAgent({
@@ -12222,13 +13607,40 @@ var resolveMemoryRuntime = async (input) => {
     input.userInput
   );
   const selected = [...residentItems, ...ranked];
+  const legacyLatencyMs = Math.round((performance.now() - legacyStartedAt) * 10) / 10;
+  const promptBlock = selected.length === 0 ? null : buildMemoryOverlay(selected, { maxTokens: MEMORY_OVERLAY_TOKEN_BUDGET });
+  const shadowEnabled = input.vNextShadowProvider != null && isMemoryVNextShadowReadEnabled();
+  if (shadowEnabled) {
+    await runMemoryVNextShadowRead({
+      ctx: {
+        db: input.db,
+        owners,
+        query: input.userInput,
+        provider: input.vNextShadowProvider
+      },
+      legacyItems: selected,
+      legacyLatencyMs,
+      legacyContextChars: promptBlock?.length ?? 0
+    });
+  }
+  const promotionCandidate = selected[0];
+  const lazyPromotionEnabled = input.vNextShadowProvider != null && isMemoryVNextLazyPromotionEnabled();
+  if (lazyPromotionEnabled && promotionCandidate) {
+    void runMemoryVNextLazyPromotion({
+      db: input.db,
+      item: promotionCandidate,
+      provider: input.vNextShadowProvider,
+      ...input.lazyPromotionEmit ? { emit: input.lazyPromotionEmit } : {}
+    }).catch(() => {
+    });
+  }
   if (selected.length === 0) {
     return { selectedItems: [], promptBlock: null };
   }
   await touchMemoryItemsInDb(input.db, selected);
   return {
     selectedItems: selected,
-    promptBlock: buildMemoryOverlay(selected, { maxTokens: MEMORY_OVERLAY_TOKEN_BUDGET })
+    promptBlock
   };
 };
 
@@ -12272,7 +13684,8 @@ var queryLocalMemory = async (env, agentKey, userInput, spaceId) => {
     userId: machineId,
     agentKey,
     userInput,
-    ...spaceId ? { spaceId } : {}
+    ...spaceId ? { spaceId } : {},
+    ...isMemoryVNextShadowReadEnabled(env) ? { vNextShadowProvider: void 0 } : {}
   });
   return resolution.promptBlock;
 };
@@ -12350,7 +13763,10 @@ async function resolveAgentRunAgentKey(args) {
 }
 async function runAgentRunCommand(args, deps) {
   const env = deps.env ?? process.env;
-  const output = deps.output ?? process.stdout;
+  const output = deps.output ?? {
+    write: (chunk) => process.stdout.write(chunk),
+    writeErr: (chunk) => process.stderr.write(chunk)
+  };
   if (args.includes("--help") || args.includes("-h")) {
     writeUsage(output, deps.commandPath);
     return 0;