agendex-cli 0.14.0 → 0.16.0

package/dist/cli.js

@@ -1058,14 +1058,14 @@ var init_cleanup = __esm(() => {
 });
 
 // src/cli.ts
-import { spawn as spawn3 } from "node:child_process";
-import { existsSync as existsSync9, statSync as statSync2, writeSync } from "node:fs";
-import { resolve as resolve6 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { spawn as spawn4 } from "node:child_process";
+import { existsSync as existsSync11, statSync as statSync2, writeSync } from "node:fs";
+import { resolve as resolve8 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // ../shared/src/adapters/catalog.ts
-import { homedir as homedir6 } from "node:os";
-import { join as join6 } from "node:path";
+import { homedir as homedir7 } from "node:os";
+import { join as join7 } from "node:path";
 
 // ../shared/src/adapters/claude-code.ts
 import { readFile, stat, writeFile } from "node:fs/promises";
@@ -1748,6 +1748,453 @@ var ohMyOpencodeAdapter = {
   }
 };
 
+// ../shared/src/adapters/plannotator.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { readFile as readFile6, stat as stat6 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { basename as basename5, dirname, join as join6, resolve as resolve2, sep as sep2 } from "node:path";
+var REQUEST_TIMEOUT_MS = 5000;
+var PROJECT_PLANS_DIRNAME = "@plans";
+function getPlannotatorDir() {
+  return process.env.AGENDEX_PLANNOTATOR_DIR || join6(homedir6(), ".plannotator");
+}
+function getPlansDir() {
+  return join6(getPlannotatorDir(), "plans");
+}
+function getSessionsDir() {
+  return join6(getPlannotatorDir(), "sessions");
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function normalizeStatusFromFilename(filePath) {
+  const name = basename5(filePath, ".md");
+  if (name.endsWith("-approved"))
+    return "approved";
+  if (name.endsWith("-denied"))
+    return "denied";
+  return "unknown";
+}
+function stripStatusSuffix(title) {
+  return title.replace(/-(approved|denied)$/i, "");
+}
+function cleanTitle2(title) {
+  return title.replace(/\d{4}-\d{2}-\d{2}/g, "").replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function extractTitle5(content, filePath) {
+  const heading = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (heading)
+    return heading.replace(/^Plan:\s*/i, "").trim();
+  const name = stripStatusSuffix(basename5(filePath, ".md"));
+  return cleanTitle2(name) || "Plannotator Plan";
+}
+function isAnnotationFile(filePath) {
+  return filePath.endsWith(".annotations.md");
+}
+function isSnapshotFile(filePath) {
+  if (!filePath.endsWith(".md"))
+    return false;
+  if (isAnnotationFile(filePath))
+    return false;
+  const status = normalizeStatusFromFilename(filePath);
+  return status === "approved" || status === "denied";
+}
+function isProjectPlansPath(filePath) {
+  return resolve2(filePath).split(sep2).includes(PROJECT_PLANS_DIRNAME);
+}
+function projectPlansDirForPath(filePath) {
+  const parts = resolve2(filePath).split(sep2);
+  const index = parts.lastIndexOf(PROJECT_PLANS_DIRNAME);
+  if (index === -1)
+    return;
+  return parts.slice(0, index + 1).join(sep2) || sep2;
+}
+function isProjectPlanFile(filePath) {
+  return filePath.endsWith(".md") && !isAnnotationFile(filePath) && isProjectPlansPath(filePath);
+}
+function isSessionFile2(filePath) {
+  return filePath.endsWith(".json");
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSafePlannotatorUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    if (url.protocol !== "http:")
+      return false;
+    if (url.username || url.password)
+      return false;
+    if (url.pathname !== "/" && url.pathname !== "")
+      return false;
+    if (url.search || url.hash)
+      return false;
+    const hostname = url.hostname.toLowerCase();
+    if (hostname === "localhost")
+      return true;
+    if (hostname === "127.0.0.1")
+      return true;
+    if (hostname === "::1" || hostname === "[::1]")
+      return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+function apiUrl(baseUrl, path) {
+  const url = new URL(baseUrl);
+  url.pathname = path;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+async function fetchJson(url, init) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      ...init,
+      redirect: "error",
+      signal: controller.signal
+    });
+    if (!res.ok)
+      return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function postJson(url, body) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      redirect: "error",
+      signal: controller.signal
+    });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function normalizeMode(value) {
+  if (value === "plan" || value === "review" || value === "annotate" || value === "archive") {
+    return value;
+  }
+  return;
+}
+function parseSessionInfo(raw) {
+  if (!isRecord3(raw))
+    return null;
+  const pid = typeof raw.pid === "number" && Number.isFinite(raw.pid) ? raw.pid : undefined;
+  const port = typeof raw.port === "number" && Number.isFinite(raw.port) ? raw.port : undefined;
+  const url = typeof raw.url === "string" ? raw.url : undefined;
+  if (!pid || !url)
+    return null;
+  return {
+    pid,
+    port,
+    url,
+    mode: normalizeMode(raw.mode),
+    project: typeof raw.project === "string" ? raw.project : undefined,
+    startedAt: typeof raw.startedAt === "string" ? raw.startedAt : undefined,
+    label: typeof raw.label === "string" ? raw.label : undefined,
+    origin: typeof raw.origin === "string" ? raw.origin : undefined,
+    reviewId: typeof raw.reviewId === "string" ? raw.reviewId : undefined,
+    sourcePlanPath: typeof raw.sourcePlanPath === "string" ? raw.sourcePlanPath : undefined
+  };
+}
+function parseDate2(value) {
+  if (!value)
+    return;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    return;
+  return date;
+}
+function metadataRecord(metadata) {
+  return {
+    source: "plannotator",
+    sourceAdapter: "plannotator",
+    plannotator: metadata
+  };
+}
+function annotationsPathForSnapshot(filePath) {
+  const snapshotBase = basename5(filePath, ".md").replace(/-(approved|denied)$/i, "");
+  return join6(dirname(filePath), `${snapshotBase}.annotations.md`);
+}
+function snapshotPathsForAnnotation(filePath) {
+  const base = basename5(filePath, ".annotations.md");
+  return [
+    join6(dirname(filePath), `${base}-approved.md`),
+    join6(dirname(filePath), `${base}-denied.md`)
+  ];
+}
+function projectPlanPathsForAnnotation(filePath) {
+  const base = basename5(filePath, ".annotations.md");
+  return [join6(dirname(filePath), `${base}.md`), ...snapshotPathsForAnnotation(filePath)];
+}
+async function countAnnotationHeadings(filePath) {
+  if (!existsSync3(filePath))
+    return;
+  try {
+    const raw = await readFile6(filePath, "utf-8");
+    const headings = raw.match(/^#{1,6}\s+/gm);
+    return headings?.length ?? (raw.trim() ? 1 : 0);
+  } catch {
+    return;
+  }
+}
+async function parseSnapshot(filePath) {
+  try {
+    const content = await readFile6(filePath, "utf-8");
+    const stats = await stat6(filePath);
+    const status = normalizeStatusFromFilename(filePath);
+    const annotationsPath = annotationsPathForSnapshot(filePath);
+    const annotationCount = await countAnnotationHeadings(annotationsPath);
+    const metadata = {
+      kind: "snapshot",
+      mode: "plan",
+      status,
+      annotationsPath: existsSync3(annotationsPath) ? annotationsPath : undefined,
+      annotationCount,
+      writebackCapable: false
+    };
+    return [
+      {
+        id: hashPath(filePath),
+        agent: "plannotator",
+        title: extractTitle5(content, filePath),
+        content,
+        filePath,
+        format: "md",
+        createdAt: stats.birthtime,
+        updatedAt: stats.mtime,
+        metadata: metadataRecord(metadata)
+      }
+    ];
+  } catch {
+    return [];
+  }
+}
+async function parseAnnotationCompanion(filePath) {
+  const plans = [];
+  for (const snapshotPath of snapshotPathsForAnnotation(filePath)) {
+    if (!existsSync3(snapshotPath))
+      continue;
+    plans.push(...await parseSnapshot(snapshotPath));
+  }
+  return plans;
+}
+async function parseProjectPlan(filePath) {
+  try {
+    const content = await readFile6(filePath, "utf-8");
+    const stats = await stat6(filePath);
+    const projectPlansDir = projectPlansDirForPath(filePath);
+    const projectRoot = projectPlansDir ? dirname(projectPlansDir) : undefined;
+    const status = normalizeStatusFromFilename(filePath);
+    const annotationsPath = annotationsPathForSnapshot(filePath);
+    const annotationCount = await countAnnotationHeadings(annotationsPath);
+    const metadata = {
+      kind: "project-plan",
+      mode: "plan",
+      status,
+      annotationsPath: existsSync3(annotationsPath) ? annotationsPath : undefined,
+      annotationCount,
+      sourcePlanPath: filePath,
+      project: projectRoot ? basename5(projectRoot) : undefined,
+      writebackCapable: false
+    };
+    return [
+      {
+        id: hashPath(filePath),
+        agent: "plannotator",
+        title: extractTitle5(content, filePath),
+        content,
+        filePath,
+        format: "md",
+        createdAt: stats.birthtime,
+        updatedAt: stats.mtime,
+        workspace: projectRoot,
+        metadata: metadataRecord(metadata)
+      }
+    ];
+  } catch {
+    return [];
+  }
+}
+async function parseProjectAnnotationCompanion(filePath) {
+  const plans = [];
+  const seen = new Set;
+  for (const planPath of projectPlanPathsForAnnotation(filePath)) {
+    const resolved = resolve2(planPath);
+    if (seen.has(resolved))
+      continue;
+    seen.add(resolved);
+    if (!existsSync3(planPath))
+      continue;
+    plans.push(...await parseProjectPlan(planPath));
+  }
+  return plans;
+}
+async function parseLiveSession(filePath) {
+  try {
+    const raw = JSON.parse(await readFile6(filePath, "utf-8"));
+    const session = parseSessionInfo(raw);
+    if (!session?.pid || !session.url)
+      return [];
+    if (!isAlive(session.pid))
+      return [];
+    if (!isSafePlannotatorUrl(session.url))
+      return [];
+    const mode = session.mode ?? "plan";
+    if (mode === "archive")
+      return [];
+    const planResponse = await fetchJson(apiUrl(session.url, "/api/plan"));
+    if (!planResponse?.plan)
+      return [];
+    const stats = await stat6(filePath);
+    const createdAt = parseDate2(session.startedAt) ?? stats.birthtime;
+    const origin = planResponse.origin ?? session.origin;
+    const responseMode = normalizeMode(planResponse.mode) ?? mode;
+    const workspace = planResponse.projectRoot;
+    const sourcePlanPath = session.sourcePlanPath ?? planResponse.filePath;
+    const metadata = {
+      kind: "live-session",
+      mode: responseMode,
+      status: "pending",
+      origin,
+      url: session.url,
+      pid: session.pid,
+      port: session.port,
+      project: session.project ?? planResponse.versionInfo?.project,
+      label: session.label,
+      reviewId: session.reviewId,
+      sessionPath: filePath,
+      sourcePlanPath,
+      startedAt: session.startedAt,
+      writebackCapable: true
+    };
+    return [
+      {
+        id: hashPath(filePath),
+        agent: origin ?? "plannotator",
+        title: extractTitle5(planResponse.plan, session.label ?? filePath),
+        content: planResponse.plan,
+        filePath: sourcePlanPath ?? filePath,
+        format: "md",
+        createdAt,
+        updatedAt: stats.mtime,
+        workspace,
+        metadata: metadataRecord(metadata)
+      }
+    ];
+  } catch {
+    return [];
+  }
+}
+function getPlannotatorMetadata(plan) {
+  const metadata = plan.metadata.plannotator;
+  if (!isRecord3(metadata))
+    return;
+  return metadata;
+}
+function formatWritebackFeedback(_plan, payload) {
+  const sections = ["# Agendex Plan Feedback", "The user reviewed this plan in Agendex Cloud."];
+  if (payload.feedback.trim()) {
+    sections.push("## Feedback", payload.feedback.trim());
+  }
+  if (payload.revisedContent?.trim()) {
+    sections.push("## Requested revision", "Use this revised plan content as the target shape when you update and resubmit the plan:", payload.revisedContent.trim());
+  }
+  if (payload.annotations?.length) {
+    sections.push("## Typed annotations", JSON.stringify(payload.annotations, null, 2));
+  }
+  sections.push("Please revise the plan and resubmit it for Plannotator review.");
+  return sections.join(`
+
+`);
+}
+function annotationsForEndpoint(annotations) {
+  return annotations ?? [];
+}
+var plannotatorAdapter = {
+  agent: "plannotator",
+  writable: false,
+  getSearchPaths() {
+    return [getPlansDir(), getSessionsDir()];
+  },
+  getWatchPaths() {
+    return [getPlansDir(), getSessionsDir()];
+  },
+  matches(filePath) {
+    const normalized = resolve2(filePath);
+    const plansDir2 = resolve2(getPlansDir());
+    const sessionsDir2 = resolve2(getSessionsDir());
+    if (normalized.startsWith(plansDir2 + sep2))
+      return isSnapshotFile(filePath) || isAnnotationFile(filePath);
+    if (normalized.startsWith(sessionsDir2 + sep2))
+      return isSessionFile2(filePath);
+    if (isProjectPlansPath(filePath))
+      return isProjectPlanFile(filePath) || isAnnotationFile(filePath);
+    return false;
+  },
+  async parse(filePath) {
+    const normalized = resolve2(filePath);
+    const plansDir2 = resolve2(getPlansDir());
+    const sessionsDir2 = resolve2(getSessionsDir());
+    if (normalized.startsWith(plansDir2 + sep2) && isSnapshotFile(filePath)) {
+      return await parseSnapshot(filePath);
+    }
+    if (normalized.startsWith(plansDir2 + sep2) && isAnnotationFile(filePath)) {
+      return await parseAnnotationCompanion(filePath);
+    }
+    if (normalized.startsWith(sessionsDir2 + sep2) && isSessionFile2(filePath)) {
+      return await parseLiveSession(filePath);
+    }
+    if (isProjectPlanFile(filePath)) {
+      return await parseProjectPlan(filePath);
+    }
+    if (isProjectPlansPath(filePath) && isAnnotationFile(filePath)) {
+      return await parseProjectAnnotationCompanion(filePath);
+    }
+    return [];
+  },
+  async write() {
+    return false;
+  },
+  async requestChanges(plan, payload) {
+    const metadata = getPlannotatorMetadata(plan);
+    if (!metadata?.url || !metadata.writebackCapable)
+      return false;
+    if (!isSafePlannotatorUrl(metadata.url))
+      return false;
+    const feedback = formatWritebackFeedback(plan, payload);
+    if (metadata.mode === "review" || metadata.mode === "annotate") {
+      return await postJson(apiUrl(metadata.url, "/api/feedback"), {
+        feedback,
+        annotations: annotationsForEndpoint(payload.annotations)
+      });
+    }
+    return await postJson(apiUrl(metadata.url, "/api/deny"), {
+      feedback,
+      planSave: { enabled: true }
+    });
+  }
+};
+
 // ../shared/src/adapters/stub.ts
 function createStubAdapter(agent, searchPaths, matchExt) {
   return {
@@ -1762,7 +2209,7 @@ function createStubAdapter(agent, searchPaths, matchExt) {
 }
 
 // ../shared/src/adapters/catalog.ts
-var home = homedir6();
+var home = homedir7();
 var ADAPTER_AGENT_ALIASES = {
   amp: "amp",
   antigravity: "antigravity",
@@ -1792,6 +2239,7 @@ var ADAPTER_AGENT_ALIASES = {
   opencode: "oh-my-opencode",
   openhands: "openhands",
   pi: "pi",
+  plannotator: "plannotator",
   qoder: "qoder",
   "qwen-code": "qwen-code",
   replit: "replit",
@@ -1812,7 +2260,7 @@ var CATALOG = [
     group: "universal",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("amp", [join6(home, ".amp")], ".json")
+    createAdapter: () => createStubAdapter("amp", [join7(home, ".amp")], ".json")
   },
   {
     id: "antigravity",
@@ -1820,7 +2268,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("antigravity", [join6(home, ".gemini", "antigravity")], ".json")
+    createAdapter: () => createStubAdapter("antigravity", [join7(home, ".gemini", "antigravity")], ".json")
   },
   {
     id: "augment",
@@ -1828,7 +2276,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("augment", [join6(home, ".augment")], ".json")
+    createAdapter: () => createStubAdapter("augment", [join7(home, ".augment")], ".json")
   },
   {
     id: "claude-code",
@@ -1844,7 +2292,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("openclaw", [join6(home, ".openclaw")], ".md")
+    createAdapter: () => createStubAdapter("openclaw", [join7(home, ".openclaw")], ".md")
   },
   {
     id: "cline",
@@ -1853,8 +2301,8 @@ var CATALOG = [
     implemented: false,
     defaultEnabled: true,
     createAdapter: () => createStubAdapter("cline", [
-      join6(home, "AppData", "Roaming", "Code", "User", "globalStorage", "saoudrizwan.claude-dev"),
-      join6(home, ".config", "Code", "User", "globalStorage", "saoudrizwan.claude-dev")
+      join7(home, "AppData", "Roaming", "Code", "User", "globalStorage", "saoudrizwan.claude-dev"),
+      join7(home, ".config", "Code", "User", "globalStorage", "saoudrizwan.claude-dev")
     ], ".json")
   },
   {
@@ -1863,7 +2311,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("codebuddy", [join6(home, ".codebuddy")], ".md")
+    createAdapter: () => createStubAdapter("codebuddy", [join7(home, ".codebuddy")], ".md")
   },
   {
     id: "codex",
@@ -1879,7 +2327,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("command-code", [join6(home, ".commandcode")], ".md")
+    createAdapter: () => createStubAdapter("command-code", [join7(home, ".commandcode")], ".md")
   },
   {
     id: "continue",
@@ -1895,7 +2343,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("crush", [join6(home, ".config", "crush")], ".json")
+    createAdapter: () => createStubAdapter("crush", [join7(home, ".config", "crush")], ".json")
   },
   {
     id: "cursor",
@@ -1911,7 +2359,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("droid", [join6(home, ".factory", "droids")], ".md")
+    createAdapter: () => createStubAdapter("droid", [join7(home, ".factory", "droids")], ".md")
   },
   {
     id: "gemini-cli",
@@ -1919,7 +2367,7 @@ var CATALOG = [
     group: "universal",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("gemini-cli", [join6(home, ".gemini")], ".md")
+    createAdapter: () => createStubAdapter("gemini-cli", [join7(home, ".gemini")], ".md")
   },
   {
     id: "github-copilot",
@@ -1927,7 +2375,7 @@ var CATALOG = [
     group: "universal",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("copilot-chat", [join6(home, ".vscode", "User", "workspaceStorage")], ".json")
+    createAdapter: () => createStubAdapter("copilot-chat", [join7(home, ".vscode", "User", "workspaceStorage")], ".json")
   },
   {
     id: "goose",
@@ -1935,7 +2383,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("goose", [join6(home, ".config", "goose")], ".json")
+    createAdapter: () => createStubAdapter("goose", [join7(home, ".config", "goose")], ".json")
   },
   {
     id: "junie",
@@ -1943,7 +2391,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("junie", [join6(home, ".junie")], ".json")
+    createAdapter: () => createStubAdapter("junie", [join7(home, ".junie")], ".json")
   },
   {
     id: "iflow-cli",
@@ -1951,7 +2399,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("iflow-cli", [join6(home, ".iflow")], ".json")
+    createAdapter: () => createStubAdapter("iflow-cli", [join7(home, ".iflow")], ".json")
   },
   {
     id: "kilo",
@@ -1959,7 +2407,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("kilo-cli", [join6(home, ".kilo")], ".md")
+    createAdapter: () => createStubAdapter("kilo-cli", [join7(home, ".kilo")], ".md")
   },
   {
     id: "kimi-cli",
@@ -1967,7 +2415,7 @@ var CATALOG = [
     group: "universal",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("kimi-cli", [join6(home, ".kimi")], ".md")
+    createAdapter: () => createStubAdapter("kimi-cli", [join7(home, ".kimi")], ".md")
   },
   {
     id: "kiro-cli",
@@ -1975,7 +2423,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("kiro-cli", [join6(home, ".kiro")], ".json")
+    createAdapter: () => createStubAdapter("kiro-cli", [join7(home, ".kiro")], ".json")
   },
   {
     id: "kode",
@@ -1983,7 +2431,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("kode", [join6(home, ".kode")], ".json")
+    createAdapter: () => createStubAdapter("kode", [join7(home, ".kode")], ".json")
   },
   {
     id: "mcpjam",
@@ -1991,7 +2439,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("mcpjam", [join6(home, ".mcpjam")], ".json")
+    createAdapter: () => createStubAdapter("mcpjam", [join7(home, ".mcpjam")], ".json")
   },
   {
     id: "mistral-vibe",
@@ -1999,7 +2447,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("mistral-vibe", [join6(home, ".vibe")], ".json")
+    createAdapter: () => createStubAdapter("mistral-vibe", [join7(home, ".vibe")], ".json")
   },
   {
     id: "mux",
@@ -2007,7 +2455,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("mux", [join6(home, ".mux")], ".json")
+    createAdapter: () => createStubAdapter("mux", [join7(home, ".mux")], ".json")
   },
   {
     id: "opencode",
@@ -2023,7 +2471,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("openhands", [join6(home, ".openhands")], ".json")
+    createAdapter: () => createStubAdapter("openhands", [join7(home, ".openhands")], ".json")
   },
   {
     id: "pi",
@@ -2031,7 +2479,15 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("pi", [join6(home, ".pi", "agent")], ".md")
+    createAdapter: () => createStubAdapter("pi", [join7(home, ".pi", "agent")], ".md")
+  },
+  {
+    id: "plannotator",
+    displayName: "Plannotator",
+    group: "universal",
+    implemented: true,
+    defaultEnabled: false,
+    createAdapter: () => plannotatorAdapter
   },
   {
     id: "qoder",
@@ -2039,7 +2495,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("qoder", [join6(home, ".qoder")], ".json")
+    createAdapter: () => createStubAdapter("qoder", [join7(home, ".qoder")], ".json")
   },
   {
     id: "qwen-code",
@@ -2047,7 +2503,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("qwen-code", [join6(home, ".qwen")], ".json")
+    createAdapter: () => createStubAdapter("qwen-code", [join7(home, ".qwen")], ".json")
   },
   {
     id: "replit",
@@ -2055,7 +2511,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("replit", [join6(home, ".replit")], ".md")
+    createAdapter: () => createStubAdapter("replit", [join7(home, ".replit")], ".md")
   },
   {
     id: "roo",
@@ -2063,7 +2519,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("roo", [join6(home, ".roo")], ".md")
+    createAdapter: () => createStubAdapter("roo", [join7(home, ".roo")], ".md")
   },
   {
     id: "trae",
@@ -2071,7 +2527,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("trae", [join6(home, ".trae")], ".md")
+    createAdapter: () => createStubAdapter("trae", [join7(home, ".trae")], ".md")
   },
   {
     id: "trae-cn",
@@ -2079,7 +2535,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("trae-cn", [join6(home, ".trae-cn")], ".md")
+    createAdapter: () => createStubAdapter("trae-cn", [join7(home, ".trae-cn")], ".md")
   },
   {
     id: "windsurf",
@@ -2087,7 +2543,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("windsurf", [join6(home, ".cascade_backups")], ".md")
+    createAdapter: () => createStubAdapter("windsurf", [join7(home, ".cascade_backups")], ".md")
   },
   {
     id: "zencoder",
@@ -2095,7 +2551,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("zencoder", [join6(home, ".zencoder")], ".json")
+    createAdapter: () => createStubAdapter("zencoder", [join7(home, ".zencoder")], ".json")
   },
   {
     id: "neovate",
@@ -2103,7 +2559,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("neovate", [join6(home, ".neovate")], ".json")
+    createAdapter: () => createStubAdapter("neovate", [join7(home, ".neovate")], ".json")
   },
   {
     id: "pochi",
@@ -2111,7 +2567,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("pochi", [join6(home, ".pochi")], ".json")
+    createAdapter: () => createStubAdapter("pochi", [join7(home, ".pochi")], ".json")
   },
   {
     id: "adal",
@@ -2119,7 +2575,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: false,
-    createAdapter: () => createStubAdapter("adal", [join6(home, ".adal")], ".json")
+    createAdapter: () => createStubAdapter("adal", [join7(home, ".adal")], ".json")
   },
   {
     id: "aider",
@@ -2127,7 +2583,7 @@ var CATALOG = [
     group: "other",
     implemented: false,
     defaultEnabled: true,
-    createAdapter: () => createStubAdapter("aider", [join6(home, ".aider")], ".aider.chat.history.md")
+    createAdapter: () => createStubAdapter("aider", [join7(home, ".aider")], ".aider.chat.history.md")
   }
 ];
 function getAdapterCatalog() {
@@ -2198,9 +2654,9 @@ function getActiveAdapters() {
 var activeAdapters = resolveAdapters(getDefaultAdapterIds());
 // ../shared/src/config.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "node:fs";
-import { homedir as homedir7 } from "node:os";
-import { join as join7, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { join as join8, resolve as resolve3 } from "node:path";
 
 // ../shared/src/setup/adapter-selection.ts
 init_dist2();
@@ -2264,7 +2720,7 @@ function getHomeDir() {
   if (process.env.HOMEDRIVE && process.env.HOMEPATH) {
     return `${process.env.HOMEDRIVE}${process.env.HOMEPATH}`;
   }
-  return homedir7();
+  return homedir8();
 }
 function setDevMode(dev) {
   devModeOverride = dev;
@@ -2275,16 +2731,19 @@ function isDevMode() {
   return process.env.AGENDEX_DEV === "1";
 }
 function getConfigDir() {
-  return join7(getHomeDir(), isDevMode() ? ".agendex-dev" : ".agendex");
+  const override = process.env.AGENDEX_CONFIG_DIR?.trim();
+  if (override)
+    return resolve3(expandHomePath(override));
+  return join8(getHomeDir(), isDevMode() ? ".agendex-dev" : ".agendex");
 }
 function ensureConfigDir() {
   const dir = getConfigDir();
-  if (!existsSync3(dir))
+  if (!existsSync4(dir))
     mkdirSync(dir, { recursive: true });
 }
 function readStoredConfig() {
   const cfgPath = getConfigPath();
-  if (!existsSync3(cfgPath))
+  if (!existsSync4(cfgPath))
     return null;
   try {
     const raw = JSON.parse(readFileSync3(cfgPath, "utf-8"));
@@ -2302,7 +2761,7 @@ function normalizeAdapterIds(input) {
 }
 function expandHomePath(p) {
   if (p.startsWith("~/") || p === "~")
-    return join7(getHomeDir(), p.slice(1));
+    return join8(getHomeDir(), p.slice(1));
   return p;
 }
 function resolveCustomPlanDirPath(userPath) {
@@ -2310,7 +2769,7 @@ function resolveCustomPlanDirPath(userPath) {
   if (!trimmed) {
     throw new Error("Custom plan directory path must not be empty");
   }
-  return resolve2(expandHomePath(trimmed));
+  return resolve3(expandHomePath(trimmed));
 }
 function normalizeCustomPlanDirs(input) {
   if (!Array.isArray(input))
@@ -2375,6 +2834,7 @@ function loadOrCreateToken() {
     return existing.token;
   const token = generateToken();
   saveConfig({
+    ...existing ?? {},
     configVersion: 3,
     token,
     enabledAdapters: existing?.enabledAdapters ?? [],
@@ -2401,7 +2861,7 @@ function loadOrCreateDeviceId() {
   return deviceId;
 }
 function getConfigPath() {
-  return join7(getConfigDir(), "config.json");
+  return join8(getConfigDir(), "config.json");
 }
 async function loadOrInitConfig(options = {}) {
   const configureAdapters = Boolean(options.configureAdapters);
@@ -2448,9 +2908,10 @@ async function loadOrInitConfig(options = {}) {
 var CLI_DAEMON_HEARTBEAT_INTERVAL_MS = 30000;
 var CLI_DAEMON_STALE_AFTER_MS = CLI_DAEMON_HEARTBEAT_INTERVAL_MS * 5;
 // ../shared/src/services/plan-service.ts
-import { existsSync as existsSync4, readdirSync as readdirSync3, statSync } from "node:fs";
-import { lstat, mkdir, readdir as readdir2, readFile as readFile6, stat as stat6, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join8, resolve as resolve3, sep as sep2 } from "node:path";
+import { existsSync as existsSync5, readdirSync as readdirSync3, realpathSync, statSync } from "node:fs";
+import { lstat, mkdir, readdir as readdir2, readFile as readFile7, stat as stat7, writeFile as writeFile3 } from "node:fs/promises";
+import { homedir as homedir9 } from "node:os";
+import { dirname as dirname2, join as join9, resolve as resolve4, sep as sep3 } from "node:path";
 
 // ../shared/src/services/plan-value.ts
 function isLowValuePlan(plan) {
@@ -2780,12 +3241,15 @@ function annotatePlanValueMetadata(plan) {
 
 // ../shared/src/services/plan-service.ts
 function getUserPlansDir() {
-  return join8(getConfigDir(), "plans");
+  return join9(getConfigDir(), "plans");
 }
 var store = new Map;
 var MAX_DEPTH = 6;
 var DISCOVERY_MAX_DEPTH = 4;
-var PROJECT_PLAN_MARKERS = [{ marker: ".sisyphus/plans", agent: "oh-my-opencode" }];
+var PROJECT_PLAN_MARKERS = [
+  { marker: ".sisyphus/plans", agent: "oh-my-opencode" },
+  { marker: "@plans", agent: "plannotator" }
+];
 var SKIP_DIRS = new Set([
   "node_modules",
   ".git",
@@ -2818,19 +3282,58 @@ var SKIP_DIRS = new Set([
   "Google Drive",
   "iCloud Drive"
 ]);
+function getRuntimeHomeDir() {
+  const homeFromEnv = process.env.HOME || process.env.USERPROFILE || (process.env.HOMEDRIVE && process.env.HOMEPATH ? `${process.env.HOMEDRIVE}${process.env.HOMEPATH}` : undefined);
+  return resolve4(homeFromEnv || homedir9());
+}
 function discoverProjectPlanDirs() {
-  const home2 = getHomeDir();
+  const home2 = canonicalPath(getRuntimeHomeDir());
   const results = [];
-  function walk(dir, depth) {
-    if (depth > DISCOVERY_MAX_DEPTH)
+  const seen = new Set;
+  let nearestAncestorMarkerRoot;
+  function addResult(dir, agent) {
+    const resolved = canonicalPath(dir);
+    const key = `${agent}:${resolved}`;
+    if (seen.has(key))
       return;
+    seen.add(key);
+    results.push({ dir: resolved, agent });
+  }
+  function inspectMarkers(dir) {
+    let found = false;
     for (const { marker, agent } of PROJECT_PLAN_MARKERS) {
-      const candidate = join8(dir, marker);
-      if (existsSync4(candidate)) {
-        results.push({ dir: candidate, agent });
+      const candidate = join9(dir, marker);
+      if (existsSync5(candidate)) {
+        addResult(candidate, agent);
+        found = true;
+      }
+    }
+    return found;
+  }
+  function walkAncestorsForCurrentProject() {
+    let dir = canonicalPath(process.cwd());
+    while (true) {
+      if (inspectMarkers(dir)) {
+        nearestAncestorMarkerRoot = dir;
         return;
       }
+      if (dir === home2)
+        return;
+      const parent = dirname2(dir);
+      if (parent === dir)
+        return;
+      dir = parent;
     }
+  }
+  function isAncestorOfNearestMarker(dir) {
+    return Boolean(nearestAncestorMarkerRoot?.startsWith(dir + sep3));
+  }
+  function walk(dir, depth) {
+    if (depth > DISCOVERY_MAX_DEPTH)
+      return;
+    const resolved = canonicalPath(dir);
+    if (!isAncestorOfNearestMarker(resolved) && inspectMarkers(dir))
+      return;
     let names;
     try {
       names = readdirSync3(dir);
@@ -2842,13 +3345,14 @@ function discoverProjectPlanDirs() {
         continue;
       if (SKIP_DIRS.has(name))
         continue;
-      const full = join8(dir, name);
+      const full = join9(dir, name);
       try {
         if (statSync(full).isDirectory())
           walk(full, depth + 1);
       } catch {}
     }
   }
+  walkAncestorsForCurrentProject();
   walk(home2, 0);
   return results;
 }
@@ -2862,9 +3366,9 @@ function notifyPlansChanged() {
 async function walkDir(dir, depth = 0, seen = new Set) {
   if (depth > MAX_DEPTH)
     return [];
-  if (!existsSync4(dir))
+  if (!existsSync5(dir))
     return [];
-  const real = resolve3(dir);
+  const real = resolve4(dir);
   if (seen.has(real))
     return [];
   seen.add(real);
@@ -2872,7 +3376,7 @@ async function walkDir(dir, depth = 0, seen = new Set) {
   try {
     const entries = await readdir2(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join8(dir, entry.name);
+      const full = join9(dir, entry.name);
       try {
         const stats = await lstat(full);
         if (stats.isSymbolicLink())
@@ -2889,8 +3393,8 @@ async function walkDir(dir, depth = 0, seen = new Set) {
 }
 async function parseGenericMarkdownPlan(filePath, extraMetadata) {
   try {
-    const content = await readFile6(filePath, "utf-8");
-    const stats = await stat6(filePath);
+    const content = await readFile7(filePath, "utf-8");
+    const stats = await stat7(filePath);
     let agent = (typeof extraMetadata.agentHint === "string" ? extraMetadata.agentHint : "") || "unknown";
     const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
     if (fmMatch) {
@@ -2918,7 +3422,7 @@ async function parseGenericMarkdownPlan(filePath, extraMetadata) {
 }
 async function scanUserPlans(into) {
   const userPlansDir = getUserPlansDir();
-  if (!existsSync4(userPlansDir))
+  if (!existsSync5(userPlansDir))
     return;
   const files = await walkDir(userPlansDir);
   for (const file of files) {
@@ -2932,19 +3436,27 @@ async function scanUserPlans(into) {
 function getCustomPlanDirs() {
   return loadConfig()?.customPlanDirs ?? [];
 }
+function canonicalPath(path) {
+  const resolved = resolve4(path);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
 function pathsOverlapFilesystemTree(a, b) {
-  const ra = resolve3(a);
-  const rb = resolve3(b);
+  const ra = canonicalPath(a);
+  const rb = canonicalPath(b);
   if (ra === rb)
     return true;
-  if (ra.startsWith(rb + sep2))
+  if (ra.startsWith(rb + sep3))
     return true;
-  if (rb.startsWith(ra + sep2))
+  if (rb.startsWith(ra + sep3))
     return true;
   return false;
 }
 function overlapsAnyRoot(candidate, roots) {
-  const resolvedCandidate = resolve3(candidate);
+  const resolvedCandidate = canonicalPath(candidate);
   for (const root of roots) {
     if (pathsOverlapFilesystemTree(resolvedCandidate, root))
       return true;
@@ -2953,9 +3465,9 @@ function overlapsAnyRoot(candidate, roots) {
 }
 async function scanCustomPlanDirs(coveredPaths, into) {
   const dirs = getCustomPlanDirs();
-  const userPlansDir = resolve3(getUserPlansDir());
+  const userPlansDir = canonicalPath(getUserPlansDir());
   for (const dir of dirs) {
-    const resolved = resolve3(dir);
+    const resolved = canonicalPath(dir);
     if (overlapsAnyRoot(resolved, coveredPaths)) {
       console.log(`[agendex] skipping custom dir (overlaps adapter / discovered coverage): ${dir}`);
       continue;
@@ -2964,7 +3476,7 @@ async function scanCustomPlanDirs(coveredPaths, into) {
       console.log(`[agendex] skipping custom dir (overlaps user plans): ${dir}`);
       continue;
     }
-    if (!existsSync4(dir)) {
+    if (!existsSync5(dir)) {
       console.log(`[agendex] skipping custom dir (not found): ${dir}`);
       continue;
     }
@@ -2993,7 +3505,7 @@ async function scan() {
   const coveredPaths = new Set;
   for (const adapter of adapters) {
     for (const searchPath of adapter.getSearchPaths()) {
-      coveredPaths.add(resolve3(searchPath));
+      coveredPaths.add(canonicalPath(searchPath));
       const files = await walkDir(searchPath);
       for (const file of files) {
         if (!adapter.matches(file))
@@ -3008,7 +3520,7 @@ async function scan() {
   }
   const discovered = discoverProjectPlanDirs();
   for (const { dir, agent } of discovered) {
-    const resolvedDir = resolve3(dir);
+    const resolvedDir = canonicalPath(dir);
     if (coveredPaths.has(resolvedDir))
       continue;
     const adapter = adapters.find((a) => a.agent === agent);
@@ -3042,29 +3554,86 @@ function getAll() {
 function getIndexablePlans() {
   return getAll().filter(isIndexablePlan);
 }
+function getById(id) {
+  return store.get(id);
+}
+function getPlanSourceAdapter(plan) {
+  const sourceAdapter = plan.metadata.sourceAdapter;
+  return typeof sourceAdapter === "string" && sourceAdapter.trim() ? sourceAdapter : undefined;
+}
+function findAdapterForPlan(plan) {
+  const adapters = getActiveAdapters();
+  const sourceAdapter = getPlanSourceAdapter(plan);
+  return adapters.find((adapter) => adapter.agent === sourceAdapter) ?? adapters.find((adapter) => adapter.agent === plan.agent);
+}
+async function requestChanges(id, payload) {
+  const plan = store.get(id);
+  if (!plan)
+    return false;
+  const adapter = findAdapterForPlan(plan);
+  if (!adapter?.requestChanges)
+    return false;
+  const ok = await adapter.requestChanges(plan, payload);
+  if (ok) {
+    const plannotator = typeof plan.metadata.plannotator === "object" && plan.metadata.plannotator !== null ? { ...plan.metadata.plannotator, lastWritebackStatus: "sent", lastWritebackAt: Date.now() } : undefined;
+    if (plannotator)
+      plan.metadata = { ...plan.metadata, plannotator };
+    plan.updatedAt = new Date;
+    notifyPlansChanged();
+  }
+  return ok;
+}
+function planBelongsToAdapter(plan, adapter) {
+  if (plan.agent === adapter.agent)
+    return true;
+  return adapter.agent === "plannotator" && typeof plan.metadata.plannotator === "object" && plan.metadata.plannotator !== null;
+}
+function removePlansForPath(filePath, adapter) {
+  const normalized = resolve4(filePath);
+  const removed = [];
+  for (const [id, plan] of store.entries()) {
+    const planPath = resolve4(plan.filePath);
+    const sessionPath = typeof plan.metadata.plannotator === "object" && plan.metadata.plannotator !== null ? plan.metadata.plannotator.sessionPath : undefined;
+    if ((planPath === normalized || sessionPath === normalized) && (!adapter || planBelongsToAdapter(plan, adapter))) {
+      removed.push(plan);
+      store.delete(id);
+    }
+  }
+  if (removed.length > 0)
+    notifyPlansChanged();
+  return removed;
+}
 async function rescanFile(filePath) {
   const adapters = getActiveAdapters();
-  const normalized = resolve3(filePath);
+  const normalized = resolve4(filePath);
+  const removedPlans = [];
   for (const adapter of adapters) {
     if (!adapter.matches(filePath))
       continue;
-    const discoveredDirs = discoverProjectPlanDirs().filter((d2) => d2.agent === adapter.agent).map((d2) => resolve3(d2.dir));
+    const discoveredDirs = discoverProjectPlanDirs().filter((d2) => d2.agent === adapter.agent).map((d2) => resolve4(d2.dir));
     const allSearchPaths = [
-      ...adapter.getSearchPaths().map((sp) => resolve3(sp)),
+      ...adapter.getSearchPaths().map((sp) => resolve4(sp)),
       ...discoveredDirs
     ];
-    const isInSearchPath = allSearchPaths.some((sp) => normalized.startsWith(sp + sep2) || normalized === sp);
+    const isInSearchPath = allSearchPaths.some((sp) => normalized.startsWith(sp + sep3) || normalized === sp);
     if (!isInSearchPath)
       continue;
-    const plans = (await adapter.parse(filePath)).map(annotatePlanValueMetadata);
+    const rawPlans = await adapter.parse(filePath);
+    if (rawPlans.length === 0) {
+      removedPlans.push(...removePlansForPath(filePath, adapter));
+      continue;
+    }
+    const plans = rawPlans.map(annotatePlanValueMetadata);
     for (const plan of plans) {
       store.set(plan.id, plan);
     }
     notifyPlansChanged();
     return plans;
   }
-  const userPlansDir = resolve3(getUserPlansDir());
-  if (normalized.endsWith(".md") && (normalized.startsWith(userPlansDir + sep2) || normalized === userPlansDir)) {
+  if (removedPlans.length > 0)
+    return removedPlans;
+  const userPlansDir = resolve4(getUserPlansDir());
+  if (normalized.endsWith(".md") && (normalized.startsWith(userPlansDir + sep3) || normalized === userPlansDir)) {
     const plan = await parseGenericMarkdownPlan(filePath, { userCreated: true });
     if (plan) {
       store.set(plan.id, plan);
@@ -3075,8 +3644,8 @@ async function rescanFile(filePath) {
   if (normalized.endsWith(".md")) {
     const customDirs = getCustomPlanDirs();
     for (const dir of customDirs) {
-      const resolvedDir = resolve3(dir);
-      if (normalized.startsWith(resolvedDir + sep2) || normalized === resolvedDir) {
+      const resolvedDir = resolve4(dir);
+      if (normalized.startsWith(resolvedDir + sep3) || normalized === resolvedDir) {
         const plan = await parseGenericMarkdownPlan(filePath, {
           source: "custom-dir",
           customDir: dir
@@ -3092,8 +3661,8 @@ async function rescanFile(filePath) {
   return [];
 }
 // ../shared/src/services/watcher.ts
-import { existsSync as existsSync5, watch } from "node:fs";
-import { join as join9, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync6, watch } from "node:fs";
+import { join as join10, resolve as resolve5 } from "node:path";
 var debounceTimer = null;
 var pendingFiles = new Set;
 var activeWatchers = [];
@@ -3111,13 +3680,13 @@ function closeAllWatchers() {
   activeWatchers.length = 0;
 }
 function watchDir(dir, matchFn, onChange) {
-  if (!existsSync5(dir))
+  if (!existsSync6(dir))
     return;
   try {
     const watcher = watch(dir, { recursive: true }, async (_event, filename) => {
       if (!filename)
         return;
-      const fullPath = join9(dir, filename);
+      const fullPath = join10(dir, filename);
       if (!matchFn(fullPath))
         return;
       pendingFiles.add(fullPath);
@@ -3150,23 +3719,23 @@ function setupWatchers(onChange) {
   const watchedPaths = new Set;
   for (const adapter of adapters) {
     for (const watchPath of adapter.getWatchPaths()) {
-      watchedPaths.add(resolve4(watchPath));
+      watchedPaths.add(resolve5(watchPath));
       watchDir(watchPath, (f) => adapter.matches(f), onChange);
     }
   }
   const discovered = discoverProjectPlanDirs();
   for (const { dir, agent } of discovered) {
-    if (watchedPaths.has(resolve4(dir)))
+    if (watchedPaths.has(resolve5(dir)))
       continue;
     const adapter = adapters.find((a) => a.agent === agent);
     if (!adapter)
       continue;
-    watchedPaths.add(resolve4(dir));
+    watchedPaths.add(resolve5(dir));
     watchDir(dir, (f) => adapter.matches(f), onChange);
   }
   const customDirs = getCustomPlanDirs();
   for (const dir of customDirs) {
-    const resolvedCustom = resolve4(dir);
+    const resolvedCustom = resolve5(dir);
     let overlaps = false;
     for (const watched of watchedPaths) {
       if (pathsOverlapFilesystemTree(resolvedCustom, watched)) {
@@ -3186,15 +3755,15 @@ import { request as httpsRequest } from "node:https";
 import { hostname as osHostname } from "node:os";
 
 // src/pid.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { hostname } from "node:os";
-import { dirname, join as join10 } from "node:path";
+import { dirname as dirname3, join as join11 } from "node:path";
 function getPidPath() {
-  return join10(getConfigDir(), "daemon.pid");
+  return join11(getConfigDir(), "daemon.pid");
 }
 function writePid() {
   const path = getPidPath();
-  mkdirSync2(dirname(path), { recursive: true });
+  mkdirSync2(dirname3(path), { recursive: true });
   const info = {
     pid: process.pid,
     startedAtMs: Date.now(),
@@ -3204,7 +3773,7 @@ function writePid() {
 }
 function readPidInfo() {
   const path = getPidPath();
-  if (!existsSync6(path))
+  if (!existsSync7(path))
     return null;
   const raw = readFileSync4(path, "utf-8").trim();
   const asNumber = Number(raw);
@@ -3356,6 +3925,7 @@ async function sendHeartbeat() {
 }
 async function sendShutdown() {
   try {
+    getCloudConfig();
     cachedDeviceId ??= loadOrCreateDeviceId();
     await deleteDaemons([cachedDeviceId]);
   } catch {}
@@ -3376,6 +3946,7 @@ async function refreshToken(currentToken, convexUrl) {
     return null;
   return { token: body.token, expiresAt: body.expiresAt ?? 0 };
 }
+var REQUEST_TIMEOUT_MS2 = Number.parseInt(process.env.AGENDEX_HTTP_TIMEOUT_MS ?? "", 10) || 1e4;
 function requestText(urlString, options) {
   const url = new URL(urlString);
   const request = url.protocol === "https:" ? httpsRequest : httpRequest;
@@ -3383,11 +3954,12 @@ function requestText(urlString, options) {
   if (options.body) {
     headers["Content-Length"] = String(Buffer.byteLength(options.body));
   }
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const req = request(url, {
       agent: false,
       headers,
-      method: options.method
+      method: options.method,
+      timeout: REQUEST_TIMEOUT_MS2
     }, (res) => {
       let body = "";
       res.setEncoding("utf8");
@@ -3395,7 +3967,7 @@ function requestText(urlString, options) {
         body += chunk;
       });
       res.on("end", () => {
-        resolve5({
+        resolve6({
           status: res.statusCode ?? 0,
           body
         });
@@ -3403,12 +3975,71 @@ function requestText(urlString, options) {
       res.on("error", reject);
     });
     req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy(new Error(`Request to ${url.host} timed out after ${REQUEST_TIMEOUT_MS2}ms`));
+    });
     if (options.body) {
       req.write(options.body);
     }
     req.end();
   });
 }
+function authHeaders(token, contentType = false) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Connection: "close",
+    ...contentType && { "Content-Type": "application/json" }
+  };
+}
+async function fetchPlannotatorWritebacks(limit = 10) {
+  const { token, convexUrl } = getCloudConfig();
+  cachedDeviceId ??= loadOrCreateDeviceId();
+  const url = `${convexUrl}/api/cli/plannotator/writebacks?deviceId=${encodeURIComponent(cachedDeviceId)}&limit=${limit}`;
+  let activeToken = token;
+  let res = await requestText(url, {
+    method: "GET",
+    headers: authHeaders(activeToken)
+  });
+  if (res.status === 401) {
+    const refreshed = await refreshStoredToken(activeToken, convexUrl);
+    if (refreshed) {
+      activeToken = refreshed;
+      res = await requestText(url, {
+        method: "GET",
+        headers: authHeaders(activeToken)
+      });
+    }
+  }
+  if (res.status === 401)
+    throw new AuthExpiredError;
+  if (res.status < 200 || res.status >= 300)
+    return [];
+  const body = JSON.parse(res.body);
+  return body.writebacks ?? [];
+}
+async function reportPlannotatorWriteback(writebackId, status, error) {
+  const { token, convexUrl } = getCloudConfig();
+  const url = `${convexUrl}/api/cli/plannotator/writebacks/report`;
+  let activeToken = token;
+  const body = JSON.stringify({ writebackId, status, error });
+  let res = await requestText(url, {
+    method: "POST",
+    headers: authHeaders(activeToken, true),
+    body
+  });
+  if (res.status === 401) {
+    const refreshed = await refreshStoredToken(activeToken, convexUrl);
+    if (refreshed) {
+      activeToken = refreshed;
+      res = await requestText(url, {
+        method: "POST",
+        headers: authHeaders(activeToken, true),
+        body
+      });
+    }
+  }
+  return res.status >= 200 && res.status < 300;
+}
 async function fetchDevices() {
   const { token, convexUrl } = getCloudConfig();
   const url = `${convexUrl}/api/cli/devices`;
@@ -3509,6 +4140,7 @@ async function login(siteUrlOverride) {
     token: existing?.token,
     cloudToken: callback.token,
     convexUrl: callback.convexUrl,
+    deviceId: existing?.deviceId,
     enabledAdapters: existing?.enabledAdapters ?? [],
     customPlanDirs: existing?.customPlanDirs ?? []
   };
@@ -3527,6 +4159,7 @@ function logout() {
     token: existing.token,
     cloudToken: undefined,
     convexUrl: undefined,
+    deviceId: existing.deviceId,
     enabledAdapters: existing.enabledAdapters,
     customPlanDirs: existing.customPlanDirs
   };
@@ -3539,14 +4172,14 @@ async function startCallbackServer() {
   let timeout;
   let settle;
   let fail;
-  const result = new Promise((resolve5, reject) => {
-    settle = resolve5;
+  const result = new Promise((resolve6, reject) => {
+    settle = resolve6;
     fail = reject;
   });
   const finish = (value) => {
     if (!settle || !fail)
       return;
-    const resolve5 = settle;
+    const resolve6 = settle;
     const reject = fail;
     settle = undefined;
     fail = undefined;
@@ -3563,7 +4196,7 @@ async function startCallbackServer() {
       reject(value);
       return;
     }
-    resolve5(value);
+    resolve6(value);
   };
   server.on("request", (req, res) => {
     const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -3597,8 +4230,8 @@ async function startCallbackServer() {
       sockets.delete(socket);
     });
   });
-  await new Promise((resolve5, reject) => {
-    server.listen(0, "127.0.0.1", () => resolve5());
+  await new Promise((resolve6, reject) => {
+    server.listen(0, "127.0.0.1", () => resolve6());
     server.once("error", reject);
   });
   server.once("error", (error) => {
@@ -3678,19 +4311,77 @@ function spawnBrowser(command, args, options = {}) {
 
 // src/daemon.ts
 import { spawn as spawn2 } from "node:child_process";
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve6 } from "node:path";
 import { fileURLToPath } from "node:url";
 
+// src/adapters.ts
+var PLANNOTATOR_ADAPTER_ID = "plannotator";
+function envFlag(name) {
+  const value = process.env[name]?.trim().toLowerCase();
+  if (!value)
+    return;
+  if (value === "1" || value === "true" || value === "yes" || value === "on")
+    return true;
+  if (value === "0" || value === "false" || value === "no" || value === "off")
+    return false;
+  return;
+}
+function shouldEnablePlannotatorSync(config) {
+  const explicit = envFlag("AGENDEX_PLANNOTATOR_SYNC");
+  if (explicit !== undefined)
+    return explicit;
+  return Boolean(config.cloudToken && config.convexUrl);
+}
+function resolveCliAdapterIds(config) {
+  const ids = config.enabledAdapters.length > 0 ? [...config.enabledAdapters] : getDefaultAdapterIds();
+  if (shouldEnablePlannotatorSync(config) && !ids.includes(PLANNOTATOR_ADAPTER_ID)) {
+    ids.push(PLANNOTATOR_ADAPTER_ID);
+  }
+  return ids;
+}
+
+// src/payload.ts
+var SYNC_METADATA_KEY = "agendexSync";
+function isRecord4(value) {
+  return typeof value === "object" && value !== null;
+}
+function withSyncDeviceMetadata(metadata, deviceId) {
+  if (!deviceId)
+    return metadata;
+  const existing = isRecord4(metadata[SYNC_METADATA_KEY]) ? metadata[SYNC_METADATA_KEY] : {};
+  return {
+    ...metadata,
+    [SYNC_METADATA_KEY]: {
+      ...existing,
+      deviceId
+    }
+  };
+}
+function planToSyncPayload(plan, deviceId) {
+  return {
+    localPlanId: plan.id,
+    agent: plan.agent,
+    title: plan.title,
+    content: plan.content,
+    format: plan.format,
+    filePath: plan.filePath,
+    workspace: plan.workspace,
+    metadata: withSyncDeviceMetadata(plan.metadata, deviceId),
+    createdAt: plan.createdAt.getTime(),
+    updatedAt: plan.updatedAt.getTime()
+  };
+}
+
 // src/sync-cache.ts
 import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join12 } from "node:path";
 function getCachePath() {
-  return join11(getConfigDir(), "sync-cache.json");
+  return join12(getConfigDir(), "sync-cache.json");
 }
 function loadSyncCache() {
   const cachePath = getCachePath();
-  if (!existsSync7(cachePath))
+  if (!existsSync8(cachePath))
     return {};
   try {
     const raw = JSON.parse(readFileSync5(cachePath, "utf-8"));
@@ -3703,7 +4394,7 @@ function loadSyncCache() {
 }
 function saveSyncCache(cache, options) {
   const dir = getConfigDir();
-  if (!existsSync7(dir))
+  if (!existsSync8(dir))
     mkdirSync3(dir, { recursive: true });
   const cachePath = getCachePath();
   if (options?.replace) {
@@ -3729,32 +4420,71 @@ function computePayloadHash(payload) {
   return createHash2("sha256").update(canonical).digest("hex").slice(0, 20);
 }
 
+// src/writeback-delivery-cache.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join13 } from "node:path";
+var MAX_PENDING_WRITEBACK_REPORTS = 1000;
+function getCachePath2() {
+  return join13(getConfigDir(), "plannotator-writebacks-delivered.json");
+}
+function isPendingWritebackReportStatus(value) {
+  return value === "sent" || value === "failed" || value === "expired";
+}
+function normalizeReports(input) {
+  if (!Array.isArray(input))
+    return [];
+  const reports = new Map;
+  for (const item of input) {
+    if (typeof item === "string" && item.length > 0) {
+      reports.set(item, "sent");
+      continue;
+    }
+    if (item && typeof item === "object" && "id" in item && "status" in item && typeof item.id === "string" && item.id.length > 0 && isPendingWritebackReportStatus(item.status)) {
+      reports.set(item.id, item.status);
+    }
+  }
+  return [...reports.entries()].slice(-MAX_PENDING_WRITEBACK_REPORTS);
+}
+function loadPendingWritebackReports() {
+  const cachePath = getCachePath2();
+  if (!existsSync9(cachePath))
+    return new Map;
+  try {
+    return new Map(normalizeReports(JSON.parse(readFileSync6(cachePath, "utf-8"))));
+  } catch {
+    return new Map;
+  }
+}
+function savePendingWritebackReports(reports) {
+  try {
+    const dir = getConfigDir();
+    if (!existsSync9(dir))
+      mkdirSync4(dir, { recursive: true });
+    const normalizedReports = normalizeReports([...reports].map(([id, status]) => ({ id, status })));
+    writeFileSync4(getCachePath2(), JSON.stringify(normalizedReports.map(([id, status]) => ({ id, status }))));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/daemon.ts
 var MAX_RESTARTS = 5;
 var RESTART_WINDOW_MS = 60000;
 var RESTART_DELAY_MS = 5000;
-function planToPayload(plan) {
-  return {
-    localPlanId: plan.id,
-    agent: plan.agent,
-    title: plan.title,
-    content: plan.content,
-    format: plan.format,
-    filePath: plan.filePath,
-    workspace: plan.workspace,
-    metadata: plan.metadata,
-    createdAt: plan.createdAt.getTime(),
-    updatedAt: plan.updatedAt.getTime()
-  };
-}
+var PLANNOTATOR_WRITEBACK_POLL_INTERVAL_MS = 15000;
+var PLANNOTATOR_WRITEBACK_EXPIRED_ERROR = "Write-back expired before delivery.";
+var PLANNOTATOR_WRITEBACK_FAILED_ERROR = "No live Plannotator session accepted the request-changes payload.";
 async function runWorker() {
   const config = await loadOrInitConfig();
-  const adapters = resolveAdapters(config.enabledAdapters);
+  const adapterIds = resolveCliAdapterIds(config);
+  const adapters = resolveAdapters(adapterIds);
   setActiveAdapters(adapters);
-  console.log(`[agendex] daemon starting with ${config.enabledAdapters.length} adapters`);
+  console.log(`[agendex] daemon starting with ${adapterIds.length} adapters`);
   await sendHeartbeat();
   const syncCache = loadSyncCache();
   const syncQueue = [];
+  const pendingWritebackReports = loadPendingWritebackReports();
   let syncing = false;
   async function tryRefreshToken() {
     const cfg = loadConfig();
@@ -3819,6 +4549,89 @@ async function runWorker() {
     if (syncQueue.length > 0)
       processSyncQueue();
   }
+  function persistPendingWritebackReports() {
+    if (!savePendingWritebackReports(pendingWritebackReports)) {
+      console.error("[agendex] failed to persist Plannotator write-back delivery cache");
+    }
+  }
+  async function reportPendingWriteback(writebackId) {
+    const status = pendingWritebackReports.get(writebackId);
+    if (!status)
+      return;
+    const reported = await reportPlannotatorWriteback(writebackId, status, status === "expired" ? PLANNOTATOR_WRITEBACK_EXPIRED_ERROR : status === "failed" ? PLANNOTATOR_WRITEBACK_FAILED_ERROR : undefined);
+    if (reported) {
+      pendingWritebackReports.delete(writebackId);
+      persistPendingWritebackReports();
+    } else {
+      console.error("[agendex] failed to report write-back status for", writebackId, "- will retry");
+    }
+  }
+  async function handlePlannotatorWriteback(job) {
+    if (pendingWritebackReports.has(job._id)) {
+      await reportPendingWriteback(job._id);
+      return;
+    }
+    if (job.expiresAt <= Date.now()) {
+      pendingWritebackReports.set(job._id, "expired");
+      persistPendingWritebackReports();
+      await reportPendingWriteback(job._id);
+      return;
+    }
+    let localPlan = getById(job.localPlanId);
+    if (!localPlan) {
+      await scan();
+      localPlan = getById(job.localPlanId);
+    }
+    if (!localPlan) {
+      if (job.deviceId) {
+        pendingWritebackReports.set(job._id, "failed");
+        persistPendingWritebackReports();
+        await reportPendingWriteback(job._id);
+      }
+      return;
+    }
+    const ok = await requestChanges(job.localPlanId, {
+      feedback: job.feedback,
+      revisedContent: job.revisedContent,
+      annotations: job.annotations,
+      source: job.source,
+      writebackId: job._id,
+      requestedAt: Date.now()
+    });
+    if (ok) {
+      const updatedPlan = getById(job.localPlanId);
+      if (updatedPlan)
+        syncQueue.push(planToSyncPayload(updatedPlan, config.deviceId));
+      pendingWritebackReports.set(job._id, "sent");
+      persistPendingWritebackReports();
+      await reportPendingWriteback(job._id);
+      processSyncQueue();
+      return;
+    }
+    pendingWritebackReports.set(job._id, "failed");
+    persistPendingWritebackReports();
+    await reportPendingWriteback(job._id);
+  }
+  let pollingWritebacks = false;
+  async function pollPlannotatorWritebacks() {
+    if (pollingWritebacks)
+      return;
+    pollingWritebacks = true;
+    try {
+      const jobs = await fetchPlannotatorWritebacks();
+      for (const job of jobs) {
+        await handlePlannotatorWriteback(job);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === "AuthExpiredError") {
+        console.error("[agendex] session expired. Run `agendex login` to re-authenticate.");
+      } else {
+        console.error("[agendex] Plannotator write-back polling failed:", err);
+      }
+    } finally {
+      pollingWritebacks = false;
+    }
+  }
   setOnPlansChanged(() => {});
   console.log(`[agendex] initial scan...`);
   await scan();
@@ -3829,7 +4642,7 @@ async function runWorker() {
   let initialQueuedSyncable = 0;
   let initialQueuedLowValue = 0;
   for (const plan of plans) {
-    const payload = planToPayload(plan);
+    const payload = planToSyncPayload(plan, config.deviceId);
     const hash = computePayloadHash(payload);
     if (syncCache[plan.id] === hash) {
       initialSkipped++;
@@ -3852,9 +4665,13 @@ async function runWorker() {
   console.log(`[agendex] syncing ${initialQueuedSyncable} plans${lowValueSuffix} (${initialQueuedLowValue} low-value queued, ${initialSkipped} unchanged)...`);
   await processSyncQueue();
   setInterval(() => void sendHeartbeat(), CLI_DAEMON_HEARTBEAT_INTERVAL_MS);
+  if (shouldEnablePlannotatorSync(config)) {
+    setInterval(() => void pollPlannotatorWritebacks(), PLANNOTATOR_WRITEBACK_POLL_INTERVAL_MS);
+    pollPlannotatorWritebacks();
+  }
   startWatching((changedPlans) => {
     for (const plan of changedPlans) {
-      syncQueue.push(planToPayload(plan));
+      syncQueue.push(planToSyncPayload(plan, config.deviceId));
     }
     processSyncQueue();
   });
@@ -3884,17 +4701,17 @@ async function startSupervisor() {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
-  const scriptPath = resolve5(process.argv[1] ?? fileURLToPath(new URL("./cli.ts", import.meta.url)));
+  const scriptPath = resolve6(process.argv[1] ?? fileURLToPath(new URL("./cli.ts", import.meta.url)));
   const restartTimes = [];
   while (!stopping) {
     workerProc = spawn2(process.execPath, [scriptPath, "start", "--worker"], {
       stdio: ["ignore", "inherit", "inherit"]
     });
-    const exitCode = await new Promise((resolve6) => {
-      workerProc?.once("exit", (code) => resolve6(code));
+    const exitCode = await new Promise((resolve7) => {
+      workerProc?.once("exit", (code) => resolve7(code));
       workerProc?.once("error", (error) => {
         console.error("[agendex] failed to spawn worker:", error);
-        resolve6(1);
+        resolve7(1);
       });
     });
     workerProc = null;
@@ -3917,23 +4734,10 @@ async function startSupervisor() {
 }
 
 // src/sync.ts
-function planToPayload2(plan) {
-  return {
-    localPlanId: plan.id,
-    agent: plan.agent,
-    title: plan.title,
-    content: plan.content,
-    format: plan.format,
-    filePath: plan.filePath,
-    workspace: plan.workspace,
-    metadata: plan.metadata,
-    createdAt: plan.createdAt.getTime(),
-    updatedAt: plan.updatedAt.getTime()
-  };
-}
 async function syncAll(force = false) {
   const config = await loadOrInitConfig();
-  const adapters = resolveAdapters(config.enabledAdapters);
+  const adapterIds = resolveCliAdapterIds(config);
+  const adapters = resolveAdapters(adapterIds);
   setActiveAdapters(adapters);
   console.log(`[agendex] Scanning local plans...`);
   await scan();
@@ -3951,7 +4755,7 @@ async function syncAll(force = false) {
   let failed = 0;
   for (const plan of [...syncablePlans, ...lowValuePlans]) {
     activePlanIds.add(plan.id);
-    const payload = planToPayload2(plan);
+    const payload = planToSyncPayload(plan, config.deviceId);
     const hash = computePayloadHash(payload);
     if (!force && cache[plan.id] === hash) {
       skipped++;
@@ -3981,14 +4785,20 @@ async function syncAll(force = false) {
   console.log(`[agendex] Sync complete: ${synced} synced${lowValueSuffix}, ${skipped} unchanged, ${failed} failed`);
 }
 
+// src/upgrade.ts
+import { spawn as spawn3, spawnSync } from "node:child_process";
+import { realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname4, resolve as resolve7, sep as sep4 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
 // src/version.ts
-import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join14 } from "node:path";
 // package.json
 var package_default = {
   name: "agendex-cli",
-  version: "0.14.0",
+  version: "0.16.0",
   description: "Agendex CLI for login, sync, and daemon workflows",
   homepage: "https://github.com/Tyru5/Agendex#readme",
   repository: {
@@ -4032,14 +4842,14 @@ var package_default = {
 
 // src/version.ts
 var CLI_VERSION = package_default.version;
-var CACHE_FILE = process.env.AGENDEX_UPDATE_CACHE_FILE ?? join12(tmpdir(), ".agendex-update-cache.json");
+var CACHE_FILE = process.env.AGENDEX_UPDATE_CACHE_FILE ?? join14(tmpdir(), ".agendex-update-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 var UPDATE_URL = process.env.AGENDEX_UPDATE_URL ?? "https://registry.npmjs.org/agendex-cli/latest";
 function readCache(current) {
   try {
-    if (!existsSync8(CACHE_FILE))
+    if (!existsSync10(CACHE_FILE))
       return null;
-    const { result, ts } = JSON.parse(readFileSync6(CACHE_FILE, "utf8"));
+    const { result, ts } = JSON.parse(readFileSync7(CACHE_FILE, "utf8"));
     if (Date.now() - ts > CACHE_TTL_MS)
       return null;
     return normalizeResult(result, current);
@@ -4049,14 +4859,16 @@ function readCache(current) {
 }
 function writeCache(result) {
   try {
-    writeFileSync4(CACHE_FILE, JSON.stringify({ result, ts: Date.now() }));
+    writeFileSync5(CACHE_FILE, JSON.stringify({ result, ts: Date.now() }));
   } catch {}
 }
-async function checkForUpdate() {
+async function checkForUpdate(options = {}) {
   const current = CLI_VERSION;
-  const cached = readCache(current);
-  if (cached)
-    return cached;
+  if (!options.forceRefresh) {
+    const cached = readCache(current);
+    if (cached)
+      return cached;
+  }
   try {
     const controller = new AbortController;
     const timeout = setTimeout(() => controller.abort(), 3000);
@@ -4064,21 +4876,27 @@ async function checkForUpdate() {
       signal: controller.signal
     }).finally(() => clearTimeout(timeout));
     if (!res.ok) {
-      return { updateAvailable: false, current, latest: current };
+      return { checked: false, updateAvailable: false, current, latest: current };
     }
     const data = await res.json();
     const latest = data.version;
-    const result = { updateAvailable: isNewer(latest, current), current, latest };
+    const result = {
+      checked: true,
+      updateAvailable: isNewer(latest, current),
+      current,
+      latest
+    };
     writeCache(result);
     return result;
   } catch {
-    return { updateAvailable: false, current, latest: current };
+    return { checked: false, updateAvailable: false, current, latest: current };
   }
 }
 function normalizeResult(result, current) {
   if (typeof result.latest !== "string")
     return null;
   return {
+    checked: true,
     updateAvailable: isNewer(result.latest, current),
     current,
     latest: result.latest
@@ -4098,6 +4916,195 @@ function isNewer(latest, current) {
   return false;
 }
 
+// src/upgrade.ts
+var PACKAGE_NAME = "agendex-cli";
+var moduleDir = dirname4(fileURLToPath2(import.meta.url));
+function getPackageRoot() {
+  try {
+    return realpathSync2(resolve7(moduleDir, ".."));
+  } catch {
+    return resolve7(moduleDir, "..");
+  }
+}
+function detectPackageManager(packageRoot) {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  const execpath = process.env.npm_execpath ?? "";
+  if (userAgent.startsWith("bun/") || execpath.includes("bun"))
+    return "bun";
+  if (userAgent.startsWith("pnpm/") || execpath.includes("pnpm"))
+    return "pnpm";
+  if (userAgent.startsWith("yarn/") || execpath.includes("yarn"))
+    return "yarn";
+  const lower = packageRoot.toLowerCase();
+  if (lower.includes(`${sep4}.bun${sep4}`) || lower.includes("/.bun/"))
+    return "bun";
+  if (lower.includes(`${sep4}pnpm${sep4}`) || lower.includes("/pnpm/"))
+    return "pnpm";
+  if (lower.includes(`${sep4}yarn${sep4}`) || lower.includes("/yarn/"))
+    return "yarn";
+  if (typeof globalThis.Bun !== "undefined" || process.versions.bun) {
+    return "bun";
+  }
+  return "npm";
+}
+function readYarnVersion() {
+  const result = spawnSync("yarn", ["--version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32"
+  });
+  if (result.error || result.status !== 0)
+    return null;
+  return result.stdout.trim() || null;
+}
+function parseMajorVersion(version) {
+  const match = version.match(/^(\d+)/);
+  if (!match)
+    return null;
+  const major = Number(match[1]);
+  return Number.isFinite(major) ? major : null;
+}
+function buildGlobalInstallCommand(pm) {
+  const pkgSpec = `${PACKAGE_NAME}@latest`;
+  switch (pm) {
+    case "bun":
+      return {
+        supported: true,
+        command: { bin: "bun", args: ["add", "-g", pkgSpec], display: `bun add -g ${pkgSpec}` }
+      };
+    case "pnpm":
+      return {
+        supported: true,
+        command: {
+          bin: "pnpm",
+          args: ["add", "-g", pkgSpec],
+          display: `pnpm add -g ${pkgSpec}`
+        }
+      };
+    case "yarn": {
+      const yarnVersion = readYarnVersion();
+      const yarnMajorVersion = yarnVersion ? parseMajorVersion(yarnVersion) : null;
+      if (yarnMajorVersion !== null && yarnMajorVersion >= 2) {
+        return {
+          supported: false,
+          reason: `automatic upgrade with Yarn only supports Yarn Classic (v1); detected Yarn v${yarnVersion}.`,
+          manualCommand: `npm install -g ${pkgSpec}`
+        };
+      }
+      return {
+        supported: true,
+        command: {
+          bin: "yarn",
+          args: ["global", "add", pkgSpec],
+          display: `yarn global add ${pkgSpec}`
+        }
+      };
+    }
+    default:
+      return {
+        supported: true,
+        command: {
+          bin: "npm",
+          args: ["install", "-g", pkgSpec],
+          display: `npm install -g ${pkgSpec}`
+        }
+      };
+  }
+}
+function isLikelyGlobalInstall(packageRoot) {
+  const normalized = packageRoot.replace(/\\/g, "/");
+  if (!normalized.includes("/node_modules/")) {
+    return false;
+  }
+  const globalMarkers = [
+    "/lib/node_modules/",
+    "/pnpm/global/",
+    "/yarn/global/",
+    "/.bun/install/global/",
+    "/.bun/install/",
+    "/.config/yarn/global/",
+    "/AppData/Roaming/npm/",
+    "/AppData/Local/Yarn/",
+    "/AppData/Local/pnpm/"
+  ];
+  return globalMarkers.some((marker) => normalized.includes(marker));
+}
+async function runUpgrade(opts) {
+  const packageRoot = getPackageRoot();
+  const pm = detectPackageManager(packageRoot);
+  const isGlobal = isLikelyGlobalInstall(packageRoot);
+  if (!isGlobal) {
+    process.stderr.write(`[agendex] this CLI appears to be running from a local checkout or linked install:
+` + `[agendex]   ${packageRoot}
+` + `[agendex] automatic upgrade only supports global installs.
+` + `[agendex] reinstall globally (e.g. \`npm install -g ${PACKAGE_NAME}@latest\`) or update the source repo manually.
+`);
+    return 1;
+  }
+  const { checked, updateAvailable, current, latest } = await checkForUpdate({
+    forceRefresh: true
+  });
+  if (checked && !updateAvailable && !opts.force) {
+    process.stdout.write(`[agendex] already up to date (v${current})
+`);
+    return 0;
+  }
+  if (!checked) {
+    process.stderr.write(`[agendex] could not verify the latest version; attempting upgrade anyway...
+`);
+  }
+  const commandResult = buildGlobalInstallCommand(pm);
+  if (!commandResult.supported) {
+    process.stderr.write(`[agendex] ${commandResult.reason}
+`);
+    process.stderr.write(`[agendex] install the latest CLI manually, e.g. \`${commandResult.manualCommand}\`.
+`);
+    return 1;
+  }
+  const cmd = commandResult.command;
+  if (checked && updateAvailable) {
+    process.stdout.write(`[agendex] upgrading: v${current} → v${latest}
+`);
+  } else if (opts.force) {
+    process.stdout.write(`[agendex] reinstalling v${CLI_VERSION} (forced)
+`);
+  }
+  process.stdout.write(`[agendex] running: ${cmd.display}
+`);
+  return await new Promise((resolveExit) => {
+    const child = spawn3(cmd.bin, cmd.args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: process.env
+    });
+    let didError = false;
+    child.on("error", (err) => {
+      didError = true;
+      process.stderr.write(`[agendex] failed to run ${cmd.bin}: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.stderr.write(`[agendex] you can run it manually: ${cmd.display}
+`);
+      resolveExit(1);
+    });
+    child.on("close", (code) => {
+      if (didError)
+        return;
+      if (code === 0) {
+        process.stdout.write(`[agendex] upgrade complete.
+`);
+        process.stdout.write(`[agendex] note: if the daemon is running, restart it: \`agendex stop && agendex start\`
+`);
+        resolveExit(0);
+        return;
+      }
+      process.stderr.write(`[agendex] upgrade failed with exit code ${code ?? "unknown"}
+`);
+      process.stderr.write(`[agendex] you can run it manually: ${cmd.display}
+`);
+      resolveExit(code ?? 1);
+    });
+  });
+}
+
 // src/web.ts
 async function openAgendexWeb(siteUrlOverride) {
   const base = siteUrlOverride ?? getDefaultSiteUrl();
@@ -4135,7 +5142,7 @@ function firstCommandToken(argv) {
   return;
 }
 var command = firstCommandToken(args) ?? "start";
-var cliEntry = resolve6(process.argv[1] ?? fileURLToPath2(import.meta.url));
+var cliEntry = resolve8(process.argv[1] ?? fileURLToPath3(import.meta.url));
 async function main() {
   const isInternal = args.includes("--daemon") || args.includes("--worker");
   if (command === "--version" || command === "-v") {
@@ -4153,16 +5160,16 @@ async function main() {
     "add-dir",
     "remove-dir",
     "list-dirs",
+    "upgrade",
     "help",
     "--help",
     "-h"
   ].includes(command);
   if (!isInternal && !isPassthrough) {
-    const { updateAvailable, current, latest } = await checkForUpdate();
-    if (updateAvailable) {
-      writeStderr(`[agendex] update required: v${current} → v${latest}`);
-      writeStderr(`[agendex] run: npm i -g agendex-cli`);
-      return 1;
+    const { checked, updateAvailable, current, latest } = await checkForUpdate();
+    if (checked && updateAvailable) {
+      writeStderr(`[agendex] update available: v${current} → v${latest}`);
+      writeStderr(`[agendex] run: agendex upgrade`);
     }
   }
   switch (command) {
@@ -4201,7 +5208,7 @@ async function main() {
       const daemonArgs = [cliEntry, "start", "--daemon"];
       if (devFlag)
         daemonArgs.push("--dev");
-      const child = spawn3(process.execPath, daemonArgs, {
+      const child = spawn4(process.execPath, daemonArgs, {
         detached: true,
         stdio: "ignore",
         env: { ...process.env, ...devFlag ? { AGENDEX_DEV: "1" } : {} }
@@ -4335,7 +5342,7 @@ async function main() {
         return 1;
       }
       const resolved = resolveCustomPlanDirPath(dirPath);
-      if (!existsSync9(resolved)) {
+      if (!existsSync11(resolved)) {
         writeStderr(`[agendex] path does not exist: ${resolved}`);
         return 1;
       }
@@ -4354,7 +5361,7 @@ async function main() {
         const { request } = await import("node:http");
         const body = JSON.stringify({ path: resolved });
         try {
-          const res = await new Promise((resolve7, reject) => {
+          const res = await new Promise((resolve9, reject) => {
             const req = request(`http://localhost:${port}/api/v1/plan-sources`, {
               method: "POST",
               headers: {
@@ -4368,7 +5375,7 @@ async function main() {
               res2.on("data", (chunk) => {
                 data += chunk;
               });
-              res2.on("end", () => resolve7({ status: res2.statusCode ?? 0, body: data }));
+              res2.on("end", () => resolve9({ status: res2.statusCode ?? 0, body: data }));
               res2.on("error", reject);
             });
             req.on("error", reject);
@@ -4496,6 +5503,9 @@ async function main() {
       }
       return 0;
     }
+    case "upgrade": {
+      return await runUpgrade({ force: args.includes("--force") });
+    }
     case "help":
     case "--help":
     case "-h": {
@@ -4522,6 +5532,8 @@ Usage:
   agendex cleanup      Interactively remove cloud daemons
   agendex cleanup --stale  Auto-remove all stale daemons
   agendex status       Show current config state + daemon status
+  agendex upgrade      Upgrade the globally installed CLI to the latest version
+  agendex upgrade --force  Reinstall latest even if already up to date
   agendex help         Show this help message
   agendex --version    Print CLI version
   agendex -v           Print CLI version
@@ -4550,13 +5562,13 @@ function flushStream(stream) {
   if (stream.destroyed || !stream.writable) {
     return Promise.resolve();
   }
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve9, reject) => {
     stream.write("", (error) => {
       if (error) {
         reject(error);
         return;
       }
-      resolve7();
+      resolve9();
     });
   });
 }