poe-code 3.0.311 → 3.0.313

package/dist/index.js

@@ -3473,21 +3473,21 @@ function sliceOffsetMap(offsets, start, end) {
 }
 function createOffsetMap(input, absoluteStart = 0) {
   const offsets = new Array(input.length + 1).fill(absoluteStart);
-  let byteOffset = absoluteStart;
+  let byteOffset2 = absoluteStart;
   let index = 0;
   while (index < input.length) {
-    offsets[index] = byteOffset;
+    offsets[index] = byteOffset2;
     const codePoint = input.codePointAt(index) ?? 0;
     const codeUnitLength = codePoint > 65535 ? 2 : 1;
     const byteLength = codePoint <= 127 ? 1 : codePoint <= 2047 ? 2 : codePoint <= 65535 ? 3 : 4;
     for (let offsetIndex = 1; offsetIndex < codeUnitLength; offsetIndex += 1) {
-      offsets[index + offsetIndex] = byteOffset;
+      offsets[index + offsetIndex] = byteOffset2;
     }
-    byteOffset += byteLength;
+    byteOffset2 += byteLength;
     index += codeUnitLength;
-    offsets[index] = byteOffset;
+    offsets[index] = byteOffset2;
   }
-  offsets[input.length] = byteOffset;
+  offsets[input.length] = byteOffset2;
   return offsets;
 }
 var INLINE_HTML_TAGS;
@@ -4102,21 +4102,21 @@ function getTextNodeSourceOffsets(node) {
 }
 function createOffsetMap2(input, absoluteStart = 0, absoluteEnd) {
   const offsets = new Array(input.length + 1).fill(absoluteStart);
-  let byteOffset = absoluteStart;
+  let byteOffset2 = absoluteStart;
   let index = 0;
   while (index < input.length) {
-    offsets[index] = byteOffset;
+    offsets[index] = byteOffset2;
     const codePoint = input.codePointAt(index) ?? 0;
     const codeUnitLength = codePoint > 65535 ? 2 : 1;
     const byteLength = codePoint <= 127 ? 1 : codePoint <= 2047 ? 2 : codePoint <= 65535 ? 3 : 4;
     for (let offsetIndex = 1; offsetIndex < codeUnitLength; offsetIndex += 1) {
-      offsets[index + offsetIndex] = byteOffset;
+      offsets[index + offsetIndex] = byteOffset2;
     }
-    byteOffset += byteLength;
+    byteOffset2 += byteLength;
     index += codeUnitLength;
-    offsets[index] = byteOffset;
+    offsets[index] = byteOffset2;
   }
-  offsets[input.length] = absoluteEnd ?? byteOffset;
+  offsets[input.length] = absoluteEnd ?? byteOffset2;
   return offsets;
 }
 function createMappedText(value, offsets) {
@@ -16932,6 +16932,9 @@ async function configuredTimeout(options) {
 async function cacheEnabled(options) {
   return (await resolveMemoryConfig(options)).cacheEnabled;
 }
+async function mcpWritesAllowed(options) {
+  return (await resolveMemoryConfig(options)).mcpWritesAllowed;
+}
 async function defaultQueryBudget(options) {
   return (await resolveMemoryConfig(options)).defaultQueryBudget;
 }
@@ -21298,9 +21301,9 @@ function createContainerJob(containerId, runner, engine, context, detachedJobCon
       const sinceCondition = opts?.since === void 0 ? "" : ` && test $(stat -c %Y ${logFile} 2>/dev/null || stat -f %m ${logFile}) -ge ${Math.ceil(
         opts.since.getTime() / 1e3
       )}`;
-      let byteOffset = opts?.sinceByte ?? 0;
+      let byteOffset2 = opts?.sinceByte ?? 0;
       let pendingBytes = Buffer.alloc(0);
-      let pendingByteOffset = byteOffset;
+      let pendingByteOffset = byteOffset2;
       while (true) {
         const stdout = await runAndReadBytes(runner, {
           command: engine,
@@ -21310,7 +21313,7 @@ function createContainerJob(containerId, runner, engine, context, detachedJobCon
             containerId,
             "sh",
             "-c",
-            `test -f ${logFile}${sinceCondition} && tail -c +${byteOffset + 1} ${logFile} || true`
+            `test -f ${logFile}${sinceCondition} && tail -c +${byteOffset2 + 1} ${logFile} || true`
           ],
           stdout: "pipe",
           stderr: "pipe"
@@ -21318,7 +21321,7 @@ function createContainerJob(containerId, runner, engine, context, detachedJobCon
         if (stdout.byteLength > 0) {
           const combined = pendingBytes.byteLength === 0 ? stdout : Buffer.concat([pendingBytes, stdout]);
           const completeLength = completeUtf8PrefixLength(combined);
-          byteOffset += stdout.byteLength;
+          byteOffset2 += stdout.byteLength;
           pendingBytes = combined.subarray(completeLength);
           const data = combined.subarray(0, completeLength).toString("utf8");
           if (data.length > 0) {
@@ -26084,19 +26087,19 @@ async function* streamLogFile(env, jobId, opts) {
   assertSafeJobId2(jobId);
   const fs28 = env.fs ?? nodeFs3;
   const file = jobLogPath(jobId);
-  let byteOffset = opts.sinceByte ?? (opts.since === void 0 ? 0 : await readCurrentByteLength(fs28, file));
+  let byteOffset2 = opts.sinceByte ?? (opts.since === void 0 ? 0 : await readCurrentByteLength(fs28, file));
   let pendingBytes = Buffer.alloc(0);
-  let pendingByteOffset = byteOffset;
+  let pendingByteOffset = byteOffset2;
   while (true) {
     if (opts.since !== void 0 && !await wasModifiedSince(fs28, file, opts.since)) {
       await waitForLogChange(fs28, file);
       continue;
     }
-    const result = await readLogChunk(fs28, file, byteOffset);
+    const result = await readLogChunk(fs28, file, byteOffset2);
     if (result !== null) {
       const combined = pendingBytes.length === 0 ? result.bytes : Buffer.concat([pendingBytes, result.bytes]);
       const completeLength = completeUtf8PrefixLength2(combined);
-      byteOffset = result.nextByteOffset;
+      byteOffset2 = result.nextByteOffset;
       pendingBytes = combined.subarray(completeLength);
       const data = combined.subarray(0, completeLength).toString("utf8");
       if (data.length > 0) {
@@ -26163,13 +26166,13 @@ function assertSafeJobId2(jobId) {
     throw new Error(`Invalid job id "${jobId}". Job ids must be single filename components.`);
   }
 }
-async function readLogChunk(fs28, file, byteOffset) {
+async function readLogChunk(fs28, file, byteOffset2) {
   const contents = await readFileIfExists3(fs28, file);
-  if (contents === null || byteOffset >= contents.byteLength) {
+  if (contents === null || byteOffset2 >= contents.byteLength) {
     return null;
   }
   return {
-    bytes: contents.subarray(byteOffset),
+    bytes: contents.subarray(byteOffset2),
     nextByteOffset: contents.byteLength
   };
 }
@@ -70934,7 +70937,8 @@ function scanMarkdown(source) {
   if (ast.type !== "root") {
     return [];
   }
-  const headings = ast.children.filter(isHeadingNode);
+  const htmlCommentRanges = collectHtmlCommentRanges(source);
+  const headings = ast.children.filter(isHeadingNode).filter((heading) => !isInsideHtmlComment(getRequiredRange(heading).start, htmlCommentRanges));
   if (headings.length === 0) {
     return [];
   }
@@ -70955,6 +70959,30 @@ function scanMarkdown(source) {
   applyNumbers(sections, baselineDepth);
   return sections;
 }
+function collectHtmlCommentRanges(source) {
+  const ranges = [];
+  let searchStart = 0;
+  while (searchStart < source.length) {
+    const commentStart = source.indexOf("<!--", searchStart);
+    if (commentStart === -1) {
+      return ranges;
+    }
+    const commentEndMarker = source.indexOf("-->", commentStart + "<!--".length);
+    const commentEnd = commentEndMarker === -1 ? source.length : commentEndMarker + "-->".length;
+    ranges.push({
+      start: byteOffset(source, commentStart),
+      end: byteOffset(source, commentEnd)
+    });
+    searchStart = commentEnd;
+  }
+  return ranges;
+}
+function isInsideHtmlComment(offset, ranges) {
+  return ranges.some((range) => offset >= range.start && offset < range.end);
+}
+function byteOffset(source, index) {
+  return Buffer.byteLength(source.slice(0, index), "utf8");
+}
 function isHeadingNode(node) {
   return node.type === "heading";
 }
@@ -71050,6 +71078,9 @@ async function loadMarkdownDocument(file, dependencies = {}) {
   };
 }
 function resolveMarkdownPath(file, cwd = process.cwd()) {
+  if (file.trim().length === 0) {
+    throw new UserError("invalid file: expected a non-empty path");
+  }
   return path92.isAbsolute(file) ? file : path92.resolve(cwd, file);
 }
 function sliceMarkdownBytes(source, start, end) {
@@ -71085,6 +71116,9 @@ function hasYamlLikeLeadingFrontmatter(source) {
   if (lines[0] !== "---") {
     return false;
   }
+  if (lines[1]?.trim().length === 0) {
+    return false;
+  }
   for (const line of lines.slice(1)) {
     const trimmed = line.trim();
     if (trimmed.length === 0) {
@@ -71150,16 +71184,19 @@ var init_read_markdown = __esm({
 // packages/markdown-reader/src/core/resolve.ts
 function resolveSection(sections, id) {
   const trimmedId = id.trim();
+  if (trimmedId.length === 0) {
+    throw new UserError("invalid section: expected a non-empty section id");
+  }
+  const sectionByNumber = sections.find((section) => section.number === trimmedId);
+  if (sectionByNumber !== void 0) {
+    return sectionByNumber;
+  }
   const unnumberedTitleMatch = sections.find(
     (section) => section.number === null && section.title === trimmedId
   );
   if (unnumberedTitleMatch !== void 0) {
     return unnumberedTitleMatch;
   }
-  const sectionByNumber = sections.find((section) => section.number === trimmedId);
-  if (sectionByNumber !== void 0) {
-    return sectionByNumber;
-  }
   const titleMatches = sections.filter((section) => section.title === trimmedId);
   if (titleMatches.length === 1) {
     return titleMatches[0];
@@ -71181,6 +71218,9 @@ var init_resolve5 = __esm({
 // packages/markdown-reader/src/core/read-section.ts
 function createReadSection(dependencies = {}) {
   return async function readSection2(params) {
+    if (params.section.trim().length === 0) {
+      throw new UserError("invalid section: expected a non-empty section id");
+    }
     const { source, sections } = await loadMarkdownDocument(params.file, dependencies);
     const section = resolveSection(sections, params.section);
     const end = params.includeChildren === false ? section.bodyEndNoChildren : section.bodyEnd;
@@ -71201,6 +71241,7 @@ var init_read_section = __esm({
     "use strict";
     init_document();
     init_resolve5();
+    init_src21();
     readSection = createReadSection();
   }
 });
@@ -71215,8 +71256,14 @@ var init_tools2 = __esm({
     init_read_markdown();
     init_read_section();
     readParams = S.Object({
-      file: S.String({ description: "Path to the markdown file" }),
-      depth: S.Optional(S.Number({ description: "Limit TOC to headings at depth <= n" }))
+      file: S.String({ description: "Path to the markdown file", minLength: 1 }),
+      depth: S.Optional(
+        S.Number({
+          description: "Limit TOC to headings at depth <= n",
+          jsonType: "integer",
+          minimum: 0
+        })
+      )
     });
     tocEntryResult = S.Object({
       depth: S.Number(),
@@ -71236,8 +71283,11 @@ var init_tools2 = __esm({
       handler: async ({ params }) => readMarkdown(params)
     });
     readSectionParams = S.Object({
-      file: S.String({ description: "Path to the markdown file" }),
-      section: S.String({ description: "Numeric path or exact heading text to read" }),
+      file: S.String({ description: "Path to the markdown file", minLength: 1 }),
+      section: S.String({
+        description: "Numeric path or exact heading text to read",
+        minLength: 1
+      }),
       includeChildren: S.Optional(S.Boolean({ description: "Include nested child sections" }))
     });
     readSectionTool = defineCommand({
@@ -100415,6 +100465,9 @@ async function assertMemoryRootIsNotSymlink(root) {
     try {
       const stat33 = await fs12.lstat(currentPath);
       if (stat33.isSymbolicLink()) {
+        if (await isAllowedMacSystemAlias(currentPath)) {
+          continue;
+        }
         throw new MemoryPathError(`Memory root "${root}" cannot be a symbolic link.`);
       }
     } catch (error3) {
@@ -100425,6 +100478,17 @@ async function assertMemoryRootIsNotSymlink(root) {
     }
   }
 }
+async function isAllowedMacSystemAlias(currentPath) {
+  if (currentPath !== "/var") {
+    return false;
+  }
+  try {
+    const target = await fs12.readlink(currentPath);
+    return target === "/private/var" || target === "private/var";
+  } catch {
+    return false;
+  }
+}
 function isMissing(error3) {
   return hasOwnErrorCode27(error3, "ENOENT");
 }
@@ -100574,7 +100638,11 @@ function serializeFrontmatter(frontmatter, body) {
   return stringifyFrontmatter(serialized, body);
 }
 function parseSourceRef(serialized) {
-  const [rawPath, rawAnchor] = serialized.split("#", 2);
+  const parts = serialized.split("#");
+  if (parts.length > 2) {
+    throw new Error(`Invalid source ref "${serialized}".`);
+  }
+  const [rawPath, rawAnchor] = parts;
   const normalizedPath = rawPath?.trim();
   if (normalizedPath === void 0 || normalizedPath.length === 0) {
     throw new Error(`Invalid source ref "${serialized}".`);
@@ -100828,7 +100896,7 @@ async function searchMemory(root, query) {
   if (normalizedQuery.length === 0) {
     throw new Error("Search query cannot be empty.");
   }
-  const relPaths = await collectMarkdownRelPaths(root);
+  const relPaths = await collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH);
   const hits = [];
   for (const relPath of relPaths) {
     await assertNoSymlinkSegments(root, relPath);
@@ -101351,7 +101419,7 @@ async function appendToPage(root, relPath, content, opts) {
   const before = await snapshot(root);
   await fs19.mkdir(path158.dirname(pagePath), { recursive: true });
   await assertNoSymlinkSegments(root, pageRelPath);
-  const parsed = originalPage === void 0 ? { frontmatter: {}, body: "" } : parseFrontmatter4(originalPage);
+  const parsed = parseAppendTarget(originalPage, pageRelPath);
   try {
     await writeFileAtomically7(
       pagePath,
@@ -101363,6 +101431,18 @@ async function appendToPage(root, relPath, content, opts) {
     throw error3;
   }
 }
+function parseAppendTarget(originalPage, relPath) {
+  if (originalPage === void 0) {
+    return { frontmatter: {}, body: "" };
+  }
+  try {
+    return parseFrontmatter4(originalPage);
+  } catch (error3) {
+    const message2 = error3 instanceof Error ? error3.message : String(error3);
+    console.warn(`Failed to parse frontmatter for "${relPath}": ${message2}`);
+    return { frontmatter: {}, body: originalPage };
+  }
+}
 async function clearMemory(root) {
   await assertMemoryRootIsNotSymlink(root);
   const stagedRoot = `${root}.clear-${randomUUID43()}`;
@@ -101728,17 +101808,21 @@ async function clearCache(root, opts = {}) {
 async function assertIngestCachePathIsNotSymlink(root) {
   await assertNoSymlinkSegments(root, MEMORY_INGEST_CACHE_DIR_RELPATH);
 }
-function parseCacheEntry(value, _key) {
+function parseCacheEntry(value, requestedKey) {
   const object = expectRecord2(value);
+  const key2 = expectString2(getOwnEntry36(object, "key"), "key");
+  if (key2 !== requestedKey) {
+    throw new Error(`Cache entry key "${key2}" does not match requested key "${requestedKey}".`);
+  }
   return {
-    key: expectString2(getOwnEntry36(object, "key"), "key"),
+    key: key2,
     ingestedAt: expectString2(getOwnEntry36(object, "ingestedAt"), "ingestedAt"),
     sourceLabel: expectString2(getOwnEntry36(object, "sourceLabel"), "sourceLabel"),
     diff: parseMemoryDiff(getOwnEntry36(object, "diff")),
-    exitCode: expectNumber(getOwnEntry36(object, "exitCode"), "exitCode"),
-    durationMs: expectNumber(getOwnEntry36(object, "durationMs"), "durationMs"),
-    memoryTokens: expectNumber(getOwnEntry36(object, "memoryTokens"), "memoryTokens"),
-    sourceTokens: expectNumber(getOwnEntry36(object, "sourceTokens"), "sourceTokens"),
+    exitCode: expectNonNegativeInteger2(getOwnEntry36(object, "exitCode"), "exitCode"),
+    durationMs: expectNonNegativeInteger2(getOwnEntry36(object, "durationMs"), "durationMs"),
+    memoryTokens: expectNonNegativeInteger2(getOwnEntry36(object, "memoryTokens"), "memoryTokens"),
+    sourceTokens: expectNonNegativeInteger2(getOwnEntry36(object, "sourceTokens"), "sourceTokens"),
     promptTemplateVersion: expectString2(
       getOwnEntry36(object, "promptTemplateVersion"),
       "promptTemplateVersion"
@@ -101766,9 +101850,9 @@ function expectString2(value, field) {
   }
   return value;
 }
-function expectNumber(value, field) {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    throw new Error(`Expected number at "${field}".`);
+function expectNonNegativeInteger2(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`Expected non-negative integer at "${field}".`);
   }
   return value;
 }
@@ -102427,7 +102511,7 @@ async function installMemory(options) {
       }
       throw error3;
     }
-    mcpConfigPath = options.agent === "codex" ? `${options.homeDir}/.config/codex/mcp-config.json` : `${options.homeDir}/.mcp.json`;
+    mcpConfigPath = resolveMcpConfigPath(options.agent, options.homeDir, options.platform);
   }
   return {
     skillInstalled: !options.mcpOnly,
@@ -102436,6 +102520,14 @@ async function installMemory(options) {
     mcpConfigPath
   };
 }
+function resolveMcpConfigPath(agent3, homeDir, platform) {
+  const support = resolveAgentSupport3(agent3);
+  if (support.status !== "supported" || support.config === void 0) {
+    throw new Error(`Unsupported agent: ${agent3}`);
+  }
+  const configFile = typeof support.config.configFile === "function" ? support.config.configFile(platform) : support.config.configFile;
+  return configFile.startsWith("~/") ? path164.join(homeDir, configFile.slice(2)) : configFile;
+}
 async function removeInstalledSkill(options, skillPath) {
   const baseDir = options.scope === "global" ? options.homeDir : options.cwd;
   const displayPath = skillPath.startsWith("~/") ? skillPath.slice(2) : skillPath;
@@ -102456,6 +102548,45 @@ var init_install3 = __esm({
   }
 });
 
+// packages/memory/src/agent-response.ts
+function parseMemoryAgentResponse(stdout) {
+  let value;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    throw new Error("Memory agent returned invalid JSON output.");
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Memory agent returned an invalid result payload.");
+  }
+  const result = value;
+  if (typeof result.answer !== "string" || !Array.isArray(result.citations) || !isNonNegativeInteger(result.tokensUsed) || !result.citations.every(isQueryCitation)) {
+    throw new Error("Memory agent returned an invalid result payload.");
+  }
+  return {
+    answer: result.answer,
+    citations: result.citations,
+    tokensUsed: result.tokensUsed
+  };
+}
+function isQueryCitation(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const citation = value;
+  return typeof citation.relPath === "string" && (citation.section === void 0 || typeof citation.section === "string") && typeof citation.confidence === "string" && validCitationConfidences.has(citation.confidence);
+}
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+var validCitationConfidences;
+var init_agent_response = __esm({
+  "packages/memory/src/agent-response.ts"() {
+    "use strict";
+    validCitationConfidences = /* @__PURE__ */ new Set(["extracted", "inferred", "ambiguous"]);
+  }
+});
+
 // packages/memory/src/query.ts
 import * as fs25 from "node:fs/promises";
 import path165 from "node:path";
@@ -102478,7 +102609,7 @@ async function queryMemory(root, options) {
   const agentId = await resolveAgent(configOptions, options.agent ?? null) ?? options.agent ?? "claude-code";
   const context = await selectQueryContext(root, options.question, options.budget);
   const spawned = await spawn5(agentId, { prompt: context.prompt });
-  const result = parseQueryResponse(spawned.stdout);
+  const result = parseMemoryAgentResponse(spawned.stdout);
   return {
     answer: result.answer,
     citations: result.citations,
@@ -102487,26 +102618,6 @@ async function queryMemory(root, options) {
     exitCode: spawned.exitCode
   };
 }
-function parseQueryResponse(stdout) {
-  let value;
-  try {
-    value = JSON.parse(stdout);
-  } catch {
-    throw new Error("Memory agent returned invalid JSON output.");
-  }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  const result = value;
-  if (typeof result.answer !== "string" || !Array.isArray(result.citations) || typeof result.tokensUsed !== "number" || !Number.isFinite(result.tokensUsed)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  return {
-    answer: result.answer,
-    citations: result.citations,
-    tokensUsed: result.tokensUsed
-  };
-}
 async function selectQueryContext(root, question, budget) {
   if (!Number.isFinite(budget) || budget < 0) {
     throw new Error("budget must be a finite non-negative number");
@@ -102599,6 +102710,7 @@ var init_query = __esm({
     init_src44();
     init_src17();
     init_src9();
+    init_agent_response();
     init_pages();
     init_paths2();
   }
@@ -102634,7 +102746,7 @@ async function explainPage(root, options) {
   };
   const agentId = await resolveAgent(configOptions, options.agent ?? null) ?? options.agent ?? "claude-code";
   const spawned = await spawn5(agentId, { prompt });
-  const response = parseExplainResponse(spawned.stdout);
+  const response = parseMemoryAgentResponse(spawned.stdout);
   return {
     answer: response.answer,
     citations: response.citations,
@@ -102645,26 +102757,6 @@ async function explainPage(root, options) {
     outboundSources: targetPage.frontmatter.sources ?? []
   };
 }
-function parseExplainResponse(stdout) {
-  let value;
-  try {
-    value = JSON.parse(stdout);
-  } catch {
-    throw new Error("Memory agent returned invalid JSON output.");
-  }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  const response = value;
-  if (typeof response.answer !== "string" || !Array.isArray(response.citations) || typeof response.tokensUsed !== "number" || !Number.isFinite(response.tokensUsed)) {
-    throw new Error("Memory agent returned an invalid result payload.");
-  }
-  return {
-    answer: response.answer,
-    citations: response.citations,
-    tokensUsed: response.tokensUsed
-  };
-}
 function collectRelatedPages(pages, targetRelPath, outboundSources) {
   const memorySourcePaths = new Set(outboundSources.map((source) => source.path));
   return pages.filter((page) => {
@@ -102708,6 +102800,7 @@ var init_explain = __esm({
     init_src44();
     init_src17();
     init_src9();
+    init_agent_response();
     init_errors7();
     init_pages();
     init_query();
@@ -102802,7 +102895,7 @@ var init_src45 = __esm({
 var SKILL_memory_default;
 var init_SKILL_memory = __esm({
   "packages/memory/src/templates/SKILL_memory.md"() {
-    SKILL_memory_default = '## CLI \u2014 `poe-code memory <subcommand>`\n| Command | Purpose (when the agent should reach for it) |\n|---|---|\n| `init` | create `.poe-code/memory/` if missing; safe before first write |\n| `ls` | list pages + one-line descriptions; first step for recall questions |\n| `show <path>` | print one page verbatim after `ls` identifies a candidate |\n| `search <query>` | ripgrep over memory when the page is not obvious from `ls` |\n| `write <path> --reason <text>` | replace a page from stdin when authoring or rewriting |\n| `append <path>` | append stdin to a page; intended for `LOG.md`-style updates |\n| `edit <path>` | open `$EDITOR`; avoid from agents, prefer `write`/`append` |\n| `ingest <source>` | spawn an ingest agent to fold a file or URL into memory |\n| `query "<question>"` | answer a question from memory only, with citations |\n| `explain <path>` | summarize a page plus its inbound/outbound links |\n| `lint [--fix]` | find stale citations, untagged claims, contradictions |\n| `status [--no-tokens]` | show counts, bytes, and token-reduction ratio |\n| `cache status` / `cache clear` | inspect or clear the ingest cache |\n| `clear --yes` | wipe memory; destructive, user-request only |\n| `install` | install this skill and register the `poe-code-memory` MCP server |\n\n## MCP \u2014 `poe-code-memory` server\n| Tool | Purpose |\n|---|---|\n| `list_pages` | enumerate pages (preferred over shelling out to `memory ls`) |\n| `read_page` | read one page (preferred over `memory show`) |\n| `search_memory` | search memory text (preferred over `memory search`) |\n| `append_to_page` | append to a page when writes are enabled |\n| `status` | read counts and token ratio |\n\n- Prefer MCP tools over shell commands when both surfaces are available.\n- Confidence-tag non-trivial claims with `extracted`, `inferred`, or `ambiguous`.\n- Keep memory edits focused; update the minimal relevant pages.\n- Never call `memory clear` without explicit user request.\n';
+    SKILL_memory_default = '## CLI \u2014 `poe-code memory <subcommand>`\n| Command | Purpose (when the agent should reach for it) |\n|---|---|\n| `init` | create `.poe-code/memory/` if missing; safe before first write |\n| `ls` | list pages + one-line descriptions; first step for recall questions |\n| `show <path>` | print one page verbatim after `ls` identifies a candidate |\n| `search <query>` | ripgrep over memory when the page is not obvious from `ls` |\n| `write <path> --reason <text>` | replace a page from stdin when authoring or rewriting |\n| `append <path>` | append stdin to a page; intended for `LOG.md`-style updates |\n| `edit <path>` | open `$EDITOR`; avoid from agents, prefer `write`/`append` |\n| `ingest <source>` | spawn an ingest agent to fold a file or URL into memory |\n| `query "<question>"` | answer a question from memory only, with citations |\n| `explain <path>` | summarize a page plus its inbound/outbound links |\n| `lint` | find stale citations, untagged claims, contradictions |\n| `status [--no-tokens]` | show counts, bytes, and token-reduction ratio |\n| `cache status` / `cache clear` | inspect or clear the ingest cache |\n| `clear --yes` | wipe memory; destructive, user-request only |\n| `install` | install this skill and register the `poe-code-memory` MCP server |\n\n## MCP \u2014 `poe-code-memory` server\n| Tool | Purpose |\n|---|---|\n| `list_pages` | enumerate pages (preferred over shelling out to `memory ls`) |\n| `read_page` | read one page (preferred over `memory show`) |\n| `search_memory` | search memory text (preferred over `memory search`) |\n| `append_to_page` | append to a page when writes are enabled |\n| `status` | read counts and token ratio |\n\n- Prefer MCP tools over shell commands when both surfaces are available.\n- Confidence-tag non-trivial claims with `extracted`, `inferred`, or `ambiguous`.\n- Keep memory edits focused; update the minimal relevant pages.\n- Never call `memory clear` without explicit user request.\n';
   }
 });
 
@@ -102874,6 +102967,28 @@ async function queryBudget(container, value) {
     projectFilePath: container.env.projectConfigPath
   });
 }
+function parseDecimalNonNegativeInteger(value, label) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!isDecimalNonNegativeIntegerText(value)) {
+    throw new ValidationError(`${label} must be a decimal non-negative integer.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new ValidationError(`${label} must be a decimal non-negative integer.`);
+  }
+  return parsed;
+}
+function isDecimalNonNegativeIntegerText(value) {
+  if (value.length === 0) {
+    return false;
+  }
+  if (value.length > 1 && value[0] === "0") {
+    return false;
+  }
+  return [...value].every((char) => char >= "0" && char <= "9");
+}
 async function readCommandContent(content) {
   if (content !== void 0) {
     return content;
@@ -103012,6 +103127,8 @@ function registerMemoryCommand(program, container) {
   memory.command("edit").description("Open a page in $EDITOR.").argument("<path>", "Page path (relative to memory pages/)").option("--reason <text>", "Reason for the memory update", "edit").action(async (pagePath, options) => {
     const flags = resolveCommandFlags(program);
     const root = await resolveRoot(container);
+    const mem = openMemory({ root });
+    await assertInitialized(mem);
     const relPath = resolvePageRelPath(pagePath);
     const editor = resolveEditor4(container);
     if (flags.dryRun) {
@@ -103030,10 +103147,7 @@ function registerMemoryCommand(program, container) {
     const root = await resolveRoot(container);
     const mem = openMemory({ root });
     await assertInitialized(mem);
-    const timeoutMs = options.timeoutMs === void 0 ? void 0 : Number(options.timeoutMs);
-    if (timeoutMs !== void 0 && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
-      throw new ValidationError("Timeout must be a finite non-negative number.");
-    }
+    const timeoutMs = parseDecimalNonNegativeInteger(options.timeoutMs, "Timeout");
     const result = await mem.ingest({
       source: resolveIngestSource(container.env.cwd, source),
       agent: options.agent,
@@ -103046,10 +103160,7 @@ function registerMemoryCommand(program, container) {
     process.stdout.write(`${result.cacheHit ? "Cache hit" : "Ingested"}: ${result.diff.created.length} created, ${result.diff.updated.length} updated, ${result.diff.deleted.length} deleted.
 `);
   });
-  memory.command("lint").description("Audit memory confidence and provenance claims.").option("--fix", "Reserved for automated repair").action(async (options) => {
-    if (options.fix) {
-      throw new ValidationError("Automated memory lint repair is not available yet.");
-    }
+  memory.command("lint").description("Audit memory confidence and provenance claims.").action(async () => {
     const root = await resolveRoot(container);
     const mem = openMemory({ root });
     await assertInitialized(mem);
@@ -103066,24 +103177,41 @@ function registerMemoryCommand(program, container) {
     }
   });
   memory.command("query").description("Answer a question using memory-only context.").argument("<question>", "Question").option("--budget <tokens>", "Token budget").option("--agent <agent>", "Agent override").action(async (question, options) => {
+    const flags = resolveCommandFlags(program);
     const root = await resolveRoot(container);
     const mem = openMemory({ root });
     await assertInitialized(mem);
+    const budget = await queryBudget(container, options.budget);
+    if (flags.dryRun) {
+      createExecutionResources(container, flags, "memory:query").logger.dryRun(
+        `Would query memory with budget ${budget}.`
+      );
+      return;
+    }
     const result = await mem.query({
       question,
-      budget: await queryBudget(container, options.budget),
+      budget,
       agent: options.agent
     });
     process.stdout.write(`${result.answer}
 `);
   });
   memory.command("explain").description("Summarize a memory page and its relationships.").argument("<path>", "Page path (relative to memory pages/)").option("--budget <tokens>", "Token budget").option("--agent <agent>", "Agent override").action(async (pagePath, options) => {
+    const flags = resolveCommandFlags(program);
     const root = await resolveRoot(container);
     const mem = openMemory({ root });
     await assertInitialized(mem);
+    const relPath = resolvePageRelPath(pagePath);
+    const budget = await queryBudget(container, options.budget);
+    if (flags.dryRun) {
+      createExecutionResources(container, flags, "memory:explain").logger.dryRun(
+        `Would explain ${relPath} with budget ${budget}.`
+      );
+      return;
+    }
     const result = await mem.explainPage({
-      relPath: resolvePageRelPath(pagePath),
-      budget: await queryBudget(container, options.budget),
+      relPath,
+      budget,
       agent: options.agent
     });
     process.stdout.write(`${result.answer}
@@ -103217,7 +103345,12 @@ function registerMemoryMcpCommand(program, container) {
       projectConfigPath: container.env.projectConfigPath
     });
     const handle = openMemory({ root });
-    const { server } = await startMemoryMcpServer(handle, { allowWrites: options.allowWrites === true });
+    const allowWrites = options.allowWrites === true || await mcpWritesAllowed({
+      fs: container.fs,
+      filePath: container.env.configPath,
+      projectFilePath: container.env.projectConfigPath
+    });
+    const { server } = await startMemoryMcpServer(handle, { allowWrites });
     await server.listen();
   });
 }
@@ -103225,6 +103358,7 @@ var init_memory_mcp = __esm({
   "src/cli/commands/memory-mcp.ts"() {
     "use strict";
     init_src45();
+    init_src9();
   }
 });
 
@@ -137375,7 +137509,7 @@ var init_package2 = __esm({
   "package.json"() {
     package_default2 = {
       name: "poe-code",
-      version: "3.0.311",
+      version: "3.0.313",
       description: "CLI tool to configure Poe API for developer workflows.",
       type: "module",
       main: "./dist/index.js",