@foundation0/api 1.1.2 → 1.1.4

package/projects.ts

@@ -94,6 +94,9 @@ type ProjectSyncTaskOptions = {
   maxBodyLength?: number
   requestTimeoutMs?: number
   throttleMs?: number
+  retryMax?: number
+  retryBaseDelayMs?: number
+  retryMaxDelayMs?: number
   skipDependencies?: boolean
   verbose?: boolean
 }
@@ -119,6 +122,14 @@ type ProjectWriteGitTaskOptions = {
   taskSignature?: string
 }
 
+type ProjectCreateGitIssueOptions = {
+  owner?: string
+  repo?: string
+  title: string
+  body?: string
+  labels?: string[]
+}
+
 export type ProjectGitTaskRecord = {
   number: number
   title: string
@@ -160,6 +171,22 @@ export type ProjectWriteGitTaskResult = {
   issue: ProjectGitTaskRecord
 }
 
+export type ProjectGitIssueRecord = {
+  number: number
+  title: string
+  body: string
+  state: string
+  labels: string[]
+}
+
+export type ProjectCreateGitIssueResult = {
+  projectName: string
+  owner: string
+  repo: string
+  issueNumber: number
+  issue: ProjectGitIssueRecord
+}
+
 type ProjectSearchTargetSection = 'docs' | 'spec'
 
 type ProjectSearchOptions = {
@@ -227,7 +254,7 @@ export type ProjectSearchResult = {
   output: string
 }
 
-const CLI_NAME = 'example'
+const CLI_NAME = 'f0'
 const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
 const VERSION_RE_CORE = `(?:${VERSION_RE})`
 const ACTIVE_EXT_PRIORITY = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
@@ -268,10 +295,10 @@ function resolveProjectsRoot(processRoot: string): string {
 }
 
 export function usage(): string {
-  return `Usage:\n  ${CLI_NAME} projects <project-name> --generate-spec\n  ${CLI_NAME} projects <project-name> <file-path> --set-active\n  ${CLI_NAME} projects --list\n  ${CLI_NAME} projects <project-name> sync-tasks\n  ${CLI_NAME} projects <project-name> clear-issues\n\n` +
-    `Examples:\n  ${CLI_NAME} projects index --generate-spec\n  ${CLI_NAME} projects index /implementation-plan.v0.0.1 --set-active\n  ${CLI_NAME} projects index /implementation-plan --set-active --latest\n  ${CLI_NAME} projects index sync-tasks\n  ${CLI_NAME} projects index sync-tasks --verbose\n  ${CLI_NAME} projects index sync-tasks --request-timeout-ms 60000 --throttle-ms 250\n  ${CLI_NAME} projects index sync-tasks --skip-dependencies\n  ${CLI_NAME} projects index clear-issues --dry-run\n  ${CLI_NAME} projects index clear-issues --force\n  ${CLI_NAME} projects index clear-issues --state all --force\n  ${CLI_NAME} projects --list\n\n` +
+  return `Usage:\n  ${CLI_NAME} projects <project-name> --generate-spec\n  ${CLI_NAME} projects <project-name> <file-path> --set-active\n  ${CLI_NAME} projects <project-name> --sync-tasks (alias: --sync-issues)\n  ${CLI_NAME} projects <project-name> --clear-issues\n  ${CLI_NAME} projects --list\n\n` +
+    `Examples:\n  ${CLI_NAME} projects index --generate-spec\n  ${CLI_NAME} projects index /implementation-plan.v0.0.1 --set-active\n  ${CLI_NAME} projects index /implementation-plan --set-active --latest\n  ${CLI_NAME} projects index sync-tasks\n  ${CLI_NAME} projects index sync-tasks --verbose\n  ${CLI_NAME} projects index sync-tasks --request-timeout-ms 60000 --throttle-ms 250\n  ${CLI_NAME} projects index sync-tasks --retry 5 --retry-base-delay-ms 500\n  ${CLI_NAME} projects index sync-tasks --skip-dependencies\n  ${CLI_NAME} projects index clear-issues --dry-run\n  ${CLI_NAME} projects index clear-issues --force\n  ${CLI_NAME} projects index clear-issues --state all --force\n  ${CLI_NAME} projects --list\n\n` +
     `file-path is relative to the project root (leading slash required).\n` +
-    `Sync-tasks flags: --verbose --max --max-body --request-timeout-ms --throttle-ms --skip-dependencies --owner --repo --label --prefix --tracks.\n` +
+    `Sync-tasks flags: --verbose --max --max-body --request-timeout-ms --throttle-ms --retry --retry-base-delay-ms --retry-max-delay-ms --no-retry --skip-dependencies --owner --repo --label --prefix --tracks.\n` +
     `Use --verbose with clear-issues to print each deletion.\n` +
     `Use --latest to resolve /file-name to the latest version.\n` +
     `The active file created is [file].active.<ext>.\n`
@@ -1943,7 +1970,10 @@ function parseSyncTasksArgs(argv: string[]): {
     prefix: '[TASK]',
     dryRun: false,
     requestTimeoutMs: 60_000,
-    throttleMs: 0,
+    throttleMs: 200,
+    retryMax: 5,
+    retryBaseDelayMs: 500,
+    retryMaxDelayMs: 10_000,
     skipDependencies: false,
     verbose: false,
   }
@@ -2053,6 +2083,41 @@ function parseSyncTasksArgs(argv: string[]): {
       continue
     }
 
+    if (arg === '--retry') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry value: ${argv[i + 1]}`)
+      }
+      options.retryMax = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--retry-base-delay-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry-base-delay-ms value: ${argv[i + 1]}`)
+      }
+      options.retryBaseDelayMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--retry-max-delay-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry-max-delay-ms value: ${argv[i + 1]}`)
+      }
+      options.retryMaxDelayMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--no-retry') {
+      options.retryMax = 0
+      continue
+    }
+
     if (arg === '--skip-dependencies') {
       options.skipDependencies = true
       continue
@@ -2567,6 +2632,21 @@ function toProjectGitTaskRecord(issue: GitIssueLike): ProjectGitTaskRecord | nul
   }
 }
 
+function toProjectGitIssueRecord(issue: GitIssueLike): ProjectGitIssueRecord | null {
+  const raw = issue as Record<string, unknown>
+
+  const issueNumber = Number(raw.number)
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null
+
+  return {
+    number: issueNumber,
+    title: typeof raw.title === 'string' ? raw.title : `Issue #${issueNumber}`,
+    body: typeof raw.body === 'string' ? raw.body : '',
+    state: typeof raw.state === 'string' ? raw.state : 'unknown',
+    labels: normalizeIssueLabels(raw.labels),
+  }
+}
+
 function resolveProjectGitRepository(
   projectName: string,
   processRoot: string,
@@ -2660,24 +2740,141 @@ type GitIssueLike = {
   body?: unknown
 }
 
+type NetworkRetryOptions = {
+  maxRetries: number
+  baseDelayMs: number
+  maxDelayMs: number
+  retryOnStatuses: ReadonlySet<number>
+}
+
+const DEFAULT_RETRYABLE_HTTP_STATUSES = new Set<number>([408, 425, 429, 500, 502, 503, 504])
+
+function resolveNetworkRetryOptions(options: {
+  retryMax?: number
+  retryBaseDelayMs?: number
+  retryMaxDelayMs?: number
+}): NetworkRetryOptions {
+  const maxRetries = Number.isFinite(options.retryMax) ? Math.max(0, Math.floor(options.retryMax ?? 0)) : 0
+  const baseDelayMs = Number.isFinite(options.retryBaseDelayMs) ? Math.max(0, Math.floor(options.retryBaseDelayMs ?? 0)) : 0
+  const maxDelayMs = Number.isFinite(options.retryMaxDelayMs) ? Math.max(0, Math.floor(options.retryMaxDelayMs ?? 0)) : 0
+
+  return {
+    maxRetries,
+    baseDelayMs,
+    maxDelayMs,
+    retryOnStatuses: DEFAULT_RETRYABLE_HTTP_STATUSES,
+  }
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+function retryDelayMs(retryNumber: number, baseDelayMs: number, maxDelayMs: number): number {
+  if (retryNumber <= 0) {
+    return 0
+  }
+
+  const exponent = Math.max(0, retryNumber - 1)
+  const raw = baseDelayMs * (2 ** exponent)
+  const capped = maxDelayMs > 0 ? Math.min(raw, maxDelayMs) : raw
+  const jitter = 0.5 + Math.random()
+  return Math.max(0, Math.floor(capped * jitter))
+}
+
+function isRetryableError(error: unknown, retryOnStatuses: ReadonlySet<number>): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const message = String(error.message ?? '').toLowerCase()
+  const statusMatch = message.match(/status\\s*=\\s*(\\d{3})/)
+  if (statusMatch) {
+    const status = Number(statusMatch[1])
+    if (Number.isInteger(status) && retryOnStatuses.has(status)) {
+      return true
+    }
+  }
+
+  if (message.includes('request timed out')) return true
+  if (message.includes('timeout')) return true
+  if (message.includes('fetch failed')) return true
+  if (message.includes('network')) return true
+  if (message.includes('socket')) return true
+  if (message.includes('econnreset')) return true
+  if (message.includes('econnrefused')) return true
+  if (message.includes('enotfound')) return true
+  if (message.includes('eai_again')) return true
+  if (message.includes('tls')) return true
+
+  return false
+}
+
+async function withRetry<T>(
+  label: string,
+  operation: () => Promise<T>,
+  retry: NetworkRetryOptions,
+  log: ((message: string) => void) | null,
+  shouldRetryValue?: (value: T) => string | null,
+): Promise<T> {
+  const maxAttempts = Math.max(1, retry.maxRetries + 1)
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const value = await operation()
+      const retryReason = shouldRetryValue ? shouldRetryValue(value) : null
+      if (retryReason && attempt < maxAttempts) {
+        const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+        log?.(`${label}: retrying (attempt ${attempt}/${maxAttempts}) reason=${retryReason} delay=${delay}ms`)
+        if (delay > 0) await sleep(delay)
+        continue
+      }
+      return value
+    } catch (error) {
+      if (attempt >= maxAttempts || !isRetryableError(error, retry.retryOnStatuses)) {
+        throw error
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      const message = error instanceof Error ? error.message : String(error)
+      log?.(`${label}: retrying (attempt ${attempt}/${maxAttempts}) error=${message} delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    }
+  }
+
+  // Unreachable, but keeps TS happy.
+  throw new Error(`${label}: retry loop exhausted`)
+}
+
 async function fetchAllIssues(
   issueList: GitServiceApiMethod,
   owner: string,
   repo: string,
   state: 'open' | 'closed' | 'all',
   projectName: string,
-  log?: (message: string) => void
+  log?: (message: string) => void,
+  requestOptions?: { retry?: NetworkRetryOptions; throttleMs?: number },
 ): Promise<GitIssueLike[]> {
   const allIssues: GitIssueLike[] = []
   let page = 1
+  const retry = requestOptions?.retry ?? resolveNetworkRetryOptions({ retryMax: 0, retryBaseDelayMs: 0, retryMaxDelayMs: 0 })
+  const throttleMs = requestOptions?.throttleMs ?? 0
 
   while (true) {
     log?.(`Listing ${state} issues page ${page} for ${owner}/${repo}...`)
-    const listResult = await issueList(owner, repo, {
-      state,
-      limit: ISSUE_LIST_PAGE_SIZE,
-      query: { page },
-    })
+    const listResult = await withRetry(
+      `issue.list ${owner}/${repo} state=${state} page=${page}`,
+      () => issueList(owner, repo, {
+        state,
+        limit: ISSUE_LIST_PAGE_SIZE,
+        query: { page },
+      }),
+      retry,
+      log ?? null,
+      (result) => {
+        const response = result as GitServiceApiExecutionResult
+        if (response.ok) return null
+        return retry.retryOnStatuses.has(response.status) ? `status=${response.status}` : null
+      },
+    )
 
     if (!listResult.ok) {
       throw new Error(
@@ -2697,12 +2894,205 @@ async function fetchAllIssues(
       break
     }
     page += 1
+
+    if (throttleMs > 0) {
+      await sleep(throttleMs)
+    }
   }
 
   log?.(`Loaded ${allIssues.length} ${state} issues in ${owner}/${repo} across pages.`)
   return allIssues
 }
 
+async function findIssueNumberByTaskId(
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+): Promise<number | null> {
+  let page = 1
+
+  while (true) {
+    const listResult = await withRetry(
+      `issue.list (lookup ${taskId}) ${owner}/${repo} page=${page}`,
+      () => issueList(owner, repo, {
+        state: 'open',
+        limit: ISSUE_LIST_PAGE_SIZE,
+        query: { page },
+      }),
+      retry,
+      log,
+      (result) => {
+        const response = result as GitServiceApiExecutionResult
+        if (response.ok) return null
+        return retry.retryOnStatuses.has(response.status) ? `status=${response.status}` : null
+      },
+    )
+
+    if (!listResult.ok) {
+      throw new Error(
+        `Failed to list open issues for ${owner}/${repo}: status=${listResult.status} url=${listResult.request.url}`
+      )
+    }
+
+    if (!Array.isArray(listResult.body)) {
+      throw new Error(`Expected array from issue.list for ${projectName} (open issues lookup, page ${page})`)
+    }
+
+    const batch = listResult.body as GitIssueLike[]
+    for (const issue of batch) {
+      const record = toProjectGitTaskRecord(issue)
+      if (record?.taskId === taskId) {
+        return record.number
+      }
+    }
+
+    if (batch.length === 0) {
+      break
+    }
+    page += 1
+
+    if (throttleMs > 0) {
+      await sleep(throttleMs)
+    }
+  }
+
+  return null
+}
+
+async function findIssueNumberByTaskIdEventually(
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+  attempts: number,
+  delayMs: number,
+): Promise<number | null> {
+  const totalAttempts = Math.max(1, Math.floor(attempts))
+
+  for (let i = 0; i < totalAttempts; i += 1) {
+    const existing = await findIssueNumberByTaskId(issueList, owner, repo, taskId, projectName, retry, throttleMs, log)
+    if (existing) {
+      return existing
+    }
+    if (i < totalAttempts - 1 && delayMs > 0) {
+      await sleep(delayMs)
+    }
+  }
+
+  return null
+}
+
+async function createTaskIssueNumberWithRetry(
+  issueCreate: GitServiceApiMethod,
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  payload: Record<string, unknown>,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+): Promise<number> {
+  const maxAttempts = Math.max(1, retry.maxRetries + 1)
+  const verifyDelayMs = retry.baseDelayMs > 0 ? Math.min(500, retry.baseDelayMs) : 0
+  const verifyBudgetMs = retry.maxDelayMs > 0 ? Math.min(10_000, retry.maxDelayMs) : 0
+  const verifyAttempts = verifyDelayMs > 0 ? Math.max(1, Math.ceil(verifyBudgetMs / verifyDelayMs)) : 1
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const createResult = await issueCreate(owner, repo, { data: payload }) as GitServiceApiExecutionResult
+
+      if (createResult.ok) {
+        const issueNumber = buildIssueNumberFromPayload(createResult.body)
+        if (issueNumber === null) {
+          throw new Error(
+            `Created issue response for ${taskId} in ${owner}/${repo} is invalid: ${JSON.stringify(createResult.body)}`
+          )
+        }
+        return issueNumber
+      }
+
+      const shouldRetry = retry.retryOnStatuses.has(createResult.status) && attempt < maxAttempts
+      if (!shouldRetry) {
+        const bodySummary = (() => {
+          try {
+            if (typeof createResult.body === 'string') {
+              return createResult.body.slice(0, 500)
+            }
+            return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+          } catch {
+            return String(createResult.body)
+          }
+        })()
+        throw new Error(
+          `Failed to create issue for ${taskId} in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+        )
+      }
+
+      log?.(`Create issue for ${taskId}: retryable response status=${createResult.status}; checking if issue already exists...`)
+      const existing = await findIssueNumberByTaskIdEventually(
+        issueList,
+        owner,
+        repo,
+        taskId,
+        projectName,
+        retry,
+        throttleMs,
+        log,
+        verifyAttempts,
+        verifyDelayMs,
+      )
+      if (existing) {
+        log?.(`Create issue for ${taskId}: found existing issue #${existing} after failure; continuing.`)
+        return existing
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      log?.(`Create issue for ${taskId}: retrying (attempt ${attempt}/${maxAttempts}) delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    } catch (error) {
+      if (attempt >= maxAttempts || !isRetryableError(error, retry.retryOnStatuses)) {
+        throw error
+      }
+
+      const message = error instanceof Error ? error.message : String(error)
+      log?.(`Create issue for ${taskId}: retryable error (${message}); checking if issue already exists...`)
+      const existing = await findIssueNumberByTaskIdEventually(
+        issueList,
+        owner,
+        repo,
+        taskId,
+        projectName,
+        retry,
+        throttleMs,
+        log,
+        verifyAttempts,
+        verifyDelayMs,
+      )
+      if (existing) {
+        log?.(`Create issue for ${taskId}: found existing issue #${existing} after error; continuing.`)
+        return existing
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      log?.(`Create issue for ${taskId}: retrying (attempt ${attempt}/${maxAttempts}) delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    }
+  }
+
+  throw new Error(`Create issue for ${taskId}: retry loop exhausted`)
+}
+
 function issueDependenciesMatches(taskDeps: string[], issue: ProjectSyncIssueRecord): boolean {
   const fromBody = issue.dependenciesFromBody
   if (fromBody) {
@@ -2977,9 +3367,21 @@ export async function writeGitTask(
   }
 
   if (!issueNumber) {
-    const createResult = await issueCreate(owner, repo, payload)
+    const createResult = await issueCreate(owner, repo, { data: payload })
     if (!createResult.ok) {
-      throw new Error(`Failed to create task in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url}`)
+      const bodySummary = (() => {
+        try {
+          if (typeof createResult.body === 'string') {
+            return createResult.body.slice(0, 500)
+          }
+          return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+        } catch {
+          return String(createResult.body)
+        }
+      })()
+      throw new Error(
+        `Failed to create task in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+      )
     }
 
     const issue = toProjectGitTaskRecord(createResult.body as GitIssueLike)
@@ -2997,9 +3399,21 @@ export async function writeGitTask(
     }
   }
 
-  const updateResult = await issueEdit(owner, repo, issueNumber, payload)
+  const updateResult = await issueEdit(owner, repo, issueNumber, { data: payload })
   if (!updateResult.ok) {
-    throw new Error(`Failed to update issue #${issueNumber} for ${owner}/${repo}: status=${updateResult.status} url=${updateResult.request.url}`)
+    const bodySummary = (() => {
+      try {
+        if (typeof updateResult.body === 'string') {
+          return updateResult.body.slice(0, 500)
+        }
+        return JSON.stringify(updateResult.body)?.slice(0, 500) ?? String(updateResult.body)
+      } catch {
+        return String(updateResult.body)
+      }
+    })()
+    throw new Error(
+      `Failed to update issue #${issueNumber} for ${owner}/${repo}: status=${updateResult.status} url=${updateResult.request.url} body=${bodySummary}`
+    )
   }
 
   const issue = toProjectGitTaskRecord(updateResult.body as GitIssueLike)
@@ -3017,6 +3431,63 @@ export async function writeGitTask(
   }
 }
 
+export async function createGitIssue(
+  projectName: string,
+  options: ProjectCreateGitIssueOptions,
+  processRoot: string = process.cwd()
+): Promise<ProjectCreateGitIssueResult> {
+  const { owner, repo } = resolveProjectGitRepository(projectName, processRoot, options)
+  const title = typeof options.title === 'string' ? options.title.trim() : ''
+  if (!title) {
+    throw new Error('Issue title is required.')
+  }
+
+  const payload: Record<string, unknown> = { title }
+  if (typeof options.body === 'string') payload.body = options.body
+  if (options.labels) payload.labels = options.labels
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+
+  const issueCreate = resolveIssueApiMethod(git, 'create')
+  const createResult = await issueCreate(owner, repo, { data: payload })
+  if (!createResult.ok) {
+    const bodySummary = (() => {
+      try {
+        if (typeof createResult.body === 'string') {
+          return createResult.body.slice(0, 500)
+        }
+        return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+      } catch {
+        return String(createResult.body)
+      }
+    })()
+    throw new Error(
+      `Failed to create issue in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+    )
+  }
+
+  const issue = toProjectGitIssueRecord(createResult.body as GitIssueLike)
+  if (!issue) {
+    throw new Error(`Create issue response invalid for ${owner}/${repo}`)
+  }
+
+  return {
+    projectName,
+    owner,
+    repo,
+    issueNumber: issue.number,
+    issue,
+  }
+}
+
 export async function syncTasks(
   projectName: string,
   options: Partial<ProjectSyncTaskOptions> = {},
@@ -3036,8 +3507,11 @@ export async function syncTasks(
     dryRun: options.dryRun ?? false,
     max: options.max,
     maxBodyLength: options.maxBodyLength,
-    requestTimeoutMs: options.requestTimeoutMs,
-    throttleMs: options.throttleMs,
+    requestTimeoutMs: options.requestTimeoutMs ?? 60_000,
+    throttleMs: options.throttleMs ?? 200,
+    retryMax: options.retryMax ?? 5,
+    retryBaseDelayMs: options.retryBaseDelayMs ?? 500,
+    retryMaxDelayMs: options.retryMaxDelayMs ?? 10_000,
     skipDependencies: options.skipDependencies,
     owner,
     repo,
@@ -3058,7 +3532,9 @@ export async function syncTasks(
   log?.(`Resolved tracks file: ${tracksPath}`)
   log?.(`Using issue destination: ${owner}/${repo}`)
   log?.(`HTTP request timeout: ${syncOptions.requestTimeoutMs ?? 'default'}`)
+  log?.(`HTTP transport: ${(process.env.EXAMPLE_GIT_HTTP_TRANSPORT ?? '').trim() || '(auto)'}`)
   log?.(`HTTP throttle: ${syncOptions.throttleMs ?? 0}ms`)
+  log?.(`HTTP retry: max=${syncOptions.retryMax ?? 0} baseDelayMs=${syncOptions.retryBaseDelayMs ?? 0} maxDelayMs=${syncOptions.retryMaxDelayMs ?? 0}`)
   log?.(`Dependency sync: ${syncOptions.skipDependencies ? 'skipped' : 'enabled'}`)
   const markdown = await fs.readFile(tracksPath, 'utf8')
   log?.(`Loaded tracks content (${markdown.length} chars).`)
@@ -3089,8 +3565,10 @@ export async function syncTasks(
   const issueList = resolveIssueApiMethod(git, 'list')
   const issueCreate = resolveIssueApiMethod(git, 'create')
   const issueEdit = resolveIssueApiMethod(git, 'edit')
+  const issueView = resolveIssueApiMethod(git, 'view')
 
-  const allIssues = await fetchAllIssues(issueList, owner, repo, 'all', projectName, log)
+  const retry = resolveNetworkRetryOptions(syncOptions)
+  const allIssues = await fetchAllIssues(issueList, owner, repo, 'all', projectName, log, { retry, throttleMs: syncOptions.throttleMs ?? 0 })
   const existing = indexExistingTaskIssues(allIssues, projectName)
   const indexedIssueCount = [...existing.values()].reduce((acc, bucket) => acc + bucket.length, 0)
   log?.(`Loaded ${indexedIssueCount} task-like issues in ${owner}/${repo}.`)
@@ -3106,9 +3584,6 @@ export async function syncTasks(
     unchanged: 0,
   }
 
-  const sleep = (ms: number) =>
-    new Promise<void>((resolve) => setTimeout(resolve, ms))
-
   for (let i = 0; i < selected.length; i += 1) {
     const task = selected[i]
     const marker = `[${i + 1}/${selected.length}] ${task.id}`
@@ -3130,17 +3605,55 @@ export async function syncTasks(
       log?.(`${marker} updating #${targetIssue.number}`)
       if (!syncOptions.dryRun) {
         log?.(`${marker} sending update request...`)
-        const updatedResult = await issueEdit(owner, repo, targetIssue.number, {
-          data: {
-            title: payload.title,
-            body: payload.body,
-            labels: payload.labels,
-            task_id: payload.task_id,
-            task_dependencies: payload.task_dependencies,
+        const updatedResult = await withRetry(
+          `${marker} issue.edit #${targetIssue.number}`,
+          () => issueEdit(owner, repo, targetIssue.number, {
+            data: {
+              title: payload.title,
+              body: payload.body,
+              labels: payload.labels,
+              task_id: payload.task_id,
+              task_dependencies: payload.task_dependencies,
+            },
+          }) as Promise<GitServiceApiExecutionResult>,
+          retry,
+          log,
+          (result) => {
+            if (result.ok) return null
+            return retry.retryOnStatuses.has(result.status) ? `status=${result.status}` : null
           },
-        }) as GitServiceApiExecutionResult
+        )
 
         if (!updatedResult.ok) {
+          const isTimeoutOrRetryable = retry.retryOnStatuses.has(updatedResult.status)
+          if (isTimeoutOrRetryable) {
+            try {
+              const viewResult = await withRetry(
+                `${marker} issue.view #${targetIssue.number}`,
+                () => issueView(owner, repo, targetIssue.number) as Promise<GitServiceApiExecutionResult<GitIssueLike>>,
+                retry,
+                log,
+                (result) => {
+                  if (result.ok) return null
+                  return retry.retryOnStatuses.has(result.status) ? `status=${result.status}` : null
+                },
+              )
+
+              if (viewResult.ok) {
+                const record = toProjectGitTaskRecord(viewResult.body as GitIssueLike)
+                const expectedHash = computeTaskHash(task)
+                const depsMatch = areDependencyListsEqual(task.deps, record?.taskDependenciesFromPayload ?? [])
+                const signatureMatch = record?.taskSignature?.toLowerCase() === expectedHash.toLowerCase()
+                if (signatureMatch && depsMatch) {
+                  log?.(`${marker} update likely succeeded (verified after retryable failure)`)
+                  continue
+                }
+              }
+            } catch {
+              // best effort
+            }
+          }
+
           throw new Error(
             `Failed to update issue ${targetIssue.number} for ${owner}/${repo}: status=${updatedResult.status} url=${updatedResult.request.url}`
           )
@@ -3155,45 +3668,25 @@ export async function syncTasks(
 
     log?.(`${marker} creating new task issue`)
     if (!syncOptions.dryRun) {
-      let createdResult: GitServiceApiExecutionResult
-      try {
-        log?.(`${marker} sending create request...`)
-        createdResult = await issueCreate(owner, repo, {
-          data: {
-            title: payload.title,
-            body: payload.body,
-            labels: payload.labels,
-            task_id: payload.task_id,
-            task_dependencies: payload.task_dependencies,
-          },
-        }) as GitServiceApiExecutionResult
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error)
-        throw new Error(`Failed to create issue for ${task.id} in ${owner}/${repo}: ${message}`)
-      }
-
-      if (!createdResult.ok) {
-        const bodySummary = (() => {
-          try {
-            if (typeof createdResult.body === 'string') {
-              return createdResult.body.slice(0, 500)
-            }
-            return JSON.stringify(createdResult.body)?.slice(0, 500) ?? String(createdResult.body)
-          } catch {
-            return String(createdResult.body)
-          }
-        })()
-        throw new Error(
-          `Failed to create issue for ${task.id} in ${owner}/${repo}: status=${createdResult.status} url=${createdResult.request.url} body=${bodySummary}`
-        )
-      }
-
-      const issueNumber = buildIssueNumberFromPayload(createdResult.body)
-      if (issueNumber === null) {
-        throw new Error(
-          `Created issue response for ${task.id} in ${owner}/${repo} is invalid: ${JSON.stringify(createdResult.body)}`
-        )
-      }
+      log?.(`${marker} sending create request...`)
+      const issueNumber = await createTaskIssueNumberWithRetry(
+        issueCreate,
+        issueList,
+        owner,
+        repo,
+        task.id,
+        {
+          title: payload.title,
+          body: payload.body,
+          labels: payload.labels,
+          task_id: payload.task_id,
+          task_dependencies: payload.task_dependencies,
+        },
+        projectName,
+        retry,
+        syncOptions.throttleMs ?? 0,
+        log,
+      )
       issueNumbersByTask.set(task.id, issueNumber)
 
       log?.(`${marker} created #${issueNumber}`)
@@ -3246,15 +3739,20 @@ export async function syncTasks(
       .filter((value): value is number => value !== undefined && value > 0)
 
     log?.(`Issue #${issueNumber}: syncing dependencies (${desiredDependencyIssues.length} desired)...`)
-    const syncResult = await syncIssueDependenciesViaApi(
-      owner,
-      repo,
-      issueNumber,
-      desiredDependencyIssues,
-      host,
-      token,
-      syncOptions.dryRun,
-      log
+    const syncResult = await withRetry(
+      `issue.dependencies ${owner}/${repo} #${issueNumber}`,
+      () => syncIssueDependenciesViaApi(
+        owner,
+        repo,
+        issueNumber,
+        desiredDependencyIssues,
+        host,
+        token,
+        syncOptions.dryRun,
+        log
+      ),
+      retry,
+      log,
     )
     dependencyStats.added += syncResult.added
     dependencyStats.removed += syncResult.removed
@@ -3420,7 +3918,12 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     throw new Error('Missing required arguments: <project-name>.')
   }
 
-  if (maybeTarget === 'sync-tasks') {
+  if (
+    maybeTarget === 'sync-tasks' ||
+    maybeTarget === '--sync-tasks' ||
+    maybeTarget === 'sync-issues' ||
+    maybeTarget === '--sync-issues'
+  ) {
     const parsedSync = parseSyncTasksArgs(rest)
     if (parsedSync.unknownFlags.length > 0) {
       throw new Error(`Unknown flags: ${parsedSync.unknownFlags.join(', ')}`)
@@ -3432,7 +3935,7 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     return `${CLI_NAME}: synced ${result.totalTasks} tasks for ${result.projectName}${dryRun} from ${path.relative(processRoot, result.tracksPath)}${truncated} (created ${result.created}, updated ${result.updated}, skipped ${result.skipped})`
   }
 
-  if (maybeTarget === 'clear-issues') {
+  if (maybeTarget === 'clear-issues' || maybeTarget === '--clear-issues') {
     const parsedClear = parseClearIssuesArgs(rest)
     if (parsedClear.unknownFlags.length > 0) {
       throw new Error(`Unknown flags: ${parsedClear.unknownFlags.join(', ')}`)