@hasna/todos 0.13.12 → 0.15.1

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.13.12",
+    version: "0.15.1",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -2258,7 +2258,10 @@ var init_package_version = __esm(() => {
 function isBlockingDependencyStatus(status) {
   return status !== "completed" && status !== "cancelled";
 }
-var TASK_STATUSES, TASK_PRIORITIES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DispatchNotFoundError;
+function isTerminalStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+var TASK_STATUSES, TASK_PRIORITIES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
 var init_types = __esm(() => {
   TASK_STATUSES = [
     "pending",
@@ -2427,6 +2430,7 @@ var init_types = __esm(() => {
       this.name = "CompletionGuardError";
     }
   };
+  DISPATCH_STATUSES = ["pending", "sent", "failed", "cancelled"];
   DispatchNotFoundError = class DispatchNotFoundError extends Error {
     dispatchId;
     static code = "DISPATCH_NOT_FOUND";
@@ -2440,11 +2444,30 @@ var init_types = __esm(() => {
 });
 
 // src/lib/sync-utils.ts
+var exports_sync_utils = {};
+__export(exports_sync_utils, {
+  writeJsonFile: () => writeJsonFile,
+  writeHighWaterMark: () => writeHighWaterMark,
+  withSyncFingerprint: () => withSyncFingerprint,
+  readJsonFile: () => readJsonFile,
+  readHighWaterMark: () => readHighWaterMark,
+  parseTimestamp: () => parseTimestamp,
+  listJsonFiles: () => listJsonFiles,
+  hasSyncFingerprintChanged: () => hasSyncFingerprintChanged,
+  getTodosGlobalDir: () => getTodosGlobalDir,
+  getHomeDir: () => getHomeDir,
+  getFileMtimeMs: () => getFileMtimeMs,
+  ensureDir: () => ensureDir,
+  appendSyncConflict: () => appendSyncConflict,
+  TODO_SYNC_FINGERPRINT_KEY: () => TODO_SYNC_FINGERPRINT_KEY,
+  HOME: () => HOME
+});
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { createHash } from "crypto";
+import { homedir } from "os";
 import { join } from "path";
 function getHomeDir() {
-  return process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir();
 }
 function getTodosGlobalDir() {
   return join(getHomeDir(), ".hasna", "todos");
@@ -2532,7 +2555,7 @@ function hasSyncFingerprintChanged(record) {
 }
 var TODO_SYNC_FINGERPRINT_KEY = "todos_sync_fingerprint", HOME;
 var init_sync_utils = __esm(() => {
-  HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  HOME = getHomeDir();
 });
 
 // src/lib/config.ts
@@ -6410,6 +6433,15 @@ function hasOption(args, option) {
 function positionalArgs(args) {
   return args.filter((arg) => !arg.startsWith("-"));
 }
+function isBundledStaticInvocation(invocation) {
+  const command = invocation.command;
+  if (!command)
+    return false;
+  const storeBackedOptions = BUNDLED_STATIC_STORE_BACKED_OPTIONS.get(command);
+  if (!storeBackedOptions)
+    return false;
+  return !storeBackedOptions.some((option) => hasOption(invocation.commandArgs, option));
+}
 function isReadOnlyConfigInvocation(invocation) {
   if (invocation.command !== "config")
     return false;
@@ -6430,6 +6462,8 @@ function isMetadataInvocation(args, invocation) {
     return true;
   if (invocation.command === "manual" && invocation.commandArgs.length === 0)
     return true;
+  if (isBundledStaticInvocation(invocation))
+    return true;
   if (invocation.command === "help" && invocation.commandArgs.every((arg) => !arg.startsWith("-")))
     return true;
   if (invocation.command === "config") {
@@ -6447,6 +6481,14 @@ function firstPresentOption(args, candidates) {
 function disqualifyingArgument(invocation) {
   const command = invocation.command;
   const args = invocation.commandArgs;
+  const storeBackedOptions = BUNDLED_STATIC_STORE_BACKED_OPTIONS.get(command);
+  if (storeBackedOptions) {
+    const option = storeBackedOptions.find((candidate) => hasOption(args, candidate));
+    return option ? {
+      blame: option,
+      remedy: `it imports bundled fixtures into the local store, which this route disables; re-run \`${command}\` without it to read the bundled content`
+    } : null;
+  }
   switch (command) {
     case "task":
       return positionalArgs(args)[0] === "upsert" ? null : { blame: "any subcommand other than `upsert`", remedy: "use `todos task upsert`" };
@@ -6474,13 +6516,22 @@ function disqualifyingArgument(invocation) {
       const action = positionalArgs(args)[0];
       if (action === "plan" || action === "move-plan")
         return null;
+      if (action === "tag" || action === "untag") {
+        if (!hasOption(args, "--tag") && !hasOption(args, "--tags")) {
+          return {
+            blame: `\`bulk ${action}\` without --tag`,
+            remedy: `pass --tag <comma-separated>, e.g. bulk ${action} <ids...> --tag directive:k_msd4cz8t_ste6f4`
+          };
+        }
+        return firstPresentOption(args, ["--plan", "--clear-plan"]);
+      }
       if (!action) {
-        return { blame: "a missing action", remedy: "pass one of done, complete, start, delete, plan, move-plan" };
+        return { blame: "a missing action", remedy: "pass one of done, complete, start, delete, plan, move-plan, tag, untag" };
       }
       if (!["done", "complete", "start", "delete"].includes(action)) {
         return {
           blame: `the \`${action}\` action`,
-          remedy: "use one of done, complete, start, delete, plan, move-plan"
+          remedy: "use one of done, complete, start, delete, plan, move-plan, tag, untag"
         };
       }
       return firstPresentOption(args, ["--plan", "--clear-plan"]);
@@ -6537,7 +6588,8 @@ function assertRemoteCommandSupported(invocation) {
   }
   if (!command || !commandSupportsRemote(invocation)) {
     const blame = command ? disqualifyingArgument(invocation) : null;
-    const detail = blame ? `\`${command}\` is served by the Todos /v1 authority but ${blame.blame} is not; ${blame.remedy}` : `${invocationLabel(invocation)} is not supported by the Todos /v1 CLI; local SQLite fallback is disabled`;
+    const servedBy = command && BUNDLED_STATIC_STORE_BACKED_OPTIONS.has(command) ? `\`${command}\` renders bundled content on this route` : `\`${command}\` is served by the Todos /v1 authority`;
+    const detail = blame ? `${servedBy} but ${blame.blame} is not; ${blame.remedy}` : `${invocationLabel(invocation)} is not supported by the Todos /v1 CLI; local SQLite fallback is disabled`;
     throw new Error(`REMOTE_COMMAND_UNSUPPORTED: ${detail}`);
   }
 }
@@ -6557,7 +6609,7 @@ function initializeTodosCliAuthority(args = process.argv.slice(2), env = process
   }
   return { route: "remote-http", v1_base_url: client.baseUrl };
 }
-var REGISTERED_CANONICAL_COMMANDS, TODOS_CLI_COMMAND_ALIASES, DIAGNOSTIC_COMMANDS, REMOTE_COMMANDS, COMMAND_CAPABILITY_MATRIX, GLOBAL_OPTIONS_WITH_VALUES, GLOBAL_FLAGS, HELP_FLAGS, VERSION_FLAGS, dropIt = (blame) => ({ blame, remedy: "re-run without it" });
+var REGISTERED_CANONICAL_COMMANDS, TODOS_CLI_COMMAND_ALIASES, BUNDLED_STATIC_COMMANDS, BUNDLED_STATIC_STORE_BACKED_OPTIONS, DIAGNOSTIC_COMMANDS, REMOTE_COMMANDS, COMMAND_CAPABILITY_MATRIX, GLOBAL_OPTIONS_WITH_VALUES, GLOBAL_FLAGS, HELP_FLAGS, VERSION_FLAGS, dropIt = (blame) => ({ blame, remedy: "re-run without it" });
 var init_stage_a = __esm(() => {
   init_esm();
   init_cloud_router();
@@ -6747,7 +6799,28 @@ var init_stage_a = __esm(() => {
     reliability: ["scorecards"],
     lists: ["task-lists", "tl"]
   };
-  DIAGNOSTIC_COMMANDS = new Set(["help", "manual", "completions", "completion", "config", "storage"]);
+  BUNDLED_STATIC_COMMANDS = {
+    workflows: [],
+    "template-library": [],
+    onboarding: ["--import"],
+    "sdk-fixtures": ["--show", "--write"]
+  };
+  BUNDLED_STATIC_STORE_BACKED_OPTIONS = new Map;
+  for (const [canonical, storeBackedOptions] of Object.entries(BUNDLED_STATIC_COMMANDS)) {
+    BUNDLED_STATIC_STORE_BACKED_OPTIONS.set(canonical, storeBackedOptions);
+    const aliases = TODOS_CLI_COMMAND_ALIASES[canonical] ?? [];
+    for (const alias of aliases)
+      BUNDLED_STATIC_STORE_BACKED_OPTIONS.set(alias, storeBackedOptions);
+  }
+  DIAGNOSTIC_COMMANDS = new Set([
+    "help",
+    "manual",
+    "completions",
+    "completion",
+    "config",
+    "storage",
+    ...Object.keys(BUNDLED_STATIC_COMMANDS)
+  ]);
   REMOTE_COMMANDS = new Set([
     "active",
     "add",
@@ -10769,8 +10842,7 @@ function findGitRoot(startDir) {
   return null;
 }
 function getGlobalDbPath() {
-  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  return join3(home, ".hasna", "todos", "todos.db");
+  return join3(getHomeDir(), ".hasna", "todos", "todos.db");
 }
 function hasExplicitProjectArg(args = process.argv.slice(2)) {
   return args.some((arg) => arg === "--project" || arg.startsWith("--project="));
@@ -10992,6 +11064,7 @@ var init_database = __esm(() => {
   init_machines();
   init_identity_mapping();
   init_types();
+  init_sync_utils();
   ALLOWED_TABLES = new Set(["tasks", "projects", "agents", "plans", "task_lists", "task_templates", "project_knowledge_records", "project_risks", "local_retrospectives"]);
 });
 
@@ -11456,6 +11529,103 @@ var init_lock_display = __esm(() => {
   init_database();
 });
 
+// src/lib/enum-vocabulary.ts
+function editDistance2(a, b) {
+  if (a === b)
+    return 0;
+  if (!a.length)
+    return b.length;
+  if (!b.length)
+    return a.length;
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1;i <= a.length; i += 1) {
+    const current = [i];
+    for (let j = 1;j <= b.length; j += 1) {
+      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+function suggestVocabularyMatches(value, vocabulary, limit = 3) {
+  const needle = value.trim().toLowerCase();
+  if (!needle)
+    return [];
+  const scored = [];
+  for (const member of vocabulary) {
+    const candidate = member.toLowerCase();
+    if (candidate.startsWith(needle) || needle.startsWith(candidate)) {
+      scored.push({ member, score: 0 });
+      continue;
+    }
+    if (candidate.includes(needle) || needle.includes(candidate)) {
+      scored.push({ member, score: 1 });
+      continue;
+    }
+    const distance = editDistance2(needle, candidate);
+    if (distance <= Math.max(1, Math.floor(candidate.length / 3))) {
+      scored.push({ member, score: 1 + distance });
+    }
+  }
+  return scored.sort((a, b) => a.score - b.score || a.member.localeCompare(b.member)).slice(0, limit).map((entry) => entry.member);
+}
+function resolveEnumVocabulary(raw, spec) {
+  const allowList = spec.allowList !== false;
+  const rawElements = (allowList ? raw.split(",") : [raw]).map((element) => element.trim());
+  if (rawElements.every((element) => element.length === 0)) {
+    return {
+      ok: false,
+      message: `${spec.name} requires a value. Allowed values: ${spec.vocabulary.join(", ")}.`,
+      invalid: []
+    };
+  }
+  if (rawElements.some((element) => element.length === 0)) {
+    return {
+      ok: false,
+      message: `${spec.name} has an empty value in "${raw}" \u2014 remove the stray comma. ` + `Allowed values: ${spec.vocabulary.join(", ")}.`,
+      invalid: []
+    };
+  }
+  const normalized = rawElements.map((element) => spec.normalize ? spec.normalize(element) : element);
+  const allowed = new Set(spec.vocabulary);
+  const invalid2 = [];
+  for (let i = 0;i < normalized.length; i += 1) {
+    if (!allowed.has(normalized[i]))
+      invalid2.push(rawElements[i]);
+  }
+  if (invalid2.length === 0) {
+    return { ok: true, values: [...new Set(normalized)] };
+  }
+  const label = invalid2.length === 1 ? "value" : "values";
+  const parts = [
+    `Invalid ${spec.name} ${label}: ${invalid2.join(", ")}.`,
+    `Allowed values: ${spec.vocabulary.join(", ")}.`
+  ];
+  const hints = new Set;
+  const suggestions = new Set;
+  for (let i = 0;i < normalized.length; i += 1) {
+    const canonical = normalized[i];
+    if (allowed.has(canonical))
+      continue;
+    const hint = spec.hints?.[canonical.toLowerCase()];
+    if (hint) {
+      hints.add(hint);
+      continue;
+    }
+    for (const match of suggestVocabularyMatches(canonical, spec.vocabulary)) {
+      suggestions.add(match);
+    }
+  }
+  if (suggestions.size > 0)
+    parts.push(`Did you mean ${[...suggestions].join(", ")}?`);
+  for (const hint of hints)
+    parts.push(hint);
+  return { ok: false, message: parts.join(" "), invalid: invalid2 };
+}
+function collapseEnumValues(values) {
+  return values.length === 1 ? values[0] : values;
+}
+
 // src/cli/helpers.ts
 var exports_helpers = {};
 __export(exports_helpers, {
@@ -11466,9 +11636,13 @@ __export(exports_helpers, {
   resolveExplicitProject: () => resolveExplicitProject,
   priorityColors: () => priorityColors,
   printJson: () => printJson,
+  parseEnumFlagList: () => parseEnumFlagList,
+  parseEnumFlag: () => parseEnumFlag,
+  outputRecord: () => outputRecord,
   output: () => output,
   normalizeStatusList: () => normalizeStatusList,
   normalizeStatus: () => normalizeStatus,
+  normalizePriority: () => normalizePriority,
   jsonModeRequested: () => jsonModeRequested,
   handleError: () => handleError,
   getPackageVersion: () => getPackageVersion,
@@ -11476,7 +11650,10 @@ __export(exports_helpers, {
   detectGitRoot: () => detectGitRoot,
   cacheCloudTaskForIdResolution: () => cacheCloudTaskForIdResolution,
   autoProject: () => autoProject,
-  autoDetectProject: () => autoDetectProject
+  autoDetectProject: () => autoDetectProject,
+  TASK_STATUS_FLAG_HINTS: () => TASK_STATUS_FLAG_HINTS,
+  TASK_STATUS_FLAG: () => TASK_STATUS_FLAG,
+  TASK_PRIORITY_FLAG: () => TASK_PRIORITY_FLAG
 });
 import chalk from "chalk";
 import { execSync } from "child_process";
@@ -11486,8 +11663,19 @@ import { dirname as dirname3, join as join4, resolve as resolve3, sep } from "pa
 function jsonModeRequested(argv = process.argv) {
   return argv.some((arg) => arg === "--json" || /^-[a-z]+$/i.test(arg) && arg.includes("j"));
 }
+function remoteErrorDetail(e) {
+  if (!e || typeof e !== "object")
+    return null;
+  const body = e.body;
+  if (!body || typeof body !== "object" || Array.isArray(body))
+    return null;
+  const detail = body.error;
+  return typeof detail === "string" && detail.trim() ? detail.trim() : null;
+}
 function handleError(e) {
-  const message = e instanceof Error ? e.message : String(e);
+  const baseMessage = e instanceof Error ? e.message : String(e);
+  const detail = remoteErrorDetail(e);
+  const message = detail && !baseMessage.includes(detail) ? `${baseMessage}: ${detail}` : baseMessage;
   console.error(chalk.red(message));
   if (jsonModeRequested()) {
     console.log(JSON.stringify({ error: message }));
@@ -11665,7 +11853,8 @@ function autoProject(opts) {
   return autoDetectProject(opts)?.id;
 }
 function normalizeStatus(s) {
-  switch (s.toLowerCase().trim()) {
+  const folded = s.toLowerCase().trim();
+  switch (folded) {
     case "done":
       return "completed";
     case "complete":
@@ -11679,14 +11868,33 @@ function normalizeStatus(s) {
     case "canceled":
       return "cancelled";
     default:
-      return s;
+      return folded;
   }
 }
+function normalizePriority(p) {
+  return p.toLowerCase().trim();
+}
 function normalizeStatusList(statuses) {
   if (Array.isArray(statuses))
     return statuses.map(normalizeStatus);
   return normalizeStatus(statuses);
 }
+function parseEnumFlag(raw, spec) {
+  if (raw === undefined || raw === null)
+    return;
+  const result = resolveEnumVocabulary(String(raw), spec);
+  if (!result.ok)
+    handleError(new Error(result.message));
+  return collapseEnumValues(result.values);
+}
+function parseEnumFlagList(raw, spec) {
+  if (raw === undefined || raw === null)
+    return;
+  const result = resolveEnumVocabulary(String(raw), spec);
+  if (!result.ok)
+    handleError(new Error(result.message));
+  return result.values;
+}
 function writeStdoutSync(text) {
   const buffer = Buffer.from(text);
   let offset = 0;
@@ -11718,6 +11926,41 @@ function output(data, jsonMode) {
     printJson(data);
   }
 }
+function formatRecordLines(data) {
+  if (data === null || data === undefined)
+    return [];
+  if (typeof data !== "object")
+    return [String(data)];
+  if (Array.isArray(data)) {
+    return data.flatMap((entry, index) => [
+      chalk.dim(`[${index}]`),
+      ...formatRecordLines(entry).map((line) => `  ${line}`)
+    ]);
+  }
+  const lines = [];
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined)
+      continue;
+    const rendered = value === null ? chalk.dim("\u2014") : typeof value === "object" ? JSON.stringify(value) : String(value);
+    lines.push(`  ${chalk.dim(`${key}:`)} ${rendered}`);
+  }
+  return lines;
+}
+function outputRecord(data, jsonMode, heading) {
+  if (jsonMode) {
+    printJson(data);
+    return;
+  }
+  if (heading)
+    console.log(chalk.bold(heading));
+  const lines = formatRecordLines(data);
+  if (lines.length === 0) {
+    console.log(chalk.dim("(empty)"));
+    return;
+  }
+  for (const line of lines)
+    console.log(line);
+}
 function formatTaskLine(t) {
   const statusFn = statusColors[t.status] || chalk.white;
   const priorityFn = priorityColors[t.priority] || chalk.white;
@@ -11728,16 +11971,33 @@ function formatTaskLine(t) {
   const plan = t.plan_id ? chalk.magenta(` [plan:${t.plan_id.slice(0, 8)}]`) : "";
   return `${chalk.dim(t.id.slice(0, 8))} ${statusFn(t.status.padEnd(11))} ${priorityFn(t.priority.padEnd(8))} ${t.title}${assigned}${lock}${tags}${plan}`;
 }
-var stdoutRetryBuffer, stdoutRetrySignal, TASK_UUID_RE, statusColors, priorityColors;
+var stdoutRetryBuffer, stdoutRetrySignal, TASK_UUID_RE, TASK_STATUS_FLAG_HINTS, TASK_STATUS_FLAG, TASK_PRIORITY_FLAG, statusColors, priorityColors;
 var init_helpers = __esm(() => {
   init_cloud_router();
   init_database();
   init_projects();
   init_lock_display();
   init_package_version();
+  init_types();
   stdoutRetryBuffer = new SharedArrayBuffer(4);
   stdoutRetrySignal = new Int32Array(stdoutRetryBuffer);
   TASK_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  TASK_STATUS_FLAG_HINTS = {
+    all: "To include every status, use -a/--all instead of a --status value.",
+    any: "To include every status, use -a/--all instead of a --status value.",
+    open: "Unstarted and running work is pending and in_progress (the default when no --status is given)."
+  };
+  TASK_STATUS_FLAG = {
+    name: "--status",
+    vocabulary: TASK_STATUSES,
+    normalize: normalizeStatus,
+    hints: TASK_STATUS_FLAG_HINTS
+  };
+  TASK_PRIORITY_FLAG = {
+    name: "--priority",
+    vocabulary: TASK_PRIORITIES,
+    normalize: normalizePriority
+  };
   statusColors = {
     pending: chalk.yellow,
     in_progress: chalk.blue,
@@ -12523,7 +12783,7 @@ var init_event_hooks = __esm(() => {
 // node_modules/.bun/@hasna+events@0.1.11/node_modules/@hasna/events/dist/index.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
-import { homedir } from "os";
+import { homedir as homedir2 } from "os";
 import { join as join5 } from "path";
 import { createHmac, timingSafeEqual } from "crypto";
 import { randomUUID as randomUUID2 } from "crypto";
@@ -12625,7 +12885,7 @@ function channelMatchesEvent(channel, event) {
   return channel.filters.some((filter) => eventMatchesFilter(event, filter));
 }
 function getEventsDataDir(override) {
-  return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join5(homedir(), ".hasna", "events");
+  return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join5(homedir2(), ".hasna", "events");
 }
 
 class JsonEventsStore {
@@ -15960,11 +16220,13 @@ function updateTask(id, input, db) {
     }
     sets.push("status = ?");
     params.push(input.status);
+    if (isTerminalStatus(input.status)) {
+      sets.push("locked_by = NULL");
+      sets.push("locked_at = NULL");
+    }
     if (input.status === "completed") {
       sets.push("completed_at = ?");
       params.push(completionTimestamp);
-      sets.push("locked_by = NULL");
-      sets.push("locked_at = NULL");
     } else if (task.status === "completed" && input.completed_at === undefined) {
       sets.push("completed_at = NULL");
     }
@@ -16088,6 +16350,7 @@ function updateTask(id, input, db) {
     logTaskChange(id, "approve", "approved_by", null, input.approved_by, agentId, d);
   const reopened = input.status !== undefined && input.status !== "completed" && task.status === "completed" && input.completed_at === undefined;
   const completedNow = input.status === "completed";
+  const terminalNow = input.status !== undefined && isTerminalStatus(input.status);
   const updatedTask = {
     ...task,
     ...Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined)),
@@ -16095,8 +16358,8 @@ function updateTask(id, input, db) {
     metadata: input.metadata ?? task.metadata,
     version: task.version + 1,
     updated_at: timestamp2,
-    locked_by: completedNow ? null : task.locked_by,
-    locked_at: completedNow ? null : task.locked_at,
+    locked_by: terminalNow ? null : task.locked_by,
+    locked_at: terminalNow ? null : task.locked_at,
     completed_at: completedNow ? completionTimestamp : reopened ? null : input.completed_at !== undefined ? input.completed_at : task.completed_at,
     sla_minutes: input.sla_minutes !== undefined ? input.sla_minutes : task.sla_minutes,
     actual_minutes: input.actual_minutes ?? task.actual_minutes,
@@ -19054,6 +19317,49 @@ var init_tasks = __esm(() => {
   init_calendar();
 });
 
+// src/lib/bulk-tags.ts
+function parseTagList(raw) {
+  if (!raw)
+    return [];
+  const seen = new Set;
+  const tags = [];
+  for (const segment of raw.split(",")) {
+    const tag = segment.trim();
+    if (!tag || seen.has(tag))
+      continue;
+    seen.add(tag);
+    tags.push(tag);
+  }
+  return tags;
+}
+function resolveTagArgument(tag, tags) {
+  if (tag === undefined)
+    return { ok: true, raw: tags };
+  if (tags === undefined)
+    return { ok: true, raw: tag };
+  const left = parseTagList(tag);
+  const right = parseTagList(tags);
+  const same = left.length === right.length && left.every((entry) => right.includes(entry));
+  if (!same)
+    return { ok: false, conflict: { tag, tags } };
+  return { ok: true, raw: tag };
+}
+function resolveBulkTags(current, action, tags) {
+  const existing = Array.isArray(current) ? current.filter((tag) => typeof tag === "string") : [];
+  if (tags.length === 0)
+    return { tags: [...existing], changed: false };
+  if (action === "tag") {
+    const present = new Set(existing);
+    const additions = tags.filter((tag) => !present.has(tag));
+    if (additions.length === 0)
+      return { tags: [...existing], changed: false };
+    return { tags: [...existing, ...additions], changed: true };
+  }
+  const removing = new Set(tags);
+  const remaining = existing.filter((tag) => !removing.has(tag));
+  return { tags: remaining, changed: remaining.length !== existing.length };
+}
+
 // src/cli/claim-guard.ts
 function resolveClaimIdentity(verb, explicit) {
   const resolved = resolveWritableIdentity(explicit);
@@ -19074,10 +19380,10 @@ function normalizeAgentNameInput(name) {
 
 // src/lib/assignee-validation.ts
 import { readFileSync as readFileSync4 } from "fs";
-import { homedir as homedir2 } from "os";
+import { homedir as homedir3 } from "os";
 import { join as join8 } from "path";
 function defaultSeatRosterPath() {
-  return process.env["TODOS_SEAT_ROSTER_PATH"] || join8(homedir2(), ".hasna", "identities", "hasna-seats.roster.json");
+  return process.env["TODOS_SEAT_ROSTER_PATH"] || join8(homedir3(), ".hasna", "identities", "hasna-seats.roster.json");
 }
 function loadSeatSlugs(path = defaultSeatRosterPath()) {
   try {
@@ -20211,14 +20517,30 @@ function resolveProjectIdOrSlug(input) {
     return row.id;
   handleError(new Error(`Project not found: ${input}`));
 }
+function projectRefFromOpts(opts, globalOpts) {
+  const own = typeof opts.project === "string" ? opts.project : undefined;
+  const global = typeof globalOpts.project === "string" ? globalOpts.project : undefined;
+  return own || global;
+}
+function projectOptOut(opts) {
+  return opts.project === false;
+}
+function warnMissingProject(resolvedProjectId, optedOut) {
+  if (resolvedProjectId || optedOut)
+    return;
+  console.error(chalk3.yellow("Warning: task filed with no project \u2014 it will not appear in any project list, per-seat report, or drain. " + "Pass --project <id-or-slug>, or --no-project if filing it globally is deliberate."));
+}
 function parseStatus(value) {
   if (!value)
     return;
-  const normalized = normalizeStatus(value);
-  if (!TASK_STATUSES.includes(normalized)) {
-    handleError(new Error(`--status must be one of: ${TASK_STATUSES.join(", ")}`));
-  }
-  return normalized;
+  return parseEnumFlagList(value, { ...TASK_STATUS_FLAG, allowList: false })?.[0];
+}
+function listScanLimit() {
+  const raw = process.env["TODOS_LIST_SCAN_LIMIT"];
+  if (raw === undefined || raw.trim() === "")
+    return DEFAULT_LIST_SCAN_LIMIT;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_LIST_SCAN_LIMIT;
 }
 function parseIntOption(value, flag) {
   if (value === undefined)
@@ -20243,10 +20565,7 @@ function resolvePlanId(input) {
 function parsePriority(value) {
   if (!value)
     return;
-  if (!TASK_PRIORITIES.includes(value)) {
-    handleError(new Error("--priority must be one of: low, medium, high, critical"));
-  }
-  return value;
+  return parseEnumFlagList(value, { ...TASK_PRIORITY_FLAG, allowList: false })?.[0];
 }
 function parseJsonObject3(value, flag) {
   if (!value)
@@ -20360,7 +20679,7 @@ function computeLocalReparent(current, opts) {
   return patch;
 }
 function registerTaskCommands(program2) {
-  program2.command("add <title>").description("Create a new task").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("--parent <id>", "Parent task ID").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--plan <id>", "Assign to a plan").option("--assign <agent>", "Assign to agent").option("--status <status>", "Initial status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("--estimated <minutes>", "Estimated time in minutes").option("--sla-minutes <minutes>", "SLA minutes before unfinished work is escalated").option("--sla <minutes>", "Alias for --sla-minutes").option("--approval", "Require approval before completion").option("--recurrence <rule>", "Recurrence rule, e.g. 'every day', 'every weekday', 'every 2 weeks'").option("--due <date>", "Due date (ISO string or YYYY-MM-DD)").option("--reason <text>", "Why this task exists").option("--project <id>", "Assign to project by ID or slug (overrides auto-detect)").option("--unassigned", "Deliberately file this task with no assignee").option("--assign-seat", "Allow --assign to name a durable seat (a seat queue has no session watching it)").option("--created-by <agent>", "Record a different filer than the resolved agent identity").action(async (title, opts) => {
+  program2.command("add <title>").description("Create a new task").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("--parent <id>", "Parent task ID").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--plan <id>", "Assign to a plan").option("--assign <agent>", "Assign to agent").option("--status <status>", "Initial status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("--estimated <minutes>", "Estimated time in minutes").option("--sla-minutes <minutes>", "SLA minutes before unfinished work is escalated").option("--sla <minutes>", "Alias for --sla-minutes").option("--approval", "Require approval before completion").option("--recurrence <rule>", "Recurrence rule, e.g. 'every day', 'every weekday', 'every 2 weeks'").option("--due <date>", "Due date (ISO string or YYYY-MM-DD)").option("--reason <text>", "Why this task exists").option("--project <id>", "Assign to project by ID or slug (overrides auto-detect)").option("--no-project", "Deliberately file this task with no project (silences the orphan warning)").option("--unassigned", "Deliberately file this task with no assignee").option("--assign-seat", "Allow --assign to name a durable seat (a seat queue has no session watching it)").option("--created-by <agent>", "Record a different filer than the resolved agent identity").action(async (title, opts) => {
     const globalOpts = program2.opts();
     opts.tags = opts.tags || opts.tag;
     opts.list = opts.list || opts.taskList;
@@ -20375,8 +20694,9 @@ function registerTaskCommands(program2) {
     if (cloud) {
       let task3;
       try {
-        const cloudProjectRef = opts.project || globalOpts.project;
+        const cloudProjectRef = projectRefFromOpts(opts, globalOpts);
         const cloudProjectId = cloudProjectRef ? await cloudResolveProjectRef(cloud, cloudProjectRef) : undefined;
+        warnMissingProject(cloudProjectId, projectOptOut(opts));
         const cloudTaskListId = opts.list ? await cloudResolveTaskListRef(cloud, opts.list, cloudProjectId) : undefined;
         if (opts.list && !cloudTaskListId) {
           throw new Error(`Could not resolve task list ID or slug: ${opts.list}`);
@@ -20399,6 +20719,7 @@ function registerTaskCommands(program2) {
           created_by: creator.agent_id || undefined,
           session_id: globalOpts.session,
           project_id: cloudProjectId,
+          working_dir: process.cwd(),
           estimated_minutes: opts.estimated !== undefined ? parseIntOption(opts.estimated, "--estimated") : undefined,
           sla_minutes: opts.slaMinutes !== undefined || opts.sla !== undefined ? parseIntOption(opts.slaMinutes ?? opts.sla, "--sla-minutes") : undefined,
           requires_approval: opts.approval || undefined,
@@ -20417,8 +20738,9 @@ function registerTaskCommands(program2) {
       }
       return;
     }
-    const explicitProject = opts.project || globalOpts.project;
-    const projectId = explicitProject ? resolveProjectIdOrSlug(explicitProject) : autoProject(globalOpts);
+    const explicitProject = projectRefFromOpts(opts, globalOpts);
+    const projectId = explicitProject ? resolveProjectIdOrSlug(explicitProject) : projectOptOut(opts) ? undefined : autoProject(globalOpts);
+    warnMissingProject(projectId, projectOptOut(opts));
     opts.tags = opts.tags || opts.tag;
     opts.list = opts.list || opts.taskList;
     const taskListId = opts.list ? (() => {
@@ -20630,15 +20952,19 @@ function registerTaskCommands(program2) {
       }
       filter["task_list_id"] = listId;
     }
-    if (opts.status) {
-      filter["status"] = opts.status.includes(",") ? opts.status.split(",").map((s) => normalizeStatus(s.trim())) : normalizeStatus(opts.status);
+    if (opts.status !== undefined) {
+      filter["status"] = parseEnumFlag(opts.status, TASK_STATUS_FLAG);
     } else if (!opts.all) {
       filter["status"] = ["pending", "in_progress"];
     }
-    if (opts.priority)
-      filter["priority"] = opts.priority;
-    if (opts.assigned)
-      filter["assigned_to"] = opts.assigned;
+    if (opts.priority !== undefined)
+      filter["priority"] = parseEnumFlag(opts.priority, TASK_PRIORITY_FLAG);
+    let assignedFilter;
+    let assignedWasTyped = false;
+    if (opts.assigned) {
+      assignedFilter = opts.assigned;
+      assignedWasTyped = true;
+    }
     if (opts.createdBy)
       filter["created_by"] = canonicalAgentRef(opts.createdBy);
     if (opts.notCreatedBy)
@@ -20649,7 +20975,8 @@ function registerTaskCommands(program2) {
         console.error(chalk3.red("--inbox needs an agent identity. Run `todos init <name>` or pass --agent <id>."));
         process.exit(1);
       }
-      filter["assigned_to"] = me.agent_id;
+      assignedFilter = me.agent_id;
+      assignedWasTyped = false;
       filter["not_created_by"] = me.agent_id;
     }
     if (opts.tags)
@@ -20665,8 +20992,11 @@ function registerTaskCommands(program2) {
       }
     }
     if (opts.agentName) {
-      filter["assigned_to"] = opts.agentName;
+      assignedFilter = opts.agentName;
+      assignedWasTyped = true;
     }
+    if (assignedFilter !== undefined)
+      filter["assigned_to"] = assignedFilter;
     if (opts.recurring)
       filter["has_recurrence"] = true;
     if (opts.limit !== undefined) {
@@ -20678,11 +21008,23 @@ function registerTaskCommands(program2) {
     }
     const creatorFilterActive = Boolean(filter["created_by"] || filter["not_created_by"]);
     const requestedLimit = filter["limit"];
-    const serverFilter = creatorFilterActive && cloud && requestedLimit !== undefined ? (() => {
-      const { limit: _dropped, ...rest } = filter;
-      return rest;
-    })() : filter;
+    const reordersAfterQuery = Boolean(opts.sort);
+    const narrowsAfterQuery = Boolean(opts.dueToday) || Boolean(opts.overdue) || creatorFilterActive && cloud;
+    const withholdLimit = requestedLimit !== undefined && (reordersAfterQuery || narrowsAfterQuery);
+    const scanCeiling = cloud && (withholdLimit || requestedLimit === undefined) ? Math.max(requestedLimit ?? 0, listScanLimit()) : undefined;
+    const serverFilter = (() => {
+      const base = withholdLimit ? (() => {
+        const { limit: _dropped, ...rest } = filter;
+        return rest;
+      })() : filter;
+      return scanCeiling === undefined ? base : { ...base, limit: scanCeiling };
+    })();
     let tasks = cloud ? await cloudListTasks(cloud, serverFilter) : listTasks(serverFilter);
+    if (scanCeiling !== undefined && tasks.length >= scanCeiling) {
+      console.error(chalk3.yellow(`Warning: this query reached its ${scanCeiling}-row scan limit, so the rows below were
+` + `         selected from a truncated set and may not be the true result.
+` + `         Narrow it (--project, --status, --assigned) or raise TODOS_LIST_SCAN_LIMIT.`));
+    }
     if (cloud && creatorFilterActive) {
       if (tasks.length > 0 && tasks.every((t) => !("created_by" in t))) {
         console.error(chalk3.yellow(`Warning: this server does not record task authorship, so the creator filter matched nothing to exclude.
@@ -20699,8 +21041,6 @@ function registerTaskCommands(program2) {
           return false;
         return true;
       });
-      if (requestedLimit !== undefined)
-        tasks = tasks.slice(0, requestedLimit);
     }
     if (opts.dueToday) {
       const todayEnd = new Date;
@@ -20725,6 +21065,21 @@ function registerTaskCommands(program2) {
         return 0;
       });
     }
+    if (withholdLimit && requestedLimit !== undefined)
+      tasks = tasks.slice(0, requestedLimit);
+    if (assignedWasTyped && assignedFilter && tasks.length === 0) {
+      try {
+        const roster = await loadAssigneeContext(() => cloud ? cloudListAgents(cloud) : listAgents(), true);
+        if (!roster.degraded) {
+          const target = canonicalAgentRef(assignedFilter);
+          const known = roster.agents.some((a) => canonicalAgentRef(a.name) === target || canonicalAgentRef(a.id) === target);
+          if (!known) {
+            console.error(chalk3.yellow(`Warning: no agent named '${assignedFilter}' is registered, so this empty result may be a
+` + `         mistyped name rather than an empty queue. Check with 'todos agents'.`));
+          }
+        }
+      } catch {}
+    }
     const fmt = opts.format || (globalOpts.json ? "json" : "table");
     const outputTasks = redactBroadTasks(tasks);
     if (fmt === "json") {
@@ -21496,17 +21851,26 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
       handleError(new Error("Task not found."));
     }
   });
-  program2.command("bulk <action> <ids...>").description("Bulk operation on multiple tasks (done, start, delete, plan/move-plan)").option("--plan <id>", "Plan ID for the plan/move-plan action").option("--clear-plan", "Remove plan assignment for the plan/move-plan action").action(async (action, ids, opts) => {
+  program2.command("bulk <action> <ids...>").description("Bulk operation on multiple tasks (done, start, delete, plan/move-plan, tag, untag)").option("--plan <id>", "Plan ID for the plan/move-plan action").option("--clear-plan", "Remove plan assignment for the plan/move-plan action").option("--tag <tags>", "Comma-separated tags for the tag/untag action").option("--tags <tags>", "Comma-separated tags for the tag/untag action (alias for --tag)").action(async (action, ids, opts) => {
     const globalOpts = program2.opts();
     const results = [];
     const cloud = getTodosCloudClient();
     const isPlanAction = action === "plan" || action === "move-plan";
+    const isTagAction = action === "tag" || action === "untag";
     if (isPlanAction && Boolean(opts.plan) === Boolean(opts.clearPlan)) {
       handleError(new Error("Use exactly one of --plan or --clear-plan with bulk plan."));
     }
-    const knownActions = new Set(["done", "complete", "start", "delete", "plan", "move-plan"]);
+    const knownActions = new Set(["done", "complete", "start", "delete", "plan", "move-plan", "tag", "untag"]);
     if (!knownActions.has(action)) {
-      handleError(new Error(`Unknown action: ${action}. Use: done, start, delete, plan (alias: move-plan)`));
+      handleError(new Error(`Unknown action: ${action}. Use: done, start, delete, plan (alias: move-plan), tag, untag`));
+    }
+    const tagArgument = resolveTagArgument(opts.tag, opts.tags);
+    if (isTagAction && !tagArgument.ok) {
+      handleError(new Error(`--tag and --tags name different tag sets (--tag "${tagArgument.conflict.tag}" vs --tags "${tagArgument.conflict.tags}"). ` + "They are aliases; pass one, or pass the same set to both."));
+    }
+    const bulkTags = isTagAction && tagArgument.ok ? parseTagList(tagArgument.raw) : [];
+    if (isTagAction && bulkTags.length === 0) {
+      handleError(new Error(`bulk ${action} needs --tag. Example: todos bulk ${action} <ids...> --tag directive:k_msd4cz8t_ste6f4`));
     }
     const bulkClaimAgentId = action === "start" ? resolveClaimIdentity("start", globalOpts.agent) : undefined;
     if (cloud) {
@@ -21535,6 +21899,14 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
             await cloudTaskAction(cloud, resolvedId, "start", { agent_id: bulkClaimAgentId });
           } else if (action === "delete") {
             await cloudDeleteTask(cloud, resolvedId);
+          } else if (isTagAction) {
+            const current = await cloudGetTask(cloud, resolvedId);
+            if (!current)
+              throw new Error(`Task not found: ${rawId}`);
+            const resolution = resolveBulkTags(current.tags, action, bulkTags);
+            if (resolution.changed) {
+              await cloudUpdateTask(cloud, resolvedId, { version: current.version, tags: resolution.tags });
+            }
           } else {
             const current = await cloudGetTask(cloud, resolvedId);
             if (!current)
@@ -21571,6 +21943,16 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
         } else if (action === "delete") {
           deleteTask(resolvedId);
           results.push({ id: resolvedId, success: true });
+        } else if (isTagAction) {
+          const current = getTask(resolvedId);
+          if (!current) {
+            throw new Error(`Task not found: ${rawId}`);
+          }
+          const resolution = resolveBulkTags(current.tags, action, bulkTags);
+          if (resolution.changed) {
+            updateTask(resolvedId, { version: current.version, tags: resolution.tags });
+          }
+          results.push({ id: resolvedId, success: true });
         } else if (isPlanAction) {
           const current = getTask(resolvedId);
           if (!current) {
@@ -21579,7 +21961,7 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
           updateTask(resolvedId, { version: current.version, plan_id: planId });
           results.push({ id: resolvedId, success: true });
         } else {
-          handleError(new Error(`Unknown action: ${action}. Use: done, start, delete, plan (alias: move-plan)`));
+          handleError(new Error(`Unknown action: ${action}. Use: done, start, delete, plan (alias: move-plan), tag, untag`));
         }
       } catch (e) {
         results.push({ id: rawId, success: false, error: e instanceof Error ? e.message : String(e) });
@@ -21597,6 +21979,7 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
     }
   });
 }
+var DEFAULT_LIST_SCAN_LIMIT = 1e4;
 var init_task_commands = __esm(() => {
   init_database();
   init_projects();
@@ -21607,9 +21990,10 @@ var init_task_commands = __esm(() => {
   init_lock_display();
   init_claim_guard();
   init_assignee_guard();
+  init_assignee_context();
+  init_agents();
   init_helpers();
   init_output_redaction();
-  init_types();
 });
 
 // src/lib/plan-artifacts.ts
@@ -23441,7 +23825,8 @@ __export(exports_saved_search_views, {
   normalizeScope: () => normalizeScope,
   listSearchViews: () => listSearchViews,
   getSearchView: () => getSearchView,
-  deleteSearchView: () => deleteSearchView
+  deleteSearchView: () => deleteSearchView,
+  SAVED_SEARCH_SCOPES: () => SAVED_SEARCH_SCOPES
 });
 function parseFilters(value) {
   if (!value)
@@ -23461,10 +23846,8 @@ function rowToSavedSearchView(row) {
   };
 }
 function normalizeScope(scope) {
-  if (scope === "all" || scope === "tasks" || scope === "projects" || scope === "plans" || scope === "runs" || scope === "comments") {
-    return scope;
-  }
-  return "tasks";
+  const candidate = (scope ?? "").trim().toLowerCase();
+  return SAVED_SEARCH_SCOPES.includes(candidate) ? candidate : "tasks";
 }
 function normalizeName(name) {
   const normalized = name.trim();
@@ -23767,10 +24150,12 @@ function runSearchView(idOrName, db) {
     throw new Error(`Saved search view not found: ${idOrName}`);
   return { ...runSavedSearch(view.filters, view.scope, d), view };
 }
+var SAVED_SEARCH_SCOPES;
 var init_saved_search_views = __esm(() => {
   init_database();
   init_local_fields();
   init_search();
+  SAVED_SEARCH_SCOPES = ["all", "tasks", "projects", "plans", "runs", "comments"];
 });
 
 // src/lib/claude-tasks.ts
@@ -26340,12 +26725,11 @@ function buildSearchFilters(query, opts, projectId) {
   const customFields = parseJsonObjectOption(opts.fieldCustom, "--field-custom");
   const labels = splitList(opts.fieldLabel);
   const tags = splitList(opts.tag);
-  const statuses = splitList(opts.status)?.map(normalizeStatus);
   const filters = {
     query: query || opts.query,
     project_id: opts.allProjects ? undefined : projectId,
-    status: statuses,
-    priority: splitList(opts.priority),
+    status: parseEnumFlagList(opts.status, TASK_STATUS_FLAG),
+    priority: parseEnumFlagList(opts.priority, TASK_PRIORITY_FLAG),
     assigned_to: opts.assigned,
     agent_id: opts.agentId,
     task_list_id: filterPatch?.task_list_id === undefined ? resolveTaskListFilter(opts.taskList, projectId) : undefined,
@@ -26450,7 +26834,7 @@ function registerProjectCommands(program2) {
     try {
       const cloud = getTodosCloudClient();
       const projectId = opts.allProjects ? undefined : cloud ? undefined : autoProject(globalOpts);
-      const scope = normalizeScope(opts.scope);
+      const scope = parseEnumFlag(opts.scope, SEARCH_SCOPE_FLAG) ?? "tasks";
       const searchOpts = buildSearchFilters(query, opts, projectId);
       if (opts.saveAs) {
         const view = saveSearchView({
@@ -26542,7 +26926,7 @@ function registerProjectCommands(program2) {
       const view = saveSearchView({
         name,
         description: opts.description,
-        scope: normalizeScope(opts.scope),
+        scope: parseEnumFlag(opts.scope, SEARCH_SCOPE_FLAG) ?? "tasks",
         filters: buildSearchFilters(opts.query, opts, projectId)
       });
       output(view, Boolean(globalOpts.json));
@@ -26555,7 +26939,7 @@ function registerProjectCommands(program2) {
   views.command("list").description("List local saved search views").option("--scope <scope>", "Filter by scope").action((opts) => {
     const globalOpts = program2.opts();
     try {
-      const rows = listSearchViews(opts.scope ? normalizeScope(opts.scope) : undefined);
+      const rows = listSearchViews(parseEnumFlag(opts.scope, SEARCH_SCOPE_FLAG));
       output(rows, Boolean(globalOpts.json));
       if (!globalOpts.json) {
         if (rows.length === 0) {
@@ -26751,7 +27135,7 @@ function registerProjectCommands(program2) {
     const cloud = getTodosCloudClient();
     if (opts.show) {
       const project = cloud ? await cloudResolveProject(cloud, opts.show) : resolveExplicitProject(opts.show);
-      output(project, Boolean(globalOpts.json));
+      outputRecord(project, Boolean(globalOpts.json), "Project:");
       return;
     }
     if (opts.update) {
@@ -26765,7 +27149,7 @@ function registerProjectCommands(program2) {
       }
       const current = cloud ? await cloudResolveProject(cloud, opts.update) : resolveExplicitProject(opts.update);
       const project = cloud ? await cloudUpdateProject(cloud, current.id, patch) : updateProject(current.id, patch);
-      output(project, Boolean(globalOpts.json));
+      outputRecord(project, Boolean(globalOpts.json), "Project updated:");
       return;
     }
     if (opts.deregister) {
@@ -27073,6 +27457,7 @@ Indexed ${result.index.files.length} file(s), ${result.index.total_symbols} symb
   program2.command("export").description("Export tasks").option("-f, --format <format>", "Format: json, md, todos.md, or bridge", "json").option("-o, --output <path>", "Write export output to a file").option("--encrypt", "Encrypt bridge exports with a local encryption profile").option("--encryption-profile <name>", "Encryption profile name", "default").option("--allow-plaintext-sensitive", "Deprecated; bridge exports are redacted unless --encrypt is used").action(async (opts) => {
     const { listTasks: listTasks2 } = await Promise.resolve().then(() => (init_tasks(), exports_tasks));
     const globalOpts = program2.opts();
+    opts.format = parseEnumFlag(opts.format, EXPORT_FORMAT_FLAG) ?? "json";
     const projectId = autoProject(globalOpts);
     const writeOutput = async (content) => {
       if (opts.output) {
@@ -27234,7 +27619,7 @@ function resolveTaskListId(partialId) {
   }
   return id;
 }
-var CLOUD_GRAPH_EDGE_CONCURRENCY = 6;
+var SEARCH_SCOPE_FLAG, EXPORT_FORMATS, EXPORT_FORMAT_FLAG, CLOUD_GRAPH_EDGE_CONCURRENCY = 6;
 var init_project_commands = __esm(() => {
   init_database();
   init_projects();
@@ -27246,12 +27631,26 @@ var init_project_commands = __esm(() => {
   init_config();
   init_helpers();
   init_output_redaction();
+  SEARCH_SCOPE_FLAG = {
+    name: "--scope",
+    vocabulary: SAVED_SEARCH_SCOPES,
+    normalize: (value) => value.toLowerCase().trim(),
+    allowList: false
+  };
+  EXPORT_FORMATS = ["json", "md", "markdown", "todos.md", "todos-md", "bridge"];
+  EXPORT_FORMAT_FLAG = {
+    name: "--format",
+    vocabulary: EXPORT_FORMATS,
+    normalize: (value) => value.toLowerCase().trim(),
+    allowList: false
+  };
 });
 
 // src/cli/commands/agent-commands.ts
 var exports_agent_commands = {};
 __export(exports_agent_commands, {
-  registerAgentCommands: () => registerAgentCommands
+  registerAgentCommands: () => registerAgentCommands,
+  findCaseVariantRows: () => findCaseVariantRows
 });
 import chalk6 from "chalk";
 import { execSync as execSync2 } from "child_process";
@@ -27265,6 +27664,15 @@ function resolveCloudAgentByNameOrId(agents, nameOrId) {
     return null;
   return matches.reduce((freshest, candidate) => new Date(candidate.last_seen_at).getTime() > new Date(freshest.last_seen_at).getTime() ? candidate : freshest);
 }
+function findCaseVariantRows(agents, requested) {
+  const raw = requested.trim();
+  const target = normalizeAgentNameInput(raw);
+  if (!target)
+    return [];
+  if (agents.some((agent) => agent.name === raw))
+    return [];
+  return agents.filter((agent) => normalizeAgentNameInput(agent.name) === target);
+}
 function clearIdentityIfMine(agentId, agentName) {
   const persisted = readPersistedIdentity();
   if (!persisted)
@@ -27278,7 +27686,22 @@ function registerAgentCommands(program2) {
     const globalOpts = program2.opts();
     try {
       const cloud = getTodosCloudClient();
-      const result = cloud ? await cloudRegisterAgent(cloud, { name, description: opts.description }) : (await Promise.resolve().then(() => (init_agents(), exports_agents))).registerAgent({ name, description: opts.description });
+      const registrationName = name.trim();
+      if (cloud) {
+        let roster = null;
+        try {
+          roster = await cloudListAgents(cloud);
+        } catch {
+          console.error(chalk6.yellow("Warning: could not read the shared roster, so the case-variant check was skipped for this registration."));
+        }
+        const variants = roster ? findCaseVariantRows(roster, registrationName) : [];
+        if (variants.length > 0) {
+          const listed = variants.map((a) => `${a.name} (${a.id})`).join(", ");
+          console.error(chalk6.red(`'${name}' is a case variant of an agent that already exists: ${listed}. ` + `Agent names are ONE case-insensitive identity, so registering this spelling would create a second row ` + `and split the identity in two \u2014 tasks assigned to one spelling are invisible to the other. ` + `Register with the existing spelling instead.`));
+          process.exit(1);
+        }
+      }
+      const result = cloud ? await cloudRegisterAgent(cloud, { name: registrationName, description: opts.description }) : (await Promise.resolve().then(() => (init_agents(), exports_agents))).registerAgent({ name: registrationName, description: opts.description });
       const { isAgentConflict: isAgentConflict2 } = await Promise.resolve().then(() => (init_agents(), exports_agents));
       if (isAgentConflict2(result)) {
         console.error(chalk6.red("CONFLICT:"), result.message);
@@ -27623,7 +28046,7 @@ ${isOnline ? chalk6.green("\u25CF") : chalk6.dim("\u25CB")} ${chalk6.bold(agent.
           const list2 = cloud ? await cloudGetTaskList(cloud, resolved) : getTaskList(resolved);
           if (!list2)
             throw new Error(`Task list not found: ${ref}`);
-          output(list2, Boolean(globalOpts.json));
+          outputRecord(list2, Boolean(globalOpts.json), "Task list:");
           return;
         }
         const patch = {
@@ -27634,7 +28057,7 @@ ${isOnline ? chalk6.green("\u25CF") : chalk6.dim("\u25CB")} ${chalk6.bold(agent.
         if (Object.keys(patch).length === 0)
           throw new Error("lists --update requires --name, --slug, or --description");
         const list = cloud ? await cloudUpdateTaskList(cloud, resolved, patch) : updateTaskList(resolved, patch);
-        output(list, Boolean(globalOpts.json));
+        outputRecord(list, Boolean(globalOpts.json), "Task list updated:");
         return;
       }
       if (opts.delete) {
@@ -32185,9 +32608,11 @@ async function updateTask2(id, input, store) {
     throw new Error(`Task ${id} version conflict: expected ${existing.version}, got ${input.version}`);
   }
   const reopened = existing.status === "completed" && input.status !== undefined && input.status !== "completed" && input.completed_at === undefined;
+  const terminalNow = input.status !== undefined && isTerminalStatus(input.status);
   const task = {
     ...existing,
     ...definedPatch(input),
+    ...terminalNow ? { locked_by: null, locked_at: null } : {},
     version: existing.version + 1,
     updated_at: new Date().toISOString(),
     tags: input.tags ?? existing.tags,
@@ -34528,8 +34953,19 @@ function handleStats(_ctx, json2) {
     recurring_tasks: countRecurringTasks()
   });
 }
+function taskStatusQueryParam(url) {
+  const raw = url.searchParams.get("status");
+  if (!raw)
+    return { ok: true, value: undefined };
+  const result = resolveEnumVocabulary(raw, { name: "status", vocabulary: TASK_STATUSES });
+  if (!result.ok)
+    return { ok: false, message: result.message };
+  return { ok: true, value: collapseEnumValues(result.values) };
+}
 async function handleListTasks(_req, url, _ctx, json2, taskToSummary2) {
-  const status = url.searchParams.get("status") || undefined;
+  const statusParam = taskStatusQueryParam(url);
+  if (!statusParam.ok)
+    return json2({ error: statusParam.message }, 400);
   const projectId = url.searchParams.get("project_id") || undefined;
   const sessionId = url.searchParams.get("session_id") || undefined;
   const agentId = url.searchParams.get("agent_id") || undefined;
@@ -34537,7 +34973,7 @@ async function handleListTasks(_req, url, _ctx, json2, taskToSummary2) {
   const offsetParam = url.searchParams.get("offset");
   const fields = parseFieldsParam(url);
   const tasks = listTasks({
-    status,
+    status: statusParam.value,
     project_id: projectId,
     session_id: sessionId,
     agent_id: agentId,
@@ -34602,9 +35038,19 @@ async function handleUpsertTask(req, ctx, json2, taskToSummary2) {
 }
 function handleTasksExport(_req, url, _ctx, _json, taskToSummary2) {
   const format = url.searchParams.get("format") || "json";
-  const status = url.searchParams.get("status") || undefined;
+  const statusParam = taskStatusQueryParam(url);
+  if (!statusParam.ok) {
+    return new Response(JSON.stringify({ error: statusParam.message }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
   const projectId = url.searchParams.get("project_id") || undefined;
-  const tasks = listTasks({ status, project_id: projectId, limit: 1e4 });
+  const tasks = listTasks({
+    status: statusParam.value,
+    project_id: projectId,
+    limit: 1e4
+  });
   const summaries = tasks.map((t) => taskToSummary2(t));
   if (format === "csv") {
     const headers = ["id", "short_id", "title", "status", "priority", "project_id", "assigned_to", "agent_id", "created_at", "updated_at", "completed_at", "due_at"];
@@ -35186,6 +35632,7 @@ var init_routes = __esm(() => {
   init_tasks();
   init_database();
   init_types();
+  init_types();
   init_projects();
   init_agents();
   init_plans();
@@ -37070,8 +37517,38 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           operationId: "listTasks",
           summary: "List tasks",
           parameters: [
-            { name: "status", in: "query", schema: { type: "string" } },
-            { name: "priority", in: "query", schema: { type: "string" } },
+            {
+              name: "status",
+              in: "query",
+              description: `Task status, or a comma-separated list of statuses. Allowed values: ${TASK_STATUSES.join(", ")}.`,
+              style: "form",
+              explode: false,
+              schema: {
+                oneOf: [
+                  { type: "string", enum: [...TASK_STATUSES] },
+                  {
+                    type: "array",
+                    items: { type: "string", enum: [...TASK_STATUSES] }
+                  }
+                ]
+              }
+            },
+            {
+              name: "priority",
+              in: "query",
+              description: `Task priority, or a comma-separated list of priorities. Allowed values: ${TASK_PRIORITIES.join(", ")}.`,
+              style: "form",
+              explode: false,
+              schema: {
+                oneOf: [
+                  { type: "string", enum: [...TASK_PRIORITIES] },
+                  {
+                    type: "array",
+                    items: { type: "string", enum: [...TASK_PRIORITIES] }
+                  }
+                ]
+              }
+            },
             { name: "project_id", in: "query", schema: { type: "string" } },
             { name: "parent_id", in: "query", schema: { type: "string", nullable: true } },
             { name: "include_subtasks", in: "query", schema: { type: "boolean" } },
@@ -37583,6 +38060,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
 var taskSchema, projectSchema, taskListSchema, taskCommentSchema, planSchema, templateTaskSchema, templateSchema, templateVariableSchema, createTemplateTaskInputSchema;
 var init_openapi = __esm(() => {
   init_package_version();
+  init_types();
   taskSchema = {
     type: "object",
     properties: {
@@ -37850,6 +38328,15 @@ function json3(body, status = 200) {
 function error(status, message, extra) {
   return json3({ error: message, ...extra ?? {} }, status);
 }
+function enumQueryParam(url, name, vocabulary) {
+  const raw = url.searchParams.get(name);
+  if (raw === null || raw === "")
+    return { ok: true, value: undefined };
+  const result = resolveEnumVocabulary(raw, { name, vocabulary });
+  if (!result.ok)
+    return { ok: false, response: error(400, result.message) };
+  return { ok: true, value: collapseEnumValues(result.values) };
+}
 function validateTaskCompletion(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return { ok: false, message: "completion body must be an object" };
@@ -38270,14 +38757,16 @@ async function handleV1Request(req, url, dependencies = {}) {
             return error(400, "include_subtasks must be true or false");
           }
           const hasParentFilter = url.searchParams.has("parent_id");
+          const statusParam = enumQueryParam(url, "status", TASK_STATUSES);
+          if (!statusParam.ok)
+            return statusParam.response;
+          const priorityParam = enumQueryParam(url, "priority", TASK_PRIORITIES);
+          if (!priorityParam.ok)
+            return priorityParam.response;
           const filter = {
             ...url.searchParams.get("q") ? { query: url.searchParams.get("q") } : {},
-            ...url.searchParams.get("status") ? {
-              status: url.searchParams.get("status").includes(",") ? url.searchParams.get("status").split(",") : url.searchParams.get("status")
-            } : {},
-            ...url.searchParams.get("priority") ? {
-              priority: url.searchParams.get("priority").includes(",") ? url.searchParams.get("priority").split(",") : url.searchParams.get("priority")
-            } : {},
+            ...statusParam.value !== undefined ? { status: statusParam.value } : {},
+            ...priorityParam.value !== undefined ? { priority: priorityParam.value } : {},
             ...url.searchParams.get("project_id") ? { project_id: url.searchParams.get("project_id") } : {},
             ...hasParentFilter ? { parent_id: url.searchParams.get("parent_id") || null, include_subtasks: true } : includeSubtasks !== null ? { include_subtasks: includeSubtasks === "true" } : {},
             ...url.searchParams.get("plan_id") ? { plan_id: url.searchParams.get("plan_id") } : {},
@@ -38911,7 +39400,13 @@ async function handleV1Request(req, url, dependencies = {}) {
         return error(405, `method ${method} not allowed on /v1/refs/:ref`);
       if (!store.gitRefs)
         return error(501, "git ref links are not supported by this storage backend");
-      const refs = await store.gitRefs.find(id);
+      let decodedRef;
+      try {
+        decodedRef = decodeURIComponent(id);
+      } catch {
+        return error(400, "ref path segment has invalid percent encoding");
+      }
+      const refs = await store.gitRefs.find(decodedRef);
       return json3({ refs, count: refs.length });
     }
     if (resource === "next" && !id) {
@@ -43509,7 +44004,7 @@ async function validateMcpAssignee(value, allowSeat) {
   return verdict.assignee;
 }
 function registerTaskCrudTools(server, ctx) {
-  const { shouldRegisterTool, resolveId, formatError, formatTask } = ctx;
+  const { shouldRegisterTool, resolveId, formatError, formatTask, applyFocus } = ctx;
   function mutationTaskResponse(task) {
     const compact = compactTask(task, 240);
     compact["version"] = task.version;
@@ -43585,6 +44080,7 @@ function registerTaskCrudTools(server, ctx) {
             payload.max_retries = retry_count;
           if (deadline)
             payload.due_at = deadline;
+          applyFocus(payload, router.agent_id || undefined);
           const created = await cloudCreateTask(cloud, payload);
           return { content: [{ type: "text", text: mutationTaskResponse(created) }] };
         }
@@ -43611,6 +44107,7 @@ function registerTaskCrudTools(server, ctx) {
           resolved.max_retries = retry_count;
         if (deadline)
           resolved.due_at = deadline;
+        applyFocus(resolved, router.agent_id || undefined);
         const task = createTask(resolved);
         return { content: [{ type: "text", text: mutationTaskResponse(task) }] };
       } catch (e) {
@@ -50421,10 +50918,23 @@ function registerTaskAutoTools(server, ctx) {
           return { content: [{ type: "text", text: "No active agents available for rebalancing." }] };
         const activeTasks = listTasks4({ project_id: resolvedProjectId, status: ["pending", "in_progress"], limit: 1000 }, undefined);
         const agentKeyByAlias = new Map;
+        const ambiguousAgentAliases = new Set;
+        const indexAgentAlias = (alias, agentId) => {
+          const normalizedAlias2 = alias.toLowerCase();
+          if (ambiguousAgentAliases.has(normalizedAlias2))
+            return;
+          const existingAgentId = agentKeyByAlias.get(normalizedAlias2);
+          if (existingAgentId !== undefined && existingAgentId !== agentId) {
+            agentKeyByAlias.delete(normalizedAlias2);
+            ambiguousAgentAliases.add(normalizedAlias2);
+            return;
+          }
+          agentKeyByAlias.set(normalizedAlias2, agentId);
+        };
         for (const agent of agents) {
-          agentKeyByAlias.set(String(agent.id).toLowerCase(), agent.id);
+          indexAgentAlias(String(agent.id), agent.id);
           if (agent.name)
-            agentKeyByAlias.set(String(agent.name).toLowerCase(), agent.id);
+            indexAgentAlias(String(agent.name), agent.id);
         }
         const canonicalAgentKey = (assignedTo) => assignedTo ? agentKeyByAlias.get(assignedTo.toLowerCase()) : undefined;
         const load = new Map(agents.map((agent) => [agent.id, activeTasks.filter((t) => canonicalAgentKey(t.assigned_to) === agent.id).length]));
@@ -61810,9 +62320,16 @@ ${text2}` }] };
           return { content: [{ type: "text", text: `Agent not found: ${id || name}` }], isError: true };
         }
         const oldName = agent.name;
-        const updated = updateAgent(agent.id, { name: new_name });
         const db = getDatabase();
-        const tasksResult = db.run("UPDATE tasks SET assigned_to = ? WHERE LOWER(assigned_to) = LOWER(?)", [new_name, oldName]);
+        let oldNameUniquelyIdentifiesAgent = false;
+        try {
+          oldNameUniquelyIdentifiesAgent = resolvePartialId(db, "agents", oldName) === agent.id;
+        } catch (error2) {
+          if (!(error2 instanceof IdentityAliasAmbiguousError))
+            throw error2;
+        }
+        const updated = updateAgent(agent.id, { name: new_name });
+        const tasksResult = db.run(oldNameUniquelyIdentifiesAgent ? "UPDATE tasks SET assigned_to = ? WHERE LOWER(assigned_to) = LOWER(?)" : "UPDATE tasks SET assigned_to = ? WHERE assigned_to = ?", [new_name, oldName]);
         const taskNote = tasksResult.changes > 0 ? `
 Updated assigned_to on ${tasksResult.changes} task(s).` : "";
         return {
@@ -61996,6 +62513,7 @@ var init_agents2 = __esm(() => {
   init_agents();
   init_config();
   init_database();
+  init_types();
   init_cloud_router();
 });
 
@@ -62828,7 +63346,8 @@ function buildServer() {
     formatError,
     formatTask,
     formatTaskDetail,
-    getAgentFocus
+    getAgentFocus,
+    applyFocus
   };
   registerTaskCrudTools(server, toolContext);
   registerTaskProjectTools(server, toolContext);
@@ -66275,7 +66794,7 @@ ${error2.message}
     const globalOpts = program2.opts();
     const projectId = autoProject(globalOpts);
     const interval = parseInt(opts.interval, 10) * 1000;
-    const statusFilter = opts.status ? opts.status.split(",").map((s) => normalizeStatus(s.trim())) : ["pending", "in_progress"];
+    const statusFilter = parseEnumFlagList(opts.status, TASK_STATUS_FLAG) ?? ["pending", "in_progress"];
     function render2() {
       const tasks = listTasks({ project_id: projectId, status: statusFilter });
       const all = listTasks({ project_id: projectId });
@@ -68882,8 +69401,8 @@ Findings`));
       const row = db.query("SELECT COUNT(*) as count FROM tasks").get();
       const { statSync: statSync12 } = await import("fs");
       const { join: join27 } = await import("path");
-      const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-      const dbPath = process.env["HASNA_TODOS_DB_PATH"] || process.env["TODOS_DB_PATH"] || join27(home, ".hasna", "todos", "todos.db");
+      const { getHomeDir: getHomeDir2 } = await Promise.resolve().then(() => (init_sync_utils(), exports_sync_utils));
+      const dbPath = process.env["HASNA_TODOS_DB_PATH"] || process.env["TODOS_DB_PATH"] || join27(getHomeDir2(), ".hasna", "todos", "todos.db");
       let size = "unknown";
       try {
         size = `${(statSync12(dbPath).size / 1024 / 1024).toFixed(1)} MB`;
@@ -72048,7 +72567,8 @@ var init_mcp_hooks_commands = __esm(() => {
   init_tasks();
   init_helpers();
   init_cloud_router();
-  HOME2 = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  init_sync_utils();
+  HOME2 = getHomeDir();
 });
 
 // src/cli/commands/dispatch.tsx
@@ -72161,7 +72681,11 @@ function registerDispatchCommands(program2) {
         process.exit(1);
       }
     }
-    const statuses = opts.status ? opts.status.split(",").map((s) => s.trim()) : undefined;
+    const statuses = parseEnumFlagList(opts.status, {
+      name: "--status",
+      vocabulary: DISPATCH_STATUSES,
+      normalize: (value) => value.toLowerCase().trim()
+    });
     const dispatches = listDispatches({ status: statuses, limit: opts.limit ?? 20 });
     if (useJson) {
       console.log(JSON.stringify(dispatches, null, 2));
@@ -72194,6 +72718,8 @@ var init_dispatch3 = __esm(() => {
   init_dispatch();
   init_dispatch_formatter();
   init_tmux();
+  init_types();
+  init_helpers();
 });
 
 // src/cli/commands/machines.tsx