threadnote 0.3.5 → 0.3.7

package/dist/threadnote.cjs

@@ -552,13 +552,13 @@ var require_help = __commonJS({
         function callFormatItem(term, description) {
           return helper.formatItem(term, termWidth, description, helper);
         }
-        let output = [
+        let output2 = [
           `${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(cmd))}`,
           ""
         ];
         const commandDescription = helper.commandDescription(cmd);
         if (commandDescription.length > 0) {
-          output = output.concat([
+          output2 = output2.concat([
             helper.boxWrap(
               helper.styleCommandDescription(commandDescription),
               helpWidth
@@ -572,7 +572,7 @@ var require_help = __commonJS({
             helper.styleArgumentDescription(helper.argumentDescription(argument))
           );
         });
-        output = output.concat(
+        output2 = output2.concat(
           this.formatItemList("Arguments:", argumentList, helper)
         );
         const optionGroups = this.groupItems(
@@ -587,7 +587,7 @@ var require_help = __commonJS({
               helper.styleOptionDescription(helper.optionDescription(option))
             );
           });
-          output = output.concat(this.formatItemList(group, optionList, helper));
+          output2 = output2.concat(this.formatItemList(group, optionList, helper));
         });
         if (helper.showGlobalOptions) {
           const globalOptionList = helper.visibleGlobalOptions(cmd).map((option) => {
@@ -596,7 +596,7 @@ var require_help = __commonJS({
               helper.styleOptionDescription(helper.optionDescription(option))
             );
           });
-          output = output.concat(
+          output2 = output2.concat(
             this.formatItemList("Global Options:", globalOptionList, helper)
           );
         }
@@ -612,9 +612,9 @@ var require_help = __commonJS({
               helper.styleSubcommandDescription(helper.subcommandDescription(sub))
             );
           });
-          output = output.concat(this.formatItemList(group, commandList, helper));
+          output2 = output2.concat(this.formatItemList(group, commandList, helper));
         });
-        return output.join("\n");
+        return output2.join("\n");
       }
       /**
        * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
@@ -3564,7 +3564,7 @@ async function walkFiles(root) {
   return files;
 }
 function globToRegExp(glob) {
-  let output = "^";
+  let output2 = "^";
   for (let index = 0; index < glob.length; index += 1) {
     const char = glob[index];
     if (char === "*") {
@@ -3572,23 +3572,23 @@ function globToRegExp(glob) {
       if (next === "*") {
         const afterNext = glob[index + 2];
         if (afterNext === "/") {
-          output += "(?:.*/)?";
+          output2 += "(?:.*/)?";
           index += 2;
         } else {
-          output += ".*";
+          output2 += ".*";
           index += 1;
         }
       } else {
-        output += "[^/]*";
+        output2 += "[^/]*";
       }
     } else if (char === "?") {
-      output += "[^/]";
+      output2 += "[^/]";
     } else {
-      output += escapeRegExp(char);
+      output2 += escapeRegExp(char);
     }
   }
-  output += "$";
-  return new RegExp(output);
+  output2 += "$";
+  return new RegExp(output2);
 }
 function getGlobBase(pattern) {
   const parts = pattern.split("/");
@@ -3933,8 +3933,8 @@ function exactRecallTerms(query) {
   }
   return terms.sort((left, right) => exactRecallTermScore(right) - exactRecallTermScore(left)).slice(0, 4);
 }
-function grepOutputHasMatches(output) {
-  return !output.includes("matches        []") && !output.includes('"matches":[]') && !output.includes("match_count    0");
+function grepOutputHasMatches(output2) {
+  return !output2.includes("matches        []") && !output2.includes('"matches":[]') && !output2.includes("match_count    0");
 }
 function exactRecallTermScore(term) {
   let score = term.length;
@@ -4991,14 +4991,14 @@ function resolveYamlBinary(data) {
   return bitlen % 8 === 0;
 }
 function constructYamlBinary(data) {
-  var idx, tailbits, input = data.replace(/[\r\n=]/g, ""), max = input.length, map2 = BASE64_MAP, bits = 0, result = [];
+  var idx, tailbits, input2 = data.replace(/[\r\n=]/g, ""), max = input2.length, map2 = BASE64_MAP, bits = 0, result = [];
   for (idx = 0; idx < max; idx++) {
     if (idx % 4 === 0 && idx) {
       result.push(bits >> 16 & 255);
       result.push(bits >> 8 & 255);
       result.push(bits & 255);
     }
-    bits = bits << 6 | map2.indexOf(input.charAt(idx));
+    bits = bits << 6 | map2.indexOf(input2.charAt(idx));
   }
   tailbits = max % 4 * 6;
   if (tailbits === 0) {
@@ -5231,8 +5231,8 @@ for (i = 0; i < 256; i++) {
   simpleEscapeMap[i] = simpleEscapeSequence(i);
 }
 var i;
-function State$1(input, options) {
-  this.input = input;
+function State$1(input2, options) {
+  this.input = input2;
   this.filename = options["filename"] || null;
   this.schema = options["schema"] || _default;
   this.onWarning = options["onWarning"] || null;
@@ -5241,7 +5241,7 @@ function State$1(input, options) {
   this.listener = options["listener"] || null;
   this.implicitTypes = this.schema.compiledImplicit;
   this.typeMap = this.schema.compiledTypeMap;
-  this.length = input.length;
+  this.length = input2.length;
   this.position = 0;
   this.line = 0;
   this.lineStart = 0;
@@ -6245,19 +6245,19 @@ function readDocument(state) {
     return;
   }
 }
-function loadDocuments(input, options) {
-  input = String(input);
+function loadDocuments(input2, options) {
+  input2 = String(input2);
   options = options || {};
-  if (input.length !== 0) {
-    if (input.charCodeAt(input.length - 1) !== 10 && input.charCodeAt(input.length - 1) !== 13) {
-      input += "\n";
+  if (input2.length !== 0) {
+    if (input2.charCodeAt(input2.length - 1) !== 10 && input2.charCodeAt(input2.length - 1) !== 13) {
+      input2 += "\n";
     }
-    if (input.charCodeAt(0) === 65279) {
-      input = input.slice(1);
+    if (input2.charCodeAt(0) === 65279) {
+      input2 = input2.slice(1);
     }
   }
-  var state = new State$1(input, options);
-  var nullpos = input.indexOf("\0");
+  var state = new State$1(input2, options);
+  var nullpos = input2.indexOf("\0");
   if (nullpos !== -1) {
     state.position = nullpos;
     throwError(state, "null byte is not allowed in input");
@@ -6272,12 +6272,12 @@ function loadDocuments(input, options) {
   }
   return state.documents;
 }
-function loadAll$1(input, iterator, options) {
+function loadAll$1(input2, iterator, options) {
   if (iterator !== null && typeof iterator === "object" && typeof options === "undefined") {
     options = iterator;
     iterator = null;
   }
-  var documents = loadDocuments(input, options);
+  var documents = loadDocuments(input2, options);
   if (typeof iterator !== "function") {
     return documents;
   }
@@ -6285,8 +6285,8 @@ function loadAll$1(input, iterator, options) {
     iterator(documents[index]);
   }
 }
-function load$1(input, options) {
-  var documents = loadDocuments(input, options);
+function load$1(input2, options) {
+  var documents = loadDocuments(input2, options);
   if (documents.length === 0) {
     return void 0;
   } else if (documents.length === 1) {
@@ -6907,11 +6907,11 @@ function inspectNode(object, objects, duplicatesIndexes) {
     }
   }
 }
-function dump$1(input, options) {
+function dump$1(input2, options) {
   options = options || {};
   var state = new State(options);
-  if (!state.noRefs) getDuplicateReferences(input, state);
-  var value = input;
+  if (!state.noRefs) getDuplicateReferences(input2, state);
+  var value = input2;
   if (state.replacer) {
     value = state.replacer.call({ "": value }, "", value);
   }
@@ -7033,19 +7033,34 @@ function readStringArray(object, key) {
 }
 
 // src/memory.ts
+function parseMemoryKind(value) {
+  if (["durable", "handoff", "incident", "preference", "smoke"].includes(value)) {
+    return value;
+  }
+  throw new Error(`Unsupported memory kind "${value}". Expected durable, handoff, incident, preference, or smoke.`);
+}
+function parseMemoryStatus(value) {
+  if (["active", "archived", "superseded"].includes(value)) {
+    return value;
+  }
+  throw new Error(`Unsupported memory status "${value}". Expected active, archived, or superseded.`);
+}
 async function runRemember(config, options) {
   const text = await getInputText(options.text, options.stdin === true);
   if (!text.trim()) {
     throw new Error("Provide memory text with --text or --stdin.");
   }
-  const memory = [
-    "MEMORY",
-    `source_agent_client: ${options.sourceAgentClient ?? "codex"}`,
-    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`,
-    "",
-    text.trim()
-  ].join("\n");
-  await storeMemory(config, memory, options.dryRun === true);
+  const metadata = {
+    kind: options.kind ?? "durable",
+    project: normalizeOptionalMetadata(options.project),
+    sourceAgentClient: options.sourceAgentClient ?? "codex",
+    status: options.status ?? "active",
+    supersedes: options.replace,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    topic: normalizeOptionalMetadata(options.topic)
+  };
+  const memory = formatMemoryDocument("MEMORY", metadata, text.trim());
+  await storeMemory(config, memory, { dryRun: options.dryRun === true, metadata, replaceUri: options.replace });
 }
 async function runMigrateMemories(config, options) {
   const dryRun = options.dryRun === true;
@@ -7096,7 +7111,7 @@ async function runMigrateMemories(config, options) {
       if (!dryRun) {
         await (0, import_promises4.writeFile)(migrationPath, candidate.text, { encoding: "utf8", mode: 384 });
         await (0, import_promises4.chmod)(migrationPath, 384);
-        await writeDurableMemoryFile(ov, config, memoryUri, migrationPath);
+        await writeDurableMemoryFile(ov, config, memoryUri, migrationPath, "create");
         existingHashes.add(candidate.hash);
       }
       migratedCount += 1;
@@ -7116,6 +7131,62 @@ async function runMigrateMemories(config, options) {
     ].join("; ")
   );
 }
+async function runMigrateLifecycle(config, options) {
+  const dryRun = options.dryRun === true || options.apply !== true;
+  const limit = options.limit ? parsePositiveInteger(options.limit, "lifecycle migration limit") : void 0;
+  const ov = await openVikingCliForMode(dryRun);
+  const candidates = await legacyLifecycleHandoffCandidates(config);
+  const migrationPath = (0, import_node_path4.join)(config.agentContextHome, "lifecycle-memory-migration.txt");
+  let existingCount = 0;
+  let migratedCount = 0;
+  let skippedCount = 0;
+  try {
+    for (const candidate of candidates) {
+      if (limit !== void 0 && migratedCount >= limit) {
+        break;
+      }
+      const destinationUri = lifecycleMigrationUri(config, candidate.metadata, sha256(candidate.original.trim()));
+      const migratedMemory = formatMemoryDocument(
+        "HANDOFF",
+        candidate.metadata,
+        ["Migrated legacy handoff from the historical events trail.", "", candidate.original.trim()].join("\n")
+      );
+      console.log(`${dryRun ? "Would migrate" : "Migrating"} ${candidate.sourceUri} -> ${destinationUri}`);
+      if (!dryRun) {
+        if (await vikingResourceExists(ov, config, destinationUri)) {
+          existingCount += 1;
+          console.log(`Archived copy already exists; cleaning up legacy source: ${candidate.sourceUri}`);
+        } else {
+          await (0, import_promises4.writeFile)(migrationPath, migratedMemory, { encoding: "utf8", mode: 384 });
+          await (0, import_promises4.chmod)(migrationPath, 384);
+          await ensureMemoryDirectory(ov, config, memoryDirectoryUri(config, candidate.metadata));
+          await writeDurableMemoryFile(ov, config, destinationUri, migrationPath, "create");
+        }
+        const removedOriginal = await removeVikingResourceWithRetry(ov, config, candidate.sourceUri);
+        if (!removedOriginal) {
+          console.error(
+            `Migrated copy stored, but original is still processing. Retry later: threadnote forget ${candidate.sourceUri}`
+          );
+          skippedCount += 1;
+        }
+      }
+      migratedCount += 1;
+    }
+  } finally {
+    if (!dryRun) {
+      await (0, import_promises4.rm)(migrationPath, { force: true });
+    }
+  }
+  console.log(
+    [
+      `Lifecycle migration summary: ${migratedCount} clear legacy handoff(s) ${dryRun ? "would be migrated" : "migrated"}`,
+      `${existingCount} existing archived copy/copies reused`,
+      `${skippedCount} legacy source(s) still processing`,
+      `${candidates.length} clear legacy handoff candidate(s) found`,
+      dryRun ? "Run with --apply to perform this migration." : void 0
+    ].filter((part) => part !== void 0).join("; ")
+  );
+}
 async function runRecall(config, options) {
   const ov = await openVikingCliForMode(options.dryRun === true);
   const inferredUri = options.uri ?? (options.inferScope === false ? void 0 : await inferRecallUri(config, options.query));
@@ -7128,7 +7199,10 @@ async function runRecall(config, options) {
     args.push("--node-limit", String(parsePositiveInteger(options.nodeLimit, "node limit")));
   }
   await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
-  await printExactMemoryMatches(config, ov, options.query, options.dryRun === true);
+  await printExactMemoryMatches(config, ov, options.query, {
+    dryRun: options.dryRun === true,
+    includeArchived: options.includeArchived === true
+  });
 }
 async function runRead(config, uri, options) {
   assertVikingUri(uri);
@@ -7159,13 +7233,70 @@ async function runList(config, uri, options) {
   await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
 }
 async function runHandoff(config, options) {
-  const handoff = await buildHandoff(options);
-  await storeMemory(config, handoff, options.dryRun === true);
+  const { handoff, metadata } = await buildHandoff(options);
+  await storeMemory(config, handoff, { dryRun: options.dryRun === true, metadata, replaceUri: options.replace });
+}
+async function runArchive(config, uri, options) {
+  assertVikingUri(uri);
+  const ov = await openVikingCliForMode(options.dryRun === true);
+  const readResult = await maybeRun(options.dryRun === true, ov, withIdentity(config, ["read", uri]));
+  const original = readResult?.stdout.trim();
+  if (options.dryRun === true) {
+    const fallbackMetadata = {
+      archivedFrom: uri,
+      kind: options.kind ?? "handoff",
+      project: normalizeOptionalMetadata(options.project),
+      sourceAgentClient: "threadnote",
+      status: "archived",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      topic: normalizeOptionalMetadata(options.topic)
+    };
+    const archiveMemory2 = formatMemoryDocument(
+      "MEMORY",
+      fallbackMetadata,
+      ["Archived original Threadnote memory.", "", "<original memory content would be read here>"].join("\n")
+    );
+    await storeMemory(config, archiveMemory2, { dryRun: true, metadata: fallbackMetadata });
+    console.log(formatShellCommand(ov, withIdentity(config, ["rm", uri])));
+    return;
+  }
+  if (!original) {
+    throw new Error(`Could not read ${uri} before archiving.`);
+  }
+  const inferredMetadata = inferMemoryMetadata(original);
+  const metadata = {
+    archivedFrom: uri,
+    kind: options.kind ?? inferredMetadata.kind ?? "handoff",
+    project: normalizeOptionalMetadata(options.project) ?? inferredMetadata.project,
+    sourceAgentClient: "threadnote",
+    status: "archived",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    topic: normalizeOptionalMetadata(options.topic) ?? inferredMetadata.topic
+  };
+  const archiveMemory = formatMemoryDocument(
+    "MEMORY",
+    metadata,
+    ["Archived original Threadnote memory.", "", original].join("\n")
+  );
+  await storeMemory(config, archiveMemory, { dryRun: false, metadata });
+  const removedOriginal = await removeVikingResourceWithRetry(ov, config, uri);
+  if (removedOriginal) {
+    console.log(`Archived original memory: ${uri}`);
+  } else {
+    console.error(`Archive stored, but original memory is still processing. Retry later: threadnote forget ${uri}`);
+  }
 }
 async function runForget(config, uri, options) {
   assertVikingUri(uri);
   const ov = await openVikingCliForMode(options.dryRun === true);
-  await maybeRun(options.dryRun === true, ov, withIdentity(config, ["rm", uri]));
+  if (options.dryRun === true) {
+    await maybeRun(true, ov, withIdentity(config, ["rm", uri]));
+    return;
+  }
+  const removed = await removeVikingResourceWithRetry(ov, config, uri);
+  if (!removed) {
+    throw new Error(`Resource is still being processed; retry later: threadnote forget ${uri}`);
+  }
 }
 async function runExportPack(config, options) {
   const ov = await openVikingCliForMode(options.dryRun === true);
@@ -7201,27 +7332,24 @@ async function inferProjectFromQuery(config, normalizedQuery) {
     return void 0;
   }
 }
-async function printExactMemoryMatches(config, ov, query, dryRun) {
+async function printExactMemoryMatches(config, ov, query, options) {
   const terms = exactRecallTerms(query);
   if (terms.length === 0) {
     return;
   }
-  const scopes = [
-    `viking://user/${uriSegment(config.user)}/memories`,
-    `viking://agent/${uriSegment(config.agentId)}/memories`
-  ];
+  const scopes = exactMemoryScopes(config, options.includeArchived);
   const outputs = [];
   for (const term of terms) {
     for (const scope of scopes) {
       const args = withIdentity(config, ["grep", term, "--uri", scope, "--node-limit", "5"]);
-      if (dryRun) {
+      if (options.dryRun) {
         outputs.push(formatShellCommand(ov, args));
         continue;
       }
       const result = await runCommand(ov, args, { allowFailure: true });
-      const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
-      if (result.exitCode === 0 && grepOutputHasMatches(output)) {
-        outputs.push(output);
+      const output2 = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+      if (result.exitCode === 0 && grepOutputHasMatches(output2)) {
+        outputs.push(output2);
       }
     }
   }
@@ -7231,11 +7359,15 @@ async function printExactMemoryMatches(config, ov, query, dryRun) {
   console.log("\nExact durable memory matches:");
   console.log(outputs.join("\n\n"));
 }
-async function storeMemory(config, memory, dryRun) {
-  const ov = await openVikingCliForMode(dryRun);
+async function storeMemory(config, memory, options) {
+  if (options.replaceUri) {
+    assertVikingUri(options.replaceUri);
+  }
+  const ov = await openVikingCliForMode(options.dryRun);
   const memoryPath = (0, import_node_path4.join)(config.agentContextHome, "last-memory.txt");
-  const memoryUri = durableMemoryUri(config, memory);
-  if (dryRun) {
+  const memoryUri = memoryUriFor(config, memory, options.metadata);
+  const writeMode = await memoryWriteMode(ov, config, memoryUri, options.metadata);
+  if (options.dryRun) {
     console.log(memory);
     console.log("\nWould run:");
     console.log(
@@ -7247,29 +7379,44 @@ async function storeMemory(config, memory, dryRun) {
           "--from-file",
           memoryPath,
           "--mode",
-          "create",
+          writeMode,
           "--wait",
           "--timeout",
           "120"
         ])
       )
     );
+    if (options.replaceUri && options.replaceUri !== memoryUri) {
+      console.log(formatShellCommand(ov, withIdentity(config, ["rm", options.replaceUri])));
+    }
     return;
   }
   await (0, import_promises4.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
   await (0, import_promises4.chmod)(memoryPath, 384);
-  await ensureDurableMemoryDirectory(ov, config);
-  await writeDurableMemoryFile(ov, config, memoryUri, memoryPath);
-  console.log(`Stored durable memory: ${memoryUri}`);
+  await ensureMemoryDirectory(ov, config, memoryDirectoryUri(config, options.metadata));
+  await writeDurableMemoryFile(ov, config, memoryUri, memoryPath, writeMode);
+  console.log(`Stored memory: ${memoryUri}`);
+  if (options.replaceUri && options.replaceUri !== memoryUri) {
+    const removedReplacedMemory = await removeVikingResourceWithRetry(ov, config, options.replaceUri);
+    if (removedReplacedMemory) {
+      console.log(`Forgot replaced memory: ${options.replaceUri}`);
+    } else {
+      console.error(
+        `Replacement stored, but the superseded memory is still processing. Retry later: threadnote forget ${options.replaceUri}`
+      );
+    }
+  } else if (options.replaceUri === memoryUri) {
+    console.log(`Updated existing memory in place: ${memoryUri}`);
+  }
 }
-async function writeDurableMemoryFile(ov, config, memoryUri, memoryPath) {
+async function writeDurableMemoryFile(ov, config, memoryUri, memoryPath, writeMode) {
   const args = withIdentity(config, [
     "write",
     memoryUri,
     "--from-file",
     memoryPath,
     "--mode",
-    "create",
+    writeMode,
     "--wait",
     "--timeout",
     "120"
@@ -7306,29 +7453,49 @@ async function waitForOpenVikingQueue(ov, config) {
     console.error(result.stderr.trim());
   }
 }
+async function removeVikingResourceWithRetry(ov, config, uri) {
+  const args = withIdentity(config, ["rm", uri]);
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    console.log(`${attempt === 0 ? "Running" : "Retrying"}: ${formatShellCommand(ov, args)}`);
+    const result = await runCommand(ov, args, { allowFailure: true });
+    if (result.exitCode === 0) {
+      if (result.stdout.trim()) {
+        console.log(result.stdout.trim());
+      }
+      if (result.stderr.trim()) {
+        console.error(result.stderr.trim());
+      }
+      return true;
+    }
+    if (isResourceBusy(result.stderr, result.stdout) && attempt === 3) {
+      return false;
+    }
+    if (!isResourceBusy(result.stderr, result.stdout)) {
+      throw new Error(`${formatShellCommand(ov, args)} failed: ${result.stderr || result.stdout}`);
+    }
+    await sleep(1e3 * (attempt + 1));
+  }
+  return false;
+}
 async function vikingResourceExists(ov, config, uri) {
   const stat3 = await runCommand(ov, withIdentity(config, ["stat", uri]), { allowFailure: true });
   return stat3.exitCode === 0;
 }
 async function ensureDurableMemoryDirectory(ov, config) {
-  const directoryUri = durableMemoryDirectoryUri(config);
-  const stat3 = await runCommand(ov, withIdentity(config, ["stat", directoryUri]), { allowFailure: true });
-  if (stat3.exitCode === 0) {
-    return;
-  }
-  await maybeRun(
-    false,
-    ov,
-    withIdentity(config, [
-      "mkdir",
-      directoryUri,
-      "--description",
-      "Threadnote durable handoffs, memories, and cross-agent notes."
-    ])
-  );
+  await ensureMemoryDirectory(ov, config, durableMemoryDirectoryUri(config));
 }
-function durableMemoryUri(config, memory) {
-  return `${durableMemoryDirectoryUri(config)}/threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+async function ensureMemoryDirectory(ov, config, directoryUri) {
+  for (const uri of vikingDirectoryChain(directoryUri)) {
+    const statResult = await runCommand(ov, withIdentity(config, ["stat", uri]), { allowFailure: true });
+    if (statResult.exitCode === 0) {
+      continue;
+    }
+    await maybeRun(
+      false,
+      ov,
+      withIdentity(config, ["mkdir", uri, "--description", "Threadnote lifecycle-aware local memories."])
+    );
+  }
 }
 function durableMemoryDirectoryUri(config) {
   return `viking://user/${uriSegment(config.user)}/memories/events`;
@@ -7336,6 +7503,185 @@ function durableMemoryDirectoryUri(config) {
 function migratedDurableMemoryUri(config, hash) {
   return `${durableMemoryDirectoryUri(config)}/threadnote-migrated-${hash.slice(0, 16)}.md`;
 }
+async function hasLegacyLifecycleHandoffCandidates(config) {
+  return (await legacyLifecycleHandoffCandidates(config, 1)).length > 0;
+}
+async function legacyLifecycleHandoffCandidates(config, limit) {
+  const eventsRoot = (0, import_node_path4.join)(localUserMemoriesRoot(config), "events");
+  let entries;
+  try {
+    entries = await (0, import_promises4.readdir)(eventsRoot, { withFileTypes: true });
+  } catch (_err) {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.name.startsWith(".") || !entry.name.endsWith(".md")) {
+      continue;
+    }
+    const sourcePath = (0, import_node_path4.join)(eventsRoot, entry.name);
+    const original = await readTextIfExists(sourcePath);
+    if (!original || !isClearLegacyHandoffMemory(original) || sensitiveMemoryReason(original)) {
+      continue;
+    }
+    const sourceUri = `${durableMemoryDirectoryUri(config)}/${entry.name}`;
+    candidates.push({
+      metadata: {
+        archivedFrom: sourceUri,
+        kind: "handoff",
+        project: inferLegacyProject(original),
+        sourceAgentClient: "threadnote",
+        status: "archived",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      original,
+      sourceUri
+    });
+    if (limit !== void 0 && candidates.length >= limit) {
+      break;
+    }
+  }
+  return candidates;
+}
+function lifecycleMigrationUri(config, metadata, hash) {
+  return `${memoryDirectoryUri(config, metadata)}/legacy-${hash.slice(0, 16)}.md`;
+}
+function exactMemoryScopes(config, includeArchived) {
+  const userBase = `viking://user/${uriSegment(config.user)}/memories`;
+  const scopes = [
+    `${userBase}/preferences`,
+    `${userBase}/durable/projects`,
+    `${userBase}/handoffs/active`,
+    `${userBase}/incidents/active`,
+    `${userBase}/events`,
+    `viking://agent/${uriSegment(config.agentId)}/memories`
+  ];
+  return includeArchived ? [...scopes, `${userBase}/durable/archived`, `${userBase}/handoffs/archived`, `${userBase}/incidents/archived`] : scopes;
+}
+function memoryUriFor(config, memory, metadata) {
+  const filename = shouldUseStableMemoryUri(metadata) ? `${uriSegment(metadata.topic ?? "current")}.md` : `threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+  return `${memoryDirectoryUri(config, metadata)}/${filename}`;
+}
+function memoryDirectoryUri(config, metadata) {
+  const baseUri = `viking://user/${uriSegment(config.user)}/memories`;
+  const projectSegment = uriSegment(metadata.project ?? "general");
+  switch (metadata.kind) {
+    case "preference":
+      return metadata.status === "active" ? `${baseUri}/preferences` : `${baseUri}/preferences/${uriSegment(metadata.status)}`;
+    case "handoff":
+      return `${baseUri}/handoffs/${uriSegment(metadata.status)}/${projectSegment}`;
+    case "incident":
+      return `${baseUri}/incidents/${uriSegment(metadata.status)}/${projectSegment}`;
+    case "smoke":
+      return `${baseUri}/smoke/${uriSegment(metadata.status)}`;
+    case "durable":
+      return metadata.status === "active" ? `${baseUri}/durable/projects/${projectSegment}` : `${baseUri}/durable/${uriSegment(metadata.status)}/${projectSegment}`;
+  }
+}
+function shouldUseStableMemoryUri(metadata) {
+  return metadata.status === "active" && metadata.topic !== void 0 && metadata.kind !== "smoke";
+}
+async function memoryWriteMode(ov, config, memoryUri, metadata) {
+  if (!shouldUseStableMemoryUri(metadata)) {
+    return "create";
+  }
+  return await vikingResourceExists(ov, config, memoryUri) ? "replace" : "create";
+}
+function vikingDirectoryChain(directoryUri) {
+  const prefix = "viking://";
+  if (!directoryUri.startsWith(prefix)) {
+    return [directoryUri];
+  }
+  const parts = directoryUri.slice(prefix.length).split("/").filter(Boolean);
+  const startIndex = parts[0] === "user" && parts.length > 2 ? 3 : 1;
+  const chain = [];
+  for (let index = startIndex; index <= parts.length; index += 1) {
+    chain.push(`${prefix}${parts.slice(0, index).join("/")}`);
+  }
+  return chain;
+}
+function formatMemoryDocument(title, metadata, body) {
+  const header = [
+    title,
+    `kind: ${metadata.kind}`,
+    `status: ${metadata.status}`,
+    metadata.project ? `project: ${metadata.project}` : void 0,
+    metadata.topic ? `topic: ${metadata.topic}` : void 0,
+    `source_agent_client: ${metadata.sourceAgentClient}`,
+    `timestamp: ${metadata.timestamp}`,
+    metadata.supersedes ? `supersedes: ${metadata.supersedes}` : void 0,
+    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0
+  ].filter((line) => line !== void 0);
+  return [...header, "", body.trim()].join("\n");
+}
+function inferMemoryMetadata(memory) {
+  const header = memory.slice(0, Math.max(0, memory.indexOf("\n\n")) || memory.length);
+  const firstLine2 = header.split("\n")[0]?.trim();
+  const kind = parseOptionalMemoryKind(parseHeaderValue(header, "kind")) ?? (firstLine2 === "HANDOFF" ? "handoff" : void 0);
+  const status = parseOptionalMemoryStatus(parseHeaderValue(header, "status"));
+  const project = normalizeOptionalMetadata(parseHeaderValue(header, "project")) ?? normalizeOptionalMetadata(parseHeaderValue(header, "repo"));
+  const topic = normalizeOptionalMetadata(parseHeaderValue(header, "topic")) ?? normalizeOptionalMetadata(parseHeaderValue(header, "task"));
+  return {
+    kind,
+    project,
+    sourceAgentClient: parseHeaderValue(header, "source_agent_client") ?? void 0,
+    status,
+    topic
+  };
+}
+function parseHeaderValue(header, key) {
+  const prefix = `${key}:`;
+  return header.split("\n").find((line) => line.startsWith(prefix))?.slice(prefix.length).trim();
+}
+function isClearLegacyHandoffMemory(memory) {
+  if (/^kind:\s*/m.test(memory) || /^status:\s*/m.test(memory)) {
+    return false;
+  }
+  const trimmed = memory.trim();
+  if (trimmed.startsWith("HANDOFF\n")) {
+    return true;
+  }
+  if (!trimmed.startsWith("MEMORY\n")) {
+    return false;
+  }
+  return /^(?:#+\s*)?(?:final\s+)?handoff(?:\s+update)?\b/i.test(memoryBody(trimmed));
+}
+function memoryBody(memory) {
+  const separatorIndex = memory.indexOf("\n\n");
+  return separatorIndex === -1 ? "" : memory.slice(separatorIndex + 2).trim();
+}
+function inferLegacyProject(memory) {
+  const explicit = parseHeaderValue(memory, "project") ?? parseHeaderValue(memory, "repo") ?? parseHeaderValue(memory, "repo_path") ?? /\brepo(?:_path)?\s+([~/A-Za-z0-9_.:/-]+)/.exec(memory)?.[1];
+  if (!explicit) {
+    return "general";
+  }
+  const trimmed = explicit.trim().replace(/[`.,;]+$/g, "");
+  return trimmed.includes("/") ? (0, import_node_path4.basename)(trimmed) : trimmed;
+}
+function parseOptionalMemoryKind(value) {
+  if (!value) {
+    return void 0;
+  }
+  try {
+    return parseMemoryKind(value);
+  } catch (_err) {
+    return void 0;
+  }
+}
+function parseOptionalMemoryStatus(value) {
+  if (!value) {
+    return void 0;
+  }
+  try {
+    return parseMemoryStatus(value);
+  } catch (_err) {
+    return void 0;
+  }
+}
+function normalizeOptionalMetadata(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
 async function legacySourceAccounts(config, options) {
   const explicitAccounts = options.sourceAccount?.filter((account) => account.trim().length > 0) ?? [];
   if (explicitAccounts.length > 0) {
@@ -7488,12 +7834,16 @@ function legacySourceLabel(candidate) {
 function localVikingDataRoot(config) {
   return (0, import_node_path4.join)(config.agentContextHome, "data", "viking");
 }
+function localUserMemoriesRoot(config) {
+  return (0, import_node_path4.join)(localVikingDataRoot(config), config.account, "user", uriSegment(config.user), "memories");
+}
 function uniqueStrings(values) {
   return [...new Set(values)].sort();
 }
 function isResourceBusy(stderr, stdout) {
-  return `${stderr}
-${stdout}`.includes("resource is busy");
+  const output2 = `${stderr}
+${stdout}`.toLowerCase();
+  return output2.includes("resource is busy") || output2.includes("resource is being processed");
 }
 async function buildHandoff(options) {
   const repoRoot = await gitValue(["rev-parse", "--show-toplevel"]) ?? getInvocationCwd();
@@ -7501,13 +7851,20 @@ async function buildHandoff(options) {
   const status = await gitValue(["status", "--short"], repoRoot) ?? "";
   const diffStat = await gitValue(["diff", "--stat", "HEAD"], repoRoot) ?? "";
   const touchedFiles = await gitTouchedFiles(repoRoot);
-  return [
-    "HANDOFF",
-    `repo: ${(0, import_node_path4.basename)(repoRoot)}`,
+  const repoName = (0, import_node_path4.basename)(repoRoot);
+  const metadata = {
+    kind: "handoff",
+    project: normalizeOptionalMetadata(options.project) ?? repoName,
+    sourceAgentClient: options.sourceAgentClient ?? "codex",
+    status: "active",
+    supersedes: options.replace,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    topic: normalizeOptionalMetadata(options.topic)
+  };
+  const body = [
+    `repo: ${repoName}`,
     `repo_path: ${repoRoot}`,
     `branch: ${branch || "unknown"}`,
-    `source_agent_client: ${options.sourceAgentClient ?? "codex"}`,
-    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     `task: ${options.task ?? "unspecified"}`,
     "",
     "files_touched:",
@@ -7528,6 +7885,7 @@ async function buildHandoff(options) {
     "next_step:",
     options.nextStep ?? "- inspect the current repo state and continue from this handoff"
   ].join("\n");
+  return { handoff: formatMemoryDocument("HANDOFF", metadata, body), metadata };
 }
 async function gitTouchedFiles(cwd) {
   const changedFiles = await gitValue(["diff", "--name-only", "HEAD"], cwd);
@@ -7619,14 +7977,14 @@ async function runInitManifest(config, options) {
       uri: existingManifest.futureMonorepo.uri
     };
   }
-  const output = jsYaml.dump(outputManifest, { lineWidth: 120, noRefs: true });
+  const output2 = jsYaml.dump(outputManifest, { lineWidth: 120, noRefs: true });
   if (options.dryRun === true) {
     console.log(`# Would write ${manifestPath}`);
-    console.log(output.trimEnd());
+    console.log(output2.trimEnd());
     return;
   }
   await ensureDirectory((0, import_node_path5.dirname)(manifestPath), false);
-  await (0, import_promises5.writeFile)(manifestPath, output, { encoding: "utf8", mode: 384 });
+  await (0, import_promises5.writeFile)(manifestPath, output2, { encoding: "utf8", mode: 384 });
   await (0, import_promises5.chmod)(manifestPath, 384);
   console.log(`Wrote manifest: ${manifestPath}`);
   console.log("Seed with:");
@@ -7837,11 +8195,11 @@ function redactJsonValue(value) {
   if (!isJsonObject(value)) {
     return value;
   }
-  const output = {};
+  const output2 = {};
   for (const [key, nestedValue] of Object.entries(value)) {
-    output[key] = isSensitiveKey(key) ? "[REDACTED]" : redactJsonValue(nestedValue);
+    output2[key] = isSensitiveKey(key) ? "[REDACTED]" : redactJsonValue(nestedValue);
   }
-  return output;
+  return output2;
 }
 function isSensitiveKey(key) {
   return /token|secret|password|credential|authorization|api[_-]?key|client[_-]?secret|bearer/i.test(key);
@@ -7865,15 +8223,476 @@ function detectSecretMatches(content) {
 }
 
 // src/lifecycle.ts
-var import_node_child_process2 = require("node:child_process");
-var import_node_fs3 = require("node:fs");
-var import_promises6 = require("node:fs/promises");
-var import_node_os4 = require("node:os");
-var import_node_path6 = require("node:path");
+var import_node_child_process2 = require("node:child_process");
+var import_node_fs4 = require("node:fs");
+var import_promises8 = require("node:fs/promises");
+var import_node_os5 = require("node:os");
+var import_node_path7 = require("node:path");
+
+// src/update.ts
+var import_node_fs3 = require("node:fs");
+var import_promises6 = require("node:fs/promises");
+var import_node_os4 = require("node:os");
+var import_node_path6 = require("node:path");
+var import_promises7 = require("node:readline/promises");
+var import_node_process = require("node:process");
+var NPM_PACKAGE_NAME = "threadnote";
+var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+var UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
+var POST_UPDATE_MIGRATIONS_FILE = "post-update-migrations.json";
+var POST_UPDATE_STATE_FILE = "post-update-state.json";
+function parseUpdateRuntime(value) {
+  if (value === "auto" || value === "npm" || value === "bun" || value === "deno") {
+    return value;
+  }
+  throw new Error(`Invalid update runtime: ${value}. Expected auto, npm, bun, or deno.`);
+}
+async function maybeNotifyUpdate(config, options = {}) {
+  if (isUpdateNotificationDisabled()) {
+    return;
+  }
+  try {
+    const info = await getUpdateInfo(config, {
+      allowCacheWrite: options.dryRun !== true,
+      preferFresh: false,
+      registry: updateRegistry()
+    });
+    if (!info.isUpdateAvailable) {
+      return;
+    }
+    console.log("");
+    console.log(`Update available: threadnote ${info.currentVersion} -> ${info.latestVersion}`);
+    console.log("Run: threadnote update");
+  } catch (_err) {
+    return;
+  }
+}
+async function runUpdate(config, options) {
+  const registry = normalizeRegistry(options.registry ?? updateRegistry());
+  const info = await getUpdateInfo(config, {
+    allowCacheWrite: options.dryRun !== true,
+    preferFresh: true,
+    registry
+  });
+  console.log(`Current version: ${info.currentVersion}`);
+  console.log(`Latest version:  ${info.latestVersion}`);
+  console.log(`Registry:        ${info.registry}`);
+  if (options.check === true) {
+    if (info.isUpdateAvailable) {
+      console.log(`Update available. Run: threadnote update`);
+    } else {
+      console.log(
+        compareVersions(info.currentVersion, info.latestVersion) > 0 ? "Current version is newer than npm latest." : "Threadnote is up to date."
+      );
+    }
+    return;
+  }
+  if (!info.isUpdateAvailable && options.force !== true) {
+    console.log("Threadnote is up to date.");
+    return;
+  }
+  const runtime = await resolveUpdateRuntime(options.runtime ?? "auto");
+  const updateCommand = updatePackageCommand(runtime, registry);
+  await maybeRun(options.dryRun === true, updateCommand.executable, updateCommand.args);
+  if (options.repair === false) {
+    console.log("Skipping repair because --no-repair was provided.");
+    return;
+  }
+  const threadnoteCommand = await installedThreadnoteCommand(runtime);
+  await maybeRun(options.dryRun === true, threadnoteCommand, ["repair", "--no-post-update"]);
+  if (options.postUpdate !== false) {
+    const postUpdateArgs = [
+      "post-update",
+      "--from-version",
+      info.currentVersion,
+      "--to-version",
+      info.latestVersion,
+      ...options.yes === true ? ["--yes"] : []
+    ];
+    if (options.dryRun === true) {
+      await maybeRun(true, threadnoteCommand, postUpdateArgs);
+    } else {
+      console.log(`Running: ${formatShellCommand(threadnoteCommand, postUpdateArgs)}`);
+      const postUpdateExitCode = await runInteractive(threadnoteCommand, postUpdateArgs);
+      if (postUpdateExitCode !== 0) {
+        throw new Error(`${formatShellCommand(threadnoteCommand, postUpdateArgs)} exited with ${postUpdateExitCode}.`);
+      }
+    }
+  } else {
+    console.log("Skipping post-update migration prompts because --no-post-update was provided.");
+  }
+  console.log("Update complete. Restart Cursor, Codex, Claude, or open a fresh agent session so MCP tools reload.");
+}
+async function runPostUpdate(config, options) {
+  if (!options.fromVersion || !options.toVersion) {
+    throw new Error("Provide --from-version and --to-version for post-update.");
+  }
+  await runApplicablePostUpdateMigrations(config, {
+    dryRun: options.dryRun === true,
+    fromVersion: options.fromVersion,
+    interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    markHandled: true,
+    toVersion: options.toVersion,
+    yes: options.yes === true
+  });
+}
+async function maybeRunPostUpdateAfterRepair(config, options) {
+  const toVersion = await currentPackageVersion();
+  const state = await readPostUpdateState(config);
+  const migrations = await applicablePostUpdateMigrations(config, {
+    fromVersion: "0.0.0",
+    handledMigrationIds: state.handledMigrationIds,
+    toVersion
+  });
+  if (migrations.length === 0) {
+    return;
+  }
+  console.log("");
+  console.log("Repair found package post-update migrations.");
+  console.log("This also covers updates launched by older Threadnote versions that only knew how to run repair.");
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+    console.log(
+      "This process is non-interactive, so Threadnote will print the manual migration command instead of prompting."
+    );
+    console.log(`Run the prompt manually with: threadnote post-update --from-version 0.0.0 --to-version ${toVersion}`);
+  }
+  await runApplicablePostUpdateMigrations(config, {
+    dryRun: options.dryRun,
+    fromVersion: "0.0.0",
+    interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    markHandled: true,
+    toVersion,
+    yes: false
+  });
+}
+async function getUpdateInfo(config, options) {
+  const currentVersion = await currentPackageVersion();
+  const cached = options.preferFresh ? void 0 : await readFreshCache(config, options.registry);
+  const latestVersion = cached?.latestVersion ?? await fetchLatestVersion(options.registry);
+  if (!cached && options.allowCacheWrite) {
+    await writeUpdateCache(config, { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latestVersion, registry: options.registry });
+  }
+  return {
+    currentVersion,
+    isUpdateAvailable: compareVersions(currentVersion, latestVersion) < 0,
+    latestVersion,
+    registry: options.registry
+  };
+}
+async function currentPackageVersion() {
+  const rawPackage = await (0, import_promises6.readFile)((0, import_node_path6.join)(toolRoot(), "package.json"), "utf8");
+  const parsed = JSON.parse(rawPackage);
+  if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
+    throw new Error("Could not read current threadnote package version.");
+  }
+  return parsed.version;
+}
+async function fetchLatestVersion(registry) {
+  const url = new URL(`${NPM_PACKAGE_NAME}/latest`, normalizeRegistry(registry));
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, 2500);
+  try {
+    const response = await fetch(url, { headers: { accept: "application/json" }, signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`npm registry returned HTTP ${response.status}`);
+    }
+    const parsed = await response.json();
+    if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
+      throw new Error("npm registry response did not include a version.");
+    }
+    return parsed.version;
+  } catch (err) {
+    throw new Error(`Could not check npm for updates: ${errorMessage(err)}`, { cause: err });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function readFreshCache(config, registry) {
+  const rawCache = await readFileIfExists(updateCachePath(config));
+  if (!rawCache) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(rawCache);
+    if (!isJsonObject(parsed) || typeof parsed.checkedAt !== "string" || typeof parsed.latestVersion !== "string" || parsed.registry !== registry) {
+      return void 0;
+    }
+    const checkedAt = Date.parse(parsed.checkedAt);
+    if (!Number.isFinite(checkedAt) || Date.now() - checkedAt > UPDATE_CHECK_TTL_MS) {
+      return void 0;
+    }
+    return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion, registry };
+  } catch (_err) {
+    return void 0;
+  }
+}
+async function writeUpdateCache(config, cache) {
+  await ensureDirectory(config.agentContextHome, false);
+  await (0, import_promises6.writeFile)(updateCachePath(config), `${JSON.stringify(cache, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+}
+function updateCachePath(config) {
+  return (0, import_node_path6.join)(config.agentContextHome, "update-check.json");
+}
+async function runApplicablePostUpdateMigrations(config, options) {
+  const state = await readPostUpdateState(config);
+  const migrations = await applicablePostUpdateMigrations(config, {
+    fromVersion: options.fromVersion,
+    handledMigrationIds: state.handledMigrationIds,
+    toVersion: options.toVersion
+  });
+  if (migrations.length === 0) {
+    console.log("No post-update memory migrations apply.");
+    return;
+  }
+  console.log("");
+  console.log("Post-update memory migrations are available.");
+  const threadnoteCommand = currentThreadnoteCommand() ?? await findExecutable([NPM_PACKAGE_NAME]) ?? NPM_PACKAGE_NAME;
+  const handledMigrationIds = new Set(state.handledMigrationIds);
+  for (const migration of migrations) {
+    printPostUpdateMigration(migration);
+    const accepted = options.dryRun || options.yes || options.interactive && await confirmPostUpdateMigration("Apply this migration now? [y/N] ");
+    if (!accepted) {
+      console.log("Skipped. Run manually later:");
+      console.log(`  ${formatMigrationCommand(threadnoteCommand, migration.commandArgs)}`);
+      continue;
+    }
+    await maybeRun(options.dryRun, threadnoteCommand, migration.commandArgs);
+    if (!options.dryRun) {
+      handledMigrationIds.add(migration.id);
+      for (const instruction of migration.instructions) {
+        console.log(instruction);
+      }
+    } else {
+      console.log("After this migration succeeds, Threadnote will print:");
+      for (const instruction of migration.instructions) {
+        console.log(`  ${instruction}`);
+      }
+    }
+  }
+  if (!options.dryRun && options.markHandled) {
+    await writePostUpdateState(config, { handledMigrationIds: [...handledMigrationIds].sort() });
+  }
+}
+async function applicablePostUpdateMigrations(config, options) {
+  const migrations = await readPostUpdateMigrations();
+  const handled = new Set(options.handledMigrationIds);
+  const applicable = [];
+  for (const migration of migrations) {
+    if (handled.has(migration.id)) {
+      continue;
+    }
+    if (compareVersions(options.fromVersion, migration.introducedIn) >= 0) {
+      continue;
+    }
+    if (compareVersions(migration.introducedIn, options.toVersion) > 0) {
+      continue;
+    }
+    if (migration.requiresLegacyHandoffs === true && !await hasLegacyLifecycleHandoffCandidates(config)) {
+      continue;
+    }
+    applicable.push(migration);
+  }
+  return applicable;
+}
+async function readPostUpdateMigrations() {
+  const raw = await readFileIfExists((0, import_node_path6.join)(toolRoot(), "config", POST_UPDATE_MIGRATIONS_FILE));
+  if (!raw) {
+    return [];
+  }
+  const parsed = JSON.parse(raw);
+  if (!isJsonObject(parsed) || !Array.isArray(parsed.migrations)) {
+    throw new Error(`${POST_UPDATE_MIGRATIONS_FILE} must contain a migrations array.`);
+  }
+  return parsed.migrations.map(parsePostUpdateMigration);
+}
+function parsePostUpdateMigration(value) {
+  if (!isJsonObject(value) || typeof value.id !== "string" || typeof value.introducedIn !== "string" || typeof value.title !== "string" || !Array.isArray(value.description) || !Array.isArray(value.commandArgs) || !Array.isArray(value.instructions)) {
+    throw new Error(`Invalid entry in ${POST_UPDATE_MIGRATIONS_FILE}.`);
+  }
+  return {
+    commandArgs: stringArray(value, "commandArgs"),
+    description: stringArray(value, "description"),
+    id: value.id,
+    instructions: stringArray(value, "instructions"),
+    introducedIn: value.introducedIn,
+    requiresLegacyHandoffs: value.requiresLegacyHandoffs === true,
+    title: value.title
+  };
+}
+function stringArray(value, key) {
+  const raw = value[key];
+  if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
+    throw new Error(`Invalid ${key} in ${POST_UPDATE_MIGRATIONS_FILE}.`);
+  }
+  return raw;
+}
+function printPostUpdateMigration(migration) {
+  console.log("");
+  console.log(`${migration.title} (${migration.introducedIn})`);
+  for (const line of migration.description) {
+    console.log(`- ${line}`);
+  }
+}
+async function confirmPostUpdateMigration(prompt) {
+  const readline = (0, import_promises7.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
+  try {
+    const answer = (await readline.question(prompt)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    readline.close();
+  }
+}
+function formatMigrationCommand(executable, args) {
+  return [executable, ...args].map((part) => /\s/.test(part) ? JSON.stringify(part) : part).join(" ");
+}
+function currentThreadnoteCommand() {
+  const entrypoint = process.argv[1]?.trim();
+  return entrypoint ? entrypoint : void 0;
+}
+async function readPostUpdateState(config) {
+  const raw = await readFileIfExists(postUpdateStatePath(config));
+  if (!raw) {
+    return { handledMigrationIds: [] };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isJsonObject(parsed) || !Array.isArray(parsed.handledMigrationIds)) {
+      return { handledMigrationIds: [] };
+    }
+    return { handledMigrationIds: parsed.handledMigrationIds.filter((id) => typeof id === "string") };
+  } catch (_err) {
+    return { handledMigrationIds: [] };
+  }
+}
+async function writePostUpdateState(config, state) {
+  await ensureDirectory(config.agentContextHome, false);
+  await (0, import_promises6.writeFile)(postUpdateStatePath(config), `${JSON.stringify(state, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+}
+function postUpdateStatePath(config) {
+  return (0, import_node_path6.join)(config.agentContextHome, POST_UPDATE_STATE_FILE);
+}
+async function resolveUpdateRuntime(runtime) {
+  if (runtime !== "auto") {
+    await requireRuntime(runtime);
+    return runtime;
+  }
+  for (const candidate of ["npm", "bun", "deno"]) {
+    if (await findExecutable([candidate])) {
+      return candidate;
+    }
+  }
+  throw new Error("Install Node/npm, Bun, or Deno to update threadnote.");
+}
+async function requireRuntime(runtime) {
+  if (!await findExecutable([runtime])) {
+    throw new Error(`${runtime} was requested but was not found on PATH.`);
+  }
+}
+async function installedThreadnoteCommand(runtime) {
+  const runtimeBin = await runtimeThreadnoteBin(runtime);
+  if (runtimeBin && await isExecutable(runtimeBin)) {
+    return runtimeBin;
+  }
+  return await findExecutable([NPM_PACKAGE_NAME]) ?? NPM_PACKAGE_NAME;
+}
+async function runtimeThreadnoteBin(runtime) {
+  if (runtime === "npm") {
+    const result = await runCommand("npm", ["prefix", "--global"], { allowFailure: true });
+    const prefix = result.stdout.trim();
+    return prefix ? (0, import_node_path6.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
+  }
+  if (runtime === "bun") {
+    const result = await runCommand("bun", ["pm", "bin", "-g"], { allowFailure: true });
+    const binDir = result.stdout.trim();
+    return binDir ? (0, import_node_path6.join)(binDir, NPM_PACKAGE_NAME) : void 0;
+  }
+  return (0, import_node_path6.join)(process.env.DENO_INSTALL ?? (0, import_node_path6.join)((0, import_node_os4.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
+}
+async function isExecutable(path) {
+  try {
+    await (0, import_promises6.access)(path, import_node_fs3.constants.X_OK);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+function updatePackageCommand(runtime, registry) {
+  if (runtime === "npm") {
+    return { executable: "npm", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
+  }
+  if (runtime === "bun") {
+    return { executable: "bun", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
+  }
+  return {
+    executable: "env",
+    args: [
+      `NPM_CONFIG_REGISTRY=${registry}`,
+      "deno",
+      "install",
+      "--global",
+      "--force",
+      "--name",
+      NPM_PACKAGE_NAME,
+      "--allow-read",
+      "--allow-write",
+      "--allow-run",
+      "--allow-env",
+      "--allow-net",
+      `npm:${NPM_PACKAGE_NAME}@latest`
+    ]
+  };
+}
+function normalizeRegistry(registry) {
+  return registry.endsWith("/") ? registry : `${registry}/`;
+}
+function updateRegistry() {
+  return normalizeRegistry(process.env.THREADNOTE_NPM_REGISTRY ?? DEFAULT_NPM_REGISTRY);
+}
+function isUpdateNotificationDisabled() {
+  return process.env.CI !== void 0 || process.env.NO_UPDATE_NOTIFIER !== void 0 || process.env.THREADNOTE_NO_UPDATE_CHECK !== void 0;
+}
+function compareVersions(currentVersion, latestVersion) {
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = current.numbers[index] - latest.numbers[index];
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  if (current.prerelease === latest.prerelease) {
+    return 0;
+  }
+  if (current.prerelease === void 0) {
+    return 1;
+  }
+  if (latest.prerelease === void 0) {
+    return -1;
+  }
+  return current.prerelease.localeCompare(latest.prerelease);
+}
+function parseVersion(version) {
+  const normalized = version.trim().replace(/^v/, "");
+  const [core2, prerelease] = normalized.split("-", 2);
+  const parts = core2.split(".").map((part) => Number(part));
+  return {
+    numbers: [safeVersionNumber(parts[0]), safeVersionNumber(parts[1]), safeVersionNumber(parts[2])],
+    prerelease
+  };
+}
+function safeVersionNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+// src/lifecycle.ts
 async function runDoctor(config, options) {
   const checks = [];
   checks.push({ name: "mode", status: "ok", detail: options.dryRun ? "dry run; no writes" : "read-only checks" });
-  checks.push({ name: "platform", status: (0, import_node_os4.platform)() === "darwin" ? "ok" : "warn", detail: (0, import_node_os4.platform)() });
+  checks.push({ name: "platform", status: (0, import_node_os5.platform)() === "darwin" ? "ok" : "warn", detail: (0, import_node_os5.platform)() });
   checks.push(await commandCheck("node", ["--version"]));
   checks.push(await commandCheck("python3", ["--version"]));
   checks.push(await commandCheck("openviking-server", ["--help"]));
@@ -7886,9 +8705,9 @@ async function runDoctor(config, options) {
   checks.push(await commandShimCheck());
   checks.push(...await userAgentInstructionsChecks());
   checks.push(await manifestCheck(config.manifestPath));
-  checks.push(await fileCheck((0, import_node_path6.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
-  checks.push(await fileCheck((0, import_node_path6.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
-  checks.push(await fileCheck((0, import_node_path6.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
+  checks.push(await fileCheck((0, import_node_path7.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
+  checks.push(await fileCheck((0, import_node_path7.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
+  checks.push(await fileCheck((0, import_node_path7.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
   checks.push(await healthCheck(config));
   for (const check of checks) {
     console.log(`${formatStatus(check.status)} ${check.name}: ${check.detail}`);
@@ -7905,9 +8724,9 @@ async function runInstall(config, options) {
   const repairInvalidConfigs = options.repairInvalidConfigs === true;
   const dryRun = options.dryRun === true;
   await ensureDirectory(config.agentContextHome, dryRun);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "logs"), dryRun);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "redacted"), dryRun);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "mcp"), dryRun);
+  await ensureDirectory((0, import_node_path7.join)(config.agentContextHome, "logs"), dryRun);
+  await ensureDirectory((0, import_node_path7.join)(config.agentContextHome, "redacted"), dryRun);
+  await ensureDirectory((0, import_node_path7.join)(config.agentContextHome, "mcp"), dryRun);
   await installCommandShim(dryRun);
   await installUserAgentInstructions(dryRun);
   const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
@@ -7933,17 +8752,17 @@ async function runInstall(config, options) {
   }
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path6.join)(config.agentContextHome, "ov.conf"),
+    destinationPath: (0, import_node_path7.join)(config.agentContextHome, "ov.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairOpenVikingConfig(content, config) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path6.join)(toolRoot(), "config", "ov.conf.template.json")
+    templatePath: (0, import_node_path7.join)(toolRoot(), "config", "ov.conf.template.json")
   });
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path6.join)(config.agentContextHome, "ovcli.conf"),
+    destinationPath: (0, import_node_path7.join)(config.agentContextHome, "ovcli.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairLegacyOvCliConfig(content) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path6.join)(toolRoot(), "config", "ovcli.conf.template.json")
+    templatePath: (0, import_node_path7.join)(toolRoot(), "config", "ovcli.conf.template.json")
   });
   if (options.start !== false) {
     const healthy = await repairServerHealth(config, dryRun);
@@ -7982,6 +8801,9 @@ async function runRepair(config, options) {
   }
   console.log("\nPost-repair doctor:");
   await runDoctor(config, { dryRun, strict: false });
+  if (options.postUpdate !== false) {
+    await maybeRunPostUpdateAfterRepair(config, { dryRun });
+  }
 }
 async function runUninstall(config, options) {
   const dryRun = options.dryRun === true;
@@ -7990,7 +8812,7 @@ async function runUninstall(config, options) {
   }
   console.log("Uninstalling local Threadnote setup.");
   await runStop(config, { dryRun });
-  await removePathIfExists((0, import_node_path6.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
+  await removePathIfExists((0, import_node_path7.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
   await removeLaunchAgent(dryRun);
   await removeMcpConfigs(options.mcp ?? "available", dryRun);
   await removeMcpSnippets(config, dryRun);
@@ -8025,7 +8847,7 @@ async function repairManifest(config, dryRun) {
     return;
   }
   const project = projectManifestForRepo(repoRoot, []);
-  const output = jsYaml.dump(
+  const output2 = jsYaml.dump(
     {
       version: 1,
       projects: [
@@ -8041,19 +8863,19 @@ async function repairManifest(config, dryRun) {
   );
   if (dryRun) {
     console.log(`# Would write replacement manifest: ${config.manifestPath}`);
-    console.log(output.trimEnd());
+    console.log(output2.trimEnd());
     return;
   }
-  await ensureDirectory((0, import_node_path6.dirname)(config.manifestPath), false);
+  await ensureDirectory((0, import_node_path7.dirname)(config.manifestPath), false);
   const currentContent = await readFileIfExists(config.manifestPath);
   if (currentContent !== void 0) {
     const backupPath = `${config.manifestPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises6.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
-    await (0, import_promises6.chmod)(backupPath, 384);
+    await (0, import_promises8.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises8.chmod)(backupPath, 384);
     console.log(`Backup: ${backupPath}`);
   }
-  await (0, import_promises6.writeFile)(config.manifestPath, output, { encoding: "utf8", mode: 384 });
-  await (0, import_promises6.chmod)(config.manifestPath, 384);
+  await (0, import_promises8.writeFile)(config.manifestPath, output2, { encoding: "utf8", mode: 384 });
+  await (0, import_promises8.chmod)(config.manifestPath, 384);
   console.log(`Wrote replacement manifest: ${config.manifestPath}`);
 }
 async function repairServerHealth(config, dryRun) {
@@ -8094,16 +8916,16 @@ async function runStart(config, options) {
     );
   }
   const logPath = openVikingLogPath(config);
-  await ensureDirectory((0, import_node_path6.dirname)(logPath), false);
+  await ensureDirectory((0, import_node_path7.dirname)(logPath), false);
   if (options.foreground === true) {
     const result = await runInteractive(server, args);
     process.exitCode = result;
     return;
   }
-  const logFd = (0, import_node_fs3.openSync)(logPath, "a");
+  const logFd = (0, import_node_fs4.openSync)(logPath, "a");
   const child = spawnDetachedServerWithLog(server, args, logFd);
   child.unref();
-  await (0, import_promises6.writeFile)((0, import_node_path6.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
+  await (0, import_promises8.writeFile)((0, import_node_path7.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
 `, "utf8");
   const health = await waitForOpenVikingHealth(config, START_HEALTH_TIMEOUT_MS);
   if (health) {
@@ -8118,7 +8940,7 @@ function spawnDetachedServerWithLog(server, args, logFd) {
   try {
     return spawnDetachedServer(server, args, logFd);
   } finally {
-    (0, import_node_fs3.closeSync)(logFd);
+    (0, import_node_fs4.closeSync)(logFd);
   }
 }
 function spawnDetachedServer(server, args, logFd) {
@@ -8129,14 +8951,14 @@ function spawnDetachedServer(server, args, logFd) {
 }
 async function runStop(config, options) {
   const launchAgentPath = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
-  if ((0, import_node_os4.platform)() === "darwin") {
+  if ((0, import_node_os5.platform)() === "darwin") {
     if (options.dryRun === true || await exists(launchAgentPath)) {
       await maybeRun(options.dryRun === true, "launchctl", ["unload", launchAgentPath], { allowFailure: true });
     } else {
       console.log(`No LaunchAgent found: ${launchAgentPath}`);
     }
   }
-  const pidPath = (0, import_node_path6.join)(config.agentContextHome, "openviking-server.pid");
+  const pidPath = (0, import_node_path7.join)(config.agentContextHome, "openviking-server.pid");
   const pidText = await readFileIfExists(pidPath);
   if (!pidText) {
     console.log("No pid file found for detached OpenViking server.");
@@ -8232,7 +9054,7 @@ async function pythonSystemCertificatesCheck() {
   };
 }
 async function commandShimCheck() {
-  const shimPath = (0, import_node_path6.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path7.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     return { name: "threadnote shim", status: "warn", detail: `${shimPath} missing; repair will create it` };
@@ -8298,11 +9120,11 @@ async function hasPythonModule(serverPath, moduleName) {
 async function siblingPythonForExecutable(executablePath) {
   let resolvedPath;
   try {
-    resolvedPath = await (0, import_promises6.realpath)(executablePath);
+    resolvedPath = await (0, import_promises8.realpath)(executablePath);
   } catch (_err) {
     return void 0;
   }
-  const pythonPath = (0, import_node_path6.join)((0, import_node_path6.dirname)(resolvedPath), "python");
+  const pythonPath = (0, import_node_path7.join)((0, import_node_path7.dirname)(resolvedPath), "python");
   return await exists(pythonPath) ? pythonPath : void 0;
 }
 async function manifestCheck(path) {
@@ -8424,38 +9246,38 @@ function printInstallNextSteps(options) {
 }
 async function writeTemplateIfMissing(options) {
   if (await exists(options.destinationPath)) {
-    const currentContent = await (0, import_promises6.readFile)(options.destinationPath, "utf8");
+    const currentContent = await (0, import_promises8.readFile)(options.destinationPath, "utf8");
     if (options.shouldRepair?.(currentContent) !== true) {
       console.log(`Already exists: ${options.destinationPath}`);
       return;
     }
-    const rendered2 = renderTemplate(await (0, import_promises6.readFile)(options.templatePath, "utf8"), options.config);
+    const rendered2 = renderTemplate(await (0, import_promises8.readFile)(options.templatePath, "utf8"), options.config);
     if (options.dryRun) {
       console.log(`Would repair generated config: ${options.destinationPath}`);
       return;
     }
     const backupPath = `${options.destinationPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises6.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
-    await (0, import_promises6.chmod)(backupPath, 384);
-    await (0, import_promises6.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
-    await (0, import_promises6.chmod)(options.destinationPath, 384);
+    await (0, import_promises8.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises8.chmod)(backupPath, 384);
+    await (0, import_promises8.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
+    await (0, import_promises8.chmod)(options.destinationPath, 384);
     console.log(`Repaired generated config: ${options.destinationPath}`);
     console.log(`Backup: ${backupPath}`);
     return;
   }
-  const rendered = renderTemplate(await (0, import_promises6.readFile)(options.templatePath, "utf8"), options.config);
+  const rendered = renderTemplate(await (0, import_promises8.readFile)(options.templatePath, "utf8"), options.config);
   if (options.dryRun) {
     console.log(`Would write ${options.destinationPath}`);
     return;
   }
-  await ensureDirectory((0, import_node_path6.dirname)(options.destinationPath), false);
-  await (0, import_promises6.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
-  await (0, import_promises6.chmod)(options.destinationPath, 384);
+  await ensureDirectory((0, import_node_path7.dirname)(options.destinationPath), false);
+  await (0, import_promises8.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
+  await (0, import_promises8.chmod)(options.destinationPath, 384);
   console.log(`Wrote ${options.destinationPath}`);
 }
 async function installCommandShim(dryRun) {
   const binDir = expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin");
-  const shimPath = (0, import_node_path6.join)(binDir, "threadnote");
+  const shimPath = (0, import_node_path7.join)(binDir, "threadnote");
   const existingContent = await readFileIfExists(shimPath);
   if (existingContent && !isManagedCommandShim(existingContent)) {
     console.log(`WARN not overwriting existing command shim: ${shimPath}`);
@@ -8471,12 +9293,12 @@ async function installCommandShim(dryRun) {
     return;
   }
   await ensureDirectory(binDir, false);
-  await (0, import_promises6.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
-  await (0, import_promises6.chmod)(shimPath, 493);
+  await (0, import_promises8.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
+  await (0, import_promises8.chmod)(shimPath, 493);
   console.log(`Wrote command shim: ${shimPath}`);
 }
 async function removeCommandShim(dryRun) {
-  const shimPath = (0, import_node_path6.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path7.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     console.log(`Already absent: ${shimPath}`);
@@ -8506,8 +9328,8 @@ async function installUserAgentInstructions(dryRun) {
       console.log(currentContent === void 0 ? `Would write ${targetPath}` : `Would update ${targetPath}`);
       continue;
     }
-    await ensureDirectory((0, import_node_path6.dirname)(targetPath), false);
-    await (0, import_promises6.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await ensureDirectory((0, import_node_path7.dirname)(targetPath), false);
+    await (0, import_promises8.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(currentContent === void 0 ? `Wrote ${targetPath}` : `Updated ${targetPath}`);
   }
 }
@@ -8536,12 +9358,12 @@ async function removeUserAgentInstructions(dryRun) {
       console.log(`Would update ${targetPath}`);
       continue;
     }
-    await (0, import_promises6.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await (0, import_promises8.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(`Updated ${targetPath}`);
   }
 }
 async function renderUserAgentInstructionsBlock() {
-  const instructions = (await (0, import_promises6.readFile)((0, import_node_path6.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
+  const instructions = (await (0, import_promises8.readFile)((0, import_node_path7.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
   return `${USER_INSTRUCTIONS_START_MARKER}
 ${instructions}
 ${USER_INSTRUCTIONS_END_MARKER}`;
@@ -8616,12 +9438,12 @@ function isManagedCommandShim(content) {
   return content.includes(SHIM_MARKER);
 }
 async function installLaunchAgent(config, dryRun) {
-  if ((0, import_node_os4.platform)() !== "darwin") {
+  if ((0, import_node_os5.platform)() !== "darwin") {
     throw new Error("launchd autostart is only supported on macOS.");
   }
-  const source = (0, import_node_path6.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
+  const source = (0, import_node_path7.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
   const destination = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
-  const rendered = renderTemplate(await (0, import_promises6.readFile)(source, "utf8"), config);
+  const rendered = renderTemplate(await (0, import_promises8.readFile)(source, "utf8"), config);
   if (dryRun) {
     console.log(`Would write ${destination}`);
     console.log(`Would run: launchctl unload ${destination}`);
@@ -8629,9 +9451,9 @@ async function installLaunchAgent(config, dryRun) {
     console.log(`Would run: launchctl start ${LAUNCHD_LABEL}`);
     return;
   }
-  await ensureDirectory((0, import_node_path6.dirname)(destination), false);
-  await ensureDirectory((0, import_node_path6.dirname)(openVikingLogPath(config)), false);
-  await (0, import_promises6.writeFile)(destination, rendered, "utf8");
+  await ensureDirectory((0, import_node_path7.dirname)(destination), false);
+  await ensureDirectory((0, import_node_path7.dirname)(openVikingLogPath(config)), false);
+  await (0, import_promises8.writeFile)(destination, rendered, "utf8");
   await maybeRun(false, "launchctl", ["unload", destination], { allowFailure: true });
   await maybeRun(false, "launchctl", ["load", destination]);
   await maybeRun(false, "launchctl", ["start", LAUNCHD_LABEL]);
@@ -8694,7 +9516,7 @@ function isGeneratedLocalPilotConfig(parsed, config) {
   if (typeof parsed.default_user !== "string") {
     return false;
   }
-  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path6.join)(config.agentContextHome, "data")) {
+  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path7.join)(config.agentContextHome, "data")) {
     return false;
   }
   return isJsonObject(parsed.server) && parsed.server.host === config.host && String(parsed.server.port) === String(config.port);
@@ -8713,259 +9535,6 @@ function parsePackageManager(value) {
   throw new Error(`Invalid package manager: ${value}`);
 }
 
-// src/update.ts
-var import_node_fs4 = require("node:fs");
-var import_promises7 = require("node:fs/promises");
-var import_node_os5 = require("node:os");
-var import_node_path7 = require("node:path");
-var NPM_PACKAGE_NAME = "threadnote";
-var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
-var UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
-function parseUpdateRuntime(value) {
-  if (value === "auto" || value === "npm" || value === "bun" || value === "deno") {
-    return value;
-  }
-  throw new Error(`Invalid update runtime: ${value}. Expected auto, npm, bun, or deno.`);
-}
-async function maybeNotifyUpdate(config, options = {}) {
-  if (isUpdateNotificationDisabled()) {
-    return;
-  }
-  try {
-    const info = await getUpdateInfo(config, {
-      allowCacheWrite: options.dryRun !== true,
-      preferFresh: false,
-      registry: updateRegistry()
-    });
-    if (!info.isUpdateAvailable) {
-      return;
-    }
-    console.log("");
-    console.log(`Update available: threadnote ${info.currentVersion} -> ${info.latestVersion}`);
-    console.log("Run: threadnote update");
-  } catch (_err) {
-    return;
-  }
-}
-async function runUpdate(config, options) {
-  const registry = normalizeRegistry(options.registry ?? updateRegistry());
-  const info = await getUpdateInfo(config, {
-    allowCacheWrite: options.dryRun !== true,
-    preferFresh: true,
-    registry
-  });
-  console.log(`Current version: ${info.currentVersion}`);
-  console.log(`Latest version:  ${info.latestVersion}`);
-  console.log(`Registry:        ${info.registry}`);
-  if (options.check === true) {
-    if (info.isUpdateAvailable) {
-      console.log(`Update available. Run: threadnote update`);
-    } else {
-      console.log(
-        compareVersions(info.currentVersion, info.latestVersion) > 0 ? "Current version is newer than npm latest." : "Threadnote is up to date."
-      );
-    }
-    return;
-  }
-  if (!info.isUpdateAvailable && options.force !== true) {
-    console.log("Threadnote is up to date.");
-    return;
-  }
-  const runtime = await resolveUpdateRuntime(options.runtime ?? "auto");
-  const updateCommand = updatePackageCommand(runtime, registry);
-  await maybeRun(options.dryRun === true, updateCommand.executable, updateCommand.args);
-  if (options.repair === false) {
-    console.log("Skipping repair because --no-repair was provided.");
-    return;
-  }
-  const threadnoteCommand = await installedThreadnoteCommand(runtime);
-  await maybeRun(options.dryRun === true, threadnoteCommand, ["repair"]);
-  console.log("Update complete. Restart Cursor, Codex, Claude, or open a fresh agent session so MCP tools reload.");
-}
-async function getUpdateInfo(config, options) {
-  const currentVersion = await currentPackageVersion();
-  const cached = options.preferFresh ? void 0 : await readFreshCache(config, options.registry);
-  const latestVersion = cached?.latestVersion ?? await fetchLatestVersion(options.registry);
-  if (!cached && options.allowCacheWrite) {
-    await writeUpdateCache(config, { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latestVersion, registry: options.registry });
-  }
-  return {
-    currentVersion,
-    isUpdateAvailable: compareVersions(currentVersion, latestVersion) < 0,
-    latestVersion,
-    registry: options.registry
-  };
-}
-async function currentPackageVersion() {
-  const rawPackage = await (0, import_promises7.readFile)((0, import_node_path7.join)(toolRoot(), "package.json"), "utf8");
-  const parsed = JSON.parse(rawPackage);
-  if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
-    throw new Error("Could not read current threadnote package version.");
-  }
-  return parsed.version;
-}
-async function fetchLatestVersion(registry) {
-  const url = new URL(`${NPM_PACKAGE_NAME}/latest`, normalizeRegistry(registry));
-  const controller = new AbortController();
-  const timeout = setTimeout(() => {
-    controller.abort();
-  }, 2500);
-  try {
-    const response = await fetch(url, { headers: { accept: "application/json" }, signal: controller.signal });
-    if (!response.ok) {
-      throw new Error(`npm registry returned HTTP ${response.status}`);
-    }
-    const parsed = await response.json();
-    if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
-      throw new Error("npm registry response did not include a version.");
-    }
-    return parsed.version;
-  } catch (err) {
-    throw new Error(`Could not check npm for updates: ${errorMessage(err)}`, { cause: err });
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-async function readFreshCache(config, registry) {
-  const rawCache = await readFileIfExists(updateCachePath(config));
-  if (!rawCache) {
-    return void 0;
-  }
-  try {
-    const parsed = JSON.parse(rawCache);
-    if (!isJsonObject(parsed) || typeof parsed.checkedAt !== "string" || typeof parsed.latestVersion !== "string" || parsed.registry !== registry) {
-      return void 0;
-    }
-    const checkedAt = Date.parse(parsed.checkedAt);
-    if (!Number.isFinite(checkedAt) || Date.now() - checkedAt > UPDATE_CHECK_TTL_MS) {
-      return void 0;
-    }
-    return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion, registry };
-  } catch (_err) {
-    return void 0;
-  }
-}
-async function writeUpdateCache(config, cache) {
-  await ensureDirectory(config.agentContextHome, false);
-  await (0, import_promises7.writeFile)(updateCachePath(config), `${JSON.stringify(cache, null, 2)}
-`, { encoding: "utf8", mode: 384 });
-}
-function updateCachePath(config) {
-  return (0, import_node_path7.join)(config.agentContextHome, "update-check.json");
-}
-async function resolveUpdateRuntime(runtime) {
-  if (runtime !== "auto") {
-    await requireRuntime(runtime);
-    return runtime;
-  }
-  for (const candidate of ["npm", "bun", "deno"]) {
-    if (await findExecutable([candidate])) {
-      return candidate;
-    }
-  }
-  throw new Error("Install Node/npm, Bun, or Deno to update threadnote.");
-}
-async function requireRuntime(runtime) {
-  if (!await findExecutable([runtime])) {
-    throw new Error(`${runtime} was requested but was not found on PATH.`);
-  }
-}
-async function installedThreadnoteCommand(runtime) {
-  const runtimeBin = await runtimeThreadnoteBin(runtime);
-  if (runtimeBin && await isExecutable(runtimeBin)) {
-    return runtimeBin;
-  }
-  return await findExecutable([NPM_PACKAGE_NAME]) ?? NPM_PACKAGE_NAME;
-}
-async function runtimeThreadnoteBin(runtime) {
-  if (runtime === "npm") {
-    const result = await runCommand("npm", ["prefix", "--global"], { allowFailure: true });
-    const prefix = result.stdout.trim();
-    return prefix ? (0, import_node_path7.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
-  }
-  if (runtime === "bun") {
-    const result = await runCommand("bun", ["pm", "bin", "-g"], { allowFailure: true });
-    const binDir = result.stdout.trim();
-    return binDir ? (0, import_node_path7.join)(binDir, NPM_PACKAGE_NAME) : void 0;
-  }
-  return (0, import_node_path7.join)(process.env.DENO_INSTALL ?? (0, import_node_path7.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
-}
-async function isExecutable(path) {
-  try {
-    await (0, import_promises7.access)(path, import_node_fs4.constants.X_OK);
-    return true;
-  } catch (_err) {
-    return false;
-  }
-}
-function updatePackageCommand(runtime, registry) {
-  if (runtime === "npm") {
-    return { executable: "npm", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
-  }
-  if (runtime === "bun") {
-    return { executable: "bun", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
-  }
-  return {
-    executable: "env",
-    args: [
-      `NPM_CONFIG_REGISTRY=${registry}`,
-      "deno",
-      "install",
-      "--global",
-      "--force",
-      "--name",
-      NPM_PACKAGE_NAME,
-      "--allow-read",
-      "--allow-write",
-      "--allow-run",
-      "--allow-env",
-      "--allow-net",
-      `npm:${NPM_PACKAGE_NAME}@latest`
-    ]
-  };
-}
-function normalizeRegistry(registry) {
-  return registry.endsWith("/") ? registry : `${registry}/`;
-}
-function updateRegistry() {
-  return normalizeRegistry(process.env.THREADNOTE_NPM_REGISTRY ?? DEFAULT_NPM_REGISTRY);
-}
-function isUpdateNotificationDisabled() {
-  return process.env.CI !== void 0 || process.env.NO_UPDATE_NOTIFIER !== void 0 || process.env.THREADNOTE_NO_UPDATE_CHECK !== void 0;
-}
-function compareVersions(currentVersion, latestVersion) {
-  const current = parseVersion(currentVersion);
-  const latest = parseVersion(latestVersion);
-  for (let index = 0; index < 3; index += 1) {
-    const difference = current.numbers[index] - latest.numbers[index];
-    if (difference !== 0) {
-      return difference;
-    }
-  }
-  if (current.prerelease === latest.prerelease) {
-    return 0;
-  }
-  if (current.prerelease === void 0) {
-    return 1;
-  }
-  if (latest.prerelease === void 0) {
-    return -1;
-  }
-  return current.prerelease.localeCompare(latest.prerelease);
-}
-function parseVersion(version) {
-  const normalized = version.trim().replace(/^v/, "");
-  const [core2, prerelease] = normalized.split("-", 2);
-  const parts = core2.split(".").map((part) => Number(part));
-  return {
-    numbers: [safeVersionNumber(parts[0]), safeVersionNumber(parts[1]), safeVersionNumber(parts[2])],
-    prerelease
-  };
-}
-function safeVersionNumber(value) {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
-}
-
 // src/threadnote.ts
 async function main() {
   const program2 = new Command();
@@ -8980,14 +9549,17 @@ async function main() {
     await runInstall(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
-  program2.command("update").description("Update the published Threadnote package, then repair local shims and MCP config").option("--check", "Only check whether a newer version is available").option("--dry-run", "Print update and repair commands without running them").option("--force", "Run package-manager update even if this version is already current").option("--registry <url>", "npm registry URL", process.env.THREADNOTE_NPM_REGISTRY).option("--runtime <runtime>", "auto, npm, bun, or deno", parseUpdateRuntime, "auto").option("--no-repair", "Skip threadnote repair after updating the package").action(async (options) => {
+  program2.command("update").description("Update the published Threadnote package, then repair local shims and MCP config").option("--check", "Only check whether a newer version is available").option("--dry-run", "Print update and repair commands without running them").option("--force", "Run package-manager update even if this version is already current").option("--registry <url>", "npm registry URL", process.env.THREADNOTE_NPM_REGISTRY).option("--runtime <runtime>", "auto, npm, bun, or deno", parseUpdateRuntime, "auto").option("--no-repair", "Skip threadnote repair after updating the package").option("--no-post-update", "Skip post-update migration prompts").option("--yes", "Accept applicable post-update migrations without prompting").action(async (options) => {
     await runUpdate(getRuntimeConfig(program2), options);
   });
+  program2.command("post-update", { hidden: true }).description("Run packaged post-update migration prompts").requiredOption("--from-version <version>", "Version before update").requiredOption("--to-version <version>", "Version after update").option("--dry-run", "Print post-update actions without running them").option("--yes", "Accept applicable post-update migrations without prompting").action(async (options) => {
+    await runPostUpdate(getRuntimeConfig(program2), options);
+  });
   program2.command("repair").description("Repair local OpenViking install, config files, server health, shim, manifest, and MCP config").option("--dry-run", "Print the repair actions without making changes").option(
     "--mcp <clients>",
     "MCP clients to repair: available, all, none, codex, claude, cursor, or comma-separated list",
     "available"
-  ).option("--no-start", "Do not start OpenViking if health is failing").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).action(async (options) => {
+  ).option("--no-start", "Do not start OpenViking if health is failing").option("--no-post-update", "Skip post-update migration prompts after repair").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).action(async (options) => {
     const config = getRuntimeConfig(program2);
     await runRepair(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
@@ -9019,7 +9591,7 @@ async function main() {
   program2.command("mcp-install").description("Install OpenViking MCP config for a supported agent").argument("<agent>", "codex, claude, or cursor").option("--apply", "Actually modify the selected agent config").option("--name <name>", "MCP server name", OPENVIKING_MCP_NAME).option("--native-http", "Install OpenViking native HTTP MCP endpoint instead of the local stdio adapter").option("--scope <scope>", "Claude MCP config scope: user, local, or project", parseClaudeMcpScope, "user").option("--url <url>", "OpenViking native HTTP MCP URL").option("--bearer-token-env-var <name>", "Environment variable containing the local API key").action(async (agent, options) => {
     await runMcpInstall(getRuntimeConfig(program2), parseAgentClient(agent), options);
   });
-  program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").action(async (options) => {
+  program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--kind <kind>", "durable, handoff, incident, preference, or smoke", parseMemoryKind, "durable").option("--project <name>", "Project/repo/topic namespace for lifecycle-aware storage").option("--replace <uri>", "Supersede an existing viking:// memory after the new memory is stored").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--status <status>", "active, archived, or superseded", parseMemoryStatus, "active").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").option("--topic <name>", "Stable topic name; active memories with the same project/topic update one file").action(async (options) => {
     await runRemember(getRuntimeConfig(program2), options);
   });
   program2.command("migrate-memories").description("Migrate legacy session-only Threadnote memories into durable memory files").option("--all-accounts", "Scan all local OpenViking accounts under THREADNOTE_HOME").option("--dry-run", "Print migration actions without writing memories").option("--limit <count>", "Maximum number of memories to migrate").option(
@@ -9030,7 +9602,10 @@ async function main() {
   ).action(async (options) => {
     await runMigrateMemories(getRuntimeConfig(program2), options);
   });
-  program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
+  program2.command("migrate-lifecycle").description("Move clear legacy handoff memories into lifecycle-aware archive paths").option("--apply", "Perform the migration; without this, prints a dry run").option("--dry-run", "Print migration actions without writing or removing memories").option("--limit <count>", "Maximum number of legacy handoffs to migrate").action(async (options) => {
+    await runMigrateLifecycle(getRuntimeConfig(program2), options);
+  });
+  program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("--include-archived", "Include archived memories in exact durable-memory matches").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
     await runRecall(getRuntimeConfig(program2), options);
   });
   program2.command("read").description("Read a viking:// URI returned by recall or list").argument("<uri>", "viking:// URI to read").option("--dry-run", "Print ov command without reading").action(async (uri, options) => {
@@ -9039,9 +9614,12 @@ async function main() {
   program2.command("list").alias("ls").description("List a viking:// directory").argument("[uri]", "viking:// URI to list", "viking://").option("-a, --all", "Show hidden files such as .abstract.md and .overview.md").option("--dry-run", "Print ov command without listing").option("-n, --node-limit <count>", "Maximum number of nodes to list").option("-r, --recursive", "List subdirectories recursively").option("-s, --simple", "Print only paths").action(async (uri, options) => {
     await runList(getRuntimeConfig(program2), uri, options);
   });
-  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").action(async (options) => {
+  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--project <name>", "Project/repo namespace; defaults to current repo basename").option("--replace <uri>", "Supersede an existing viking:// memory after the new handoff is stored").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").option("--topic <name>", "Stable topic name; active handoffs with the same project/topic update one file").action(async (options) => {
     await runHandoff(getRuntimeConfig(program2), options);
   });
+  program2.command("archive").description("Move a memory into the archived lifecycle tree, then remove the original after the archive is stored").argument("<uri>", "viking:// memory URI to archive").option("--dry-run", "Print archive content and ov commands without changing anything").option("--kind <kind>", "durable, handoff, incident, preference, or smoke", parseMemoryKind).option("--project <name>", "Override inferred project/repo namespace").option("--topic <name>", "Override inferred topic").action(async (uri, options) => {
+    await runArchive(getRuntimeConfig(program2), uri, options);
+  });
   program2.command("forget").description("Remove a viking:// URI from local OpenViking context").argument("<uri>", "viking:// URI to remove").option("--dry-run", "Print ov command without deleting").action(async (uri, options) => {
     await runForget(getRuntimeConfig(program2), uri, options);
   });