esedre 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to Esedre are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-10-09
+
+### Added
+- **MCP Ticket Listing Implementation Plan Hydration (`includePlan` and `hasPlan`) (Ticket #58)**:
+  - Extended `esedre_list_tickets` MCP tool to return `hasPlan: boolean` on all listed tickets, indicating whether an implementation plan exists on disk.
+  - Added optional `includePlan: boolean` parameter to `esedre_list_tickets` to hydrate full `planMarkdown` directly in ticket listings, eliminating redundant sequential `esedre_get_plan` tool calls when agents review multiple active tickets.
+  - Added unit test suite in `tests/mcpServer.test.ts` verifying `hasPlan` and `includePlan` behavior across multiple tickets.
+- **Comment File Input Option for CLI & MCP Tool (Ticket #62)**:
+  - Added `--file <path>` option to `ese comment` CLI command, reading verification notes directly from UTF-8 markdown or text files on disk.
+  - Bypasses Windows `cmd.exe` `%VAR%` parameter expansion and stripping, preserving percent signs (`100%`) and literal characters verbatim.
+  - Added priority precedence for `--file` over inline `--text` and positional arguments, with existence, regular file, and non-empty content validation.
+  - Added parity `file?: string` property to `esedre_add_comment` MCP tool, with automatic local file resolution and relaxed `required: ['ticketId']` schema constraint.
+  - Added comprehensive automated test suite in `tests/cliComment.test.ts` covering error handling, priority precedence, percent preservation, and MCP execution.
+
 ## [1.1.0] - 2026-10-02
 
 ### Added

package/README.md

@@ -122,7 +122,7 @@ Core day-to-day workflow commands for scoping, viewing, planning, and verifying
 | `link` | `ese link <sourceId> <relation> <targetId> [--author "..."]` | Establish a bi-directional link between two tickets. Relations: `relates-to`, `blocks`, `parent-of`, `duplicates`. |
 | `unlink` | `ese unlink <sourceId> <targetId> [--relation <relation>]` | Remove a bi-directional link between two tickets. |
 | `milestone` | `ese milestone [list\|get\|create\|update\|delete] [args...]` | Manage project milestones and umbrella feature flags with deliverables tracking. |
-| `comment` | `ese comment <id> ["<text>"] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
+| `comment` | `ese comment <id> ["<text>"] [--file <path>] [--text "..."] [--author "..."]` | Append a developer or LLM agent note to ticket history. |
 | `snapshot`, `refresh` | `ese snapshot [--project <code>] [--json]` | Generate or refresh projection `.esedre/snapshot.json` for zero-latency agent context. |
 | `projects` | `ese projects [--json]` | List registered projects within authorized scope. |
 
@@ -199,7 +199,7 @@ To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any
 ```
 
 ### Registered Tools
-- `esedre_list_tickets`: List tickets with optional project, status, type, priority, milestone, isBlocked, linkedTo, or search filter.
+- `esedre_list_tickets`: List tickets with optional project, status, type, priority, milestone, isBlocked, linkedTo, search, or includePlan filter.
 - `esedre_get_ticket`: Retrieve full specification, summary, comments, revision, links, blocker status, and content hash (`sha1`).
 - `esedre_get_plan` & `esedre_save_plan`: Inspect and update implementation plans with optimistic concurrency (`lastHash`).
 - `esedre_create_ticket`: Mint new roadmap tickets with project code validation (up to 8 chars), optional priority, optional milestone, and specification detail markdown.
@@ -210,7 +210,7 @@ To connect Esedre to **Google Antigravity**, **Claude Code**, **Cursor**, or any
 - `esedre_get_milestone`: Retrieve milestone specifications, umbrella feature flag, and member tickets.
 - `esedre_create_milestone`: Create a project milestone with optional umbrella feature flag and target date.
 - `esedre_update_milestone`: Update milestone status, title, description, or umbrella feature flag.
-- `esedre_add_comment`: Append developer or LLM agent verification notes.
+- `esedre_add_comment`: Append developer or LLM agent verification notes with optional file path or inline text.
 
 ### Cross-Project Linked Issues & Dependencies
 

package/dist/esedre.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // bin/esedre.ts
-import fs10 from "node:fs";
-import path10 from "node:path";
+import fs11 from "node:fs";
+import path11 from "node:path";
 
 // src/storage/filesystem.ts
 import fs3 from "node:fs";
@@ -10,7 +10,7 @@ import path3 from "node:path";
 import os2 from "node:os";
 
 // src/types.ts
-var CURRENT_ESEDRE_VERSION = "1.1.0";
+var CURRENT_ESEDRE_VERSION = "1.2.0";
 var INVERSE_RELATIONS = {
   "relates-to": "relates-to",
   "blocks": "blocked-by",
@@ -3579,6 +3579,8 @@ var SecurityFilter = class {
 };
 
 // src/mcp/server.ts
+import fs4 from "node:fs";
+import path4 from "node:path";
 import readline from "node:readline";
 var EsedreMcpServer = class {
   storage;
@@ -3800,7 +3802,8 @@ Status: ${ticket.meta.status}`;
             milestone: { type: "string", description: "Filter tickets by milestone name or ID" },
             search: { type: "string", description: "Search keywords in title or ID" },
             isBlocked: { type: "boolean", description: "Filter tickets blocked by uncompleted tickets" },
-            linkedTo: { type: "string", description: "Filter tickets linked to a specific ticket ID or key" }
+            linkedTo: { type: "string", description: "Filter tickets linked to a specific ticket ID or key" },
+            includePlan: { type: "boolean", description: "When true, includes implementation plan markdown (planMarkdown) for each ticket" }
           }
         }
       },
@@ -3892,9 +3895,10 @@ Status: ${ticket.meta.status}`;
           properties: {
             ticketId: { type: ["integer", "string"], description: "Numeric ticket ID or compound key" },
             text: { type: "string", description: "Comment message" },
+            file: { type: "string", description: "Path to local file containing comment message markdown" },
             author: { type: "string", description: "Author name (e.g. Antigravity, Developer)" }
           },
-          required: ["ticketId", "text"]
+          required: ["ticketId"]
         }
       },
       {
@@ -3991,6 +3995,7 @@ Status: ${ticket.meta.status}`;
     switch (canonical) {
       case "list_tickets": {
         const type = args.type || args.category;
+        const includePlan = Boolean(args.includePlan);
         const tickets = await this.storage.listTickets({
           project: args.project,
           status: args.status,
@@ -4002,23 +4007,39 @@ Status: ${ticket.meta.status}`;
           isBlocked: args.isBlocked !== void 0 ? Boolean(args.isBlocked) : void 0,
           linkedTo: args.linkedTo
         });
-        return tickets.map((t) => ({
-          id: t.meta.id,
-          title: t.meta.title,
-          type: t.meta.type || t.meta.category,
-          category: t.meta.type || t.meta.category,
-          status: t.meta.status,
-          priority: t.meta.priority,
-          complexity: t.meta.complexity,
-          effort: t.meta.estimatedEffort,
-          milestone: t.meta.milestone,
-          featureFlag: t.meta.featureFlag,
-          inheritedFeatureFlag: t.meta.inheritedFeatureFlag,
-          project: t.projectDescriptor?.code || t.meta.project || "UNASSIGNED",
-          sha1: t.sha1 || t.meta.sha1,
-          isBlocked: t.isBlocked,
-          links: t.links
-        }));
+        const results = await Promise.all(
+          tickets.map(async (t) => {
+            let planMarkdown = t.planMarkdown;
+            if (includePlan && planMarkdown === void 0) {
+              const lookupKey = t.projectDescriptor?.code ? `${t.projectDescriptor.code}-${t.meta.id}` : t.meta.id;
+              planMarkdown = await this.storage.getPlan(lookupKey) ?? null;
+            }
+            const hasPlan = Boolean(
+              t.planMarkdown && t.planMarkdown.trim().length > 0 || planMarkdown && planMarkdown.trim().length > 0
+            );
+            return {
+              id: t.meta.id,
+              title: t.meta.title,
+              type: t.meta.type || t.meta.category,
+              category: t.meta.type || t.meta.category,
+              status: t.meta.status,
+              priority: t.meta.priority,
+              complexity: t.meta.complexity,
+              effort: t.meta.estimatedEffort,
+              milestone: t.meta.milestone,
+              featureFlag: t.meta.featureFlag,
+              inheritedFeatureFlag: t.meta.inheritedFeatureFlag,
+              project: t.projectDescriptor?.code || t.meta.project || "UNASSIGNED",
+              summary: t.detail?.summary,
+              hasPlan,
+              ...includePlan ? { planMarkdown: planMarkdown || null } : {},
+              sha1: t.sha1 || t.meta.sha1,
+              isBlocked: t.isBlocked,
+              links: t.links
+            };
+          })
+        );
+        return results;
       }
       case "get_ticket": {
         const id = this.parseTicketId(args.ticketId);
@@ -4077,8 +4098,26 @@ Status: ${ticket.meta.status}`;
       }
       case "add_comment": {
         const id = this.parseTicketId(args.ticketId);
+        let text = args.text;
+        if (!text && args.file) {
+          const resolvedPath = path4.resolve(process.cwd(), args.file);
+          if (!fs4.existsSync(resolvedPath)) {
+            throw new Error(`File not found: ${args.file}`);
+          }
+          if (!fs4.statSync(resolvedPath).isFile()) {
+            throw new Error(`Path is not a file: ${args.file}`);
+          }
+          const fileContent = fs4.readFileSync(resolvedPath, "utf-8");
+          if (!fileContent.trim()) {
+            throw new Error(`Comment file is empty: ${args.file}`);
+          }
+          text = fileContent;
+        }
+        if (!text || !text.trim()) {
+          throw new Error("Comment text or file is required");
+        }
         const comment = await this.storage.addComment(id, {
-          text: args.text,
+          text,
           author: args.author || "Agent"
         });
         return comment;
@@ -4147,19 +4186,19 @@ Status: ${ticket.meta.status}`;
 };
 
 // src/utils/manifestDetector.ts
-import fs4 from "node:fs";
-import path4 from "node:path";
+import fs5 from "node:fs";
+import path5 from "node:path";
 function sanitizeCode(input) {
   const clean = input.replace(/[^a-zA-Z0-9]/g, "");
   return clean.slice(0, MAX_PROJECT_CODE_LENGTH) || "APP";
 }
 function detectProjectManifest(targetDir) {
-  const dirBase = path4.basename(targetDir);
+  const dirBase = path5.basename(targetDir);
   for (const settingsFile of ["settings.gradle.kts", "settings.gradle"]) {
-    const fullPath = path4.join(targetDir, settingsFile);
-    if (fs4.existsSync(fullPath)) {
+    const fullPath = path5.join(targetDir, settingsFile);
+    if (fs5.existsSync(fullPath)) {
       try {
-        const content = fs4.readFileSync(fullPath, "utf-8");
+        const content = fs5.readFileSync(fullPath, "utf-8");
         const match = content.match(/rootProject\.name\s*=\s*["']([^"']+)["']/);
         if (match && match[1].trim()) {
           const rawName = match[1].trim();
@@ -4175,15 +4214,15 @@ function detectProjectManifest(targetDir) {
     }
   }
   for (const buildFile of [
-    path4.join("app", "build.gradle.kts"),
+    path5.join("app", "build.gradle.kts"),
     "build.gradle.kts",
-    path4.join("app", "build.gradle"),
+    path5.join("app", "build.gradle"),
     "build.gradle"
   ]) {
-    const fullPath = path4.join(targetDir, buildFile);
-    if (fs4.existsSync(fullPath)) {
+    const fullPath = path5.join(targetDir, buildFile);
+    if (fs5.existsSync(fullPath)) {
       try {
-        const content = fs4.readFileSync(fullPath, "utf-8");
+        const content = fs5.readFileSync(fullPath, "utf-8");
         const match = content.match(/(?:namespace|applicationId)\s*=\s*["']([^"']+)["']/);
         if (match && match[1].trim()) {
           const ns = match[1].trim();
@@ -4200,10 +4239,10 @@ function detectProjectManifest(targetDir) {
       }
     }
   }
-  const pomPath = path4.join(targetDir, "pom.xml");
-  if (fs4.existsSync(pomPath)) {
+  const pomPath = path5.join(targetDir, "pom.xml");
+  if (fs5.existsSync(pomPath)) {
     try {
-      const content = fs4.readFileSync(pomPath, "utf-8");
+      const content = fs5.readFileSync(pomPath, "utf-8");
       const stripped = content.replace(/<!--[\s\S]*?-->/g, "").replace(/<parent>[\s\S]*?<\/parent>/g, "");
       const nameMatch = stripped.match(/<name>\s*([^<]+)\s*<\/name>/);
       const artifactMatch = stripped.match(/<artifactId>\s*([^<]+)\s*<\/artifactId>/) || content.match(/<artifactId>\s*([^<]+)\s*<\/artifactId>/);
@@ -4222,10 +4261,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const pkgPath = path4.join(targetDir, "package.json");
-  if (fs4.existsSync(pkgPath)) {
+  const pkgPath = path5.join(targetDir, "package.json");
+  if (fs5.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
       if (pkg.name && typeof pkg.name === "string") {
         const baseName = pkg.name.replace(/^@[\w-]+\//, "");
         return {
@@ -4238,10 +4277,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const cargoPath = path4.join(targetDir, "Cargo.toml");
-  if (fs4.existsSync(cargoPath)) {
+  const cargoPath = path5.join(targetDir, "Cargo.toml");
+  if (fs5.existsSync(cargoPath)) {
     try {
-      const content = fs4.readFileSync(cargoPath, "utf-8");
+      const content = fs5.readFileSync(cargoPath, "utf-8");
       const match = content.match(/\[package\][\s\S]*?name\s*=\s*["']([^"']+)["']/);
       if (match && match[1].trim()) {
         const rawName = match[1].trim();
@@ -4255,10 +4294,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const pyprojectPath = path4.join(targetDir, "pyproject.toml");
-  if (fs4.existsSync(pyprojectPath)) {
+  const pyprojectPath = path5.join(targetDir, "pyproject.toml");
+  if (fs5.existsSync(pyprojectPath)) {
     try {
-      const content = fs4.readFileSync(pyprojectPath, "utf-8");
+      const content = fs5.readFileSync(pyprojectPath, "utf-8");
       const match = content.match(/name\s*=\s*["']([^"']+)["']/);
       if (match && match[1].trim()) {
         const rawName = match[1].trim();
@@ -4272,10 +4311,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const setupCfgPath = path4.join(targetDir, "setup.cfg");
-  if (fs4.existsSync(setupCfgPath)) {
+  const setupCfgPath = path5.join(targetDir, "setup.cfg");
+  if (fs5.existsSync(setupCfgPath)) {
     try {
-      const content = fs4.readFileSync(setupCfgPath, "utf-8");
+      const content = fs5.readFileSync(setupCfgPath, "utf-8");
       const match = content.match(/^name\s*=\s*([^\r\n]+)/m);
       if (match && match[1].trim()) {
         const rawName = match[1].trim();
@@ -4289,10 +4328,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const setupPyPath = path4.join(targetDir, "setup.py");
-  if (fs4.existsSync(setupPyPath)) {
+  const setupPyPath = path5.join(targetDir, "setup.py");
+  if (fs5.existsSync(setupPyPath)) {
     try {
-      const content = fs4.readFileSync(setupPyPath, "utf-8");
+      const content = fs5.readFileSync(setupPyPath, "utf-8");
       const match = content.match(/name\s*=\s*["']([^"']+)["']/);
       if (match && match[1].trim()) {
         const rawName = match[1].trim();
@@ -4306,10 +4345,10 @@ function detectProjectManifest(targetDir) {
     } catch {
     }
   }
-  const goModPath = path4.join(targetDir, "go.mod");
-  if (fs4.existsSync(goModPath)) {
+  const goModPath = path5.join(targetDir, "go.mod");
+  if (fs5.existsSync(goModPath)) {
     try {
-      const content = fs4.readFileSync(goModPath, "utf-8");
+      const content = fs5.readFileSync(goModPath, "utf-8");
       const match = content.match(/^module\s+([^\r\n\s]+)/m);
       if (match && match[1].trim()) {
         const modPath = match[1].trim();
@@ -4333,48 +4372,48 @@ function detectProjectManifest(targetDir) {
 
 // src/upgrade.ts
 import crypto2 from "node:crypto";
-import fs6 from "node:fs";
-import path6 from "node:path";
+import fs7 from "node:fs";
+import path7 from "node:path";
 
 // src/server/daemon.ts
-import fs5 from "node:fs";
-import path5 from "node:path";
+import fs6 from "node:fs";
+import path6 from "node:path";
 import os3 from "node:os";
 import http from "node:http";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = path5.dirname(__filename);
+var __dirname = path6.dirname(__filename);
 function getGlobalEsedreDir() {
   if (process.env.ESEDRE_GLOBAL_DIR) {
     return process.env.ESEDRE_GLOBAL_DIR;
   }
-  return path5.join(os3.homedir(), ".esedre");
+  return path6.join(os3.homedir(), ".esedre");
 }
 function ensureGlobalEsedreStore() {
   const globalDir = getGlobalEsedreDir();
-  const runDir = path5.join(globalDir, "run");
-  const logsDir = path5.join(globalDir, "logs");
+  const runDir = path6.join(globalDir, "run");
+  const logsDir = path6.join(globalDir, "logs");
   try {
-    fs5.mkdirSync(runDir, { recursive: true });
-    fs5.mkdirSync(logsDir, { recursive: true });
+    fs6.mkdirSync(runDir, { recursive: true });
+    fs6.mkdirSync(logsDir, { recursive: true });
     try {
-      const runEntries = fs5.readdirSync(runDir);
+      const runEntries = fs6.readdirSync(runDir);
       for (const entry of runEntries) {
         if (entry.startsWith(".probe-")) {
-          fs5.unlinkSync(path5.join(runDir, entry));
+          fs6.unlinkSync(path6.join(runDir, entry));
         }
       }
     } catch {
     }
-    const testProbe = path5.join(runDir, `.probe-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`);
+    const testProbe = path6.join(runDir, `.probe-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`);
     try {
-      fs5.writeFileSync(testProbe, "ok", "utf-8");
+      fs6.writeFileSync(testProbe, "ok", "utf-8");
       return { ok: true, path: globalDir };
     } finally {
-      if (fs5.existsSync(testProbe)) {
+      if (fs6.existsSync(testProbe)) {
         try {
-          fs5.unlinkSync(testProbe);
+          fs6.unlinkSync(testProbe);
         } catch {
         }
       }
@@ -4389,10 +4428,10 @@ function resolveStoreDir(workspaceRoot) {
     return globalStore.path;
   }
   if (workspaceRoot) {
-    const localStore = path5.join(workspaceRoot, ".esedre");
+    const localStore = path6.join(workspaceRoot, ".esedre");
     try {
-      fs5.mkdirSync(path5.join(localStore, "run"), { recursive: true });
-      fs5.mkdirSync(path5.join(localStore, "logs"), { recursive: true });
+      fs6.mkdirSync(path6.join(localStore, "run"), { recursive: true });
+      fs6.mkdirSync(path6.join(localStore, "logs"), { recursive: true });
       return localStore;
     } catch {
     }
@@ -4401,32 +4440,32 @@ function resolveStoreDir(workspaceRoot) {
 }
 function getDaemonStateFile(port, workspaceRoot) {
   const store = resolveStoreDir(workspaceRoot);
-  return path5.join(store, "run", `daemon-${port}.json`);
+  return path6.join(store, "run", `daemon-${port}.json`);
 }
 function getDaemonLogFile(port, workspaceRoot) {
   const store = resolveStoreDir(workspaceRoot);
-  return path5.join(store, "logs", `daemon-${port}.log`);
+  return path6.join(store, "logs", `daemon-${port}.log`);
 }
 function getDaemonState(port, workspaceRoot) {
   const stateFile = getDaemonStateFile(port, workspaceRoot);
-  if (!fs5.existsSync(stateFile)) {
+  if (!fs6.existsSync(stateFile)) {
     return null;
   }
   try {
-    const raw = fs5.readFileSync(stateFile, "utf-8").trim();
+    const raw = fs6.readFileSync(stateFile, "utf-8").trim();
     if (!raw) {
-      fs5.unlinkSync(stateFile);
+      fs6.unlinkSync(stateFile);
       return null;
     }
     const state = JSON.parse(raw);
     if (!state || typeof state.pid !== "number" || typeof state.port !== "number") {
-      fs5.unlinkSync(stateFile);
+      fs6.unlinkSync(stateFile);
       return null;
     }
     return state;
   } catch {
     try {
-      fs5.unlinkSync(stateFile);
+      fs6.unlinkSync(stateFile);
     } catch {
     }
     return null;
@@ -4497,7 +4536,7 @@ async function startDaemon(options = {}) {
       }
     }
     try {
-      fs5.unlinkSync(stateFile);
+      fs6.unlinkSync(stateFile);
     } catch {
     }
   }
@@ -4516,40 +4555,40 @@ async function startDaemon(options = {}) {
     };
   }
   resolveStoreDir(workspaceRoot);
-  fs5.mkdirSync(path5.dirname(logFile), { recursive: true });
-  fs5.mkdirSync(path5.dirname(stateFile), { recursive: true });
+  fs6.mkdirSync(path6.dirname(logFile), { recursive: true });
+  fs6.mkdirSync(path6.dirname(stateFile), { recursive: true });
   const MAX_LOG_SIZE_BYTES = 10 * 1024 * 1024;
   try {
-    if (fs5.existsSync(logFile)) {
-      const stats = fs5.statSync(logFile);
+    if (fs6.existsSync(logFile)) {
+      const stats = fs6.statSync(logFile);
       if (stats.size > MAX_LOG_SIZE_BYTES) {
         const oldLogFile = `${logFile}.old`;
         try {
-          if (fs5.existsSync(oldLogFile)) fs5.unlinkSync(oldLogFile);
-          fs5.renameSync(logFile, oldLogFile);
+          if (fs6.existsSync(oldLogFile)) fs6.unlinkSync(oldLogFile);
+          fs6.renameSync(logFile, oldLogFile);
         } catch {
-          fs5.truncateSync(logFile, 0);
+          fs6.truncateSync(logFile, 0);
         }
       }
     }
   } catch {
   }
-  const logFd = fs5.openSync(logFile, "a");
-  const isEsedreArgv1 = process.argv[1] && /esedre/i.test(path5.basename(process.argv[1]));
+  const logFd = fs6.openSync(logFile, "a");
+  const isEsedreArgv1 = process.argv[1] && /esedre/i.test(path6.basename(process.argv[1]));
   const cliCandidates = [
-    isEsedreArgv1 ? path5.resolve(process.argv[1]) : void 0,
-    path5.resolve(workspaceRoot, "dist", "esedre.mjs"),
-    path5.resolve(workspaceRoot, "../esedre/dist", "esedre.mjs"),
-    path5.resolve(__dirname, "esedre.mjs"),
-    path5.resolve(__dirname, "..", "dist", "esedre.mjs"),
-    path5.resolve(__dirname, "..", "..", "dist", "esedre.mjs"),
-    path5.resolve(__dirname, "..", "..", "bin", "esedre.js"),
-    path5.resolve(__dirname, "..", "..", "bin", "esedre.ts"),
-    path5.resolve(__dirname, "..", "esedre.mjs"),
-    path5.resolve(__dirname, "../../../esedre/dist", "esedre.mjs")
+    isEsedreArgv1 ? path6.resolve(process.argv[1]) : void 0,
+    path6.resolve(workspaceRoot, "dist", "esedre.mjs"),
+    path6.resolve(workspaceRoot, "../esedre/dist", "esedre.mjs"),
+    path6.resolve(__dirname, "esedre.mjs"),
+    path6.resolve(__dirname, "..", "dist", "esedre.mjs"),
+    path6.resolve(__dirname, "..", "..", "dist", "esedre.mjs"),
+    path6.resolve(__dirname, "..", "..", "bin", "esedre.js"),
+    path6.resolve(__dirname, "..", "..", "bin", "esedre.ts"),
+    path6.resolve(__dirname, "..", "esedre.mjs"),
+    path6.resolve(__dirname, "../../../esedre/dist", "esedre.mjs")
   ].filter(Boolean);
-  const cliPath = cliCandidates.find((c) => fs5.existsSync(c) && (c.endsWith(".mjs") || c.endsWith(".js") || c.endsWith(".ts"))) || cliCandidates[0];
-  if (!fs5.existsSync(cliPath)) {
+  const cliPath = cliCandidates.find((c) => fs6.existsSync(c) && (c.endsWith(".mjs") || c.endsWith(".js") || c.endsWith(".ts"))) || cliCandidates[0];
+  if (!fs6.existsSync(cliPath)) {
     throw new Error(`Could not locate Esedre executable. Searched candidates: ${cliCandidates.join(", ")}`);
   }
   const child = spawn(process.execPath, [cliPath, "start", "--foreground", "--port", String(port)], {
@@ -4561,7 +4600,7 @@ async function startDaemon(options = {}) {
   });
   child.unref();
   try {
-    fs5.closeSync(logFd);
+    fs6.closeSync(logFd);
   } catch {
   }
   const pid = child.pid;
@@ -4602,13 +4641,13 @@ async function startDaemon(options = {}) {
     logFile
   };
   const tmpState = `${stateFile}.tmp.${Date.now()}`;
-  fs5.writeFileSync(tmpState, JSON.stringify(state, null, 2) + "\n", "utf-8");
+  fs6.writeFileSync(tmpState, JSON.stringify(state, null, 2) + "\n", "utf-8");
   try {
-    fs5.renameSync(tmpState, stateFile);
+    fs6.renameSync(tmpState, stateFile);
   } catch {
-    fs5.writeFileSync(stateFile, JSON.stringify(state, null, 2) + "\n", "utf-8");
+    fs6.writeFileSync(stateFile, JSON.stringify(state, null, 2) + "\n", "utf-8");
     try {
-      fs5.unlinkSync(tmpState);
+      fs6.unlinkSync(tmpState);
     } catch {
     }
   }
@@ -4671,8 +4710,8 @@ async function stopDaemon(options = {}) {
     }
   }
   try {
-    if (fs5.existsSync(stateFile)) {
-      fs5.unlinkSync(stateFile);
+    if (fs6.existsSync(stateFile)) {
+      fs6.unlinkSync(stateFile);
     }
   } catch {
   }
@@ -4709,7 +4748,7 @@ async function getDaemonStatus(options = {}) {
   }
   if (state && !isProcessAlive(state.pid)) {
     try {
-      fs5.unlinkSync(stateFile);
+      fs6.unlinkSync(stateFile);
     } catch {
     }
   }
@@ -4727,26 +4766,26 @@ function printDaemonLogs(options = {}) {
   const port = resolvePorts(void 0, { port: options.port }).gateway;
   const workspaceRoot = options.workspaceRoot || process.cwd();
   const logFile = getDaemonLogFile(port, workspaceRoot);
-  if (!fs5.existsSync(logFile)) {
+  if (!fs6.existsSync(logFile)) {
     console.log(`\x1B[33mNo logs found at: ${logFile}\x1B[0m`);
     return;
   }
   const count = options.lines || 40;
   let content = "";
   try {
-    const stats = fs5.statSync(logFile);
+    const stats = fs6.statSync(logFile);
     const maxReadBytes = Math.min(stats.size, Math.max(256 * 1024, count * 2048));
     if (stats.size <= maxReadBytes) {
-      content = fs5.readFileSync(logFile, "utf-8");
+      content = fs6.readFileSync(logFile, "utf-8");
     } else {
-      const fd = fs5.openSync(logFile, "r");
+      const fd = fs6.openSync(logFile, "r");
       const buffer = Buffer.alloc(maxReadBytes);
-      fs5.readSync(fd, buffer, 0, maxReadBytes, stats.size - maxReadBytes);
-      fs5.closeSync(fd);
+      fs6.readSync(fd, buffer, 0, maxReadBytes, stats.size - maxReadBytes);
+      fs6.closeSync(fd);
       content = buffer.toString("utf-8");
     }
   } catch {
-    content = fs5.readFileSync(logFile, "utf-8");
+    content = fs6.readFileSync(logFile, "utf-8");
   }
   const allLines = content.split(/\r?\n/);
   const sanitizedLines = allLines.slice(-count).map((line) => {
@@ -4961,13 +5000,13 @@ When Esedre MCP is active in your agent session (\`.agents/mcp_config.json\`), u
 
 | Tool | Purpose | Key Arguments |
 |---|---|---|
-| \`esedre_list_tickets\` | List roadmap tickets with filters | \`project\` (e.g. \`Profe\`, \`Esedre\`, \`Alce\`), \`status\`, \`type\`, \`search\` |
+| \`esedre_list_tickets\` | List roadmap tickets with filters | \`project\` (e.g. \`Profe\`, \`Esedre\`, \`Alce\`), \`status\`, \`type\`, \`priority\`, \`milestone\`, \`isBlocked\`, \`linkedTo\`, \`search\`, \`includePlan\` |
 | \`esedre_get_ticket\` | Full specification, summary, comments, revision & sha1 | \`ticketId\` (numeric e.g. \`96\` or compound e.g. \`Profe-96\`) |
 | \`esedre_get_plan\` | Active implementation plan markdown | \`ticketId\` (numeric or compound) |
 | \`esedre_save_plan\` | Save implementation plan markdown with OCC | \`ticketId\`, \`planMarkdown\`, \`lastHash\` |
 | \`esedre_create_ticket\` | Mint a new ticket with auto sequential ID | \`title\` (max 48 chars), \`type\`, \`project\`, \`effort\`, \`summary\`, \`detail\` |
 | \`esedre_update_ticket\` | Update ticket attributes with OCC | \`ticketId\`, \`status\`, \`type\`, \`title\`, \`complexity\`, \`effort\`, \`inDevelopment\`, \`featureFlag\`, \`lastHash\` |
-| \`esedre_add_comment\` | Append developer or agent comment | \`ticketId\`, \`text\`, \`author\` |
+| \`esedre_add_comment\` | Append developer or agent comment | \`ticketId\`, \`text\`, \`file\`, \`author\` |
 
 ## 2. Core CLI Commands (Fallback via \`run_command\`)
 
@@ -5005,6 +5044,7 @@ Both \`esedre\` and \`ese\` work interchangeably:
 ### Append Comments or Notes
 \`\`\`bash
 .esedre/ese comment <ticketId> "Verified implementation." --author "Agent"
+.esedre/ese comment <ticketId> --file <commentFilePath> --author "Agent"
 .esedre/ese comment <ticketId> --text "Verified implementation." --author "Agent"
 \`\`\`
 
@@ -5060,8 +5100,8 @@ If the host application declares any or all of the 12 core design tokens on \`:r
   - The URL hash is preserved across hard page refreshes (F5) without falling back to \`#/chat\` or other views.
 `;
 function plantWrappers(targetDir) {
-  const esedreDir = path6.join(targetDir, ".esedre");
-  fs6.mkdirSync(esedreDir, { recursive: true });
+  const esedreDir = path7.join(targetDir, ".esedre");
+  fs7.mkdirSync(esedreDir, { recursive: true });
   const wrappers = [
     { name: "esedre.cmd", content: WRAPPER_CMD, exec: false },
     { name: "esedre.ps1", content: WRAPPER_PS1, exec: false },
@@ -5071,24 +5111,24 @@ function plantWrappers(targetDir) {
     { name: "ese", content: ESE_WRAPPER_BASH, exec: true }
   ];
   for (const w of wrappers) {
-    const fullPath = path6.join(esedreDir, w.name);
-    fs6.writeFileSync(fullPath, w.content, "utf-8");
+    const fullPath = path7.join(esedreDir, w.name);
+    fs7.writeFileSync(fullPath, w.content, "utf-8");
     if (w.exec) {
       try {
-        fs6.chmodSync(fullPath, 493);
+        fs7.chmodSync(fullPath, 493);
       } catch {
       }
     }
   }
 }
 function setupMcpConfig(targetDir) {
-  const agentsDir = path6.join(targetDir, ".agents");
-  fs6.mkdirSync(agentsDir, { recursive: true });
-  const mcpConfigPath = path6.join(agentsDir, "mcp_config.json");
+  const agentsDir = path7.join(targetDir, ".agents");
+  fs7.mkdirSync(agentsDir, { recursive: true });
+  const mcpConfigPath = path7.join(agentsDir, "mcp_config.json");
   let configObj = { mcpServers: {} };
-  if (fs6.existsSync(mcpConfigPath)) {
+  if (fs7.existsSync(mcpConfigPath)) {
     try {
-      configObj = JSON.parse(fs6.readFileSync(mcpConfigPath, "utf-8"));
+      configObj = JSON.parse(fs7.readFileSync(mcpConfigPath, "utf-8"));
       if (!configObj.mcpServers) configObj.mcpServers = {};
     } catch {
     }
@@ -5105,28 +5145,28 @@ function setupMcpConfig(targetDir) {
     };
   }
   try {
-    fs6.writeFileSync(mcpConfigPath, JSON.stringify(configObj, null, 2) + "\n", "utf-8");
+    fs7.writeFileSync(mcpConfigPath, JSON.stringify(configObj, null, 2) + "\n", "utf-8");
     return true;
   } catch {
     return false;
   }
 }
 function setupSkill(targetDir, options = {}) {
-  const skillDir = path6.join(targetDir, ".agents", "skills", "esedre");
-  fs6.mkdirSync(skillDir, { recursive: true });
-  const skillFile = path6.join(skillDir, "SKILL.md");
-  if (!fs6.existsSync(skillFile)) {
-    fs6.writeFileSync(skillFile, ESEDRE_SKILL_TEMPLATE, "utf-8");
+  const skillDir = path7.join(targetDir, ".agents", "skills", "esedre");
+  fs7.mkdirSync(skillDir, { recursive: true });
+  const skillFile = path7.join(skillDir, "SKILL.md");
+  if (!fs7.existsSync(skillFile)) {
+    fs7.writeFileSync(skillFile, ESEDRE_SKILL_TEMPLATE, "utf-8");
     return { status: "MISSING", updated: true };
   }
-  const currentContent = fs6.readFileSync(skillFile, "utf-8");
+  const currentContent = fs7.readFileSync(skillFile, "utf-8");
   const status = classifyContent(currentContent, ESEDRE_SKILL_TEMPLATE, HISTORIC_SKILL_HASHES);
   if (status === "LATEST" && !options.force) {
     return { status, updated: false };
   }
   const hasBannedOrDeprecatedTerms = currentContent.includes("companion agent") || currentContent.includes("companion LLM") || currentContent.includes("tools/esedre.mjs");
   if (options.force || status === "HISTORIC_DEFAULT" || status === "MISSING" || hasBannedOrDeprecatedTerms) {
-    fs6.writeFileSync(skillFile, ESEDRE_SKILL_TEMPLATE, "utf-8");
+    fs7.writeFileSync(skillFile, ESEDRE_SKILL_TEMPLATE, "utf-8");
     return { status: "LATEST", updated: true };
   }
   return { status, updated: false };
@@ -5140,8 +5180,8 @@ var VITE_CONFIG_FILES = [
 ];
 function findViteConfig(targetDir) {
   for (const name of VITE_CONFIG_FILES) {
-    const fullPath = path6.join(targetDir, name);
-    if (fs6.existsSync(fullPath)) {
+    const fullPath = path7.join(targetDir, name);
+    if (fs7.existsSync(fullPath)) {
       return fullPath;
     }
   }
@@ -5205,10 +5245,10 @@ function configureViteProxy(targetDir, port = DEFAULT_ESEDRE_PORT, setupProxy) {
       recommendedProxySnippet: snippet
     };
   }
-  const relativeName = path6.basename(configPath);
+  const relativeName = path7.basename(configPath);
   let content = "";
   try {
-    content = fs6.readFileSync(configPath, "utf-8");
+    content = fs7.readFileSync(configPath, "utf-8");
   } catch {
     return {
       status: "MANUAL_REQUIRED",
@@ -5239,7 +5279,7 @@ function configureViteProxy(targetDir, port = DEFAULT_ESEDRE_PORT, setupProxy) {
     };
   }
   try {
-    fs6.writeFileSync(configPath, injected, "utf-8");
+    fs7.writeFileSync(configPath, injected, "utf-8");
     return {
       status: "CONFIGURED",
       configFile: relativeName,
@@ -5254,15 +5294,15 @@ function configureViteProxy(targetDir, port = DEFAULT_ESEDRE_PORT, setupProxy) {
   }
 }
 function configureWorkspace(targetDir, options = {}) {
-  const esedreDir = path6.join(targetDir, ".esedre");
-  if (!fs6.existsSync(esedreDir)) {
-    fs6.mkdirSync(esedreDir, { recursive: true });
+  const esedreDir = path7.join(targetDir, ".esedre");
+  if (!fs7.existsSync(esedreDir)) {
+    fs7.mkdirSync(esedreDir, { recursive: true });
   }
-  const esedreJsonPath = path6.join(esedreDir, "esedre.json");
+  const esedreJsonPath = path7.join(esedreDir, "esedre.json");
   let existingRaw = null;
-  if (fs6.existsSync(esedreJsonPath)) {
+  if (fs7.existsSync(esedreJsonPath)) {
     try {
-      existingRaw = JSON.parse(fs6.readFileSync(esedreJsonPath, "utf-8"));
+      existingRaw = JSON.parse(fs7.readFileSync(esedreJsonPath, "utf-8"));
     } catch {
     }
   }
@@ -5298,16 +5338,16 @@ function configureWorkspace(targetDir, options = {}) {
       port: options.port || void 0
     };
   }
-  fs6.writeFileSync(esedreJsonPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  fs7.writeFileSync(esedreJsonPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
   let projectRegistered = false;
   if (projectCode) {
-    const hasExistingTicketsDir = fs6.existsSync(path6.join(targetDir, "tickets")) || fs6.existsSync(path6.join(targetDir, "src", "data", "planning", "tickets"));
-    const ticketsDir = path6.join(esedreDir, "tickets");
-    if (!hasExistingTicketsDir && !fs6.existsSync(ticketsDir)) {
-      fs6.mkdirSync(ticketsDir, { recursive: true });
+    const hasExistingTicketsDir = fs7.existsSync(path7.join(targetDir, "tickets")) || fs7.existsSync(path7.join(targetDir, "src", "data", "planning", "tickets"));
+    const ticketsDir = path7.join(esedreDir, "tickets");
+    if (!hasExistingTicketsDir && !fs7.existsSync(ticketsDir)) {
+      fs7.mkdirSync(ticketsDir, { recursive: true });
     }
-    const inRepoPJson = path6.join(esedreDir, "project.json");
-    if (!fs6.existsSync(inRepoPJson)) {
+    const inRepoPJson = path7.join(esedreDir, "project.json");
+    if (!fs7.existsSync(inRepoPJson)) {
       const projDesc = {
         id: 1,
         code: projectCode.toUpperCase(),
@@ -5319,14 +5359,14 @@ function configureWorkspace(targetDir, options = {}) {
           border: "border-cyan-500/40"
         }
       };
-      fs6.writeFileSync(inRepoPJson, JSON.stringify(projDesc, null, 2) + "\n", "utf-8");
+      fs7.writeFileSync(inRepoPJson, JSON.stringify(projDesc, null, 2) + "\n", "utf-8");
       projectRegistered = true;
     } else if (projectName) {
       try {
-        const existing = JSON.parse(fs6.readFileSync(inRepoPJson, "utf-8"));
+        const existing = JSON.parse(fs7.readFileSync(inRepoPJson, "utf-8"));
         if (existing.name !== projectName) {
           existing.name = projectName;
-          fs6.writeFileSync(inRepoPJson, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+          fs7.writeFileSync(inRepoPJson, JSON.stringify(existing, null, 2) + "\n", "utf-8");
         }
       } catch {
       }
@@ -5376,26 +5416,26 @@ var ESEDRE_HUB_AGENTS_TEMPLATE = `# Agent Guidelines: esedre-data
 When inspecting or managing tickets for any project (such as \`Profe\`, \`Esedre\`, or \`Alce\`), navigate to that project's workspace and utilize its local \`.esedre/snapshot.json\`, Esedre MCP tools, or \`.esedre/ese\` CLI wrapper.
 `;
 function initHub(targetDir) {
-  const resolved = path6.resolve(targetDir);
-  if (!fs6.existsSync(resolved)) {
-    fs6.mkdirSync(resolved, { recursive: true });
+  const resolved = path7.resolve(targetDir);
+  if (!fs7.existsSync(resolved)) {
+    fs7.mkdirSync(resolved, { recursive: true });
   }
-  const projectsDir = path6.join(resolved, "projects");
+  const projectsDir = path7.join(resolved, "projects");
   let projectsDirCreated = false;
-  if (!fs6.existsSync(projectsDir)) {
-    fs6.mkdirSync(projectsDir, { recursive: true });
+  if (!fs7.existsSync(projectsDir)) {
+    fs7.mkdirSync(projectsDir, { recursive: true });
     projectsDirCreated = true;
   }
-  const projectsJsonPath = path6.join(resolved, "projects.json");
+  const projectsJsonPath = path7.join(resolved, "projects.json");
   let projectsJsonCreated = false;
-  if (!fs6.existsSync(projectsJsonPath)) {
-    fs6.writeFileSync(projectsJsonPath, "[]\n", "utf-8");
+  if (!fs7.existsSync(projectsJsonPath)) {
+    fs7.writeFileSync(projectsJsonPath, "[]\n", "utf-8");
     projectsJsonCreated = true;
   }
-  const agentsMdPath = path6.join(resolved, "AGENTS.md");
+  const agentsMdPath = path7.join(resolved, "AGENTS.md");
   let agentsMdCreated = false;
-  if (!fs6.existsSync(agentsMdPath)) {
-    fs6.writeFileSync(agentsMdPath, ESEDRE_HUB_AGENTS_TEMPLATE, "utf-8");
+  if (!fs7.existsSync(agentsMdPath)) {
+    fs7.writeFileSync(agentsMdPath, ESEDRE_HUB_AGENTS_TEMPLATE, "utf-8");
     agentsMdCreated = true;
   }
   return {
@@ -5424,14 +5464,14 @@ function findOutdatedWrappers(currentWorkspaceRoot, globalConfig) {
   const outdated = [];
   const checkedDirs = /* @__PURE__ */ new Set();
   const checkDir = (dir, name) => {
-    const resolved = path6.resolve(expandHome(dir));
+    const resolved = path7.resolve(expandHome(dir));
     if (checkedDirs.has(resolved.toLowerCase())) return;
     checkedDirs.add(resolved.toLowerCase());
-    if (!fs6.existsSync(resolved)) return;
-    const cmdPath = path6.join(resolved, ".esedre", "esedre.cmd");
-    if (fs6.existsSync(cmdPath)) {
+    if (!fs7.existsSync(resolved)) return;
+    const cmdPath = path7.join(resolved, ".esedre", "esedre.cmd");
+    if (fs7.existsSync(cmdPath)) {
       try {
-        const content = fs6.readFileSync(cmdPath, "utf-8");
+        const content = fs7.readFileSync(cmdPath, "utf-8");
         if (isWrapperOutdated(content)) {
           outdated.push({ name, dir: resolved, wrapperPath: cmdPath });
         }
@@ -5440,7 +5480,7 @@ function findOutdatedWrappers(currentWorkspaceRoot, globalConfig) {
     }
   };
   if (currentWorkspaceRoot) {
-    checkDir(currentWorkspaceRoot, path6.basename(currentWorkspaceRoot));
+    checkDir(currentWorkspaceRoot, path7.basename(currentWorkspaceRoot));
   }
   if (globalConfig?.projects) {
     for (const [code, p] of Object.entries(globalConfig.projects)) {
@@ -5452,20 +5492,20 @@ function findOutdatedWrappers(currentWorkspaceRoot, globalConfig) {
 async function upgradeAllWorkspaces(options = {}) {
   const globalCfg = options.globalConfig !== void 0 ? options.globalConfig : readGlobalConfig();
   const workspaceMap = /* @__PURE__ */ new Map();
-  if (options.currentWorkspaceRoot && fs6.existsSync(options.currentWorkspaceRoot)) {
-    const hasEsedre = fs6.existsSync(path6.join(options.currentWorkspaceRoot, ".esedre")) || fs6.existsSync(path6.join(options.currentWorkspaceRoot, "esedre.json"));
+  if (options.currentWorkspaceRoot && fs7.existsSync(options.currentWorkspaceRoot)) {
+    const hasEsedre = fs7.existsSync(path7.join(options.currentWorkspaceRoot, ".esedre")) || fs7.existsSync(path7.join(options.currentWorkspaceRoot, "esedre.json"));
     if (hasEsedre) {
       const disc = findEsedreConfig(options.currentWorkspaceRoot, { fallbackToGlobal: true });
       workspaceMap.set(
-        path6.resolve(options.currentWorkspaceRoot),
-        disc.config?.projectCode || path6.basename(options.currentWorkspaceRoot)
+        path7.resolve(options.currentWorkspaceRoot),
+        disc.config?.projectCode || path7.basename(options.currentWorkspaceRoot)
       );
     }
   }
   if (globalCfg?.projects) {
     for (const [code, p] of Object.entries(globalCfg.projects)) {
-      const resolved = path6.resolve(expandHome(p));
-      if (fs6.existsSync(resolved)) {
+      const resolved = path7.resolve(expandHome(p));
+      if (fs7.existsSync(resolved)) {
         if (!workspaceMap.has(resolved)) {
           workspaceMap.set(resolved, code);
         }
@@ -5516,15 +5556,15 @@ async function upgradeAllWorkspaces(options = {}) {
 }
 
 // src/server/gateway.ts
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 import http4 from "node:http";
-import path9 from "node:path";
+import path10 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/server/uiServer.ts
 import http2 from "node:http";
-import fs7 from "node:fs";
-import path7 from "node:path";
+import fs8 from "node:fs";
+import path8 from "node:path";
 var MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -5554,27 +5594,27 @@ function startUiServer(port, webDir) {
     if (!reqPath || reqPath === "/") {
       reqPath = "/index.html";
     }
-    const safePath = path7.normalize(reqPath).replace(/^(\.\.[/\\])+/, "");
-    let filePath = path7.join(webDir, safePath);
-    const resolvedFilePath = path7.resolve(filePath);
-    const resolvedWebDir = path7.resolve(webDir);
+    const safePath = path8.normalize(reqPath).replace(/^(\.\.[/\\])+/, "");
+    let filePath = path8.join(webDir, safePath);
+    const resolvedFilePath = path8.resolve(filePath);
+    const resolvedWebDir = path8.resolve(webDir);
     if (!resolvedFilePath.startsWith(resolvedWebDir)) {
       res.writeHead(403, { "Content-Type": "text/plain" });
       res.end("Access Denied: Path escapes web root.");
       return;
     }
-    if (!fs7.existsSync(filePath) || fs7.statSync(filePath).isDirectory()) {
-      filePath = path7.join(webDir, "index.html");
+    if (!fs8.existsSync(filePath) || fs8.statSync(filePath).isDirectory()) {
+      filePath = path8.join(webDir, "index.html");
     }
-    if (!fs7.existsSync(filePath)) {
+    if (!fs8.existsSync(filePath)) {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("Esedre UI: index.html not found. Run npm run build first.");
       return;
     }
-    const ext = path7.extname(filePath).toLowerCase();
+    const ext = path8.extname(filePath).toLowerCase();
     const contentType = MIME_TYPES[ext] || "application/octet-stream";
     try {
-      const content = fs7.readFileSync(filePath);
+      const content = fs8.readFileSync(filePath);
       res.writeHead(200, { "Content-Type": contentType });
       res.end(content);
     } catch (err) {
@@ -5596,8 +5636,8 @@ function startUiServer(port, webDir) {
 
 // src/server/apiServer.ts
 import http3 from "node:http";
-import fs8 from "node:fs";
-import path8 from "node:path";
+import fs9 from "node:fs";
+import path9 from "node:path";
 var MAX_JSON_BODY_BYTES = 10 * 1024 * 1024;
 function readJsonBody(req) {
   return new Promise((resolve, reject) => {
@@ -5893,16 +5933,16 @@ function createApiHandler(storage, workspaceRoot) {
             return true;
           }
           const filePath = reqStorage.getAttachmentPath ? reqStorage.getAttachmentPath(ticketId, file) : null;
-          if (!filePath || !fs8.existsSync(filePath)) {
+          if (!filePath || !fs9.existsSync(filePath)) {
             sendJson(res, 404, { error: "Attachment not found." });
             return true;
           }
-          const stat = fs8.statSync(filePath);
+          const stat = fs9.statSync(filePath);
           if (!stat.isFile()) {
             sendJson(res, 404, { error: "Attachment not found." });
             return true;
           }
-          const ext = path8.extname(filePath).toLowerCase();
+          const ext = path9.extname(filePath).toLowerCase();
           const mimeTypes = {
             ".png": "image/png",
             ".jpg": "image/jpeg",
@@ -5920,7 +5960,7 @@ function createApiHandler(storage, workspaceRoot) {
             "Content-Length": stat.size,
             "Cache-Control": "public, max-age=86400"
           });
-          fs8.createReadStream(filePath).pipe(res);
+          fs9.createReadStream(filePath).pipe(res);
           return true;
         }
         if (pathname === "/api/planning/plan-history") {
@@ -6211,35 +6251,35 @@ function startApiServer(port, storage, workspaceRoot) {
 
 // src/server/gateway.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = path9.dirname(__filename2);
+var __dirname2 = path10.dirname(__filename2);
 function resolveWebDir(explicitWebDir, workspaceRoot) {
-  if (explicitWebDir && fs9.existsSync(path9.join(explicitWebDir, "index.html"))) {
+  if (explicitWebDir && fs10.existsSync(path10.join(explicitWebDir, "index.html"))) {
     return explicitWebDir;
   }
   const candidates = [
     // 1. Packaged layout right next to executable (e.g. tools/web)
-    path9.resolve(__dirname2, "web"),
+    path10.resolve(__dirname2, "web"),
     // 2. From workspace root: <workspaceRoot>/dist/web
-    workspaceRoot ? path9.resolve(workspaceRoot, "dist", "web") : "",
+    workspaceRoot ? path10.resolve(workspaceRoot, "dist", "web") : "",
     // 3. In-repo legacy subfolder: <workspaceRoot>/esedre/dist/web
-    workspaceRoot ? path9.resolve(workspaceRoot, "esedre", "dist", "web") : "",
+    workspaceRoot ? path10.resolve(workspaceRoot, "esedre", "dist", "web") : "",
     // 4. Sibling standalone repository from workspace root: <workspaceRoot>/../esedre/dist/web
-    workspaceRoot ? path9.resolve(workspaceRoot, "..", "esedre", "dist", "web") : "",
+    workspaceRoot ? path10.resolve(workspaceRoot, "..", "esedre", "dist", "web") : "",
     // 5. Packaged layout inside dist/web
-    path9.resolve(__dirname2, "dist", "web"),
+    path10.resolve(__dirname2, "dist", "web"),
     // 6. Sibling standalone repository from __dirname: <__dirname>/../../esedre/dist/web
-    path9.resolve(__dirname2, "..", "..", "esedre", "dist", "web"),
+    path10.resolve(__dirname2, "..", "..", "esedre", "dist", "web"),
     // 7. Source tree layout: esedre/src/server/ -> esedre/dist/web
-    path9.resolve(__dirname2, "..", "..", "dist", "web"),
+    path10.resolve(__dirname2, "..", "..", "dist", "web"),
     // 8. Legacy layout from __dirname
-    path9.resolve(__dirname2, "..", "esedre", "dist", "web")
+    path10.resolve(__dirname2, "..", "esedre", "dist", "web")
   ].filter(Boolean);
   for (const candidate of candidates) {
-    if (fs9.existsSync(path9.join(candidate, "index.html"))) {
+    if (fs10.existsSync(path10.join(candidate, "index.html"))) {
       return candidate;
     }
   }
-  return candidates[0] || path9.resolve(__dirname2, "web");
+  return candidates[0] || path10.resolve(__dirname2, "web");
 }
 function proxyRequest(req, res, targetPort, rewritePath) {
   const targetPath = rewritePath ? rewritePath(req.url || "/") : req.url || "/";
@@ -6362,7 +6402,7 @@ ${colors.bold}ROADMAP COMMANDS (Pair Programming & LLM Agents):${colors.reset}
   ${colors.bold}update${colors.reset}      <id> [-s|--status <status>] [-t|--type <type>] [-P|--priority <prio>] [--title "..."] [--complexity <c>] [--effort "<e>"] [--detail "<md>"] [--file <path>] [--in-dev] [--flag <name>] [--last-hash <sha1>] [--force] [--json]
                Mutate ticket status, type, priority, title, complexity, effort, active state, or feature flag with OCC protection.
 
-  ${colors.bold}comment${colors.reset}     <id> ["<text>"] [--text "..."] [--author "..."] [--json]
+  ${colors.bold}comment${colors.reset}     <id> ["<text>"] [--file <path>] [--text "..."] [--author "..."] [--json]
                Append a research finding, test verification, or note to ticket history.
 
   ${colors.bold}link${colors.reset}        <sourceId> <relation> <targetId> [--author "..."] [--json]
@@ -6439,7 +6479,7 @@ ${colors.bold}OPTIONS:${colors.reset}
   --blocked            Filter tickets that are blocked by uncompleted tickets.
   --linked-to <key>    Filter tickets that are linked to a specific ticket.
   --detail "<md>"      Specification markdown for ticket detail during create or update.
-  --file <path>        Path to markdown file for detail (create, update) or implementation plan (plan).
+  --file <path>        Path to markdown file for detail (create, update), implementation plan (plan), or comment (comment).
   --json              Output raw machine-readable JSON (strongly recommended for autonomous LLM coding agents).
   --last-hash <hash>  Optimistic concurrency control: last known sha1 hash of the ticket from 'get'.
   --force             Bypass optimistic concurrency last-hash conflict checks on writes.
@@ -6512,7 +6552,7 @@ function printDuplicateProjectWarnings(storage, isJson) {
   const warnings = storage.getDuplicateProjectWarnings ? storage.getDuplicateProjectWarnings() : [];
   for (const warn of warnings) {
     console.error(
-      `${colors.yellow}\u26A0\uFE0F  Warning: Duplicate project code '${warn.code}' detected across multiple data hubs (${path10.basename(warn.firstHub)} and ${path10.basename(warn.duplicateHub)}). Duplicate project codes across hubs are not supported; only '${path10.basename(warn.firstHub)}' is active.${colors.reset}`
+      `${colors.yellow}\u26A0\uFE0F  Warning: Duplicate project code '${warn.code}' detected across multiple data hubs (${path11.basename(warn.firstHub)} and ${path11.basename(warn.duplicateHub)}). Duplicate project codes across hubs are not supported; only '${path11.basename(warn.firstHub)}' is active.${colors.reset}`
     );
   }
 }
@@ -6555,7 +6595,7 @@ async function main() {
     switch (command) {
       case "init": {
         const rawTarget = positionals[0];
-        const targetDir = rawTarget ? path10.resolve(rawTarget) : discovered.workspaceRoot;
+        const targetDir = rawTarget ? path11.resolve(rawTarget) : discovered.workspaceRoot;
         const rawHubFlag = flags["hub"];
         const hubArg = typeof rawHubFlag === "string" ? rawHubFlag : void 0;
         const isHubRequested = Boolean(rawHubFlag);
@@ -6634,7 +6674,7 @@ ${colors.bold}Next Steps:${colors.reset}`);
           console.error(`${colors.red}Error: ${nameVal.error}${colors.reset}`);
           process.exit(1);
         }
-        const isTargetHub = fs10.existsSync(path10.join(targetDir, "projects.json")) || fs10.existsSync(path10.join(targetDir, "projects")) && !fs10.existsSync(path10.join(targetDir, ".esedre", "esedre.json"));
+        const isTargetHub = fs11.existsSync(path11.join(targetDir, "projects.json")) || fs11.existsSync(path11.join(targetDir, "projects")) && !fs11.existsSync(path11.join(targetDir, ".esedre", "esedre.json"));
         const isWorkspaceless = isHubRequested || isTargetHub || Boolean(discovered.config?.projectCode) && !rawTarget && discovered.config?.projectCode?.toLowerCase() !== projectCode.toLowerCase();
         let projectNewlyRegistered = false;
         let registeredProj;
@@ -6705,7 +6745,7 @@ ${colors.bold}Next Steps:${colors.reset}`);
         const viteConfigPath = findViteConfig(targetDir);
         if (viteConfigPath && setupProxy === void 0 && !isJson) {
           try {
-            const rawContent = fs10.readFileSync(viteConfigPath, "utf-8");
+            const rawContent = fs11.readFileSync(viteConfigPath, "utf-8");
             const alreadyConfigured = rawContent.includes("'/esedre'") || rawContent.includes('"/esedre"');
             if (!alreadyConfigured) {
               if (isYes) {
@@ -6715,7 +6755,7 @@ ${colors.bold}Next Steps:${colors.reset}`);
                 const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
                 try {
                   const answer = await rl.question(
-                    `${colors.cyan}?${colors.reset} Detected ${colors.bold}${path10.basename(viteConfigPath)}${colors.reset}. Would you like to configure a reverse proxy for ${colors.bold}/esedre${colors.reset} targeting http://127.0.0.1:${port}? [Y/n] `
+                    `${colors.cyan}?${colors.reset} Detected ${colors.bold}${path11.basename(viteConfigPath)}${colors.reset}. Would you like to configure a reverse proxy for ${colors.bold}/esedre${colors.reset} targeting http://127.0.0.1:${port}? [Y/n] `
                   );
                   const trimmed = answer.trim().toLowerCase();
                   setupProxy = trimmed === "" || trimmed === "y" || trimmed === "yes";
@@ -6731,10 +6771,10 @@ ${colors.bold}Next Steps:${colors.reset}`);
         let hubRelPath = void 0;
         if (rawHub) {
           const singleHub = Array.isArray(rawHub) ? rawHub[0] : rawHub;
-          const resolvedHub = path10.resolve(expandHome(singleHub));
-          if (fs10.existsSync(resolvedHub)) {
-            const rel = path10.relative(targetDir, resolvedHub).replace(/\\/g, "/");
-            const isSubdir = !rel.startsWith("..") && !path10.isAbsolute(rel);
+          const resolvedHub = path11.resolve(expandHome(singleHub));
+          if (fs11.existsSync(resolvedHub)) {
+            const rel = path11.relative(targetDir, resolvedHub).replace(/\\/g, "/");
+            const isSubdir = !rel.startsWith("..") && !path11.isAbsolute(rel);
             if (isSubdir || Boolean(flags["data-dir"])) {
               hubRelPath = rel.startsWith(".") ? rel : "./" + rel;
             }
@@ -6908,7 +6948,7 @@ ${colors.bold}Next Steps:${colors.reset}`);
         }
         console.log(`
 ${colors.bold}${colors.cyan}Esedre Central Configuration${colors.reset}`);
-        console.log(`  \u2022 Config File:  ${configPath} ${fs10.existsSync(configPath) ? colors.green + "(active)" + colors.reset : colors.dim + "(default)" + colors.reset}`);
+        console.log(`  \u2022 Config File:  ${configPath} ${fs11.existsSync(configPath) ? colors.green + "(active)" + colors.reset : colors.dim + "(default)" + colors.reset}`);
         console.log(`  \u2022 Default Port: ${globalCfg.port || DEFAULT_ESEDRE_PORT}`);
         console.log(`
 ${colors.bold}Data Hubs (dataDir):${colors.reset}`);
@@ -6978,7 +7018,7 @@ ${colors.bold}${colors.green}\u2714 Esedre multi-workspace upgrade completed acr
           }
           return;
         }
-        const targetDir = positionals[0] ? path10.resolve(positionals[0]) : discovered.workspaceRoot;
+        const targetDir = positionals[0] ? path11.resolve(positionals[0]) : discovered.workspaceRoot;
         const targetDiscovered = targetDir === discovered.workspaceRoot ? discovered : findEsedreConfig(targetDir, { fallbackToGlobal: true });
         const res = configureWorkspace(targetDir, {
           projectCode: targetDiscovered.config?.projectCode,
@@ -7107,7 +7147,7 @@ ${colors.yellow}\u26A0\uFE0F  Warning: Daemon is running v${status.version}, but
             }
           } else {
             console.log(`${colors.yellow}\u25CB Esedre daemon is STOPPED (port ${status.port})${colors.reset}`);
-            if (status.logFile && fs10.existsSync(status.logFile)) {
+            if (status.logFile && fs11.existsSync(status.logFile)) {
               console.log(`  \u2022 Recent Logs: ${status.logFile}`);
             }
           }
@@ -7312,11 +7352,11 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
         if (setPlan || filePath) {
           let content = setPlan;
           if (filePath) {
-            if (!fs10.existsSync(filePath)) {
+            if (!fs11.existsSync(filePath)) {
               console.error(`${colors.red}Error: Plan file "${filePath}" not found.${colors.reset}`);
               process.exit(1);
             }
-            content = fs10.readFileSync(filePath, "utf-8");
+            content = fs11.readFileSync(filePath, "utf-8");
           }
           await storage.savePlan(id, content, lastHash);
           if (isJson) {
@@ -7388,8 +7428,8 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
         const milestone = flags["milestone"] || flags["m"] || void 0;
         let detailMarkdown = detailArg;
         if (fileArg) {
-          const filePath = path10.resolve(fileArg);
-          if (!fs10.existsSync(filePath)) {
+          const filePath = path11.resolve(fileArg);
+          if (!fs11.existsSync(filePath)) {
             if (isJson) {
               console.error(JSON.stringify({ error: `Detail file "${fileArg}" not found` }));
             } else {
@@ -7397,7 +7437,7 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
             }
             process.exit(1);
           }
-          detailMarkdown = fs10.readFileSync(filePath, "utf-8");
+          detailMarkdown = fs11.readFileSync(filePath, "utf-8");
         }
         const created = await storage.createTicket({
           title,
@@ -7467,8 +7507,8 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
         const fileArg = flags["file"];
         let detailMarkdown = detailArg ? normalizeDashesAndMojibake(detailArg) : void 0;
         if (fileArg) {
-          const filePath = path10.resolve(fileArg);
-          if (!fs10.existsSync(filePath)) {
+          const filePath = path11.resolve(fileArg);
+          if (!fs11.existsSync(filePath)) {
             if (isJson) {
               console.error(JSON.stringify({ error: `Detail file "${fileArg}" not found` }));
             } else {
@@ -7476,7 +7516,7 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
             }
             process.exit(1);
           }
-          detailMarkdown = normalizeDashesAndMojibake(fs10.readFileSync(filePath, "utf-8"));
+          detailMarkdown = normalizeDashesAndMojibake(fs11.readFileSync(filePath, "utf-8"));
         }
         if (detailMarkdown !== void 0) updates.detailMarkdown = detailMarkdown;
         const updated = await storage.updateTicket(lookupKey, updates, lastHash);
@@ -7634,10 +7674,30 @@ ${colors.bold}Tickets:${colors.reset}`);
         }
         const projectFlag = flags["project"];
         const lookupKey = projectFlag && /^\d+$/.test(idStr) ? `${projectFlag}-${idStr}` : idStr;
-        const positionalText = positionals.slice(1).join(" ").trim();
-        const text = flags["text"] || (positionalText || void 0);
+        let text;
+        const filePath = flags["file"];
+        if (filePath) {
+          const resolvedPath = path11.resolve(process.cwd(), filePath);
+          if (!fs11.existsSync(resolvedPath)) {
+            console.error(`${colors.red}Error: File not found: ${filePath}${colors.reset}`);
+            process.exit(1);
+          }
+          if (!fs11.statSync(resolvedPath).isFile()) {
+            console.error(`${colors.red}Error: Path is not a file: ${filePath}${colors.reset}`);
+            process.exit(1);
+          }
+          const fileContent = fs11.readFileSync(resolvedPath, "utf-8");
+          if (!fileContent.trim()) {
+            console.error(`${colors.red}Error: Comment file is empty: ${filePath}${colors.reset}`);
+            process.exit(1);
+          }
+          text = fileContent;
+        } else {
+          const positionalText = positionals.slice(1).join(" ").trim();
+          text = flags["text"] || (positionalText || void 0);
+        }
         if (!text) {
-          console.error(`${colors.red}Error: Comment text is required (e.g. ese comment 96 "Verified tests" or --text "...")${colors.reset}`);
+          console.error(`${colors.red}Error: Comment text or --file is required (e.g. ese comment 96 --file note.md or ese comment 96 "Verified tests")${colors.reset}`);
           process.exit(1);
         }
         const author = flags["author"] || "User";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esedre",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Esedre: Developer roadmap, ticketing, and LLM coding partner coordination platform",
   "homepage": "https://esedre.com",
   "repository": {