@wrongstack/plugins 1.0.7 → 1.0.10

package/dist/todo-tracker.js

@@ -1,447 +1,631 @@
 // src/todo-tracker/index.ts
 import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
-import { dirname } from "node:path";
-import { atomicWrite, ensureDir } from "@wrongstack/core/utils";
+import { basename, dirname, extname } from "node:path";
+import { ToolValidationError } from "@wrongstack/core/types";
+import { atomicWrite, ensureDir, withFileLock } from "@wrongstack/core/utils";
 import { nowIso } from "@wrongstack/primitives";
+var STATUSES = ["pending", "in_progress", "completed", "dropped"];
+var PRIORITIES = ["low", "normal", "high"];
+var defaultDeps = {
+  readFile: (p) => fsp.readFile(p, "utf8"),
+  rename: (from, to) => fsp.rename(from, to),
+  atomicWrite: (p, content, opts) => atomicWrite(p, content, opts),
+  withFileLock: (p, fn) => withFileLock(p, fn),
+  ensureDir: (dir) => ensureDir(dir)
+};
+function deriveProjectSlug(filePath) {
+  const base = basename(filePath.replace(/[\\/]+$/, "").replace(/\\/g, "/"));
+  const ext = extname(base);
+  const stem = ext && ext !== base ? base.slice(0, -ext.length) : base;
+  return stem || "tracker";
+}
 function deriveFilePath(api) {
   const raw = api.config.extensions?.["todo-tracker"];
   const rawPath = raw?.["filePath"] ?? raw?.["file_path"] ?? raw?.["path"] ?? raw?.["file"] ?? raw?.["targetFile"];
   const explicit = typeof rawPath === "string" && rawPath.trim().length > 0 ? rawPath.trim() : null;
   if (explicit) {
-    const base = explicit.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "tracker";
-    return { filePath: explicit, projectSlug: base };
+    return { filePath: explicit, projectSlug: deriveProjectSlug(explicit) };
   }
   return { filePath: null, projectSlug: null };
 }
 var FILE_VERSION = 1;
-async function loadFile(filePath) {
-  let raw;
+var isStr = (v) => typeof v === "string";
+var isOptStr = (v) => v === void 0 || v === null || typeof v === "string";
+function validateItem(raw, index) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return `items[${index}] is not an object`;
+  }
+  const it = raw;
+  if (!isStr(it["id"]) || it["id"].length === 0) return `items[${index}].id is not a string`;
+  if (!isStr(it["content"])) return `items[${index}].content is not a string`;
+  if (!STATUSES.includes(it["status"])) {
+    return `items[${index}].status is not one of ${STATUSES.join("|")}`;
+  }
+  if (!PRIORITIES.includes(it["priority"])) {
+    return `items[${index}].priority is not one of ${PRIORITIES.join("|")}`;
+  }
+  if (!Array.isArray(it["tags"]) || !it["tags"].every(isStr)) {
+    return `items[${index}].tags is not a string[]`;
+  }
+  if (!isStr(it["createdAt"]) || !isStr(it["updatedAt"])) {
+    return `items[${index}] timestamps are not strings`;
+  }
+  if (!isOptStr(it["completedAt"]) || !isOptStr(it["sourceSessionId"]) || !isOptStr(it["notes"])) {
+    return `items[${index}] optional fields are not string|null`;
+  }
+  return {
+    id: it["id"],
+    content: it["content"],
+    status: it["status"],
+    priority: it["priority"],
+    tags: [...it["tags"]],
+    createdAt: it["createdAt"],
+    updatedAt: it["updatedAt"],
+    completedAt: it["completedAt"] ?? null,
+    sourceSessionId: it["sourceSessionId"] ?? null,
+    notes: it["notes"] ?? null
+  };
+}
+function parseTrackerFile(rawText) {
+  const text = rawText.charCodeAt(0) === 65279 ? rawText.slice(1) : rawText;
+  let parsed;
   try {
-    raw = await fsp.readFile(filePath, "utf8");
+    parsed = JSON.parse(text);
   } catch (err) {
-    if (err.code === "ENOENT") return null;
-    throw err;
+    return { kind: "corrupt", reason: `invalid JSON: ${err.message}` };
   }
-  try {
-    const parsed = JSON.parse(raw);
-    if (parsed.version !== FILE_VERSION || !Array.isArray(parsed.items)) {
-      return null;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { kind: "corrupt", reason: "top-level value is not an object" };
+  }
+  const obj = parsed;
+  if (typeof obj["version"] !== "number") {
+    return { kind: "corrupt", reason: "missing or non-numeric version" };
+  }
+  if (obj["version"] !== FILE_VERSION) {
+    return { kind: "unsupportedVersion", version: obj["version"] };
+  }
+  if (!Array.isArray(obj["items"])) {
+    return { kind: "invalidItems", reason: "items is not an array" };
+  }
+  const items = [];
+  for (const [i, rawItem] of obj["items"].entries()) {
+    const v = validateItem(rawItem, i);
+    if (typeof v === "string") return { kind: "invalidItems", reason: v };
+    items.push(v);
+  }
+  return {
+    kind: "ok",
+    file: {
+      version: FILE_VERSION,
+      // Any stored slug is accepted (older versions stored the basename
+      // including the extension); the current slug is written on next save.
+      projectSlug: isStr(obj["projectSlug"]) ? obj["projectSlug"] : "",
+      updatedAt: isStr(obj["updatedAt"]) ? obj["updatedAt"] : "",
+      items
     }
-    return parsed;
-  } catch {
-    return null;
+  };
+}
+async function loadFile(deps, filePath) {
+  let raw;
+  try {
+    raw = await deps.readFile(filePath);
+  } catch (err) {
+    if (err.code === "ENOENT") return { kind: "missing" };
+    throw err;
   }
+  return parseTrackerFile(raw);
 }
-async function saveFile(filePath, file) {
-  await ensureDir(dirname(filePath));
-  await atomicWrite(filePath, JSON.stringify(file, null, 2), { mode: 384 });
+function quarantineSuffix() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-");
 }
-var state = {
-  filePath: null,
-  projectSlug: null,
-  file: null,
-  addCount: 0,
-  completeCount: 0,
-  dropCount: 0,
-  removeCount: 0,
-  pullCount: 0,
-  /** Most recent mutation for /diag plugins visibility. */
-  lastMutation: null
-};
-function ensureFile() {
-  if (!state.file) {
-    state.file = {
-      version: FILE_VERSION,
-      projectSlug: state.projectSlug ?? "unconfigured",
-      updatedAt: nowIso(),
-      items: []
-    };
-  }
-  return state.file;
+function emptyFile(slug) {
+  return { version: FILE_VERSION, projectSlug: slug, updatedAt: nowIso(), items: [] };
 }
-function recordMutation(op, itemId) {
-  state.lastMutation = { op, itemId, when: nowIso() };
-  if (op === "add") state.addCount += 1;
-  else if (op === "complete") state.completeCount += 1;
-  else if (op === "drop") state.dropCount += 1;
-  else if (op === "remove") state.removeCount += 1;
-  else if (op === "pull") state.pullCount += 1;
+function requireItemId(input) {
+  const rawId = input["id"] ?? input["itemId"] ?? input["taskId"] ?? input["todoId"];
+  const id = typeof rawId === "string" ? rawId.trim() : "";
+  if (!id) throw new ToolValidationError({ message: "id is required", field: "id" });
+  return id;
 }
-function findItemIndex(id) {
-  return ensureFile().items.findIndex((it) => it.id === id);
+function commonPrefixLength(a, b) {
+  const n = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < n && a[i] === b[i]) i++;
+  return i;
 }
-function notConfiguredError() {
-  return {
-    ok: false,
-    error: 'todo-tracker: no file path configured. Set `filePath` under `config.extensions["todo-tracker"]` or run inside a session where `paths.projectDir` is provided by the host (e.g. `wstack` CLI).'
-  };
+function requireItemIndex(file, id) {
+  const idx = file.items.findIndex((it) => it.id === id);
+  if (idx !== -1) return idx;
+  const open = file.items.filter((it) => it.status === "pending" || it.status === "in_progress");
+  const pool = open.length > 0 ? open : file.items;
+  const candidates = [...pool].sort((a, b) => commonPrefixLength(b.id, id) - commonPrefixLength(a.id, id)).slice(0, 5).map((it) => `${it.id} ("${it.content.slice(0, 40)}")`);
+  const hint = candidates.length > 0 ? ` Known ${open.length > 0 ? "open " : ""}ids: ${candidates.join(", ")}` : " The tracker is empty.";
+  throw new ToolValidationError({ message: `no item with id ${id}.${hint}`, field: "id" });
 }
-var plugin = {
-  name: "todo-tracker",
-  version: "0.1.0",
-  description: "Persistent, project-scoped todo backlog that survives across sessions",
-  apiVersion: "^0.1.10",
-  capabilities: { tools: true },
-  defaultConfig: {
-    filePath: ""
-  },
-  configSchema: {
-    type: "object",
-    properties: {
-      filePath: {
-        type: "string",
-        description: "Override the auto-derived per-project path. Defaults to <projectDir>/todo-tracker.json when `paths.projectDir` is provided by the host."
+function createTodoTrackerPlugin(overrides = {}) {
+  const deps = { ...defaultDeps, ...overrides };
+  const instances = /* @__PURE__ */ new WeakMap();
+  let latest = null;
+  function unregisterTools(inst) {
+    const unregister = inst.api.tools.unregister;
+    for (const name of inst.registeredTools.splice(0)) {
+      if (typeof unregister !== "function") continue;
+      try {
+        unregister.call(inst.api.tools, name);
+      } catch (err) {
+        inst.api.log.warn("todo-tracker: failed to unregister tool", { name, err });
       }
     }
-  },
-  async setup(api) {
-    state.addCount = 0;
-    state.completeCount = 0;
-    state.dropCount = 0;
-    state.removeCount = 0;
-    state.pullCount = 0;
-    state.lastMutation = null;
-    state.file = null;
-    const derived = deriveFilePath(api);
-    if (derived.filePath === null) {
-      api.log.warn(
-        'todo-tracker: no file path configured (set `config.extensions["todo-tracker"].filePath` or wire `paths.projectDir` through PluginAPI) \u2014 tools will report a clear error'
+  }
+  function assertWritable(inst) {
+    if (inst.readOnlyReason !== null) {
+      throw new Error(`todo-tracker: store is read-only \u2014 ${inst.readOnlyReason}`);
+    }
+  }
+  function serialize(inst, fn) {
+    const run = inst.queue.then(fn, fn);
+    inst.queue = run.catch(() => void 0);
+    return run;
+  }
+  async function quarantineLocked(inst, reason) {
+    const target = `${inst.filePath}.corrupt-${quarantineSuffix()}`;
+    try {
+      await deps.rename(inst.filePath, target);
+    } catch (err) {
+      inst.readOnlyReason = `${inst.filePath} is unreadable (${reason}) and could not be moved aside (${err.message}); fix or remove the file, then reload the plugin`;
+      inst.api.log.error(
+        "todo-tracker: corrupt file could not be quarantined; store is read-only",
+        {
+          filePath: inst.filePath,
+          reason,
+          err
+        }
       );
-      return;
+      return false;
     }
-    state.filePath = derived.filePath;
-    state.projectSlug = derived.projectSlug;
-    state.file = await loadFile(state.filePath);
-    if (state.file === null) {
-      state.file = {
-        version: FILE_VERSION,
-        projectSlug: state.projectSlug ?? "tracker",
-        updatedAt: nowIso(),
-        items: []
-      };
+    inst.degradedReason = `${inst.filePath} was unreadable (${reason}); original moved to ${target}`;
+    inst.api.log.error(`todo-tracker: corrupt file quarantined to ${target}`, {
+      filePath: inst.filePath,
+      quarantinedTo: target,
+      reason
+    });
+    return true;
+  }
+  async function resolveLoad(inst, res, opts) {
+    switch (res.kind) {
+      case "ok":
+        return res.file;
+      case "missing":
+        return emptyFile(inst.projectSlug);
+      case "unsupportedVersion": {
+        inst.readOnlyReason = `${inst.filePath} has format version ${JSON.stringify(res.version)}, this plugin only writes version ${FILE_VERSION}; refusing to modify it`;
+        inst.api.log.error("todo-tracker: unsupported file version; store is read-only", {
+          filePath: inst.filePath,
+          version: res.version
+        });
+        if (opts.strict) assertWritable(inst);
+        return emptyFile(inst.projectSlug);
+      }
+      case "corrupt":
+      case "invalidItems": {
+        const quarantine = async () => {
+          const again = opts.locked ? res : await loadFile(deps, inst.filePath);
+          if (again.kind === "ok") return again.file;
+          if (again.kind === "missing") return emptyFile(inst.projectSlug);
+          if (again.kind === "unsupportedVersion") {
+            return resolveLoad(inst, again, { locked: true, strict: opts.strict });
+          }
+          const moved = await quarantineLocked(inst, again.reason);
+          if (!moved && opts.strict) assertWritable(inst);
+          return emptyFile(inst.projectSlug);
+        };
+        return opts.locked ? quarantine() : deps.withFileLock(inst.filePath, quarantine);
+      }
     }
-    api.tools.register({
-      name: "todo_tracker_list",
-      description: "List persistent todo-tracker items. Filterable by status, priority, and tag. By default only pending + in_progress items are shown.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          status: {
-            type: "string",
-            enum: ["pending", "in_progress", "completed", "dropped", "all"],
-            description: "Filter by status. 'all' returns every item; default is pending+in_progress."
-          },
-          priority: { type: "string", enum: ["low", "normal", "high"] },
-          tag: { type: "string", description: "Filter by exact tag match" },
-          limit: { type: "number", description: "Max items to return (default 50, max 200)" }
+  }
+  async function refresh(inst) {
+    if (inst.readOnlyReason !== null) return inst.file;
+    const res = await loadFile(deps, inst.filePath);
+    const file = await resolveLoad(inst, res, { locked: false, strict: false });
+    inst.file = file;
+    return file;
+  }
+  function mutate(inst, apply) {
+    return serialize(
+      inst,
+      () => deps.withFileLock(inst.filePath, async () => {
+        assertWritable(inst);
+        const res = await loadFile(deps, inst.filePath);
+        const current = await resolveLoad(inst, res, { locked: true, strict: true });
+        const draft = structuredClone(current);
+        const now = nowIso();
+        const { changed, result } = apply(draft, now);
+        if (changed) {
+          draft.version = FILE_VERSION;
+          draft.projectSlug = inst.projectSlug;
+          draft.updatedAt = now;
+          await deps.ensureDir(dirname(inst.filePath));
+          await deps.atomicWrite(inst.filePath, JSON.stringify(draft, null, 2), { mode: 384 });
+          inst.file = draft;
+        } else {
+          inst.file = current;
         }
-      },
-      permission: "auto",
-      mutating: false,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const rawStatus = typeof input["status"] === "string" ? input["status"].trim().toLowerCase() : void 0;
-        const status = rawStatus ?? "active";
-        const rawPriority = typeof input["priority"] === "string" ? input["priority"].trim().toLowerCase() : void 0;
-        const priority = rawPriority;
-        const tag = input["tag"];
-        const limit = Math.min(Math.max(Number(input["limit"] ?? 50) || 50, 1), 200);
-        const file = ensureFile();
-        let items = file.items;
-        if (status !== "all") {
-          if (status === "active") {
-            items = items.filter((it) => it.status === "pending" || it.status === "in_progress");
-          } else {
-            items = items.filter((it) => it.status.toLowerCase() === status);
-          }
+        return result;
+      })
+    );
+  }
+  function recordMutation(inst, op, itemId) {
+    inst.lastMutation = { op, itemId, when: nowIso() };
+    if (op === "add") inst.addCount += 1;
+    else if (op === "complete") inst.completeCount += 1;
+    else if (op === "drop") inst.dropCount += 1;
+    else if (op === "remove") inst.removeCount += 1;
+  }
+  function sessionCounts(inst) {
+    return {
+      add: inst.addCount,
+      complete: inst.completeCount,
+      drop: inst.dropCount,
+      remove: inst.removeCount,
+      pull: inst.pullCount
+    };
+  }
+  function disposeInstance(api) {
+    const inst = instances.get(api);
+    if (!inst) return void 0;
+    unregisterTools(inst);
+    instances.delete(api);
+    if (latest === inst) latest = null;
+    return inst;
+  }
+  const plugin2 = {
+    name: "todo-tracker",
+    version: "0.1.0",
+    description: "Persistent, project-scoped todo backlog that survives across sessions",
+    apiVersion: "^0.1.10",
+    capabilities: { tools: true },
+    defaultConfig: {
+      filePath: ""
+    },
+    configSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+          description: "Override the auto-derived per-project path. Defaults to <projectDir>/todo-tracker.json when `paths.projectDir` is provided by the host."
         }
-        if (priority) items = items.filter((it) => it.priority.toLowerCase() === priority);
-        if (tag) items = items.filter((it) => it.tags.includes(tag));
-        const total = items.length;
-        const truncated = items.slice(0, limit);
-        return {
-          ok: true,
-          total,
-          returned: truncated.length,
-          truncated: total > truncated.length,
-          items: truncated
-        };
       }
-    });
-    api.tools.register({
-      name: "todo_tracker_add",
-      description: "Append a new item to the persistent todo-tracker backlog.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          content: { type: "string", description: "What needs doing (required)" },
-          priority: { type: "string", enum: ["low", "normal", "high"], default: "normal" },
-          tags: {
-            type: "array",
-            items: { type: "string" },
-            description: "Optional tags for filtering"
-          },
-          sourceSessionId: { type: "string", description: "Session that created this item" },
-          notes: { type: "string", description: "Optional free-form notes" }
+    },
+    async setup(api) {
+      disposeInstance(api);
+      const derived = deriveFilePath(api);
+      if (derived.filePath === null) {
+        latest = null;
+        api.log.warn(
+          'todo-tracker: no file path configured (set `config.extensions["todo-tracker"].filePath` or wire `paths.projectDir` through PluginAPI) \u2014 tools will report a clear error'
+        );
+        return;
+      }
+      const inst = {
+        api,
+        filePath: derived.filePath,
+        projectSlug: derived.projectSlug ?? "tracker",
+        file: emptyFile(derived.projectSlug ?? "tracker"),
+        readOnlyReason: null,
+        degradedReason: null,
+        queue: Promise.resolve(),
+        registeredTools: [],
+        addCount: 0,
+        completeCount: 0,
+        dropCount: 0,
+        removeCount: 0,
+        pullCount: 0,
+        lastMutation: null
+      };
+      instances.set(api, inst);
+      latest = inst;
+      await refresh(inst);
+      const register = (tool) => {
+        api.tools.register(tool);
+        inst.registeredTools.push(tool.name);
+      };
+      register({
+        name: "todo_tracker_list",
+        description: "List persistent todo-tracker items. Filterable by status, priority, and tag. By default only pending + in_progress items are shown.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            status: {
+              type: "string",
+              enum: ["pending", "in_progress", "completed", "dropped", "all"],
+              description: "Filter by status. 'all' returns every item; default is pending+in_progress."
+            },
+            priority: { type: "string", enum: ["low", "normal", "high"] },
+            tag: { type: "string", description: "Filter by exact tag match" },
+            limit: { type: "number", description: "Max items to return (default 50, max 200)" }
+          }
         },
-        required: ["content"]
-      },
-      permission: "auto",
-      mutating: true,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const rawContent = input["content"] ?? input["text"] ?? input["task"] ?? input["title"] ?? input["todo"] ?? input["message"] ?? input["item"];
-        const content = typeof rawContent === "string" ? rawContent.trim() : "";
-        if (!content) {
-          return { ok: false, error: "content is required and must be a non-empty string" };
+        permission: "auto",
+        mutating: false,
+        async execute(input) {
+          const rawStatus = typeof input["status"] === "string" ? input["status"].trim().toLowerCase() : void 0;
+          const status = rawStatus ?? "active";
+          const priority = typeof input["priority"] === "string" ? input["priority"].trim().toLowerCase() : void 0;
+          const tag = typeof input["tag"] === "string" ? input["tag"] : void 0;
+          const limit = Math.min(Math.max(Number(input["limit"] ?? 50) || 50, 1), 200);
+          const file = await refresh(inst);
+          let items = file.items;
+          if (status !== "all") {
+            if (status === "active") {
+              items = items.filter((it) => it.status === "pending" || it.status === "in_progress");
+            } else {
+              items = items.filter((it) => it.status === status);
+            }
+          }
+          if (priority) items = items.filter((it) => it.priority === priority);
+          if (tag) items = items.filter((it) => it.tags.includes(tag));
+          const total = items.length;
+          const truncated = items.slice(0, limit);
+          return {
+            ok: true,
+            total,
+            returned: truncated.length,
+            truncated: total > truncated.length,
+            items: truncated,
+            ...inst.readOnlyReason ? { readOnly: inst.readOnlyReason } : {}
+          };
         }
-        const rawPri = typeof input["priority"] === "string" ? input["priority"].trim().toLowerCase() : "";
-        const priority = rawPri === "low" || rawPri === "high" ? rawPri : "normal";
-        const tags = Array.isArray(input["tags"]) ? input["tags"].filter((t) => typeof t === "string") : [];
-        const sourceSessionId = typeof input["sourceSessionId"] === "string" ? input["sourceSessionId"] : null;
-        const notes = typeof input["notes"] === "string" ? input["notes"] : null;
-        const now = nowIso();
-        const item = {
-          id: randomUUID(),
-          content,
-          status: "pending",
-          priority,
-          tags,
-          createdAt: now,
-          updatedAt: now,
-          completedAt: null,
-          sourceSessionId,
-          notes
-        };
-        const file = ensureFile();
-        file.items.push(item);
-        file.updatedAt = now;
-        await saveFile(state.filePath, file);
-        recordMutation("add", item.id);
-        api.log.info("todo-tracker: added item", { id: item.id, content });
-        try {
-          await api.session?.append?.({
-            type: "todo-tracker:add",
-            ts: now,
-            id: item.id,
-            content,
-            priority,
-            tags
+      });
+      register({
+        name: "todo_tracker_add",
+        description: "Append a new item to the persistent todo-tracker backlog.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "What needs doing (required)" },
+            priority: { type: "string", enum: ["low", "normal", "high"], default: "normal" },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional tags for filtering"
+            },
+            sourceSessionId: { type: "string", description: "Session that created this item" },
+            notes: { type: "string", description: "Optional free-form notes" }
+          },
+          required: ["content"]
+        },
+        permission: "auto",
+        mutating: true,
+        async execute(input) {
+          const rawContent = input["content"] ?? input["text"] ?? input["task"] ?? input["title"] ?? input["todo"] ?? input["message"] ?? input["item"];
+          const content = typeof rawContent === "string" ? rawContent.trim() : "";
+          if (!content) {
+            throw new ToolValidationError({
+              message: "content is required and must be a non-empty string",
+              field: "content"
+            });
+          }
+          const rawPri = typeof input["priority"] === "string" ? input["priority"].trim().toLowerCase() : "";
+          const priority = rawPri === "low" || rawPri === "high" ? rawPri : "normal";
+          const tags = Array.isArray(input["tags"]) ? input["tags"].filter((t) => typeof t === "string") : [];
+          const sourceSessionId = typeof input["sourceSessionId"] === "string" ? input["sourceSessionId"] : null;
+          const notes = typeof input["notes"] === "string" ? input["notes"] : null;
+          const item = await mutate(inst, (draft, now) => {
+            const created = {
+              id: randomUUID(),
+              content,
+              status: "pending",
+              priority,
+              tags,
+              createdAt: now,
+              updatedAt: now,
+              completedAt: null,
+              sourceSessionId,
+              notes
+            };
+            draft.items.push(created);
+            return { changed: true, result: created };
           });
-        } catch {
+          recordMutation(inst, "add", item.id);
+          api.log.info("todo-tracker: added item", { id: item.id, content });
+          try {
+            await api.session?.append?.({
+              type: "todo-tracker:add",
+              ts: item.createdAt,
+              id: item.id,
+              content,
+              priority,
+              tags
+            });
+          } catch (err) {
+            api.log.warn("todo-tracker: session.append failed (item was saved)", {
+              id: item.id,
+              err
+            });
+          }
+          return { ok: true, item };
         }
-        return { ok: true, item };
-      }
-    });
-    api.tools.register({
-      name: "todo_tracker_complete",
-      description: "Mark a tracked item as completed. Idempotent.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Item id" }
+      });
+      const setTerminalStatus = async (input, target) => {
+        const id = requireItemId(input);
+        return mutate(inst, (draft, now) => {
+          const item = draft.items[requireItemIndex(draft, id)];
+          if (item.status === target) {
+            return {
+              changed: false,
+              result: { ok: true, item, message: `already ${target} (idempotent)` }
+            };
+          }
+          item.status = target;
+          item.updatedAt = now;
+          item.completedAt = now;
+          return { changed: true, result: { ok: true, item } };
+        });
+      };
+      register({
+        name: "todo_tracker_complete",
+        description: "Mark a tracked item as completed. Idempotent.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Item id" }
+          },
+          required: ["id"]
         },
-        required: ["id"]
-      },
-      permission: "auto",
-      mutating: true,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const rawId = input["id"] ?? input["itemId"] ?? input["taskId"] ?? input["todoId"];
-        const id = typeof rawId === "string" ? rawId.trim() : "";
-        if (!id) return { ok: false, error: "id is required" };
-        const idx = findItemIndex(id);
-        if (idx === -1) return { ok: false, error: `no item with id ${id}` };
-        const file = ensureFile();
-        const item = file.items[idx];
-        if (item.status === "completed") {
-          return { ok: true, item, message: "already completed (idempotent)" };
+        permission: "auto",
+        mutating: true,
+        async execute(input) {
+          const result = await setTerminalStatus(input, "completed");
+          if (!result.message) {
+            recordMutation(inst, "complete", result.item.id);
+            api.log.info("todo-tracker: completed item", { id: result.item.id });
+          }
+          return result;
         }
-        const now = nowIso();
-        item.status = "completed";
-        item.updatedAt = now;
-        item.completedAt = now;
-        file.updatedAt = now;
-        await saveFile(state.filePath, file);
-        recordMutation("complete", id);
-        api.log.info("todo-tracker: completed item", { id });
-        return { ok: true, item };
-      }
-    });
-    api.tools.register({
-      name: "todo_tracker_drop",
-      description: "Mark a tracked item as dropped (skipped/obsolete). The row is kept for audit. Idempotent.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Item id" }
+      });
+      register({
+        name: "todo_tracker_drop",
+        description: "Mark a tracked item as dropped (skipped/obsolete). The row is kept for audit. Idempotent.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Item id" }
+          },
+          required: ["id"]
         },
-        required: ["id"]
-      },
-      permission: "auto",
-      mutating: true,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const rawId = input["id"] ?? input["itemId"] ?? input["taskId"] ?? input["todoId"];
-        const id = typeof rawId === "string" ? rawId.trim() : "";
-        if (!id) return { ok: false, error: "id is required" };
-        const idx = findItemIndex(id);
-        if (idx === -1) return { ok: false, error: `no item with id ${id}` };
-        const file = ensureFile();
-        const item = file.items[idx];
-        if (item.status === "dropped") {
-          return { ok: true, item, message: "already dropped (idempotent)" };
+        permission: "auto",
+        mutating: true,
+        async execute(input) {
+          const result = await setTerminalStatus(input, "dropped");
+          if (!result.message) recordMutation(inst, "drop", result.item.id);
+          return result;
         }
-        const now = nowIso();
-        item.status = "dropped";
-        item.updatedAt = now;
-        item.completedAt = now;
-        file.updatedAt = now;
-        await saveFile(state.filePath, file);
-        recordMutation("drop", id);
-        return { ok: true, item };
-      }
-    });
-    api.tools.register({
-      name: "todo_tracker_remove",
-      description: "Permanently delete a tracked item by id. Use todo_tracker_drop instead if you want to keep the audit row.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Item id" }
+      });
+      register({
+        name: "todo_tracker_remove",
+        description: "Permanently delete a tracked item by id. Use todo_tracker_drop instead if you want to keep the audit row.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Item id" }
+          },
+          required: ["id"]
         },
-        required: ["id"]
-      },
-      permission: "confirm",
-      mutating: true,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const rawId = input["id"] ?? input["itemId"] ?? input["taskId"] ?? input["todoId"];
-        const id = typeof rawId === "string" ? rawId.trim() : "";
-        if (!id) return { ok: false, error: "id is required" };
-        const idx = findItemIndex(id);
-        if (idx === -1) return { ok: false, error: `no item with id ${id}` };
-        const file = ensureFile();
-        const [removed] = file.items.splice(idx, 1);
-        file.updatedAt = nowIso();
-        await saveFile(state.filePath, file);
-        recordMutation("remove", id);
-        return { ok: true, removed };
-      }
-    });
-    api.tools.register({
-      name: "todo_tracker_pull",
-      description: "Return all pending + in_progress items. The LLM is expected to take this list and re-register each entry with the session-local `todo` tool (which mutates ctx.todos). After pull, the LLM may also choose to call todo_tracker_complete on items it finishes mid-session.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          limit: { type: "number", description: "Max items to return (default 50, max 200)" }
+        permission: "confirm",
+        mutating: true,
+        async execute(input) {
+          const id = requireItemId(input);
+          const removed = await mutate(inst, (draft) => {
+            const [gone] = draft.items.splice(requireItemIndex(draft, id), 1);
+            return { changed: true, result: gone };
+          });
+          recordMutation(inst, "remove", id);
+          return { ok: true, removed };
         }
-      },
-      permission: "auto",
-      mutating: false,
-      async execute(input) {
-        if (state.filePath === null) return notConfiguredError();
-        const limit = Math.min(Math.max(Number(input["limit"] ?? 50) || 50, 1), 200);
-        const file = ensureFile();
-        const items = file.items.filter((it) => it.status === "pending" || it.status === "in_progress").slice(0, limit);
-        if (items.length > 0) {
-          recordMutation("pull", items[0].id);
+      });
+      register({
+        name: "todo_tracker_pull",
+        description: "Return all pending + in_progress items. The LLM is expected to take this list and re-register each entry with the session-local `todo` tool (which mutates ctx.todos). After pull, the LLM may also choose to call todo_tracker_complete on items it finishes mid-session.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: { type: "number", description: "Max items to return (default 50, max 200)" }
+          }
+        },
+        permission: "auto",
+        mutating: false,
+        async execute(input) {
+          const limit = Math.min(Math.max(Number(input["limit"] ?? 50) || 50, 1), 200);
+          const file = await refresh(inst);
+          const open = file.items.filter(
+            (it) => it.status === "pending" || it.status === "in_progress"
+          );
+          const items = open.slice(0, limit);
+          if (items.length > 0) inst.pullCount += 1;
+          return {
+            ok: true,
+            total: open.length,
+            returned: items.length,
+            truncated: open.length > items.length,
+            items,
+            hint: "These are persistent items. To work on them this session, register each one with the built-in `todo` tool. Mark them `completed` via todo_tracker_complete when done."
+          };
         }
+      });
+      register({
+        name: "todo_tracker_status",
+        description: "Report todo-tracker counters (per-status totals) + the file path + last update timestamp.",
+        inputSchema: { type: "object", properties: {} },
+        permission: "auto",
+        mutating: false,
+        async execute() {
+          const file = await refresh(inst);
+          const byStatus = {
+            pending: 0,
+            in_progress: 0,
+            completed: 0,
+            dropped: 0
+          };
+          for (const it of file.items) {
+            if (STATUSES.includes(it.status)) byStatus[it.status] += 1;
+          }
+          return {
+            ok: true,
+            filePath: inst.filePath,
+            projectSlug: inst.projectSlug,
+            updatedAt: file.updatedAt,
+            counters: byStatus,
+            total: file.items.length,
+            session: sessionCounts(inst),
+            lastMutation: inst.lastMutation,
+            readOnly: inst.readOnlyReason,
+            degraded: inst.degradedReason
+          };
+        }
+      });
+      api.log.info("todo-tracker plugin loaded", {
+        filePath: inst.filePath,
+        projectSlug: inst.projectSlug,
+        initialItemCount: inst.file.items.length,
+        readOnly: inst.readOnlyReason,
+        degraded: inst.degradedReason
+      });
+    },
+    teardown(api) {
+      const inst = disposeInstance(api);
+      if (!inst) return;
+      api.log.info("todo-tracker: teardown complete", { sessionCounts: sessionCounts(inst) });
+    },
+    async health() {
+      const inst = latest;
+      if (inst === null) {
         return {
-          ok: true,
-          total: items.length,
-          items,
-          hint: "These are persistent items. To work on them this session, register each one with the built-in `todo` tool. Mark them `completed` via todo_tracker_complete when done."
-        };
-      }
-    });
-    api.tools.register({
-      name: "todo_tracker_status",
-      description: "Report todo-tracker counters (per-status totals) + the file path + last update timestamp.",
-      inputSchema: { type: "object", properties: {} },
-      permission: "auto",
-      mutating: false,
-      async execute() {
-        if (state.filePath === null) return notConfiguredError();
-        const file = ensureFile();
-        const byStatus = {
-          pending: 0,
-          in_progress: 0,
-          completed: 0,
-          dropped: 0
-        };
-        for (const it of file.items) byStatus[it.status] += 1;
-        return {
-          ok: true,
-          filePath: state.filePath,
-          projectSlug: state.projectSlug,
-          updatedAt: file.updatedAt,
-          counters: byStatus,
-          total: file.items.length,
-          session: {
-            add: state.addCount,
-            complete: state.completeCount,
-            drop: state.dropCount,
-            remove: state.removeCount,
-            pull: state.pullCount
-          },
-          lastMutation: state.lastMutation
+          ok: false,
+          message: "todo-tracker: no file path configured \u2014 tools will error"
         };
       }
-    });
-    api.log.info("todo-tracker plugin loaded", {
-      filePath: state.filePath,
-      projectSlug: state.projectSlug,
-      initialItemCount: state.file.items.length
-    });
-  },
-  teardown(api) {
-    const finalCounts = {
-      add: state.addCount,
-      complete: state.completeCount,
-      drop: state.dropCount,
-      remove: state.removeCount,
-      pull: state.pullCount
-    };
-    state.addCount = 0;
-    state.completeCount = 0;
-    state.dropCount = 0;
-    state.removeCount = 0;
-    state.pullCount = 0;
-    state.lastMutation = null;
-    state.file = null;
-    state.filePath = null;
-    state.projectSlug = null;
-    api.log.info("todo-tracker: teardown complete", { sessionCounts: finalCounts });
-  },
-  async health() {
-    if (state.filePath === null) {
+      const reason = inst.readOnlyReason ?? inst.degradedReason;
       return {
-        ok: false,
-        message: "todo-tracker: no file path configured \u2014 tools will error"
+        ok: reason === null,
+        message: reason === null ? `todo-tracker: ${inst.file.items.length} item(s) at ${inst.filePath}` : `todo-tracker: ${inst.readOnlyReason ? "read-only" : "degraded"} \u2014 ${reason}`,
+        filePath: inst.filePath,
+        projectSlug: inst.projectSlug,
+        total: inst.file.items.length,
+        readOnly: inst.readOnlyReason,
+        degraded: inst.degradedReason,
+        sessionCounts: sessionCounts(inst),
+        lastMutation: inst.lastMutation
       };
     }
-    const file = ensureFile();
-    return {
-      ok: true,
-      message: `todo-tracker: ${file.items.length} item(s) at ${state.filePath}`,
-      filePath: state.filePath,
-      projectSlug: state.projectSlug,
-      total: file.items.length,
-      sessionCounts: {
-        add: state.addCount,
-        complete: state.completeCount,
-        drop: state.dropCount,
-        remove: state.removeCount,
-        pull: state.pullCount
-      },
-      lastMutation: state.lastMutation
-    };
-  }
-};
+  };
+  return plugin2;
+}
+var plugin = createTodoTrackerPlugin();
 var todo_tracker_default = plugin;
 export {
-  todo_tracker_default as default
+  createTodoTrackerPlugin,
+  todo_tracker_default as default,
+  deriveProjectSlug,
+  parseTrackerFile
 };