@hasna/todos 0.15.10 → 0.15.12

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.15.10",
+    version: "0.15.12",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -2269,7 +2269,7 @@ function isBlockingDependencyStatus(status) {
 function isTerminalStatus(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
-var TASK_STATUSES, TASK_PRIORITIES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
+var TASK_STATUSES, TASK_PRIORITIES, PLAN_STATUSES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
 var init_types = __esm(() => {
   TASK_STATUSES = [
     "pending",
@@ -2284,6 +2284,7 @@ var init_types = __esm(() => {
     "high",
     "critical"
   ];
+  PLAN_STATUSES = ["active", "completed", "archived"];
   VersionConflictError = class VersionConflictError extends Error {
     taskId;
     expectedVersion;
@@ -2822,6 +2823,405 @@ var init_redaction = __esm(() => {
   REDACTION_PLACEHOLDER = String.raw`\[REDACTED(?:_[A-Z_]+)?\]`;
 });
 
+// src/lib/plan-project-link-contract.ts
+import { createHash as createHash2 } from "crypto";
+function canonicalPlanProjectLinkJson(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(canonicalPlanProjectLinkJson).join(",")}]`;
+  return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalPlanProjectLinkJson(item)}`).join(",")}}`;
+}
+function planProjectLinkDigest(value) {
+  return createHash2("sha256").update(canonicalPlanProjectLinkJson(value)).digest("hex");
+}
+function normalizePlanProjectLinkIdempotencyKey(value) {
+  const key = value?.trim() ?? "";
+  if (key.length < 8 || key.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(key)) {
+    throw new PlanProjectLinkError("PLAN_PROJECT_LINK_IDEMPOTENCY_KEY_INVALID", "idempotency_key must be 8-128 ASCII letters, digits, dots, underscores, colons, or hyphens");
+  }
+  return key;
+}
+function planProjectLinkReceiptId(idempotencyKey) {
+  return `pplr_${planProjectLinkDigest({ idempotency_key: idempotencyKey }).slice(0, 48)}`;
+}
+function planProjectLinkRollbackReceiptId(receiptId) {
+  return `pplr_inverse_${planProjectLinkDigest({ accepted_receipt_id: receiptId }).slice(0, 38)}`;
+}
+function planProjectLinkRequestHash(planId, projectId) {
+  return planProjectLinkDigest({ plan_id: planId, project_id: projectId });
+}
+function planProjectLinkResultDigest(plan, tasks) {
+  return planProjectLinkDigest({
+    plan_id: plan.id,
+    plan_project_id: plan.project_id,
+    tasks: tasks.map((task) => ({ id: task.id, plan_id: task.plan_id, project_id: task.project_id })).sort((left, right) => left.id.localeCompare(right.id))
+  });
+}
+function assertPlanProjectLinkReceipt(value) {
+  const receipt = value;
+  if (!receipt || typeof receipt !== "object" || receipt.schema_version !== PLAN_PROJECT_LINK_SCHEMA_VERSION || typeof receipt.receipt_id !== "string" || typeof receipt.idempotency_key !== "string" || typeof receipt.plan_id !== "string" || typeof receipt.project_id !== "string" || !Array.isArray(receipt.task_ids) || receipt.task_ids.some((id) => typeof id !== "string") || !receipt.prior_task_project_ids || typeof receipt.prior_task_project_ids !== "object" || typeof receipt.result_digest !== "string") {
+    throw new PlanProjectLinkError("PLAN_PROJECT_LINK_RECEIPT_NOT_FOUND", "Stored plan-project-link receipt is invalid");
+  }
+  return receipt;
+}
+function responseRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+function exactResponseKeys(value, expected, label) {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new Error(`${label} fields must be exactly: ${wanted.join(", ")}`);
+  }
+}
+function responseString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+function responseNullableString(value, label) {
+  if (value !== null && typeof value !== "string") {
+    throw new Error(`${label} must be a string or null`);
+  }
+  return value;
+}
+function responseNumber(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`);
+  }
+  return value;
+}
+function responseBoolean(value, label) {
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
+function responseDateTime(value, label) {
+  const timestamp = responseString(value, label);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(timestamp) || !Number.isFinite(Date.parse(timestamp))) {
+    throw new Error(`${label} must be an RFC 3339 date-time`);
+  }
+  return timestamp;
+}
+function responseNullableDateTime(value, label) {
+  if (value === null)
+    return null;
+  return responseDateTime(value, label);
+}
+function responseOptionalNullableString(record, field, label) {
+  if (field in record)
+    responseNullableString(record[field], `${label}.${field}`);
+}
+function responseOptionalNullableDateTime(record, field, label) {
+  if (field in record)
+    responseNullableDateTime(record[field], `${label}.${field}`);
+}
+function responseStringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value;
+}
+function responseProjectSources(value, expectedProjectId) {
+  if (!Array.isArray(value))
+    throw new Error("project.sources must be an array");
+  value.forEach((item, index) => {
+    const label = `project.sources[${index}]`;
+    const source = responseRecord(item, label);
+    responseString(source.id, `${label}.id`);
+    if (responseString(source.project_id, `${label}.project_id`) !== expectedProjectId) {
+      throw new Error(`${label}.project_id must match project.id`);
+    }
+    responseString(source.type, `${label}.type`);
+    responseString(source.name, `${label}.name`);
+    responseString(source.uri, `${label}.uri`);
+    responseNullableString(source.description, `${label}.description`);
+    responseRecord(source.metadata, `${label}.metadata`);
+    responseDateTime(source.created_at, `${label}.created_at`);
+    responseDateTime(source.updated_at, `${label}.updated_at`);
+  });
+}
+function responsePlan(value, expectedPlanId) {
+  const plan = responseRecord(value, "plan");
+  if (responseString(plan.id, "plan.id") !== expectedPlanId) {
+    throw new Error(`plan.id must match requested plan ${expectedPlanId}`);
+  }
+  responseNullableString(plan.slug, "plan.slug");
+  responseNullableString(plan.project_id, "plan.project_id");
+  responseNullableString(plan.task_list_id, "plan.task_list_id");
+  responseNullableString(plan.agent_id, "plan.agent_id");
+  responseString(plan.name, "plan.name");
+  responseNullableString(plan.description, "plan.description");
+  if (typeof plan.status !== "string" || !PLAN_STATUSES.includes(plan.status)) {
+    throw new Error(`plan.status must be one of: ${PLAN_STATUSES.join(", ")}`);
+  }
+  responseDateTime(plan.created_at, "plan.created_at");
+  responseDateTime(plan.updated_at, "plan.updated_at");
+  responseOptionalNullableString(plan, "machine_id", "plan");
+  responseOptionalNullableDateTime(plan, "synced_at", "plan");
+  return plan;
+}
+function responseProject(value, expectedProjectId) {
+  const project = responseRecord(value, "project");
+  if (responseString(project.id, "project.id") !== expectedProjectId) {
+    throw new Error(`project.id must match requested project ${expectedProjectId}`);
+  }
+  responseString(project.name, "project.name");
+  responseString(project.path, "project.path");
+  responseNullableString(project.description, "project.description");
+  responseNullableString(project.task_list_id, "project.task_list_id");
+  responseNullableString(project.task_prefix, "project.task_prefix");
+  responseNumber(project.task_counter, "project.task_counter");
+  responseDateTime(project.created_at, "project.created_at");
+  responseDateTime(project.updated_at, "project.updated_at");
+  responseOptionalNullableString(project, "machine_id", "project");
+  responseOptionalNullableDateTime(project, "synced_at", "project");
+  if ("sources" in project && project.sources !== undefined) {
+    responseProjectSources(project.sources, expectedProjectId);
+  }
+  return project;
+}
+function responseTasks(value, expectedPlanId) {
+  if (!Array.isArray(value))
+    throw new Error("tasks must be an array");
+  const seen = new Set;
+  return value.map((item, index) => {
+    const task = responseRecord(item, `tasks[${index}]`);
+    const taskId = responseString(task.id, `tasks[${index}].id`);
+    if (seen.has(taskId))
+      throw new Error(`tasks contains duplicate id ${taskId}`);
+    seen.add(taskId);
+    if (task.plan_id !== expectedPlanId) {
+      throw new Error(`tasks[${index}].plan_id must match requested plan ${expectedPlanId}`);
+    }
+    const label = `tasks[${index}]`;
+    responseNullableString(task.short_id, `${label}.short_id`);
+    responseNullableString(task.project_id, `tasks[${index}].project_id`);
+    responseNullableString(task.parent_id, `${label}.parent_id`);
+    responseNullableString(task.task_list_id, `${label}.task_list_id`);
+    responseString(task.title, `${label}.title`);
+    responseNullableString(task.description, `${label}.description`);
+    if (typeof task.status !== "string" || !TASK_STATUSES.includes(task.status)) {
+      throw new Error(`${label}.status must be one of: ${TASK_STATUSES.join(", ")}`);
+    }
+    if (typeof task.priority !== "string" || !TASK_PRIORITIES.includes(task.priority)) {
+      throw new Error(`${label}.priority must be one of: ${TASK_PRIORITIES.join(", ")}`);
+    }
+    for (const field of [
+      "agent_id",
+      "assigned_to",
+      "session_id",
+      "working_dir",
+      "locked_by",
+      "approved_by",
+      "recurrence_rule",
+      "recurrence_parent_id",
+      "spawns_template_id",
+      "reason",
+      "spawned_from_session",
+      "assigned_by",
+      "created_by",
+      "assigned_from_project",
+      "task_type",
+      "delegated_from",
+      "runner_id",
+      "current_step"
+    ]) {
+      responseNullableString(task[field], `${label}.${field}`);
+    }
+    responseStringArray(task.tags, `${label}.tags`);
+    responseRecord(task.metadata, `${label}.metadata`);
+    for (const field of [
+      "version",
+      "cost_tokens",
+      "cost_usd",
+      "delegation_depth",
+      "retry_count",
+      "max_retries"
+    ]) {
+      responseNumber(task[field], `${label}.${field}`);
+    }
+    for (const field of ["estimated_minutes", "actual_minutes", "confidence", "sla_minutes", "total_steps"]) {
+      if (task[field] !== null)
+        responseNumber(task[field], `${label}.${field}`);
+    }
+    responseBoolean(task.requires_approval, `${label}.requires_approval`);
+    responseDateTime(task.created_at, `${label}.created_at`);
+    responseDateTime(task.updated_at, `${label}.updated_at`);
+    for (const field of [
+      "locked_at",
+      "started_at",
+      "completed_at",
+      "due_at",
+      "approved_at",
+      "retry_after",
+      "runner_started_at",
+      "runner_completed_at"
+    ]) {
+      responseNullableDateTime(task[field], `${label}.${field}`);
+    }
+    responseOptionalNullableString(task, "machine_id", label);
+    responseOptionalNullableDateTime(task, "synced_at", label);
+    responseOptionalNullableDateTime(task, "archived_at", label);
+    return task;
+  });
+}
+function responseReceipt(value, expectation, planRevision, taskIds) {
+  const receipt = responseRecord(value, "receipt");
+  exactResponseKeys(receipt, [
+    "schema_version",
+    "receipt_id",
+    "idempotency_key",
+    "plan_id",
+    "project_id",
+    "prior_plan_project_id",
+    "prior_task_project_ids",
+    "task_ids",
+    "task_count",
+    "result_plan_revision",
+    "result_digest",
+    "rollback_supported",
+    "created_at"
+  ], "receipt");
+  if (receipt.schema_version !== PLAN_PROJECT_LINK_SCHEMA_VERSION) {
+    throw new Error(`receipt.schema_version must be ${PLAN_PROJECT_LINK_SCHEMA_VERSION}`);
+  }
+  const expectedReceiptId = planProjectLinkReceiptId(expectation.idempotency_key);
+  if (responseString(receipt.receipt_id, "receipt.receipt_id") !== expectedReceiptId) {
+    throw new Error("receipt.receipt_id must match the deterministic apply receipt identity");
+  }
+  if (responseString(receipt.idempotency_key, "receipt.idempotency_key") !== expectation.idempotency_key) {
+    throw new Error("receipt.idempotency_key must match the apply request");
+  }
+  if (responseString(receipt.plan_id, "receipt.plan_id") !== expectation.plan_id) {
+    throw new Error("receipt.plan_id must match the requested plan");
+  }
+  if (responseString(receipt.project_id, "receipt.project_id") !== expectation.project_id) {
+    throw new Error("receipt.project_id must match the requested project");
+  }
+  responseNullableString(receipt.prior_plan_project_id, "receipt.prior_plan_project_id");
+  const priorTaskProjectIds = responseRecord(receipt.prior_task_project_ids, "receipt.prior_task_project_ids");
+  for (const [taskId, projectId] of Object.entries(priorTaskProjectIds)) {
+    responseString(taskId, "receipt.prior_task_project_ids key");
+    responseNullableString(projectId, `receipt.prior_task_project_ids.${taskId}`);
+  }
+  if (!Array.isArray(receipt.task_ids) || receipt.task_ids.some((id) => typeof id !== "string" || id.length === 0)) {
+    throw new Error("receipt.task_ids must be an array of non-empty strings");
+  }
+  const receiptTaskIds = receipt.task_ids;
+  if (new Set(receiptTaskIds).size !== receiptTaskIds.length) {
+    throw new Error("receipt.task_ids must not contain duplicates");
+  }
+  if (receiptTaskIds.length !== taskIds.length || receiptTaskIds.some((taskId, index) => taskId !== taskIds[index])) {
+    throw new Error("receipt.task_ids must exactly match the response task identities");
+  }
+  const priorTaskIds = Object.keys(priorTaskProjectIds).sort();
+  if (priorTaskIds.length !== taskIds.length || priorTaskIds.some((taskId, index) => taskId !== [...taskIds].sort()[index])) {
+    throw new Error("receipt.prior_task_project_ids must exactly cover the response task identities");
+  }
+  if (!Number.isInteger(receipt.task_count) || receipt.task_count !== taskIds.length) {
+    throw new Error("receipt.task_count must equal the response task count");
+  }
+  if (responseString(receipt.result_plan_revision, "receipt.result_plan_revision") !== planRevision) {
+    throw new Error("receipt.result_plan_revision must equal plan.updated_at");
+  }
+  const resultDigest = responseString(receipt.result_digest, "receipt.result_digest");
+  if (!/^[a-f0-9]{64}$/.test(resultDigest)) {
+    throw new Error("receipt.result_digest must be a lowercase SHA-256 digest");
+  }
+  if (receipt.rollback_supported !== true) {
+    throw new Error("receipt.rollback_supported must be true");
+  }
+  responseDateTime(receipt.created_at, "receipt.created_at");
+  return receipt;
+}
+function assertPlanProjectLinkResponse(value, expectation) {
+  const response = responseRecord(value, `${expectation.mode} response`);
+  exactResponseKeys(response, ["mode", "action", "plan", "project", "tasks", "receipt"], `${expectation.mode} response`);
+  if (response.mode !== expectation.mode) {
+    throw new Error(`mode must be ${expectation.mode}`);
+  }
+  const allowedActions = expectation.mode === "plan" ? ["would_link", "already_linked"] : ["linked", "already_linked"];
+  if (typeof response.action !== "string" || !allowedActions.includes(response.action)) {
+    throw new Error(`action must be one of: ${allowedActions.join(", ")}`);
+  }
+  const plan = responsePlan(response.plan, expectation.plan_id);
+  responseProject(response.project, expectation.project_id);
+  const tasks = responseTasks(response.tasks, expectation.plan_id);
+  const linkedResult = expectation.mode === "apply" || response.action === "already_linked";
+  if (linkedResult) {
+    if (plan.project_id !== expectation.project_id) {
+      throw new Error("plan.project_id must match the requested project after linkage");
+    }
+    if (tasks.some((task) => task.project_id !== expectation.project_id)) {
+      throw new Error("every task.project_id must match the requested project after linkage");
+    }
+  }
+  if (expectation.mode === "plan") {
+    if (response.receipt !== null)
+      throw new Error("receipt must be null for a plan response");
+  } else {
+    if (!expectation.idempotency_key)
+      throw new Error("apply validation requires the request idempotency key");
+    const receipt = responseReceipt(response.receipt, expectation, plan.updated_at, tasks.map((task) => task.id));
+    const expectedDigest = planProjectLinkResultDigest(plan, tasks);
+    if (receipt.result_digest !== expectedDigest) {
+      throw new Error("receipt.result_digest must match the returned plan and tasks");
+    }
+  }
+  return value;
+}
+function assertPlanProjectLinkRollbackResponse(value, expectation) {
+  const response = responseRecord(value, "rollback response");
+  exactResponseKeys(response, [
+    "schema_version",
+    "action",
+    "plan",
+    "tasks",
+    "accepted_receipt_id",
+    "rollback_receipt_id",
+    "restored_at"
+  ], "rollback response");
+  if (response.schema_version !== PLAN_PROJECT_LINK_SCHEMA_VERSION) {
+    throw new Error(`schema_version must be ${PLAN_PROJECT_LINK_SCHEMA_VERSION}`);
+  }
+  if (response.action !== "restored")
+    throw new Error("action must be restored");
+  const plan = responsePlan(response.plan, expectation.plan_id);
+  responseTasks(response.tasks, expectation.plan_id);
+  if (responseString(response.accepted_receipt_id, "accepted_receipt_id") !== expectation.receipt_id) {
+    throw new Error("accepted_receipt_id must match the rollback request");
+  }
+  const expectedRollbackReceiptId = planProjectLinkRollbackReceiptId(expectation.receipt_id);
+  if (responseString(response.rollback_receipt_id, "rollback_receipt_id") !== expectedRollbackReceiptId) {
+    throw new Error("rollback_receipt_id must match the deterministic rollback receipt identity");
+  }
+  const restoredAt = responseDateTime(response.restored_at, "restored_at");
+  if (plan.updated_at !== restoredAt) {
+    throw new Error("restored_at must equal plan.updated_at");
+  }
+  return value;
+}
+var PLAN_PROJECT_LINK_SCHEMA_VERSION = "todos.plan-project-link.v1", PlanProjectLinkError;
+var init_plan_project_link_contract = __esm(() => {
+  init_types();
+  PlanProjectLinkError = class PlanProjectLinkError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+      super(message);
+      this.code = code;
+      this.details = details;
+      this.name = "PlanProjectLinkError";
+    }
+  };
+});
+
 // src/pr-groups/types.ts
 var PR_GROUP_LEDGER_SCHEMA_VERSION = 1, PR_GROUP_REPAIR_CYCLE_LIMIT = 2, PrGroupLedgerError;
 var init_types2 = __esm(() => {
@@ -2838,9 +3238,9 @@ var init_types2 = __esm(() => {
 });
 
 // src/pr-groups/ledger.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function sha256(value) {
-  return createHash2("sha256").update(value).digest("hex");
+  return createHash3("sha256").update(value).digest("hex");
 }
 function stableValue(value) {
   if (Array.isArray(value))
@@ -5376,6 +5776,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))
@@ -5397,13 +5803,40 @@ 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)
+    return [];
+  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)
@@ -5711,17 +6144,50 @@ async function cloudRollbackProjectTaskListEnsure(client, projectId, input) {
   return requiredRemoteRoute(client, "/v1/projects/:id/task-list/rollback", () => client.transport.post(`/projects/${encodeURIComponent(projectId)}/task-list/rollback`, input), ["PROJECT_NOT_FOUND", "PROJECT_TASK_LIST_RECEIPT_NOT_FOUND"]);
 }
 async function cloudPlanPlanProjectLink(client, planId, projectId) {
-  return requiredRemoteRoute(client, "/v1/plans/:id/project-link", () => client.transport.get(`/plans/${encodeURIComponent(planId)}/project-link`, { query: { project_id: projectId } }), ["PLAN_PROJECT_LINK_PLAN_NOT_FOUND", "PLAN_PROJECT_LINK_PROJECT_NOT_FOUND"]);
+  const route = `/v1/plans/${encodeURIComponent(planId)}/project-link`;
+  const response = await requiredRemoteRoute(client, "/v1/plans/:id/project-link", () => client.transport.get(`/plans/${encodeURIComponent(planId)}/project-link`, { query: { project_id: projectId } }), ["PLAN_PROJECT_LINK_PLAN_NOT_FOUND", "PLAN_PROJECT_LINK_PROJECT_NOT_FOUND"]);
+  try {
+    return assertPlanProjectLinkResponse(response, { mode: "plan", plan_id: planId, project_id: projectId });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid ${PLAN_PROJECT_LINK_SCHEMA_VERSION} plan response: ` + `${reason}; local SQLite fallback is disabled`, { cause: error });
+  }
 }
 async function cloudApplyPlanProjectLink(client, planId, projectId, input) {
-  return requiredRemoteRoute(client, "/v1/plans/:id/project-link", () => client.transport.post(`/plans/${encodeURIComponent(planId)}/project-link`, { project_id: projectId, ...input }), ["PLAN_PROJECT_LINK_PLAN_NOT_FOUND", "PLAN_PROJECT_LINK_PROJECT_NOT_FOUND"]);
+  const route = `/v1/plans/${encodeURIComponent(planId)}/project-link`;
+  const normalizedInput = {
+    ...input,
+    idempotency_key: normalizePlanProjectLinkIdempotencyKey(input.idempotency_key)
+  };
+  const response = await requiredRemoteRoute(client, "/v1/plans/:id/project-link", () => client.transport.post(`/plans/${encodeURIComponent(planId)}/project-link`, { project_id: projectId, ...normalizedInput }), ["PLAN_PROJECT_LINK_PLAN_NOT_FOUND", "PLAN_PROJECT_LINK_PROJECT_NOT_FOUND"]);
+  try {
+    return assertPlanProjectLinkResponse(response, {
+      mode: "apply",
+      plan_id: planId,
+      project_id: projectId,
+      idempotency_key: normalizedInput.idempotency_key
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid ${PLAN_PROJECT_LINK_SCHEMA_VERSION} apply response: ` + `${reason}; local SQLite fallback is disabled`, { cause: error });
+  }
 }
 async function cloudRollbackPlanProjectLink(client, planId, projectId, input) {
-  return requiredRemoteRoute(client, "/v1/plans/:id/project-link/rollback", () => client.transport.post(`/plans/${encodeURIComponent(planId)}/project-link/rollback`, { project_id: projectId, ...input }), [
+  const route = `/v1/plans/${encodeURIComponent(planId)}/project-link/rollback`;
+  const response = await requiredRemoteRoute(client, "/v1/plans/:id/project-link/rollback", () => client.transport.post(`/plans/${encodeURIComponent(planId)}/project-link/rollback`, { project_id: projectId, ...input }), [
     "PLAN_PROJECT_LINK_PLAN_NOT_FOUND",
     "PLAN_PROJECT_LINK_PROJECT_NOT_FOUND",
     "PLAN_PROJECT_LINK_RECEIPT_NOT_FOUND"
   ]);
+  try {
+    return assertPlanProjectLinkRollbackResponse(response, {
+      plan_id: planId,
+      receipt_id: input.receipt_id
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid ${PLAN_PROJECT_LINK_SCHEMA_VERSION} rollback response: ` + `${reason}; local SQLite fallback is disabled`, { cause: error });
+  }
 }
 async function cloudListPlans(client, projectId) {
   const query = projectId ? { project_id: projectId } : {};
@@ -5908,17 +6374,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();
@@ -6076,9 +6630,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" }),
@@ -6392,10 +6943,11 @@ 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();
+  init_plan_project_link_contract();
   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;
   TRANSPORT_TOKENS = {
@@ -6416,9 +6968,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
@@ -12815,7 +13368,7 @@ __export(exports_event_hooks, {
   emitLocalEventHooks: () => emitLocalEventHooks,
   LOCAL_EVENT_TYPES: () => LOCAL_EVENT_TYPES
 });
-import { createHash as createHash3, randomUUID } from "crypto";
+import { createHash as createHash4, randomUUID } from "crypto";
 import { appendFileSync, mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname4, resolve as resolve7 } from "path";
 import { createConnection } from "net";
@@ -12882,7 +13435,7 @@ function buildEnvelope(type, payload, timestamp2 = new Date().toISOString()) {
     payload: redactValue(payload ?? {}),
     source: { package: "@hasna/todos", local_only: true }
   };
-  const digest = createHash3("sha256").update(canonicalEvent(base)).digest("hex");
+  const digest = createHash4("sha256").update(canonicalEvent(base)).digest("hex");
   return { ...base, integrity: { algorithm: "sha256", digest } };
 }
 function summarize(value) {
@@ -18096,7 +18649,7 @@ var init_boards = __esm(() => {
 });
 
 // src/lib/artifact-store.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync3, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
 import { basename as basename2, dirname as dirname5, join as join7, resolve as resolve8 } from "path";
 import { tmpdir as tmpdir3 } from "os";
@@ -18121,7 +18674,7 @@ function artifactStorePath(relativePath) {
   return join7(artifactStoreRoot(), normalized);
 }
 function sha2562(buffer) {
-  return createHash4("sha256").update(buffer).digest("hex");
+  return createHash5("sha256").update(buffer).digest("hex");
 }
 function isTextLike(buffer, path) {
   if (buffer.includes(0))
@@ -20953,6 +21506,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)) {
@@ -21525,7 +22086,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;
@@ -21676,8 +22238,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,
@@ -21685,6 +22250,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,
@@ -21697,6 +22263,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}`));
@@ -21809,8 +22377,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: [],
@@ -21819,6 +22390,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,
@@ -21836,7 +22408,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) {
@@ -21847,6 +22419,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;
     }
@@ -22840,62 +23417,6 @@ var init_plan_artifacts = __esm(() => {
   init_tasks();
 });
 
-// src/lib/plan-project-link-contract.ts
-import { createHash as createHash5 } from "crypto";
-function canonicalPlanProjectLinkJson(value) {
-  if (value === null || typeof value !== "object")
-    return JSON.stringify(value);
-  if (Array.isArray(value))
-    return `[${value.map(canonicalPlanProjectLinkJson).join(",")}]`;
-  return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalPlanProjectLinkJson(item)}`).join(",")}}`;
-}
-function planProjectLinkDigest(value) {
-  return createHash5("sha256").update(canonicalPlanProjectLinkJson(value)).digest("hex");
-}
-function normalizePlanProjectLinkIdempotencyKey(value) {
-  const key = value?.trim() ?? "";
-  if (key.length < 8 || key.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(key)) {
-    throw new PlanProjectLinkError("PLAN_PROJECT_LINK_IDEMPOTENCY_KEY_INVALID", "idempotency_key must be 8-128 ASCII letters, digits, dots, underscores, colons, or hyphens");
-  }
-  return key;
-}
-function planProjectLinkReceiptId(idempotencyKey) {
-  return `pplr_${planProjectLinkDigest({ idempotency_key: idempotencyKey }).slice(0, 48)}`;
-}
-function planProjectLinkRollbackReceiptId(receiptId) {
-  return `pplr_inverse_${planProjectLinkDigest({ accepted_receipt_id: receiptId }).slice(0, 38)}`;
-}
-function planProjectLinkRequestHash(planId, projectId) {
-  return planProjectLinkDigest({ plan_id: planId, project_id: projectId });
-}
-function planProjectLinkResultDigest(plan, tasks) {
-  return planProjectLinkDigest({
-    plan_id: plan.id,
-    plan_project_id: plan.project_id,
-    tasks: tasks.map((task) => ({ id: task.id, plan_id: task.plan_id, project_id: task.project_id })).sort((left, right) => left.id.localeCompare(right.id))
-  });
-}
-function assertPlanProjectLinkReceipt(value) {
-  const receipt = value;
-  if (!receipt || typeof receipt !== "object" || receipt.schema_version !== PLAN_PROJECT_LINK_SCHEMA_VERSION || typeof receipt.receipt_id !== "string" || typeof receipt.idempotency_key !== "string" || typeof receipt.plan_id !== "string" || typeof receipt.project_id !== "string" || !Array.isArray(receipt.task_ids) || receipt.task_ids.some((id) => typeof id !== "string") || !receipt.prior_task_project_ids || typeof receipt.prior_task_project_ids !== "object" || typeof receipt.result_digest !== "string") {
-    throw new PlanProjectLinkError("PLAN_PROJECT_LINK_RECEIPT_NOT_FOUND", "Stored plan-project-link receipt is invalid");
-  }
-  return receipt;
-}
-var PLAN_PROJECT_LINK_SCHEMA_VERSION = "todos.plan-project-link.v1", PlanProjectLinkError;
-var init_plan_project_link_contract = __esm(() => {
-  PlanProjectLinkError = class PlanProjectLinkError extends Error {
-    code;
-    details;
-    constructor(code, message, details = {}) {
-      super(message);
-      this.code = code;
-      this.details = details;
-      this.name = "PlanProjectLinkError";
-    }
-  };
-});
-
 // src/lib/plan-project-link.ts
 async function exactPlanProjectLinkState(store, planId, projectId) {
   const [plan, project] = await Promise.all([
@@ -40339,6 +40860,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
         ProjectTaskListEnsureResult: projectTaskListEnsureResultSchema,
         ProjectTaskListRollbackResult: projectTaskListRollbackResultSchema,
         TaskComment: taskCommentSchema,
+        TaskGitRef: taskGitRefSchema,
         Plan: planSchema,
         PlanProjectLinkReceipt: planProjectLinkReceiptSchema,
         PlanProjectLinkResult: planProjectLinkResultSchema,
@@ -41500,6 +42022,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",
@@ -41951,7 +42559,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();
@@ -42087,6 +42695,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"],