@hasna/todos 0.15.11 → 0.15.13

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.15.11",
+    version: "0.15.13",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -3025,7 +3025,6 @@ function responseTasks(value, expectedPlanId) {
       "reason",
       "spawned_from_session",
       "assigned_by",
-      "created_by",
       "assigned_from_project",
       "task_type",
       "delegated_from",
@@ -3034,6 +3033,9 @@ function responseTasks(value, expectedPlanId) {
     ]) {
       responseNullableString(task[field], `${label}.${field}`);
     }
+    responseOptionalNullableString(task, "created_by", label);
+    if (!("created_by" in task))
+      task["created_by"] = null;
     responseStringArray(task.tags, `${label}.tags`);
     responseRecord(task.metadata, `${label}.metadata`);
     for (const field of [
@@ -5776,6 +5778,12 @@ function toListQuery(filter = {}) {
     query["offset"] = filter.offset;
   return query;
 }
+function priorityRank(priority) {
+  return PRIORITY_RANK[priority ?? ""] ?? 4;
+}
+function compareCloudTaskOrder(a, b) {
+  return priorityRank(a.priority) - priorityRank(b.priority) || b.created_at.localeCompare(a.created_at) || a.id.localeCompare(b.id);
+}
 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))
@@ -5797,13 +5805,42 @@ async function requireTagsFilterCapability(client) {
     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);
+async function requestCloudTaskPage(client, filter) {
   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;
 }
+async function cloudListTasks(client, filter = {}) {
+  if (filter.tags?.length)
+    await requireTagsFilterCapability(client);
+  const statuses = Array.isArray(filter.status) ? filter.status : undefined;
+  if (!statuses)
+    return requestCloudTaskPage(client, filter);
+  if (statuses.length === 0) {
+    const { status: _status2, ...unfiltered } = filter;
+    return requestCloudTaskPage(client, unfiltered);
+  }
+  if (statuses.length === 1) {
+    return requestCloudTaskPage(client, { ...filter, status: statuses[0] });
+  }
+  const { status: _status, limit, offset, ...baseFilter } = filter;
+  const start = offset ?? 0;
+  const windowEnd = typeof limit === "number" ? start + limit : undefined;
+  const pages = await Promise.all(statuses.map((status) => requestCloudTaskPage(client, {
+    ...baseFilter,
+    status,
+    ...windowEnd === undefined ? {} : { limit: windowEnd }
+  })));
+  const seen = new Set;
+  const union = pages.flat().filter((task) => {
+    if (seen.has(task.id))
+      return false;
+    seen.add(task.id);
+    return true;
+  });
+  union.sort(compareCloudTaskOrder);
+  return union.slice(start, windowEnd);
+}
 async function cloudResolveTaskRef(client, ref) {
   const input = ref.trim().toLowerCase();
   if (!input)
@@ -5832,7 +5869,18 @@ async function cloudGetTask(client, id) {
   return raw == null ? null : unwrapTask(raw);
 }
 async function cloudCreateTask(client, input) {
-  return unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => client.create("tasks", input)));
+  const expectedParentId = typeof input["parent_id"] === "string" ? input["parent_id"] : null;
+  const created = unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => expectedParentId === null ? client.create("tasks", input) : client.create("tasks", input, { retry: false }), ["PARENT_TASK_NOT_FOUND"]));
+  if (!created || typeof created.id !== "string" || !created.id.trim()) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: configured Todos authority ${remoteAuthorityBase(client)} returned a task create ` + "response without a stored task id; no success row or local SQLite fallback is permitted");
+  }
+  if (expectedParentId === null)
+    return created;
+  const persisted = await cloudGetTask(client, created.id);
+  if (!persisted || persisted.id !== created.id || (persisted.parent_id ?? null) !== expectedParentId) {
+    throw new Error(`TASK_CREATE_PERSISTENCE_UNVERIFIED: configured Todos authority ${remoteAuthorityBase(client)} accepted ` + `POST /v1/tasks but authoritative GET /v1/tasks/${encodeURIComponent(created.id)} did not return the same ` + "stored task id and parent_id; no success row or local SQLite fallback is permitted");
+  }
+  return persisted;
 }
 async function cloudUpdateTask(client, id, patch) {
   return unwrapTask(await client.update("tasks", id, patch));
@@ -6341,17 +6389,105 @@ async function cloudFindCommit(client, sha) {
   const env = raw ?? {};
   return env.commit ?? null;
 }
+function parseCloudTaskGitRef(value, route) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned a non-object git ref; local SQLite fallback is disabled`);
+  }
+  const ref = value;
+  const requiredStrings = ["id", "task_id", "name", "created_at", "updated_at"];
+  if (requiredStrings.some((field) => typeof ref[field] !== "string" || !ref[field].trim())) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an incomplete git ref identity; local SQLite fallback is disabled`);
+  }
+  if (ref["ref_type"] !== "branch" && ref["ref_type"] !== "pull_request") {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid git ref type; local SQLite fallback is disabled`);
+  }
+  for (const field of ["url", "provider"]) {
+    if (ref[field] !== null && typeof ref[field] !== "string") {
+      throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid git ref ${field}; local SQLite fallback is disabled`);
+    }
+  }
+  if (!ref["metadata"] || typeof ref["metadata"] !== "object" || Array.isArray(ref["metadata"])) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned invalid git ref metadata; local SQLite fallback is disabled`);
+  }
+  return ref;
+}
+function parseCloudTaskGitRefEnvelope(raw, route) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned a non-object git ref envelope; local SQLite fallback is disabled`);
+  }
+  const envelope = raw;
+  if (!Array.isArray(envelope["refs"]) || !Number.isSafeInteger(envelope["count"]) || envelope["count"] !== envelope["refs"].length) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an incomplete git ref envelope; local SQLite fallback is disabled`);
+  }
+  return envelope["refs"].map((ref) => parseCloudTaskGitRef(ref, route));
+}
+function openApiHasOperation(document, path, method) {
+  if (!document || typeof document !== "object" || Array.isArray(document))
+    return false;
+  const paths = document["paths"];
+  if (!paths || typeof paths !== "object" || Array.isArray(paths))
+    return false;
+  const route = paths[path];
+  return Boolean(route && typeof route === "object" && !Array.isArray(route) && route[method] && typeof route[method] === "object");
+}
+async function fetchGitRefCapabilities(client) {
+  const document = await requiredRemoteRoute(client, "/v1/openapi.json", () => client.transport.get("/openapi.json"));
+  const supported = new Set;
+  if (openApiHasOperation(document, "/v1/tasks/{id}/refs", "get"))
+    supported.add("task-read");
+  if (openApiHasOperation(document, "/v1/tasks/{id}/refs", "post"))
+    supported.add("task-write");
+  if (openApiHasOperation(document, "/v1/refs/{ref}", "get"))
+    supported.add("reverse-read");
+  return supported;
+}
+async function requireGitRefCapabilities(client, required) {
+  const authority = remoteAuthorityBase(client);
+  let capabilities = gitRefCapabilityCache.get(authority);
+  if (!capabilities) {
+    capabilities = fetchGitRefCapabilities(client);
+    gitRefCapabilityCache.set(authority, capabilities);
+  }
+  const supported = await capabilities;
+  const missing = required.filter((capability) => !supported.has(capability));
+  if (missing.length > 0) {
+    throw new Error(`REMOTE_GIT_REF_UNSUPPORTED: configured Todos authority ${authority} does not advertise the complete git-ref ` + `contract (${missing.join(", ")} missing); deploy the current @hasna/todos /v1 server before retrying; ` + "no ref mutation or local SQLite fallback was attempted");
+  }
+}
+function sameCloudTaskGitRef(ref, expected) {
+  return ref.id === expected.id && ref.task_id === expected.task_id && ref.ref_type === expected.ref_type && ref.name === expected.name;
+}
+async function cloudListTaskRefs(client, taskId) {
+  await requireGitRefCapabilities(client, ["task-read"]);
+  const route = `/v1/tasks/${encodeURIComponent(taskId)}/refs`;
+  const raw = await requiredRemoteRoute(client, route, () => client.transport.get(`/tasks/${encodeURIComponent(taskId)}/refs`));
+  return parseCloudTaskGitRefEnvelope(raw, route);
+}
 async function cloudLinkRef(client, taskId, input) {
-  const raw = await client.transport.post(`/tasks/${encodeURIComponent(taskId)}/refs`, input);
-  if (raw && typeof raw === "object" && "ref" in raw) {
-    return raw.ref;
+  await requireGitRefCapabilities(client, ["task-read", "task-write", "reverse-read"]);
+  const route = `/v1/tasks/${encodeURIComponent(taskId)}/refs`;
+  const raw = await requiredRemoteRoute(client, route, () => client.transport.post(`/tasks/${encodeURIComponent(taskId)}/refs`, input));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length !== 1 || !("ref" in raw)) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned a non-authoritative git ref response envelope; ` + "local SQLite fallback is disabled");
+  }
+  const linked = parseCloudTaskGitRef(raw.ref, route);
+  if (linked.task_id !== taskId || linked.ref_type !== input.ref_type || linked.name !== input.name) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned a different git ref identity; local SQLite fallback is disabled`);
+  }
+  const [taskRefs, reverseRefs] = await Promise.all([
+    cloudListTaskRefs(client, taskId),
+    cloudFindRefs(client, input.name)
+  ]);
+  if (!taskRefs.some((ref) => sameCloudTaskGitRef(ref, linked)) || !reverseRefs.some((ref) => sameCloudTaskGitRef(ref, linked))) {
+    throw new Error(`REMOTE_REF_PERSISTENCE_UNVERIFIED: configured Todos authority ${remoteAuthorityBase(client)} accepted ${route} ` + "but authoritative task and reverse readback did not return the linked ref; no success line or local SQLite " + "fallback is permitted");
   }
-  return raw;
+  return linked;
 }
 async function cloudFindRefs(client, ref) {
-  const raw = await client.transport.get(`/refs/${encodeURIComponent(ref)}`);
-  const env = raw ?? {};
-  return Array.isArray(env.refs) ? env.refs : [];
+  await requireGitRefCapabilities(client, ["reverse-read"]);
+  const route = `/v1/refs/${encodeURIComponent(ref)}`;
+  const raw = await requiredRemoteRoute(client, route, () => client.transport.get(`/refs/${encodeURIComponent(ref)}`));
+  return parseCloudTaskGitRefEnvelope(raw, route);
 }
 async function cloudResolvePlan(client, ref, projectId) {
   const normalizedRef = ref.toLowerCase();
@@ -6509,9 +6645,6 @@ async function cloudRecordVerification(client, id, input) {
   }
   return raw;
 }
-function priorityRank(priority) {
-  return PRIORITY_RANK[priority ?? ""] ?? 4;
-}
 async function cloudActiveTasks(client, filter = {}) {
   const [pending, inProgress] = await Promise.all([
     cloudListTasks(client, { ...filter, status: "pending" }),
@@ -6825,7 +6958,7 @@ async function cloudTimeline(client, options = {}) {
   const limit = options.limit ?? 50;
   return { entries: entries.slice(offset, offset + limit), total, limit, offset };
 }
-var UUID_RE, TRANSPORT_TOKENS, COMPLETION_EVIDENCE_FIELDS, completionCapabilityCache, SERVER_MODE_CANDIDATES, cachedServerMode = null, listTagsCapabilityCache, RELATION_HYDRATION_CONCURRENCY = 6, PRIORITY_RANK;
+var UUID_RE, TRANSPORT_TOKENS, COMPLETION_EVIDENCE_FIELDS, completionCapabilityCache, gitRefCapabilityCache, SERVER_MODE_CANDIDATES, cachedServerMode = null, PRIORITY_RANK, listTagsCapabilityCache, RELATION_HYDRATION_CONCURRENCY = 6;
 var init_cloud_router = __esm(() => {
   init_types();
   init_redaction();
@@ -6850,9 +6983,10 @@ var init_cloud_router = __esm(() => {
     "confidence"
   ];
   completionCapabilityCache = new Map;
+  gitRefCapabilityCache = new Map;
   SERVER_MODE_CANDIDATES = ["postgres", "cloud", "self_hosted"];
-  listTagsCapabilityCache = new Map;
   PRIORITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+  listTagsCapabilityCache = new Map;
 });
 
 // src/cli/stage-a.ts
@@ -12391,13 +12525,19 @@ function jsonModeRequested(argv = process.argv) {
   return argv.some((arg) => arg === "--json" || /^-[a-z]+$/i.test(arg) && arg.includes("j"));
 }
 function remoteErrorDetail(e) {
-  if (!e || typeof e !== "object")
-    return null;
-  const body = e.body;
-  if (!body || typeof body !== "object" || Array.isArray(body))
-    return null;
-  const detail = body.error;
-  return typeof detail === "string" && detail.trim() ? detail.trim() : null;
+  const seen = new Set;
+  let current = e;
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const body = current.body;
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      const detail = body.error;
+      if (typeof detail === "string" && detail.trim())
+        return detail.trim();
+    }
+    current = current.cause;
+  }
+  return null;
 }
 function handleError(e) {
   const baseMessage = e instanceof Error ? e.message : String(e);
@@ -21387,6 +21527,14 @@ async function cloudDetailRelations(cloud, id) {
     return { dependencies: [], blocked_by: [], blocks: [] };
   }
 }
+async function cloudDetailGitRefs(cloud, id) {
+  try {
+    return await cloudListTaskRefs(cloud, id);
+  } catch (e) {
+    console.error(chalk3.dim(`Warning: could not verify task git refs: ${e instanceof Error ? e.message : String(e)}`));
+    return null;
+  }
+}
 function resolveProjectIdOrSlug(input) {
   const db = getDatabase();
   if (isPathLike(input)) {
@@ -21959,7 +22107,8 @@ function registerTaskCommands(program2) {
     }
     const creatorFilterActive = Boolean(filter["created_by"] || filter["not_created_by"]);
     const requestedLimit = filter["limit"];
-    const reordersAfterQuery = Boolean(opts.sort);
+    const combinesScalarStatusPages = Boolean(cloud && Array.isArray(filter["status"]) && filter["status"].length > 1);
+    const reordersAfterQuery = Boolean(opts.sort) || combinesScalarStatusPages;
     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;
@@ -22110,8 +22259,11 @@ function registerTaskCommands(program2) {
     let task2;
     if (cloud) {
       const remote = await cloudGetTask(cloud, await resolveTaskIdForCommand(id, cloud));
-      const commentPage = remote ? await cloudListComments(cloud, remote.id, page.request) : null;
-      const relations = remote ? await cloudDetailRelations(cloud, remote.id) : null;
+      const [commentPage, relations, gitRefs] = remote ? await Promise.all([
+        cloudListComments(cloud, remote.id, page.request),
+        cloudDetailRelations(cloud, remote.id),
+        cloudDetailGitRefs(cloud, remote.id)
+      ]) : [null, null, null];
       task2 = remote ? {
         subtasks: [],
         ...remote,
@@ -22119,6 +22271,7 @@ function registerTaskCommands(program2) {
         dependencies: relations.dependencies,
         blocked_by: relations.blocked_by,
         blocks: relations.blocks,
+        git_refs: gitRefs,
         comments: commentPage.comments,
         comments_page: {
           count: commentPage.count,
@@ -22131,6 +22284,8 @@ function registerTaskCommands(program2) {
     } else {
       const resolvedId = resolveTaskId(id);
       task2 = applyLocalCommentPage(getTaskWithRelations(resolvedId), page);
+      const { getTaskGitRefs: getTaskGitRefs2 } = await Promise.resolve().then(() => (init_task_commits(), exports_task_commits));
+      task2.git_refs = getTaskGitRefs2(resolvedId);
     }
     if (!task2) {
       handleError(new Error(`Task not found: ${id}`));
@@ -22243,8 +22398,11 @@ function registerTaskCommands(program2) {
     let task2;
     if (cloud) {
       const remote = await cloudGetTask(cloud, resolvedId);
-      const commentPage = remote ? await cloudListComments(cloud, remote.id, page.request) : null;
-      const relations = remote ? await cloudDetailRelations(cloud, remote.id) : null;
+      const [commentPage, relations, gitRefs] = remote ? await Promise.all([
+        cloudListComments(cloud, remote.id, page.request),
+        cloudDetailRelations(cloud, remote.id),
+        cloudDetailGitRefs(cloud, remote.id)
+      ]) : [null, null, null];
       task2 = remote ? {
         subtasks: [],
         checklist: [],
@@ -22253,6 +22411,7 @@ function registerTaskCommands(program2) {
         dependencies: relations.dependencies,
         blocked_by: relations.blocked_by,
         blocks: relations.blocks,
+        git_refs: gitRefs,
         comments: commentPage.comments,
         comments_page: {
           count: commentPage.count,
@@ -22270,7 +22429,7 @@ function registerTaskCommands(program2) {
     }
     if (globalOpts.json && !cloud) {
       const { listTaskFiles: listTaskFiles2 } = await Promise.resolve().then(() => (init_task_files(), exports_task_files));
-      const { getTaskCommits: getTaskCommits2 } = await Promise.resolve().then(() => (init_task_commits(), exports_task_commits));
+      const { getTaskCommits: getTaskCommits2, getTaskGitRefs: getTaskGitRefs2 } = await Promise.resolve().then(() => (init_task_commits(), exports_task_commits));
       try {
         task2.files = listTaskFiles2(task2.id);
       } catch (e) {
@@ -22281,6 +22440,11 @@ function registerTaskCommands(program2) {
       } catch (e) {
         console.error(chalk3.dim(`Warning: could not load task commits: ${e instanceof Error ? e.message : String(e)}`));
       }
+      try {
+        task2.git_refs = getTaskGitRefs2(task2.id);
+      } catch (e) {
+        console.error(chalk3.dim(`Warning: could not load task git refs: ${e instanceof Error ? e.message : String(e)}`));
+      }
       output(task2, true);
       return;
     }
@@ -28987,7 +29151,10 @@ function isResolvedTask(task) {
   return !(metadata && metadata["unresolved"] === true);
 }
 async function buildCloudProjectDependencyGraph(cloud, projectId) {
-  const tasks = await cloudListTasks(cloud, projectId ? { project_id: projectId } : {});
+  const tasks = await cloudListTasks(cloud, {
+    ...projectId ? { project_id: projectId } : {},
+    include_subtasks: true
+  });
   const edges = [];
   const seen = new Set;
   let cursor = 0;
@@ -29366,8 +29533,8 @@ function registerProjectCommands(program2) {
     const globalOpts = program2.opts();
     const cloud = getTodosCloudClient();
     if (!id) {
-      if (opts.needs || opts.remove || opts.graph || opts.direction !== "both") {
-        handleError(new Error("A task id is required with --needs, --remove, --graph, or --direction."));
+      if (opts.needs || opts.remove || opts.direction !== "both") {
+        handleError(new Error("A task id is required with --needs, --remove, or --direction."));
       }
       const projectRef = opts.project ?? globalOpts.project;
       if (cloud) {
@@ -34438,6 +34605,7 @@ class PostgresJsonRecordStore {
       const current = await this.get(type, value.id);
       if (current)
         return current;
+      throw new Error(`POSTGRES_WRITE_PERSISTENCE_UNVERIFIED: ${type} ${value.id} was not accepted and no persisted readback exists`);
     }
     return value;
   }
@@ -35209,6 +35377,9 @@ class PostgresJsonRecordStore {
 }
 async function createTask2(input, store, context) {
   const timestamp2 = new Date().toISOString();
+  if (input.parent_id && !await store.get("tasks", input.parent_id)) {
+    throw new TaskNotFoundError(input.parent_id);
+  }
   const linkedPlan = input.plan_id ? await store.get("plans", input.plan_id) : null;
   const requestedProjectId = input.project_id ?? context?.projectId ?? null;
   if (linkedPlan?.project_id && requestedProjectId && requestedProjectId !== linkedPlan.project_id) {
@@ -40717,6 +40888,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
         ProjectTaskListEnsureResult: projectTaskListEnsureResultSchema,
         ProjectTaskListRollbackResult: projectTaskListRollbackResultSchema,
         TaskComment: taskCommentSchema,
+        TaskGitRef: taskGitRefSchema,
         Plan: planSchema,
         PlanProjectLinkReceipt: planProjectLinkReceiptSchema,
         PlanProjectLinkResult: planProjectLinkResultSchema,
@@ -40734,6 +40906,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
             status: { type: "string" },
             priority: { type: "string" },
             project_id: { type: "string" },
+            parent_id: { type: "string" },
             plan_id: { type: "string" },
             assigned_to: { type: "string" },
             agent_id: { type: "string" },
@@ -41878,6 +42051,92 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           }
         }
       },
+      "/v1/tasks/{id}/refs": {
+        get: {
+          operationId: "listTaskGitRefs",
+          summary: "List git branch and pull-request refs linked to a task",
+          parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["refs", "count"],
+                    properties: {
+                      refs: { type: "array", items: { $ref: "#/components/schemas/TaskGitRef" } },
+                      count: { type: "integer", minimum: 0 }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        post: {
+          operationId: "linkTaskGitRef",
+          summary: "Link a git branch or pull-request ref to a task",
+          parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  additionalProperties: false,
+                  required: ["ref_type", "name"],
+                  properties: {
+                    ref_type: { type: "string", enum: ["branch", "pull_request"] },
+                    name: { type: "string", minLength: 1 },
+                    url: { type: "string" },
+                    provider: { type: "string" },
+                    metadata: { type: "object", additionalProperties: true }
+                  }
+                }
+              }
+            }
+          },
+          responses: {
+            "201": {
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["ref"],
+                    properties: { ref: { $ref: "#/components/schemas/TaskGitRef" } }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/refs/{ref}": {
+        get: {
+          operationId: "findTaskGitRefs",
+          summary: "Find task links by git branch or pull-request ref",
+          parameters: [{ name: "ref", in: "path", required: true, schema: { type: "string" } }],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["refs", "count"],
+                    properties: {
+                      refs: { type: "array", items: { $ref: "#/components/schemas/TaskGitRef" } },
+                      count: { type: "integer", minimum: 0 }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
       "/v1/tasks/{id}/start": {
         post: {
           operationId: "startTask",
@@ -42329,7 +42588,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
     }
   };
 }
-var taskSchema, projectSchema, taskListSchema, projectTaskListEnsureReceiptSchema, projectTaskListEnsureResultSchema, projectTaskListRollbackResultSchema, taskCommentSchema, planSchema, planProjectLinkReceiptSchema, planProjectLinkResultSchema, planProjectLinkRollbackResultSchema, templateTaskSchema, templateSchema, templateVariableSchema, createTemplateTaskInputSchema;
+var taskSchema, projectSchema, taskListSchema, projectTaskListEnsureReceiptSchema, projectTaskListEnsureResultSchema, projectTaskListRollbackResultSchema, taskCommentSchema, taskGitRefSchema, planSchema, planProjectLinkReceiptSchema, planProjectLinkResultSchema, planProjectLinkRollbackResultSchema, templateTaskSchema, templateSchema, templateVariableSchema, createTemplateTaskInputSchema;
 var init_openapi = __esm(() => {
   init_package_version();
   init_types();
@@ -42342,6 +42601,7 @@ var init_openapi = __esm(() => {
       status: { type: "string" },
       priority: { type: "string" },
       project_id: { type: "string", nullable: true },
+      parent_id: { type: "string", nullable: true },
       assigned_to: { type: "string", nullable: true },
       agent_id: { type: "string", nullable: true },
       tags: { type: "array", items: { type: "string" } },
@@ -42465,6 +42725,32 @@ var init_openapi = __esm(() => {
       created_at: { type: "string", format: "date-time" }
     }
   };
+  taskGitRefSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "id",
+      "task_id",
+      "ref_type",
+      "name",
+      "url",
+      "provider",
+      "metadata",
+      "created_at",
+      "updated_at"
+    ],
+    properties: {
+      id: { type: "string", minLength: 1 },
+      task_id: { type: "string", minLength: 1 },
+      ref_type: { type: "string", enum: ["branch", "pull_request"] },
+      name: { type: "string", minLength: 1 },
+      url: { type: "string", nullable: true },
+      provider: { type: "string", nullable: true },
+      metadata: { type: "object", additionalProperties: true },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  };
   planSchema = {
     type: "object",
     required: ["id", "slug", "name", "status", "created_at", "updated_at"],
@@ -43210,8 +43496,25 @@ async function handleV1Request(req, url, dependencies = {}) {
           if (!body || typeof body.title !== "string" || !body.title.trim()) {
             return error(400, "title is required");
           }
-          const task = await store.tasks.create(body, contextFromPrincipal(principal, body));
-          return json4({ task }, 201);
+          const storageContext = contextFromPrincipal(principal, body);
+          if (body.parent_id !== undefined) {
+            if (typeof body.parent_id !== "string" || !body.parent_id.trim()) {
+              return error(400, "parent_id must be a non-empty task id", {
+                code: "PARENT_TASK_ID_INVALID"
+              });
+            }
+            if (!await store.tasks.get(body.parent_id, storageContext)) {
+              return error(404, `parent task not found: ${body.parent_id}`, {
+                code: "PARENT_TASK_NOT_FOUND"
+              });
+            }
+          }
+          const created = await store.tasks.create(body, storageContext);
+          const persisted = created?.id ? await store.tasks.get(created.id, storageContext) : null;
+          if (!persisted || persisted.id !== created.id || (persisted.parent_id ?? null) !== (body.parent_id ?? null)) {
+            return error(500, "TASK_CREATE_PERSISTENCE_UNVERIFIED: task create was acknowledged but authoritative readback did not return the same stored task id and parent_id", { code: "TASK_CREATE_PERSISTENCE_UNVERIFIED" });
+          }
+          return json4({ task: persisted }, 201);
         }
         return error(405, `method ${method} not allowed on /v1/tasks`);
       }
@@ -43985,6 +44288,9 @@ async function handleV1Request(req, url, dependencies = {}) {
         candidate_task_ids: e.candidateTaskIds
       });
     }
+    if (e instanceof TaskNotFoundError) {
+      return error(404, e.message, { code: TaskNotFoundError.code });
+    }
     if (e instanceof LockError)
       return error(409, e.message, { code: LockError.code });
     if (e instanceof TaskNotStartableError) {

package/dist/contracts.js

@@ -12379,7 +12379,7 @@ var init_tasks = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/todos",
-  version: "0.15.11",
+  version: "0.15.13",
   description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   type: "module",
   main: "dist/index.js",

package/dist/index.js

@@ -12492,7 +12492,7 @@ var init_dispatches = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/todos",
-  version: "0.15.11",
+  version: "0.15.13",
   description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   type: "module",
   main: "dist/index.js",
@@ -26973,6 +26973,7 @@ class PostgresJsonRecordStore {
       const current = await this.get(type, value.id);
       if (current)
         return current;
+      throw new Error(`POSTGRES_WRITE_PERSISTENCE_UNVERIFIED: ${type} ${value.id} was not accepted and no persisted readback exists`);
     }
     return value;
   }
@@ -27744,6 +27745,9 @@ class PostgresJsonRecordStore {
 }
 async function createTask2(input, store, context) {
   const timestamp3 = new Date().toISOString();
+  if (input.parent_id && !await store.get("tasks", input.parent_id)) {
+    throw new TaskNotFoundError(input.parent_id);
+  }
   const linkedPlan = input.plan_id ? await store.get("plans", input.plan_id) : null;
   const requestedProjectId = input.project_id ?? context?.projectId ?? null;
   if (linkedPlan?.project_id && requestedProjectId && requestedProjectId !== linkedPlan.project_id) {

package/dist/lib/plan-project-link-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-project-link-contract.d.ts","sourceRoot":"","sources":["../../src/lib/plan-project-link-contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,IAAI,EACJ,sBAAsB,EACtB,qBAAqB,EACrB,6BAA6B,EAC7B,IAAI,EACL,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,gCAAgC,EAAG,4BAAqC,CAAC;AAEtF,MAAM,MAAM,wBAAwB,GAChC,kCAAkC,GAClC,qCAAqC,GACrC,0CAA0C,GAC1C,6CAA6C,GAC7C,mCAAmC,GACnC,2CAA2C,GAC3C,wCAAwC,GACxC,qCAAqC,GACrC,gCAAgC,GAChC,qCAAqC,GACrC,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAEvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFhC,IAAI,EAAE,wBAAwB,EACvC,OAAO,EAAE,MAAM,EACN,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAKjD;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQnE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE5D;AAED,wBAAgB,sCAAsC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CASxF;AAED,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAQxG;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAsBnF;AAED,KAAK,kCAAkC,GAAG;IACxC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,0CAA0C,GAAG;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AA8RF,wFAAwF;AACxF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,kCAAkC,GAC9C,qBAAqB,CA2CvB;AAED,sFAAsF;AACtF,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,0CAA0C,GACtD,6BAA6B,CA6B/B"}
+{"version":3,"file":"plan-project-link-contract.d.ts","sourceRoot":"","sources":["../../src/lib/plan-project-link-contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,IAAI,EACJ,sBAAsB,EACtB,qBAAqB,EACrB,6BAA6B,EAC7B,IAAI,EACL,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,gCAAgC,EAAG,4BAAqC,CAAC;AAEtF,MAAM,MAAM,wBAAwB,GAChC,kCAAkC,GAClC,qCAAqC,GACrC,0CAA0C,GAC1C,6CAA6C,GAC7C,mCAAmC,GACnC,2CAA2C,GAC3C,wCAAwC,GACxC,qCAAqC,GACrC,gCAAgC,GAChC,qCAAqC,GACrC,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAEvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFhC,IAAI,EAAE,wBAAwB,EACvC,OAAO,EAAE,MAAM,EACN,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAKjD;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQnE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE5D;AAED,wBAAgB,sCAAsC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CASxF;AAED,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAQxG;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAsBnF;AAED,KAAK,kCAAkC,GAAG;IACxC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,0CAA0C,GAAG;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAgSF,wFAAwF;AACxF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,kCAAkC,GAC9C,qBAAqB,CA2CvB;AAED,sFAAsF;AACtF,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,0CAA0C,GACtD,6BAA6B,CA6B/B"}