@hasna/todos 0.13.1 → 0.13.3

package/dist/server/index.js

@@ -70,7 +70,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.13.1",
+    version: "0.13.3",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -104,6 +104,10 @@ var init_package = __esm(() => {
       "./storage": {
         types: "./dist/storage.d.ts",
         import: "./dist/storage.js"
+      },
+      "./testing": {
+        types: "./dist/testing.d.ts",
+        import: "./dist/testing.js"
       }
     },
     workspaces: [
@@ -116,13 +120,13 @@ var init_package = __esm(() => {
       "README.md"
     ],
     scripts: {
-      build: "rm -rf dist dashboard/dist && cd dashboard && bun install --frozen-lockfile && bun run build && cd .. && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts --outdir dist --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && tsc --emitDeclarationOnly --outDir dist",
-      "build:server": "rm -rf dist && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts --outdir dist --target bun --external '@hasna/contracts' --external '@hasna/contracts/*'",
+      build: "rm -rf dist dashboard/dist && cd dashboard && bun install --frozen-lockfile && bun run build && cd .. && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts --outdir dist --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && tsc --emitDeclarationOnly --outDir dist",
+      "build:server": "rm -rf dist && bun build src/cli/index.tsx --outdir dist/cli --target bun --external ink --external react --external chalk --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/mcp/index.ts --outdir dist/mcp --target bun --external @modelcontextprotocol/sdk --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/server/index.ts --outdir dist/server --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/sdk/index.ts --outdir dist/sdk --target bun --external '@hasna/contracts' --external '@hasna/contracts/*' && bun build src/index.ts src/mcp.ts src/registry.ts src/contracts.ts src/storage.ts src/testing.ts --outdir dist --target bun --external '@hasna/contracts' --external '@hasna/contracts/*'",
       migrate: "bun run src/server/index.ts migrate",
       "backfill:comment-redaction": "bun run src/server/index.ts redact-comments",
       "generate:sdk": "bun run scripts/generate-sdk.ts",
       "build:dashboard": "cd dashboard && bun install --frozen-lockfile && bun run build",
-      typecheck: "tsc --noEmit",
+      typecheck: "tsc --noEmit -p tsconfig.typecheck.json",
       test: "bun test",
       "test:no-cloud": "bun test src/no-cloud-boundary.test.ts src/local-first.test.ts src/lib/public-release-gate.test.ts",
       "dev:cli": "bun run src/cli/index.tsx",
@@ -201,15 +205,18 @@ var init_package_version = __esm(() => {
 var exports_config = {};
 __export(exports_config, {
   parseStorageMode: () => parseStorageMode,
+  parseStorageBackend: () => parseStorageBackend,
   loadTodosStorageConfig: () => loadTodosStorageConfig,
   loadStorageConfig: () => loadStorageConfig,
   isTodosShadowEnabled: () => isTodosShadowEnabled,
   isTodosRemoteStorageEnabled: () => isTodosRemoteStorageEnabled,
+  isTodosPostgresBackend: () => isTodosPostgresBackend,
   getTodosStorageShadowEnvName: () => getTodosStorageShadowEnvName,
   getTodosStorageMode: () => getTodosStorageMode,
   getTodosStorageEnvName: () => getTodosStorageEnvName,
   getTodosStorageDatabaseUrl: () => getTodosStorageDatabaseUrl,
   getTodosStorageDatabaseEnv: () => getTodosStorageDatabaseEnv,
+  getTodosStorageBackend: () => getTodosStorageBackend,
   getStorageMode: () => getStorageMode,
   getStorageDatabaseUrl: () => getStorageDatabaseUrl,
   getStorageDatabaseEnv: () => getStorageDatabaseEnv,
@@ -234,7 +241,7 @@ function getCanonicalTodosRdsConfig(env = process.env) {
   };
 }
 function loadTodosStorageConfig(env = process.env) {
-  const mode = getTodosStorageMode(env);
+  const mode = getTodosStorageBackend(env);
   const databaseUrl = getTodosStorageDatabaseUrl(env);
   const bucket = readStorageEnv(env, "s3Bucket").value;
   const prefix = readStorageEnv(env, "s3Prefix").value ?? "todos/";
@@ -271,29 +278,41 @@ function loadTodosStorageConfig(env = process.env) {
 function loadStorageConfig(env = process.env) {
   return loadTodosStorageConfig(env);
 }
+function isTodosPostgresBackend(config) {
+  return config.mode === "postgres";
+}
 function isTodosRemoteStorageEnabled(config) {
-  return config.mode === "remote" || config.mode === "hybrid";
+  return isTodosPostgresBackend(config);
 }
 function assertTodosRemoteStorageConfig(config) {
-  if (!isTodosRemoteStorageEnabled(config))
+  if (!isTodosPostgresBackend(config))
     return;
   if (!config.database?.url) {
     throw new Error(`${TODOS_STORAGE_ENV.databaseUrl} is required when ${TODOS_STORAGE_ENV.mode}=${config.mode}`);
   }
 }
-function parseStorageMode(value) {
+function parseStorageBackend(value) {
   const normalized = clean(value)?.toLowerCase();
   if (!normalized)
-    return "local";
-  if (normalized === "local" || normalized === "remote" || normalized === "hybrid")
+    return "sqlite";
+  if (normalized === "sqlite" || normalized === "postgres")
     return normalized;
-  throw new Error(`${TODOS_STORAGE_ENV.mode} must be local, remote, or hybrid`);
+  const legacy = LEGACY_BACKEND_TOKENS[normalized];
+  if (legacy)
+    return legacy;
+  throw new Error(`${TODOS_STORAGE_ENV.mode} must be sqlite or postgres (legacy values local and remote are accepted)`);
+}
+function parseStorageMode(value) {
+  return parseStorageBackend(value);
+}
+function getTodosStorageBackend(env = process.env) {
+  return parseStorageBackend(readStorageEnv(env, "mode").value);
 }
 function getTodosStorageMode(env = process.env) {
-  return parseStorageMode(readStorageEnv(env, "mode").value);
+  return getTodosStorageBackend(env);
 }
 function getStorageMode(env = process.env) {
-  return getTodosStorageMode(env);
+  return getTodosStorageBackend(env);
 }
 function isTodosShadowEnabled(env = process.env) {
   return parseBoolean(readStorageEnv(env, "shadow").value, false);
@@ -304,8 +323,8 @@ function getTodosStorageShadowEnvName(env = process.env) {
 function assertTodosShadowConfig(config, env = process.env) {
   if (!isTodosShadowEnabled(env))
     return;
-  if (config.mode !== "local") {
-    throw new Error(`${readStorageEnv(env, "shadow").name} shadow mirror requires ${TODOS_STORAGE_ENV.mode}=local (got ${config.mode})`);
+  if (config.mode !== "sqlite") {
+    throw new Error(`${readStorageEnv(env, "shadow").name} shadow mirror requires the sqlite backend (got ${config.mode})`);
   }
   if (!config.database?.url) {
     throw new Error(`${TODOS_STORAGE_ENV.databaseUrl} is required when ${readStorageEnv(env, "shadow").name} is enabled`);
@@ -361,7 +380,7 @@ function parsePositiveInteger(value, fallback) {
   }
   return parsed;
 }
-var TODOS_STORAGE_TABLES, STORAGE_TABLES, TODOS_STORAGE_ENV, TODOS_STORAGE_FALLBACK_ENV, CANONICAL_TODOS_RDS_CLUSTER_ENV = "HASNA_TODOS_RDS_CLUSTER", CANONICAL_TODOS_RDS_RUNTIME_PATH_ENV = "HASNA_TODOS_RDS_RUNTIME_PATH", CANONICAL_TODOS_RDS_DATABASE = "todos";
+var TODOS_STORAGE_TABLES, STORAGE_TABLES, TODOS_STORAGE_ENV, TODOS_STORAGE_FALLBACK_ENV, CANONICAL_TODOS_RDS_CLUSTER_ENV = "HASNA_TODOS_RDS_CLUSTER", CANONICAL_TODOS_RDS_RUNTIME_PATH_ENV = "HASNA_TODOS_RDS_RUNTIME_PATH", CANONICAL_TODOS_RDS_DATABASE = "todos", LEGACY_BACKEND_TOKENS;
 var init_config = __esm(() => {
   TODOS_STORAGE_TABLES = [
     "todos_sync_records",
@@ -402,6 +421,14 @@ var init_config = __esm(() => {
     syncBatchSize: "TODOS_SYNC_BATCH_SIZE",
     syncDryRun: "TODOS_SYNC_DRY_RUN"
   };
+  LEGACY_BACKEND_TOKENS = {
+    local: "sqlite",
+    remote: "postgres",
+    postgresql: "postgres",
+    hybrid: "postgres",
+    self_hosted: "postgres",
+    cloud: "postgres"
+  };
 });
 
 // src/storage/cloud-client.ts
@@ -466,7 +493,10 @@ var init_cloud_client = __esm(() => {
 });
 
 // src/types/index.ts
-var TASK_STATUSES, VersionConflictError, TaskNotFoundError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DispatchNotFoundError;
+function isBlockingDependencyStatus(status) {
+  return status !== "completed" && status !== "cancelled";
+}
+var TASK_STATUSES, VersionConflictError, TaskNotFoundError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DispatchNotFoundError;
 var init_types = __esm(() => {
   TASK_STATUSES = [
     "pending",
@@ -499,6 +529,22 @@ var init_types = __esm(() => {
       this.name = "TaskNotFoundError";
     }
   };
+  TaskReferenceAmbiguousError = class TaskReferenceAmbiguousError extends Error {
+    reference;
+    static code = "TASK_REFERENCE_AMBIGUOUS";
+    candidateTaskIds;
+    candidateProjectIds;
+    constructor(reference, candidates) {
+      const candidateTaskIds = [...new Set(candidates.map((candidate) => candidate.task_id))].sort();
+      const candidateProjectIds = [...new Set(candidates.map((candidate) => candidate.project_id).filter((projectId) => typeof projectId === "string" && projectId.length > 0))].sort();
+      const projectList = candidateProjectIds.length > 0 ? candidateProjectIds.join(", ") : "(unscoped)";
+      super(`Task reference is ambiguous: "${reference}". Candidate project IDs: ${projectList}. ` + "Use a full task UUID.");
+      this.reference = reference;
+      this.name = "TaskReferenceAmbiguousError";
+      this.candidateTaskIds = candidateTaskIds;
+      this.candidateProjectIds = candidateProjectIds;
+    }
+  };
   ProjectNotFoundError = class ProjectNotFoundError extends Error {
     projectId;
     static code = "PROJECT_NOT_FOUND";
@@ -1083,6 +1129,185 @@ var init_postgres_sync = __esm(() => {
   };
 });
 
+// src/lib/integrity.ts
+function resolveIntegritySeverity(spec, measurement) {
+  if (spec.kind === "dangling")
+    return "error";
+  if (spec.escalate_when_open && (measurement.open_count ?? 0) > 0)
+    return "error";
+  return spec.base_severity;
+}
+function plural(entity, count) {
+  const [one, many] = ENTITY_LABEL[entity];
+  return count === 1 ? one : many;
+}
+function formatIntegrityMessage(spec, measurement) {
+  const noun = plural(spec.entity, measurement.count);
+  const verb = measurement.count === 1 ? ["has", "references"] : ["have", "reference"];
+  const open = measurement.open_count === null || measurement.open_count === 0 ? "" : ` (${measurement.open_count} still open)`;
+  return spec.kind === "missing" ? `${measurement.count} ${noun} ${verb[0]} no ${spec.field}${open}` : `${measurement.count} ${noun} ${verb[1]} a ${spec.target.replace("_", " ")} that is not registered${open}`;
+}
+function measuredCondition(spec, measurement, source) {
+  return {
+    id: spec.id,
+    entity: spec.entity,
+    field: spec.field,
+    kind: spec.kind,
+    count: measurement.count,
+    open_count: measurement.open_count,
+    severity: measurement.count > 0 ? resolveIntegritySeverity(spec, measurement) : null,
+    verified: true,
+    source,
+    message: formatIntegrityMessage(spec, measurement),
+    impact: spec.impact
+  };
+}
+function unverifiedCondition(spec, reason) {
+  return {
+    id: spec.id,
+    entity: spec.entity,
+    field: spec.field,
+    kind: spec.kind,
+    count: null,
+    open_count: null,
+    severity: null,
+    verified: false,
+    source: "unverified",
+    unverified_reason: reason,
+    message: `${spec.id}: NOT CHECKED \u2014 ${reason}`,
+    impact: spec.impact
+  };
+}
+function summarizeIntegrity(conditions) {
+  const measured = conditions.filter((condition) => condition.verified && condition.count !== null);
+  const findings = measured.filter((condition) => (condition.count ?? 0) > 0);
+  const unverified = conditions.length - measured.length;
+  return {
+    ok: unverified === 0 && findings.length === 0,
+    findings: findings.length,
+    rows: findings.reduce((total, condition) => total + (condition.count ?? 0), 0),
+    errors: findings.filter((condition) => condition.severity === "error").length,
+    warnings: findings.filter((condition) => condition.severity === "warn").length,
+    unverified,
+    complete: unverified === 0
+  };
+}
+function buildIntegrityReport(conditions, generatedAt) {
+  const measuredSources = [...new Set(conditions.map((condition) => condition.source))].filter((source) => source !== "unverified");
+  return {
+    schema_version: TODOS_INTEGRITY_SCHEMA_VERSION,
+    generated_at: generatedAt,
+    source: measuredSources.length === 0 ? "unverified" : measuredSources.length === 1 ? measuredSources[0] : "remote-derived",
+    conditions,
+    summary: summarizeIntegrity(conditions)
+  };
+}
+function sqliteOpenStatusList() {
+  return OPEN_TASK_STATUSES.map((status) => `'${status}'`).join(", ");
+}
+function buildSqliteIntegritySql(spec) {
+  const table = SQLITE_TABLE[spec.entity];
+  const target = SQLITE_TABLE[spec.target];
+  const column = `t."${spec.field}"`;
+  const predicate = spec.kind === "missing" ? `(${column} IS NULL OR ${column} = '')` : `${column} IS NOT NULL AND ${column} <> '' ` + `AND NOT EXISTS (SELECT 1 FROM "${target}" r WHERE r."id" = ${column})`;
+  const openExpr = spec.entity === "task" ? `SUM(CASE WHEN t."status" IN (${sqliteOpenStatusList()}) THEN 1 ELSE 0 END)` : "NULL";
+  return `SELECT COUNT(*) AS count, ${openExpr} AS open_count FROM "${table}" t WHERE ${predicate}`;
+}
+function buildPostgresIntegritySql(spec, options) {
+  const params = [options.service, RECORD_TYPE[spec.entity]];
+  const p = (value) => {
+    params.push(value);
+    return `$${params.length}`;
+  };
+  const column = `t.payload->>'${spec.field}'`;
+  const predicate = spec.kind === "missing" ? `(${column} IS NULL OR ${column} = '')` : `${column} IS NOT NULL AND ${column} <> '' AND NOT EXISTS (` + `SELECT 1 FROM ${options.table} r WHERE r.service = $1 AND r.object_type = ${p(RECORD_TYPE[spec.target])} ` + `AND r.deleted_at IS NULL AND r.object_id = ${column})`;
+  const openExpr = spec.entity === "task" ? `COUNT(*) FILTER (WHERE t.payload->>'status' IN (${OPEN_TASK_STATUSES.map((status) => p(status)).join(", ")}))::int` : "NULL::int";
+  const sql = `/* todos:integrity-${spec.id} */ SELECT COUNT(*)::int AS count, ${openExpr} AS open_count ` + `FROM ${options.table} t WHERE t.service = $1 AND t.object_type = $2 AND t.deleted_at IS NULL AND ${predicate}`;
+  return { sql, params };
+}
+var TODOS_INTEGRITY_SCHEMA_VERSION = "todos.integrity.v1", TERMINAL_TASK_STATUSES, OPEN_TASK_STATUSES, INTEGRITY_CONDITIONS, ENTITY_LABEL, SQLITE_TABLE, RECORD_TYPE;
+var init_integrity = __esm(() => {
+  init_types();
+  TERMINAL_TASK_STATUSES = ["completed", "failed", "cancelled"];
+  OPEN_TASK_STATUSES = TASK_STATUSES.filter((status) => !TERMINAL_TASK_STATUSES.includes(status));
+  INTEGRITY_CONDITIONS = [
+    {
+      id: "tasks_without_project",
+      entity: "task",
+      field: "project_id",
+      target: "project",
+      kind: "missing",
+      base_severity: "warn",
+      escalate_when_open: true,
+      impact: "invisible to every project-scoped read (list, status, next, claim)"
+    },
+    {
+      id: "tasks_without_task_list",
+      entity: "task",
+      field: "task_list_id",
+      target: "task_list",
+      kind: "missing",
+      base_severity: "warn",
+      escalate_when_open: true,
+      impact: "invisible to every task-list read \u2014 the list reports zero open work"
+    },
+    {
+      id: "tasks_with_unregistered_project",
+      entity: "task",
+      field: "project_id",
+      target: "project",
+      kind: "dangling",
+      base_severity: "error",
+      escalate_when_open: false,
+      impact: "points at a project id that does not exist; the reference can never resolve"
+    },
+    {
+      id: "tasks_with_unregistered_task_list",
+      entity: "task",
+      field: "task_list_id",
+      target: "task_list",
+      kind: "dangling",
+      base_severity: "error",
+      escalate_when_open: false,
+      impact: "points at a task-list id that does not exist; the reference can never resolve"
+    },
+    {
+      id: "task_lists_without_project",
+      entity: "task_list",
+      field: "project_id",
+      target: "project",
+      kind: "missing",
+      base_severity: "warn",
+      escalate_when_open: false,
+      impact: "unbound list \u2014 unreachable from any project, so its tasks are unroutable"
+    },
+    {
+      id: "task_lists_with_unregistered_project",
+      entity: "task_list",
+      field: "project_id",
+      target: "project",
+      kind: "dangling",
+      base_severity: "error",
+      escalate_when_open: false,
+      impact: "points at a project id that does not exist; the list can never be reached"
+    }
+  ];
+  ENTITY_LABEL = {
+    task: ["task", "tasks"],
+    task_list: ["task list", "task lists"]
+  };
+  SQLITE_TABLE = {
+    task: "tasks",
+    task_list: "task_lists",
+    project: "projects"
+  };
+  RECORD_TYPE = {
+    task: "tasks",
+    task_list: "task_lists",
+    project: "projects"
+  };
+});
+
 // src/lib/sync-utils.ts
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
@@ -1201,11 +1426,15 @@ function secretPatterns() {
   return [...customPatterns(), ...DEFAULT_SECRET_PATTERNS];
 }
 function isRedactionPlaceholderMatch(match) {
-  const placeholder = String.raw`\[REDACTED(?:_[A-Z_]+)?\]`;
   const trimmed = match.trim();
-  return new RegExp(`^${placeholder}$`).test(trimmed) || new RegExp(`=\\s*['"]?${placeholder}['"]?$`).test(trimmed);
+  return new RegExp(`^${REDACTION_PLACEHOLDER}$`).test(trimmed) || new RegExp(`=\\s*['"]?${REDACTION_PLACEHOLDER}['"]?$`).test(trimmed);
+}
+function isRedactionPlaceholderKey(key) {
+  return new RegExp(`^${REDACTION_PLACEHOLDER}$`).test(key.trim());
 }
 function isSecretKey(key) {
+  if (isRedactionPlaceholderKey(key))
+    return false;
   if (NON_SECRET_USAGE_KEYS.has(key.toLowerCase()))
     return false;
   if (DEFAULT_SECRET_KEY_PATTERN.test(key))
@@ -1263,7 +1492,7 @@ function upsertSecretSafetyConfig(input) {
   saveConfig({ ...config, secret_safety: next });
   return next;
 }
-var DEFAULT_SECRET_PATTERNS, DEFAULT_SECRET_KEY_PATTERN, NON_SECRET_USAGE_KEYS;
+var DEFAULT_SECRET_PATTERNS, DEFAULT_SECRET_KEY_PATTERN, NON_SECRET_USAGE_KEYS, REDACTION_PLACEHOLDER;
 var init_redaction = __esm(() => {
   init_config2();
   DEFAULT_SECRET_PATTERNS = [
@@ -1287,6 +1516,7 @@ var init_redaction = __esm(() => {
     "completion_tokens",
     "cost_tokens"
   ]);
+  REDACTION_PLACEHOLDER = String.raw`\[REDACTED(?:_[A-Z_]+)?\]`;
 });
 
 // src/storage/postgres-adapter.ts
@@ -1417,6 +1647,9 @@ function createPostgresTodosStorageAdapter(options) {
       exportSnapshot: () => exportSnapshot(store),
       importSnapshot: (snapshot, context) => importSnapshot(snapshot, store, context)
     },
+    integrity: {
+      report: () => store.integrityReport()
+    },
     transaction: (fn) => fn(adapter)
   };
   return adapter;
@@ -1523,8 +1756,9 @@ class PostgresJsonRecordStore {
       conds.push(`payload->>'agent_id' = ${p(filter.agent_id)}`);
     if (filter.session_id !== undefined)
       conds.push(`payload->>'session_id' = ${p(filter.session_id)}`);
-    if (filter.tags?.length)
-      conds.push(`payload->'tags' @> ${p(filter.tags)}::jsonb`);
+    if (filter.tags?.length) {
+      conds.push(`EXISTS (SELECT 1 FROM jsonb_array_elements_text(COALESCE(payload->'tags', '[]'::jsonb)) AS task_tags(tag) ` + `WHERE ${inClause("task_tags.tag", filter.tags)})`);
+    }
     if (filter.has_recurrence !== undefined) {
       conds.push(`(COALESCE(payload->>'recurrence_rule', '') <> '') = ${p(filter.has_recurrence)}`);
     }
@@ -1585,7 +1819,8 @@ class PostgresJsonRecordStore {
             AND object_id COLLATE "C" >= $2 AND object_id COLLATE "C" < $3
           LIMIT 2`, [this.service, raw, upper]);
       if (prefixResult.rows.length > 1) {
-        throw new Error(`Task reference is ambiguous: "${ref}"`);
+        const candidates = prefixResult.rows.map((row) => payloadRecord2(row.payload));
+        throw new TaskReferenceAmbiguousError(ref, candidates.map((task) => ({ task_id: task.id, project_id: task.project_id })));
       }
       if (prefixResult.rows.length === 1) {
         return payloadRecord2(prefixResult.rows[0].payload);
@@ -1596,7 +1831,8 @@ class PostgresJsonRecordStore {
           AND LOWER(payload->>'short_id') = $2
         LIMIT 2`, [this.service, raw]);
     if (shortIdResult.rows.length > 1) {
-      throw new Error(`Task reference is ambiguous: "${ref}"`);
+      const candidates = shortIdResult.rows.map((row) => payloadRecord2(row.payload));
+      throw new TaskReferenceAmbiguousError(ref, candidates.map((task) => ({ task_id: task.id, project_id: task.project_id })));
     }
     if (shortIdResult.rows.length === 1) {
       return payloadRecord2(shortIdResult.rows[0].payload);
@@ -1610,6 +1846,24 @@ class PostgresJsonRecordStore {
     const result = await this.options.client.query(sql, params);
     return Number(result.rows[0]?.count ?? 0);
   }
+  async integrityReport() {
+    await this.ensureSchema();
+    const conditions = [];
+    for (const spec of INTEGRITY_CONDITIONS) {
+      const { sql, params } = buildPostgresIntegritySql(spec, { table: this.tableName, service: this.service });
+      try {
+        const result = await this.options.client.query(sql, params);
+        const row = result.rows[0];
+        conditions.push(measuredCondition(spec, {
+          count: Number(row?.count ?? 0),
+          open_count: spec.entity === "task" ? Number(row?.open_count ?? 0) : null
+        }, "postgres"));
+      } catch (error) {
+        conditions.push(unverifiedCondition(spec, error instanceof Error ? error.message : String(error)));
+      }
+    }
+    return buildIntegrityReport(conditions, new Date().toISOString());
+  }
   async listTombstones() {
     await this.ensureSchema();
     const result = await this.options.client.query(`SELECT object_type, object_id, payload, updated_at, deleted_at, source_machine_id, version
@@ -2085,7 +2339,7 @@ async function startTask(id, agentId, store) {
   if (task.status !== "pending" && task.status !== "in_progress") {
     throw new Error(`Task is ${task.status} and cannot be started by ${agentId}`);
   }
-  return patchTask(task, {
+  const started = await patchTask(task, {
     status: "in_progress",
     assigned_to: task.assigned_to ?? agentId,
     agent_id: task.agent_id ?? agentId,
@@ -2093,6 +2347,8 @@ async function startTask(id, agentId, store) {
     locked_at: new Date().toISOString(),
     started_at: task.started_at ?? new Date().toISOString()
   }, store);
+  await logTaskChange(task.id, "start", "status", task.status, "in_progress", agentId, store);
+  return started;
 }
 async function completeTask(id, agentId, options, store) {
   const task = await store.completeTask(id, agentId, options);
@@ -2209,9 +2465,11 @@ async function removeDependency(taskId, dependsOn, store) {
 }
 async function listDependencies(taskId, store) {
   const edges = await store.list("dependencies");
+  const incoming = edges.filter((edge) => edge.depends_on === taskId).map((edge) => ({ task_id: edge.task_id, depends_on: edge.depends_on }));
   return {
     dependencies: edges.filter((edge) => edge.task_id === taskId).map((edge) => ({ task_id: edge.task_id, depends_on: edge.depends_on })),
-    blocked_by: edges.filter((edge) => edge.depends_on === taskId).map((edge) => ({ task_id: edge.task_id, depends_on: edge.depends_on }))
+    blocks: incoming,
+    blocked_by: incoming
   };
 }
 async function addVerification(input, store, context) {
@@ -2757,6 +3015,7 @@ var CLOUD_LOCK_EXPIRY_MINUTES = 30, TASK_ORDER_TIEBREAK = "CASE payload->>'prior
 var init_postgres_adapter = __esm(() => {
   init_types();
   init_postgres_sync();
+  init_integrity();
   init_redaction();
   TASK_ORDER_BY = `ORDER BY ${TASK_ORDER_TIEBREAK}`;
 });
@@ -4755,6 +5014,7 @@ __export(exports_cloud, {
   resolveCloudDatabaseUrl: () => resolveCloudDatabaseUrl,
   pingCloud: () => pingCloud,
   normalizeCloudPayloads: () => normalizeCloudPayloads,
+  isPostgresBackendConfigured: () => isPostgresBackendConfigured,
   isCloudModeEnabled: () => isCloudModeEnabled,
   getCloudVerifier: () => getCloudVerifier,
   getCloudStorageAdapter: () => getCloudStorageAdapter,
@@ -4777,9 +5037,12 @@ function resolveCloudDatabaseUrl(env = process.env) {
 function resolveSigningSecret(env = process.env) {
   return env.HASNA_TODOS_API_SIGNING_KEY || env.HASNA_API_SIGNING_KEY || env.API_KEY_SIGNING_SECRET || undefined;
 }
-function isCloudModeEnabled(env = process.env) {
+function isPostgresBackendConfigured(env = process.env) {
   return Boolean(resolveCloudDatabaseUrl(env));
 }
+function isCloudModeEnabled(env = process.env) {
+  return isPostgresBackendConfigured(env);
+}
 function getClient() {
   if (cachedClient)
     return cachedClient;
@@ -8607,6 +8870,30 @@ function findGitRoot(startDir) {
   }
   return null;
 }
+function getGlobalDbPath() {
+  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  return join3(home, ".hasna", "todos", "todos.db");
+}
+function hasExplicitProjectArg(args = process.argv.slice(2)) {
+  return args.some((arg) => arg === "--project" || arg.startsWith("--project="));
+}
+function getCliCommand(args = process.argv.slice(2)) {
+  const globalOptionsWithValues = new Set(["--project", "--agent", "--session"]);
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (globalOptionsWithValues.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("-"))
+      continue;
+    return arg;
+  }
+  return null;
+}
+function canCreateScopedProjectDb(args = process.argv.slice(2)) {
+  return getCliCommand(args) === "project-bootstrap" && !args.some((arg) => arg === "--dry-run" || arg.startsWith("--dry-run="));
+}
 function getDbPath() {
   if (process.env["HASNA_TODOS_DB_PATH"]) {
     return process.env["HASNA_TODOS_DB_PATH"];
@@ -8614,18 +8901,19 @@ function getDbPath() {
   if (process.env["TODOS_DB_PATH"]) {
     return process.env["TODOS_DB_PATH"];
   }
+  if (hasExplicitProjectArg())
+    return getGlobalDbPath();
   const cwd = process.cwd();
   const nearest = findNearestProjectDb(cwd);
   if (nearest)
     return nearest;
   if (process.env["TODOS_DB_SCOPE"] === "project") {
     const gitRoot = findGitRoot(cwd);
-    if (gitRoot) {
+    if (gitRoot && canCreateScopedProjectDb()) {
       return join3(gitRoot, ".hasna", "todos", "todos.db");
     }
   }
-  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  return join3(home, ".hasna", "todos", "todos.db");
+  return getGlobalDbPath();
 }
 function getDatabasePath() {
   return getDbPath();
@@ -8641,8 +8929,8 @@ function ensureDir2(filePath) {
 function openDatabase(path) {
   ensureDir2(path);
   const db = new Database(path);
-  db.run("PRAGMA journal_mode = WAL");
   db.run("PRAGMA busy_timeout = 5000");
+  db.run("PRAGMA journal_mode = WAL");
   db.run("PRAGMA foreign_keys = ON");
   runMigrations(db);
   ensureAgentIdentitySchema(db);
@@ -8728,10 +9016,13 @@ function resolvePartialId(db, table, partialId) {
     return null;
   }
   if (table === "tasks") {
-    const shortIdRows = db.query("SELECT id FROM tasks WHERE short_id = ?").all(partialId);
+    const shortIdRows = db.query("SELECT id, project_id FROM tasks WHERE LOWER(short_id) = LOWER(?) ORDER BY project_id, id").all(partialId);
     if (shortIdRows.length === 1) {
       return shortIdRows[0].id;
     }
+    if (shortIdRows.length > 1) {
+      throw new TaskReferenceAmbiguousError(partialId, shortIdRows.map((row) => ({ task_id: row.id, project_id: row.project_id })));
+    }
   }
   if (table === "task_lists") {
     const slugRow = db.query("SELECT id FROM task_lists WHERE slug = ?").get(partialId);
@@ -8895,7 +9186,7 @@ function authNotConfiguredMessage(host) {
 `);
 }
 function resolveAuthPosture(input) {
-  const hosted = input.hosted ?? isCloudModeEnabled();
+  const hosted = input.hosted ?? isPostgresBackendConfigured();
   const hasCredentialSource = Boolean(input.apiKey) || input.hasGeneratedKeys;
   if (hasCredentialSource) {
     return {
@@ -11040,7 +11331,7 @@ function scanTextForSecrets(text, options = {}) {
   };
 }
 function redactText(text, options = {}) {
-  const placeholder = options.placeholder ?? REDACTION_PLACEHOLDER;
+  const placeholder = options.placeholder ?? REDACTION_PLACEHOLDER2;
   let out = text;
   for (const { pattern, allowlist_ok } of DEFAULT_PATTERNS) {
     out = out.replace(new RegExp(pattern.source, pattern.flags), (match) => {
@@ -11067,7 +11358,7 @@ function redactExportRecord(record) {
   }
   return base;
 }
-var SECRET_REDACTION_SCHEMA, REDACTION_PLACEHOLDER = "[REDACTED]", DEFAULT_PATTERNS, DEFAULT_ALLOWLIST, customRedactors;
+var SECRET_REDACTION_SCHEMA, REDACTION_PLACEHOLDER2 = "[REDACTED]", DEFAULT_PATTERNS, DEFAULT_ALLOWLIST, customRedactors;
 var init_secret_redaction = __esm(() => {
   init_redaction();
   SECRET_REDACTION_SCHEMA = ["todos", "secret_redaction", "v1"].join(".");
@@ -13059,10 +13350,11 @@ function getTaskWithRelations(id, db) {
        JOIN task_dependencies td ON td.depends_on = t.id
        WHERE td.task_id = ?`).all(id);
   const dependencies = depRows.map(rowToTask);
-  const blockedByRows = d.query(`SELECT t.* FROM tasks t
+  const blocked_by = dependencies.filter((dep) => isBlockingDependencyStatus(dep.status));
+  const blocksRows = d.query(`SELECT t.* FROM tasks t
        JOIN task_dependencies td ON td.task_id = t.id
        WHERE td.depends_on = ?`).all(id);
-  const blocked_by = blockedByRows.map(rowToTask);
+  const blocks = blocksRows.map(rowToTask);
   const comments = d.query("SELECT * FROM task_comments WHERE task_id = ? ORDER BY created_at").all(id);
   const parent = task.parent_id ? getTask(task.parent_id, d) : null;
   const checklist = getChecklist(id, d);
@@ -13071,6 +13363,7 @@ function getTaskWithRelations(id, db) {
     subtasks,
     dependencies,
     blocked_by,
+    blocks,
     comments,
     parent,
     checklist
@@ -17215,6 +17508,32 @@ var init_headless_boundaries = __esm(() => {
   LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 });
 
+// src/db/integrity.ts
+function tableExists(db, table) {
+  return Boolean(db.query("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table));
+}
+function scanSqliteIntegrity(db = getDatabase()) {
+  const missing = Object.keys(REQUIRED_TABLES).filter((table) => !tableExists(db, table));
+  const conditions = INTEGRITY_CONDITIONS.map((spec) => {
+    if (missing.length > 0) {
+      return unverifiedCondition(spec, `local schema is missing table(s): ${missing.join(", ")}`);
+    }
+    try {
+      const row = db.query(buildSqliteIntegritySql(spec)).get();
+      return measuredCondition(spec, { count: Number(row?.count ?? 0), open_count: spec.entity === "task" ? Number(row?.open_count ?? 0) : null }, "sqlite");
+    } catch (error) {
+      return unverifiedCondition(spec, error instanceof Error ? error.message : String(error));
+    }
+  });
+  return buildIntegrityReport(conditions, now());
+}
+var REQUIRED_TABLES;
+var init_integrity2 = __esm(() => {
+  init_database();
+  init_integrity();
+  REQUIRED_TABLES = { tasks: true, task_lists: true, projects: true };
+});
+
 // src/lib/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
@@ -17222,7 +17541,7 @@ __export(exports_doctor, {
 });
 import { chmodSync, copyFileSync, existsSync as existsSync7, mkdirSync as mkdirSync5, statSync as statSync3 } from "fs";
 import { basename as basename2, dirname as dirname5, join as join6 } from "path";
-function tableExists(db, table) {
+function tableExists2(db, table) {
   return Boolean(db.query("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table));
 }
 function quoteIdent(identifier) {
@@ -17306,7 +17625,7 @@ function findDuplicateIndexes(db) {
   return duplicates;
 }
 function findMissingProjectRoots(db) {
-  if (!tableExists(db, "projects"))
+  if (!tableExists2(db, "projects"))
     return 0;
   let missing = 0;
   const rows = db.query("SELECT path FROM projects WHERE path IS NOT NULL AND path != ''").all();
@@ -17321,7 +17640,7 @@ function findMissingProjectRoots(db) {
   return missing;
 }
 function addTaskStateChecks(db, checks) {
-  if (!tableExists(db, "tasks"))
+  if (!tableExists2(db, "tasks"))
     return;
   const columns = getTableColumns(db, "tasks");
   const staleCutoff = new Date(Date.now() - 30 * 60 * 1000).toISOString();
@@ -17393,15 +17712,42 @@ function createBackup(dbPath) {
 function pushRepair(repairs, type, message, applied, count) {
   repairs.push({ type, message, applied, count });
 }
-function summarize2(checks, repairs) {
+function summarize2(checks, repairs, integrity) {
   return {
     errors: checks.filter((check) => check.severity === "error").length,
     warnings: checks.filter((check) => check.severity === "warn").length,
     infos: checks.filter((check) => check.severity === "info").length,
     repairable: checks.filter((check) => check.repairable).length,
-    applied: repairs.filter((repair) => repair.applied).length
+    applied: repairs.filter((repair) => repair.applied).length,
+    integrity_findings: integrity.summary.findings,
+    integrity_rows: integrity.summary.rows,
+    integrity_unverified: integrity.summary.unverified
   };
 }
+function addIntegrityChecks(integrity, checks) {
+  for (const condition of integrity.conditions) {
+    if (!condition.verified) {
+      addCheck(checks, {
+        severity: "warn",
+        type: `${condition.id}_unverified`,
+        message: condition.message,
+        repairable: false,
+        integrity: true
+      });
+      continue;
+    }
+    if ((condition.count ?? 0) === 0)
+      continue;
+    addCheck(checks, {
+      severity: condition.severity ?? "warn",
+      type: condition.id,
+      message: `${condition.message} \u2014 ${condition.impact}`,
+      count: condition.count ?? undefined,
+      repairable: false,
+      integrity: true
+    });
+  }
+}
 function deleteOrphans(db, table, where) {
   const before = countQuery(db, `SELECT COUNT(*) as count FROM ${table} WHERE ${where}`);
   if (before > 0)
@@ -17430,7 +17776,7 @@ function runTodosDoctor(options = {}) {
       message: `Schema at migration ${migrationCurrent}`
     });
   }
-  const missingTables = REQUIRED_TABLES.filter((table) => !tableExists(db, table));
+  const missingTables = REQUIRED_TABLES2.filter((table) => !tableExists2(db, table));
   if (missingTables.length > 0) {
     addCheck(checks, {
       severity: "error",
@@ -17440,7 +17786,7 @@ function runTodosDoctor(options = {}) {
       repairable: true
     });
   }
-  const orphanedParents = tableExists(db, "tasks") ? countQuery(db, "SELECT COUNT(*) as count FROM tasks t WHERE t.parent_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM tasks p WHERE p.id = t.parent_id)") : 0;
+  const orphanedParents = tableExists2(db, "tasks") ? countQuery(db, "SELECT COUNT(*) as count FROM tasks t WHERE t.parent_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM tasks p WHERE p.id = t.parent_id)") : 0;
   if (orphanedParents > 0) {
     addCheck(checks, {
       severity: "error",
@@ -17450,7 +17796,7 @@ function runTodosDoctor(options = {}) {
       repairable: true
     });
   }
-  const orphanedDependencies = tableExists(db, "task_dependencies") && tableExists(db, "tasks") ? countQuery(db, "SELECT COUNT(*) as count FROM task_dependencies d WHERE NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = d.task_id) OR NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = d.depends_on)") : 0;
+  const orphanedDependencies = tableExists2(db, "task_dependencies") && tableExists2(db, "tasks") ? countQuery(db, "SELECT COUNT(*) as count FROM task_dependencies d WHERE NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = d.task_id) OR NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = d.depends_on)") : 0;
   if (orphanedDependencies > 0) {
     addCheck(checks, {
       severity: "error",
@@ -17469,7 +17815,7 @@ function runTodosDoctor(options = {}) {
   ];
   let orphanedRows = 0;
   for (const [table, where] of orphanTables) {
-    if (!tableExists(db, table))
+    if (!tableExists2(db, table))
       continue;
     orphanedRows += countQuery(db, `SELECT COUNT(*) as count FROM ${table} WHERE ${where}`);
   }
@@ -17483,6 +17829,8 @@ function runTodosDoctor(options = {}) {
     });
   }
   addTaskStateChecks(db, checks);
+  const integrity = scanSqliteIntegrity(db);
+  addIntegrityChecks(integrity, checks);
   const corruptJson = findCorruptJsonMetadata(db);
   if (corruptJson.length > 0) {
     addCheck(checks, {
@@ -17541,12 +17889,12 @@ function runTodosDoctor(options = {}) {
       db.run("UPDATE tasks SET parent_id = NULL WHERE parent_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM tasks p WHERE p.id = tasks.parent_id)");
       pushRepair(repairs, "orphaned_task_parents", "Cleared missing parent references", true, orphanedParents);
     }
-    if (orphanedDependencies > 0 && tableExists(db, "task_dependencies")) {
+    if (orphanedDependencies > 0 && tableExists2(db, "task_dependencies")) {
       const count = deleteOrphans(db, "task_dependencies", "NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = task_dependencies.task_id) OR NOT EXISTS (SELECT 1 FROM tasks t WHERE t.id = task_dependencies.depends_on)");
       pushRepair(repairs, "orphaned_task_dependencies", "Deleted dependency rows referencing missing tasks", true, count);
     }
     for (const [table, where] of orphanTables) {
-      if (!tableExists(db, table))
+      if (!tableExists2(db, table))
         continue;
       const count = deleteOrphans(db, table, where);
       if (count > 0)
@@ -17575,26 +17923,30 @@ function runTodosDoctor(options = {}) {
       }
     }
   }
-  const finalChecks = apply && hasRepairableIssue ? runTodosDoctor({ db, dbPath, apply: false }).checks : checks;
-  const summary = summarize2(finalChecks, repairs);
+  const reread = apply && hasRepairableIssue ? runTodosDoctor({ db, dbPath, apply: false }) : undefined;
+  const finalChecks = reread?.checks ?? checks;
+  const finalIntegrity = reread?.integrity ?? integrity;
+  const summary = summarize2(finalChecks, repairs, finalIntegrity);
   return {
-    ok: !finalChecks.some((check) => check.severity === "error"),
+    ok: !finalChecks.some((check) => check.severity === "error") && finalIntegrity.summary.ok,
     dry_run: !apply,
     database_path: dbPath,
     migration: { current: getMigrationLevel(db), expected: migrationExpected },
     backup,
     checks: finalChecks,
     repairs,
+    integrity: finalIntegrity,
     summary
   };
 }
-var REQUIRED_TABLES;
+var REQUIRED_TABLES2;
 var init_doctor = __esm(() => {
   init_database();
+  init_integrity2();
   init_migrations();
   init_schema();
   init_recurrence();
-  REQUIRED_TABLES = [
+  REQUIRED_TABLES2 = [
     "_migrations",
     "projects",
     "tasks",
@@ -18986,15 +19338,15 @@ function resolveTaskRefLocal(db, ref) {
     return null;
   if (TASK_UUID_RE.test(raw))
     return getTask(raw, db);
-  const prefixRows = db.query("SELECT id FROM tasks WHERE LOWER(id) LIKE ? ESCAPE '\\' LIMIT 2").all(`${raw.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
+  const prefixRows = db.query("SELECT id, project_id FROM tasks WHERE LOWER(id) LIKE ? ESCAPE '\\' ORDER BY project_id, id LIMIT 2").all(`${raw.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
   if (prefixRows.length > 1) {
-    throw new Error(`Task reference is ambiguous: "${ref}"`);
+    throw new TaskReferenceAmbiguousError(ref, prefixRows.map((row) => ({ task_id: row.id, project_id: row.project_id })));
   }
   if (prefixRows.length === 1)
     return getTask(prefixRows[0].id, db);
-  const shortIdRows = db.query("SELECT id FROM tasks WHERE LOWER(short_id) = ? LIMIT 2").all(raw);
+  const shortIdRows = db.query("SELECT id, project_id FROM tasks WHERE LOWER(short_id) = ? ORDER BY project_id, id LIMIT 2").all(raw);
   if (shortIdRows.length > 1) {
-    throw new Error(`Task reference is ambiguous: "${ref}"`);
+    throw new TaskReferenceAmbiguousError(ref, shortIdRows.map((row) => ({ task_id: row.id, project_id: row.project_id })));
   }
   if (shortIdRows.length === 1)
     return getTask(shortIdRows[0].id, db);
@@ -19143,6 +19495,9 @@ function createLocalSqliteTodosStorageAdapter(options = {}) {
       exportSnapshot: () => exportSqliteTodosStorageSnapshot(database()),
       importSnapshot: (snapshot) => importSqliteTodosStorageSnapshot(snapshot, database())
     },
+    integrity: {
+      report: () => scanSqliteIntegrity(database())
+    },
     transaction: (fn) => {
       const tx = database().transaction(() => fn(adapter));
       return tx();
@@ -19152,6 +19507,7 @@ function createLocalSqliteTodosStorageAdapter(options = {}) {
 }
 var TASK_UUID_RE;
 var init_local_sqlite = __esm(() => {
+  init_types();
   init_search();
   init_tasks();
   init_projects();
@@ -19162,6 +19518,7 @@ var init_local_sqlite = __esm(() => {
   init_audit();
   init_comments();
   init_database();
+  init_integrity2();
   init_sqlite_snapshot();
   TASK_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 });
@@ -20460,6 +20817,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
             { name: "task_list_id", in: "query", schema: { type: "string" } },
             { name: "assigned_to", in: "query", schema: { type: "string" } },
             { name: "agent_id", in: "query", schema: { type: "string" } },
+            { name: "tags", in: "query", schema: { type: "string" }, description: "Comma-separated tags; matches tasks carrying any of them" },
             { name: "limit", in: "query", schema: { type: "integer", minimum: 1 } },
             { name: "offset", in: "query", schema: { type: "integer", minimum: 0 } }
           ],
@@ -21664,6 +22022,9 @@ async function handleV1Request(req, url, dependencies = {}) {
             ...url.searchParams.get("task_list_id") ? { task_list_id: url.searchParams.get("task_list_id") } : {},
             ...url.searchParams.get("assigned_to") ? { assigned_to: url.searchParams.get("assigned_to") } : {},
             ...url.searchParams.get("agent_id") ? { agent_id: url.searchParams.get("agent_id") } : {},
+            ...url.searchParams.get("tags") ? {
+              tags: url.searchParams.get("tags").split(",").map((tag) => tag.trim()).filter(Boolean)
+            } : {},
             ...url.searchParams.get("limit") ? { limit: Number(url.searchParams.get("limit")) } : {},
             ...url.searchParams.get("offset") ? { offset: Number(url.searchParams.get("offset")) } : {}
           };
@@ -21945,6 +22306,13 @@ async function handleV1Request(req, url, dependencies = {}) {
           try {
             task = await store.tasks.resolveRef(id);
           } catch (e) {
+            if (e instanceof TaskReferenceAmbiguousError) {
+              return error(409, e.message, {
+                code: TaskReferenceAmbiguousError.code,
+                candidate_project_ids: e.candidateProjectIds,
+                candidate_task_ids: e.candidateTaskIds
+              });
+            }
             const msg = e.message || "";
             if (/ambiguous/i.test(msg))
               return error(409, msg);
@@ -22302,6 +22670,15 @@ async function handleV1Request(req, url, dependencies = {}) {
       ]);
       return json3({ tasks, tasks_all: tasksAll, subtasks: tasksAll - tasks, projects: projects.length });
     }
+    if (resource === "integrity" && !id) {
+      if (method !== "GET")
+        return error(405, `method ${method} not allowed on /v1/integrity`);
+      if (typeof store.integrity?.report !== "function") {
+        return error(501, "referential-integrity reporting is not supported by this storage backend");
+      }
+      const integrity = await store.integrity.report();
+      return json3({ integrity });
+    }
     if (resource === "import") {
       if (method !== "POST")
         return error(405, `method ${method} not allowed on /v1/import`);
@@ -22321,6 +22698,13 @@ async function handleV1Request(req, url, dependencies = {}) {
     }
     return error(404, `unknown /v1 resource: ${resource ?? "(root)"}`);
   } catch (e) {
+    if (e instanceof TaskReferenceAmbiguousError) {
+      return error(409, e.message, {
+        code: TaskReferenceAmbiguousError.code,
+        candidate_project_ids: e.candidateProjectIds,
+        candidate_task_ids: e.candidateTaskIds
+      });
+    }
     if (e instanceof LockError)
       return error(409, e.message, { code: LockError.code });
     if (e instanceof ResourceConflictError)
@@ -44653,9 +45037,6 @@ function cleanMode(value) {
   const normalized = value?.trim().toLowerCase();
   return normalized || null;
 }
-function modeRole(mode) {
-  return mode === "local" ? "local" : "remote";
-}
 function resolveTodosCliStorageMode(env = process.env) {
   for (const source of ["HASNA_TODOS_STORAGE_MODE", "TODOS_STORAGE_MODE"]) {
     if (env[source] !== undefined && env[source].trim() === "") {
@@ -44668,22 +45049,25 @@ function resolveTodosCliStorageMode(env = process.env) {
     ["HASNA_TODOS_STORAGE_MODE", canonical],
     ["TODOS_STORAGE_MODE", fallback]
   ]) {
-    if (value && !VALID_STORAGE_MODES.has(value)) {
-      throw new Error(`REMOTE_STORAGE_MODE_INVALID: ${source}=${value} must be local, remote, self_hosted, cloud, or hybrid; ` + "local SQLite fallback is disabled for invalid routing state");
+    if (value && !(value in TRANSPORT_TOKENS)) {
+      throw new Error(`REMOTE_STORAGE_MODE_INVALID: ${source}=${value} must be sqlite (local file) or http (hosted /v1 authority); ` + "legacy values local and remote are accepted; " + "local SQLite fallback is disabled for invalid routing state");
     }
   }
-  if (canonical && fallback && modeRole(canonical) !== modeRole(fallback)) {
+  const canonicalTransport = canonical ? TRANSPORT_TOKENS[canonical] : null;
+  const fallbackTransport = fallback ? TRANSPORT_TOKENS[fallback] : null;
+  if (canonicalTransport && fallbackTransport && canonicalTransport !== fallbackTransport) {
     throw new Error(`REMOTE_STORAGE_MODE_CONFLICT: HASNA_TODOS_STORAGE_MODE=${canonical} conflicts with ` + `TODOS_STORAGE_MODE=${fallback}; local SQLite fallback is disabled`);
   }
-  const mode = canonical ?? fallback ?? "local";
+  const transport = canonicalTransport ?? fallbackTransport ?? "sqlite";
   return {
-    mode,
-    selected: CLOUD_MODES.has(mode),
+    mode: transport,
+    transport,
+    selected: transport === "http",
     source: canonical ? "HASNA_TODOS_STORAGE_MODE" : fallback ? "TODOS_STORAGE_MODE" : "default"
   };
 }
-function requestedStorageMode(env) {
-  return resolveTodosCliStorageMode(env).mode;
+function requestedTransport(env) {
+  return resolveTodosCliStorageMode(env).transport;
 }
 function normalizeRemoteAuthorityUrl(value) {
   const trimmed = value?.trim();
@@ -44736,7 +45120,7 @@ function getTodosRemoteAuthorityConfigStatus(env = process.env) {
     return {
       selected: false,
       ok: true,
-      mode: mode || "local",
+      mode,
       api_url_configured: false,
       api_key_configured: false,
       v1_base_url: null,
@@ -44848,8 +45232,7 @@ async function requiredRemoteRoute(client, route, request) {
   }
 }
 function getTodosCloudClient(env = process.env) {
-  const mode = requestedStorageMode(env);
-  if (!CLOUD_MODES.has(mode))
+  if (requestedTransport(env) !== "http")
     return null;
   const resolved = resolveStorageClient("todos", requireTodosRemoteAuthorityEnv(env), {
     fetchImpl: (input, init) => globalThis.fetch(input, { ...init, redirect: "manual" })
@@ -44884,13 +45267,38 @@ function toListQuery(filter = {}) {
     query["assigned_to"] = filter.assigned_to;
   if (filter.agent_id)
     query["agent_id"] = filter.agent_id;
+  if (filter.tags?.length)
+    query["tags"] = filter.tags.join(",");
   if (typeof filter.limit === "number")
     query["limit"] = filter.limit;
   if (typeof filter.offset === "number")
     query["offset"] = filter.offset;
   return query;
 }
+async function fetchListTagsCapability(client) {
+  const document = await requiredRemoteRoute(client, "/v1/openapi.json", () => client.transport.get("/openapi.json"));
+  if (!document || typeof document !== "object" || Array.isArray(document))
+    return false;
+  const paths = document["paths"];
+  const tasksPath = paths && typeof paths === "object" && !Array.isArray(paths) ? paths["/v1/tasks"] : undefined;
+  const get = tasksPath && typeof tasksPath === "object" && !Array.isArray(tasksPath) ? tasksPath["get"] : undefined;
+  const parameters = get && typeof get === "object" && !Array.isArray(get) ? get["parameters"] : undefined;
+  return Array.isArray(parameters) && parameters.some((parameter) => parameter && typeof parameter === "object" && parameter["name"] === "tags");
+}
+async function requireTagsFilterCapability(client) {
+  const authority = remoteAuthorityBase(client);
+  let capability = listTagsCapabilityCache.get(authority);
+  if (!capability) {
+    capability = fetchListTagsCapability(client);
+    listTagsCapabilityCache.set(authority, capability);
+  }
+  if (!await capability) {
+    throw new Error(`REMOTE_TAGS_FILTER_UNSUPPORTED: configured Todos authority ${authority} does not advertise the tags ` + "query param on GET /v1/tasks; deploy the current @hasna/todos /v1 server to filter by tag; " + "no unfiltered task read was issued");
+  }
+}
 async function cloudListTasks(client, filter = {}) {
+  if (filter.tags?.length)
+    await requireTagsFilterCapability(client);
   const res = await requiredRemoteRoute(client, "/v1/tasks", () => client.list("tasks", { query: toListQuery(filter) }));
   const envelope = res.raw;
   return Array.isArray(envelope?.tasks) ? envelope.tasks : res.items;
@@ -44998,6 +45406,8 @@ function redactComment3(comment) {
 }
 async function cloudCountTasks(client, filter = {}) {
   const { limit: _drop, offset: _o, ...rest } = filter;
+  if (rest.tags?.length)
+    await requireTagsFilterCapability(client);
   const res = await requiredRemoteRoute(client, "/v1/tasks", () => client.list("tasks", { query: { ...toListQuery(rest), limit: 1 } }));
   const envelope = res.raw;
   if (typeof envelope?.total === "number")
@@ -45060,14 +45470,23 @@ async function cloudResolveTaskListRef(client, ref, projectId) {
   }
   throw new Error(`Task list not found: "${input}"`);
 }
-var UUID_RE, CLOUD_MODES, VALID_STORAGE_MODES, completionCapabilityCache;
+var UUID_RE, TRANSPORT_TOKENS, completionCapabilityCache, listTagsCapabilityCache;
 var init_cloud_router = __esm(() => {
+  init_types();
   init_redaction();
   init_http_client();
   UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  CLOUD_MODES = new Set(["self_hosted", "cloud", "remote", "hybrid"]);
-  VALID_STORAGE_MODES = new Set(["local", ...CLOUD_MODES]);
+  TRANSPORT_TOKENS = {
+    sqlite: "sqlite",
+    http: "http",
+    local: "sqlite",
+    remote: "http",
+    self_hosted: "http",
+    cloud: "http",
+    hybrid: "http"
+  };
   completionCapabilityCache = new Map;
+  listTagsCapabilityCache = new Map;
 });
 
 // src/mcp/tools/task-crud.ts
@@ -48653,12 +49072,11 @@ ${task.description || ""}`.split(/\r?\n/);
 function normalizeStackLocation(value) {
   return value.replace(/:\d+(?::\d+)?/g, "").replace(/^file:\/\//, "").toLowerCase().trim();
 }
-function fingerprint(task) {
+function fingerprintContent(task) {
   const body = task.description || "";
   const text = `${task.title}
 ${body}`;
   return {
-    task,
     title: normalizeText(task.title),
     body: normalizeText(body),
     text: normalizeText(text),
@@ -48667,6 +49085,9 @@ ${body}`;
     stackKeys: stackKeysFor(task)
   };
 }
+function fingerprint(task) {
+  return { task, ...fingerprintContent(task) };
+}
 function intersects(left, right) {
   for (const value of left)
     if (right.has(value))
@@ -49875,7 +50296,7 @@ function tableColumns(db, table) {
 }
 function assertMigratedSchema(db) {
   const issues = [];
-  for (const table of REQUIRED_TABLES2) {
+  for (const table of REQUIRED_TABLES3) {
     if (!hasTable(db, table))
       issues.push(`missing table ${table}`);
   }
@@ -49983,7 +50404,7 @@ function createReleaseCompatibilityReport(options = {}) {
     migrations: {
       current_level: MIGRATIONS.length,
       simulated_levels: simulatedLevels,
-      checked_tables: REQUIRED_TABLES2,
+      checked_tables: REQUIRED_TABLES3,
       checked_columns: REQUIRED_COLUMNS
     },
     exports: {
@@ -50003,7 +50424,7 @@ function createReleaseCompatibilityReport(options = {}) {
         "todos --help",
         "todos-mcp --help",
         "todos-serve --help",
-        "todos doctor"
+        "todos doctor --no-fail-on-findings"
       ],
       smoke_tests: [
         "command -v todos",
@@ -50011,7 +50432,7 @@ function createReleaseCompatibilityReport(options = {}) {
         "command -v todos-serve",
         "todos --version",
         "todos --help",
-        "todos doctor"
+        "todos doctor --no-fail-on-findings"
       ],
       rollback: [
         "npm view @hasna/todos versions --json",
@@ -50060,14 +50481,14 @@ function renderReleaseCompatibilityMarkdown(report) {
   return lines.join(`
 `);
 }
-var LOCAL_RELEASE_COMPATIBILITY_SCHEMA_VERSION = 1, EXPECTED_PACKAGE_NAME = "@hasna/todos", EXPECTED_REPOSITORY = "https://github.com/hasna/todos.git", EXPECTED_BINS, EXPECTED_EXPORTS, REQUIRED_SCRIPTS, REQUIRED_TABLES2, REQUIRED_COLUMNS;
+var LOCAL_RELEASE_COMPATIBILITY_SCHEMA_VERSION = 1, EXPECTED_PACKAGE_NAME = "@hasna/todos", EXPECTED_REPOSITORY = "https://github.com/hasna/todos.git", EXPECTED_BINS, EXPECTED_EXPORTS, REQUIRED_SCRIPTS, REQUIRED_TABLES3, REQUIRED_COLUMNS;
 var init_release_compatibility = __esm(() => {
   init_migrations();
   init_schema();
   EXPECTED_BINS = ["todos", "todos-mcp", "todos-serve"];
   EXPECTED_EXPORTS = [".", "./sdk", "./mcp", "./registry", "./contracts", "./storage"];
   REQUIRED_SCRIPTS = ["build", "test:no-cloud", "verify:release", "prepublishOnly"];
-  REQUIRED_TABLES2 = [
+  REQUIRED_TABLES3 = [
     "_migrations",
     "projects",
     "tasks",
@@ -53826,7 +54247,7 @@ function limits(input) {
     verification_limit: clamp(input.verification_limit, DEFAULT_LIMITS.verification_limit, 100),
     run_limit: clamp(input.run_limit, DEFAULT_LIMITS.run_limit, 20),
     dependency_limit: clamp(input.dependency_limit, DEFAULT_LIMITS.dependency_limit, 100),
-    plan_task_limit: clamp(input.plan_task_limit, DEFAULT_LIMITS.plan_task_limit, 100),
+    plan_task_limit: clamp(input.plan_task_limit, DEFAULT_LIMITS.plan_task_limit, MAX_CONTEXT_TASKS),
     max_text_chars: clamp(input.max_text_chars, DEFAULT_LIMITS.max_text_chars, 50000),
     summary_char_limit: clamp(input.summary_char_limit, DEFAULT_LIMITS.summary_char_limit, 4000),
     stale_after_hours: clamp(input.stale_after_hours, DEFAULT_LIMITS.stale_after_hours, 24 * 365)
@@ -53849,6 +54270,13 @@ function taskSummary(task) {
     priority: task.priority
   };
 }
+function latestPlanTasks(planId, limit, db) {
+  const rows = db.query(`SELECT * FROM tasks
+     WHERE plan_id = ? AND archived_at IS NULL
+     ORDER BY updated_at DESC, created_at DESC, id ASC
+     LIMIT ?`).all(planId, limit);
+  return rows.map(rowToTask);
+}
 function acceptanceCriteria(task, maxText) {
   const metadata = task.metadata || {};
   const raw = metadata["acceptance_criteria"] ?? metadata["acceptanceCriteria"] ?? metadata["criteria"];
@@ -53946,7 +54374,7 @@ function summarizeSection(pack, section, maxChars) {
       return "No plan was attached.";
     return summarizeStrings([
       `Plan ${pack.plan.name} is ${pack.plan.status}`,
-      `${pack.plan.tasks.length} listed plan tasks`,
+      `${pack.plan.tasks.length} of ${pack.plan.total_tasks} plan tasks listed; ${pack.plan.omitted_tasks} omitted`,
       ...pack.plan.tasks.slice(0, 4).map((task) => `${task.status} ${task.short_id || task.id.slice(0, 8)} ${task.title}`)
     ], maxChars);
   }
@@ -54096,7 +54524,8 @@ function createAgentContextPack(input, db) {
   const limit = limits(input);
   const project = task.project_id ? getProject(task.project_id, d) : null;
   const plan = task.plan_id ? getPlan(task.plan_id, d) : null;
-  const planTasks = task.plan_id ? listTasks2({ plan_id: task.plan_id, limit: limit.plan_task_limit + 1 }, d) : [];
+  const planTasks = task.plan_id ? latestPlanTasks(task.plan_id, limit.plan_task_limit, d) : [];
+  const totalPlanTasks = task.plan_id ? countTasks({ plan_id: task.plan_id }, d) : 0;
   const upstream = getTaskDependencies(task.id, d).map((dep) => taskSummary(getTask(dep.depends_on, d))).filter((item) => Boolean(item));
   const downstream = getTaskDependents(task.id, d).map((dep) => taskSummary(getTask(dep.task_id, d))).filter((item) => Boolean(item));
   const comments = listComments(task.id, d);
@@ -54139,6 +54568,9 @@ function createAgentContextPack(input, db) {
     warnings.push(`${runs.length - selectedRuns.length} older runs omitted`);
   if (fileMap.size > relevantFiles.length)
     warnings.push(`${fileMap.size - relevantFiles.length} relevant files omitted`);
+  if (totalPlanTasks > planTasks.length && plan) {
+    warnings.push(`${totalPlanTasks - planTasks.length} plan tasks omitted (${totalPlanTasks} total); load more on demand with "todos plans --show ${plan.id}" and inspect task details with "todos show <task-id>" or "todos context-pack <task-id>"`);
+  }
   const contextTask = {
     id: task.id,
     short_id: task.short_id,
@@ -54170,8 +54602,9 @@ function createAgentContextPack(input, db) {
       description: truncate2(plan.description, limit.max_text_chars),
       status: plan.status,
       agent_id: plan.agent_id,
-      tasks: planTasks.slice(0, limit.plan_task_limit).map(taskSummary).filter((item) => Boolean(item)),
-      omitted_tasks: Math.max(0, planTasks.length - limit.plan_task_limit)
+      tasks: planTasks.map(taskSummary).filter((item) => Boolean(item)),
+      total_tasks: totalPlanTasks,
+      omitted_tasks: Math.max(0, totalPlanTasks - planTasks.length)
     } : null,
     acceptance_criteria: acceptanceCriteria(task, limit.max_text_chars),
     dependencies: {
@@ -54281,6 +54714,8 @@ ${pack.task.description}` : null,
     "## Project And Plan",
     pack.project ? `- Project: ${pack.project.name} (${pack.project.path})` : "- Project: none",
     pack.plan ? `- Plan: ${pack.plan.name} (${pack.plan.status})` : "- Plan: none",
+    pack.plan ? `- Plan tasks: ${pack.plan.tasks.length} shown of ${pack.plan.total_tasks} total (${pack.plan.omitted_tasks} omitted)` : null,
+    pack.plan && pack.plan.omitted_tasks > 0 ? `- Load more on demand: \`todos plans --show ${pack.plan.id}\`; inspect one task with \`todos show <task-id>\` or \`todos context-pack <task-id>\`.` : null,
     pack.plan && pack.plan.tasks.length > 0 ? bullet(pack.plan.tasks.map((task) => `${task.status} ${task.short_id || task.id.slice(0, 8)} ${task.title}`)) : null,
     "",
     "## Acceptance Criteria",
@@ -54361,7 +54796,7 @@ function renderAgentContextPack(pack, format, compact2 = false) {
     return compact2 ? renderAgentContextPackCompactMarkdown(pack) : renderAgentContextPackMarkdown(pack);
   return compact2 ? JSON.stringify(pack) : JSON.stringify(pack, null, 2);
 }
-var DEFAULT_LIMITS, ALL_CONTEXT_SECTIONS, BUDGET_TRIM_ORDER;
+var DEFAULT_LIMITS, MAX_CONTEXT_TASKS = 24, ALL_CONTEXT_SECTIONS, BUDGET_TRIM_ORDER;
 var init_context_packs = __esm(() => {
   init_comments();
   init_database();
@@ -54380,7 +54815,7 @@ var init_context_packs = __esm(() => {
     verification_limit: 10,
     run_limit: 3,
     dependency_limit: 12,
-    plan_task_limit: 20,
+    plan_task_limit: 24,
     max_text_chars: 6000,
     summary_char_limit: 480,
     stale_after_hours: 72
@@ -79203,7 +79638,7 @@ function parseObject2(value) {
 function normalizeKey(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9._:/-]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function normalizeFingerprint(value) {
+function normalizeTaskFindingFingerprint(value) {
   const normalized = normalizeKey(value);
   if (!normalized)
     throw new Error("finding fingerprint is required");
@@ -79312,7 +79747,7 @@ function assertTask(taskId, db) {
     throw new TaskNotFoundError(taskId);
 }
 function nextFinding(input, db) {
-  const fingerprint2 = normalizeFingerprint(input.fingerprint);
+  const fingerprint2 = normalizeTaskFindingFingerprint(input.fingerprint);
   const title = redactOptional(input.title, 300);
   if (!title)
     throw new Error("finding title is required");
@@ -79460,7 +79895,7 @@ function resolveMissingTaskFindings(input, db) {
   const timestamp4 = input.resolved_at || now();
   const status = normalizeResolutionStatus(input.status);
   const runId = resolveRunForTask(input.run_id, input.task_id, d);
-  const present = new Set(input.fingerprints.map(normalizeFingerprint));
+  const present = new Set(input.fingerprints.map(normalizeTaskFindingFingerprint));
   const warnings = [];
   const conditions = ["task_id = ?", "status = 'open'"];
   const params = [input.task_id];
@@ -91205,6 +91640,15 @@ function formatError2(error3) {
   if (error3 instanceof TaskNotFoundError) {
     return JSON.stringify({ code: TaskNotFoundError.code, message: error3.message, suggestion: TaskNotFoundError.suggestion });
   }
+  if (error3 instanceof TaskReferenceAmbiguousError) {
+    return JSON.stringify({
+      code: TaskReferenceAmbiguousError.code,
+      message: error3.message,
+      candidate_project_ids: error3.candidateProjectIds,
+      candidate_task_ids: error3.candidateTaskIds,
+      suggestion: "Use a full task UUID."
+    });
+  }
   if (error3 instanceof ProjectNotFoundError) {
     return JSON.stringify({ code: ProjectNotFoundError.code, message: error3.message, suggestion: ProjectNotFoundError.suggestion });
   }
@@ -91977,7 +92421,7 @@ Dashboard not found at: ${dashboardDir}`);
       const path = url.pathname;
       const method = req.method;
       const reqOrigin = req.headers.get("origin") || undefined;
-      const corsHeaders = reqOrigin && (reqOrigin === `http://localhost:${port}` || reqOrigin === "http://localhost:0") ? {
+      const corsHeaders = reqOrigin && reqOrigin === `http://localhost:${ctx.port}` ? {
         "Access-Control-Allow-Origin": reqOrigin,
         "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
         "Access-Control-Allow-Headers": "Content-Type, X-API-Key, Authorization",
@@ -92002,23 +92446,24 @@ Dashboard not found at: ${dashboardDir}`);
       }
       if ((path === "/health" || path === "/ready" || path === "/version") && method === "GET") {
         const { getPackageVersion: getPackageVersion2 } = await Promise.resolve().then(() => (init_package_version(), exports_package_version));
-        const { isCloudModeEnabled: isCloudModeEnabled2, pingCloud: pingCloud2 } = await Promise.resolve().then(() => (init_cloud(), exports_cloud));
-        const mode = isCloudModeEnabled2() ? "remote" : "local";
+        const { isPostgresBackendConfigured: isPostgresBackendConfigured2, pingCloud: pingCloud2 } = await Promise.resolve().then(() => (init_cloud(), exports_cloud));
+        const backend = isPostgresBackendConfigured2() ? "postgresql" : "sqlite";
+        const mode = backend === "postgresql" ? "remote" : "local";
         const version2 = getPackageVersion2();
         if (path === "/version") {
-          return Response.json({ status: "ok", version: version2, mode, name: "todos" });
+          return Response.json({ status: "ok", version: version2, mode, backend, name: "todos" });
         }
         if (path === "/ready") {
-          if (mode === "remote") {
+          if (backend === "postgresql") {
             try {
               await pingCloud2();
             } catch (e) {
-              return Response.json({ status: "unavailable", version: version2, mode, error: e.message }, { status: 503 });
+              return Response.json({ status: "unavailable", version: version2, mode, backend, error: e.message }, { status: 503 });
             }
           }
-          return Response.json({ status: "ready", version: version2, mode });
+          return Response.json({ status: "ready", version: version2, mode, backend });
         }
-        return Response.json({ status: "ok", version: version2, mode, name: "todos" });
+        return Response.json({ status: "ok", version: version2, mode, backend, name: "todos" });
       }
       if ((path === "/openapi.json" || path === "/v1/openapi.json") && method === "GET") {
         const { buildV1OpenApiDocument: buildV1OpenApiDocument2 } = await Promise.resolve().then(() => (init_openapi(), exports_openapi));
@@ -92265,7 +92710,9 @@ Dashboard not found at: ${dashboardDir}`);
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  const serverUrl = `http://localhost:${port}`;
+  const boundPort = server.port ?? port;
+  ctx.port = boundPort;
+  const serverUrl = `http://localhost:${boundPort}`;
   console.log(`Todos Dashboard running at ${serverUrl}`);
   if (shouldOpen) {
     try {
@@ -92306,7 +92753,39 @@ var init_serve = __esm(() => {
 
 // src/server/index.ts
 init_package_version();
+
+// src/server/port.ts
 var DEFAULT_PORT = 19427;
+function coercePort(raw) {
+  if (raw === undefined)
+    return;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed))
+    return;
+  if (trimmed.length > 1 && trimmed.startsWith("0"))
+    return;
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed > 65535)
+    return;
+  return parsed;
+}
+function refuseInvalidPort(source, raw) {
+  console.error(`Invalid ${source}: ${JSON.stringify(raw)} is not a port.
+` + `Use an integer from 0 to 65535, where 0 asks the kernel for a free port.`);
+  process.exit(1);
+}
+async function findFreePort(start) {
+  for (let port = start;port < start + 100; port++) {
+    try {
+      const server = Bun.serve({ port, fetch: () => new Response("") });
+      server.stop(true);
+      return port;
+    } catch {}
+  }
+  return start;
+}
+
+// src/server/index.ts
 function hasVersionFlag2() {
   return process.argv.includes("--version") || process.argv.includes("-V");
 }
@@ -92341,11 +92820,8 @@ Environment:
 function parsePort() {
   const portArg = process.argv.find((a) => a === "--port" || a.startsWith("--port="));
   if (portArg) {
-    if (portArg.includes("=")) {
-      return parseInt(portArg.split("=")[1], 10) || DEFAULT_PORT;
-    }
-    const idx = process.argv.indexOf(portArg);
-    return parseInt(process.argv[idx + 1], 10) || DEFAULT_PORT;
+    const raw = portArg.includes("=") ? portArg.split("=")[1] : process.argv[process.argv.indexOf(portArg) + 1];
+    return coercePort(raw) ?? refuseInvalidPort("--port", raw ?? "");
   }
   return DEFAULT_PORT;
 }
@@ -92358,16 +92834,6 @@ function parseStringArg(name) {
   const idx = process.argv.indexOf(arg);
   return process.argv[idx + 1] || undefined;
 }
-async function findFreePort(start) {
-  for (let port = start;port < start + 100; port++) {
-    try {
-      const server = Bun.serve({ port, fetch: () => new Response("") });
-      server.stop(true);
-      return port;
-    } catch {}
-  }
-  return start;
-}
 async function runMigrate() {
   const {
     ensureCloudSchema: ensureCloudSchema2,
@@ -92463,9 +92929,10 @@ async function main2() {
     return;
   }
   const explicitPortArg = process.argv.some((a) => a === "--port" || a.startsWith("--port="));
-  const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+  const rawEnvPort = process.env.PORT?.trim();
+  const envPort = rawEnvPort ? coercePort(rawEnvPort) ?? refuseInvalidPort("PORT", rawEnvPort) : undefined;
   const requestedPort = explicitPortArg ? parsePort() : envPort ?? parsePort();
-  const port = envPort || explicitPortArg ? requestedPort : await findFreePort(requestedPort);
+  const port = envPort !== undefined || explicitPortArg ? requestedPort : await findFreePort(requestedPort);
   if (port !== requestedPort) {
     console.log(`Port ${requestedPort} in use, using ${port}`);
   }