@hasna/todos 0.14.0 → 0.15.2

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.14.0",
+    version: "0.15.2",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -2444,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");
@@ -2536,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
@@ -6414,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;
@@ -6434,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") {
@@ -6451,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`" };
@@ -6478,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"]);
@@ -6541,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}`);
   }
 }
@@ -6561,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();
@@ -6751,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",
@@ -10773,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="));
@@ -10996,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"]);
 });
 
@@ -11502,14 +11571,21 @@ function suggestVocabularyMatches(value, vocabulary, limit = 3) {
 }
 function resolveEnumVocabulary(raw, spec) {
   const allowList = spec.allowList !== false;
-  const rawElements = (allowList ? raw.split(",") : [raw]).map((element) => element.trim()).filter((element) => element.length > 0);
-  if (rawElements.length === 0) {
+  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 = [];
@@ -12707,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";
@@ -12809,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 {
@@ -19241,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);
@@ -19261,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 {
@@ -20398,11 +20517,31 @@ 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;
   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)
     return;
@@ -20540,11 +20679,10 @@ 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;
-    const creator = resolveCreatorIdentity(opts.createdBy || globalOpts.agent);
     const router = resolveWritableIdentity(opts.createdBy || globalOpts.agent);
     const requestedAssign = opts.assign ? await resolveValidatedAssignee(opts.assign, Boolean(opts.assignSeat), (v) => `--assign ${v} --assign-seat`) : undefined;
     const assignee = requestedAssign || (opts.unassigned ? undefined : router.agent_id || undefined);
@@ -20555,8 +20693,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}`);
@@ -20576,9 +20715,10 @@ function registerTaskCommands(program2) {
           status: parseStatus(opts.status),
           task_list_id: cloudTaskListId,
           agent_id: globalOpts.agent || router.agent_id || undefined,
-          created_by: creator.agent_id || undefined,
+          created_by: router.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,
@@ -20597,8 +20737,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 ? (() => {
@@ -20622,7 +20763,7 @@ function registerTaskCommands(program2) {
         status: parseStatus(opts.status),
         task_list_id: taskListId,
         agent_id: globalOpts.agent || router.agent_id || undefined,
-        created_by: creator.agent_id || undefined,
+        created_by: router.agent_id || undefined,
         session_id: globalOpts.session,
         project_id: projectId,
         working_dir: process.cwd(),
@@ -20810,15 +20951,19 @@ function registerTaskCommands(program2) {
       }
       filter["task_list_id"] = listId;
     }
-    if (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)
+    if (opts.priority !== undefined)
       filter["priority"] = parseEnumFlag(opts.priority, TASK_PRIORITY_FLAG);
-    if (opts.assigned)
-      filter["assigned_to"] = opts.assigned;
+    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)
@@ -20829,7 +20974,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)
@@ -20845,8 +20991,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) {
@@ -20858,11 +21007,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.
@@ -20879,8 +21040,6 @@ function registerTaskCommands(program2) {
           return false;
         return true;
       });
-      if (requestedLimit !== undefined)
-        tasks = tasks.slice(0, requestedLimit);
     }
     if (opts.dueToday) {
       const todayEnd = new Date;
@@ -20905,6 +21064,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") {
@@ -21676,17 +21850,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) {
@@ -21715,6 +21898,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)
@@ -21751,6 +21942,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) {
@@ -21759,7 +21960,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) });
@@ -21777,6 +21978,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();
@@ -21787,6 +21989,8 @@ var init_task_commands = __esm(() => {
   init_lock_display();
   init_claim_guard();
   init_assignee_guard();
+  init_assignee_context();
+  init_agents();
   init_helpers();
   init_output_redaction();
 });
@@ -39195,7 +39399,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) {
@@ -43793,7 +44003,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;
@@ -43826,7 +44036,7 @@ function registerTaskCrudTools(server, ctx) {
       project_id: exports_external.string().optional().describe("Project ID"),
       task_list_id: exports_external.string().optional().describe("Task list ID"),
       assigned_to: exports_external.string().optional().describe("Agent ID or name to assign to"),
-      created_by: exports_external.string().optional().describe("Agent who FILED this task. Defaults to the ambient agent identity (todos init / TODOS_AGENT_ID)."),
+      created_by: exports_external.string().optional().describe("Agent who FILED this task. Defaults to the PROCESS-BOUND ambient identity (--agent / TODOS_AGENT_ID) if set; the machine-shared identity `todos init` persists to disk is never used here, because it names the station, not the caller."),
       unassigned: exports_external.boolean().optional().describe("Deliberately file with no assignee. Without it, the task defaults to the filer."),
       allow_seat: exports_external.boolean().optional().describe("Allow assigned_to to name a durable seat. A seat queue has no session watching it, so this must be deliberate."),
       depends_on: exports_external.array(exports_external.string()).optional().describe("Array of task IDs this task depends on"),
@@ -43841,14 +44051,13 @@ function registerTaskCrudTools(server, ctx) {
       try {
         const { depends_on, assigned_to, project_id, task_list_id, tags, estimate, confidence, retry_count, deadline, created_by, unassigned, allow_seat, ...rest } = params;
         const requestedAssignee = assigned_to ? await validateMcpAssignee(assigned_to, Boolean(allow_seat)) : undefined;
-        const creator = resolveCreatorIdentity(created_by);
         const router = resolveWritableIdentity(created_by);
         const assignee = requestedAssignee || (unassigned ? undefined : router.agent_id || undefined);
         const cloud = getTodosCloudClient();
         if (cloud) {
           const payload = { ...rest };
-          if (creator.agent_id)
-            payload.created_by = creator.agent_id;
+          if (router.agent_id)
+            payload.created_by = router.agent_id;
           if (router.agent_id)
             payload.agent_id = payload.agent_id ?? router.agent_id;
           if (assignee)
@@ -43869,12 +44078,13 @@ 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) }] };
         }
         const resolved = { ...rest };
-        if (creator.agent_id)
-          resolved.created_by = creator.agent_id;
+        if (router.agent_id)
+          resolved.created_by = router.agent_id;
         if (router.agent_id)
           resolved.agent_id = resolved.agent_id ?? router.agent_id;
         if (assignee)
@@ -43895,6 +44105,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) {
@@ -63133,7 +63344,8 @@ function buildServer() {
     formatError,
     formatTask,
     formatTaskDetail,
-    getAgentFocus
+    getAgentFocus,
+    applyFocus
   };
   registerTaskCrudTools(server, toolContext);
   registerTaskProjectTools(server, toolContext);
@@ -66580,7 +66792,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 });
@@ -69187,8 +69399,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`;
@@ -72353,7 +72565,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