@danypops/tickets 0.2.0 → 0.2.1

package/README.md

@@ -165,7 +165,7 @@ up the new credential — `buildRepositories()` runs once at daemon startup.
 
 ## The `pi-tickets` extension
 
-`extensions/pi-tickets/` registers a single `tickets` tool for
+Published as `@danypops/pi-tickets`. `../../extensions/pi-tickets/` (this repo's workspace member) registers a single `tickets` tool for
 [pi](https://github.com/badlogic/pi) with one action per CLI command (`list`,
 `get`, `create`, `update`, `search`, `children`, `comments`, `comment_add`,
 `backends`, `ledger_search`, `ledger_stats`, `focus_set`, `focus_get`,
@@ -189,27 +189,21 @@ shows the current focus at all times, refreshed on session start and after
 every `tickets` tool call — so a focus the LLM sets via `focus_set` mid-
 conversation shows up in the footer too, and vice versa.
 
-To use it:
-
-```bash
-cd extensions/pi-tickets
-bun install
-```
-
-then either symlink (or copy) `extensions/pi-tickets` into
-`~/.pi/agent/extensions/pi-tickets`, or add its path to `settings.json`:
+To use it, add it to pi's `settings.json`:
 
 ```json
-{ "extensions": ["/path/to/tickets/extensions/pi-tickets"] }
+{ "packages": ["npm:@danypops/pi-tickets"] }
 ```
 
+Or, for local development against this monorepo, point at the workspace
+member directory instead: `{ "packages": ["/path/to/tickets/extensions/pi-tickets"] }`.
+
 ## Development
 
 ```bash
-bun install
-bun run typecheck   # tsc --noEmit against src/ and test/
-bun test            # domain, adapters, application service, auth flows, daemon
-cd extensions/pi-tickets && bun install && bun test && bun run typecheck
+bun install                # from the repo root -- links both workspace members
+bun run typecheck          # both packages
+bun test                   # both packages
 ```
 
 Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -20,14 +20,15 @@
   ],
   "scripts": {
     "daemon": "bun run src/daemon/main.ts",
-    "test": "bun test --path-ignore-patterns 'extensions/**'",
-    "test:extension": "cd extensions/pi-tickets && bun install && bun test",
-    "test:all": "npm run test && npm run test:extension",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/daemon-kit": "^0.2.1",
+    "@danypops/daemon-kit": "^0.3.0",
+    "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.0",
+    "jira.js": "^5.4.0",
+    "octokit": "^5.0.5",
     "yaml": "^2.6.0"
   },
   "devDependencies": {
@@ -50,7 +51,8 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/DanyPops/tickets.git"
+    "url": "git+https://github.com/DanyPops/tickets.git",
+    "directory": "packages/tickets"
   },
   "homepage": "https://github.com/DanyPops/tickets#readme",
   "bugs": {

package/src/adapters/github.ts

@@ -1,19 +1,39 @@
 /**
  * GitHub adapter — driven implementation of IssueRepository/CommentCapable against
- * the GitHub REST API v3 (docs: https://docs.github.com/en/rest/issues/issues).
- * Token is optional: public repos allow unauthenticated reads at a lower rate limit.
+ * the GitHub REST API v3, via octokit (github.com/octokit) rather than a hand-rolled
+ * HTTP client: it's GitHub's own official SDK, generated from GitHub's OpenAPI spec,
+ * and its typed `assignees: string[]` matches the real write contract exactly (see
+ * RESEARCH.md). Token is optional: public repos allow unauthenticated reads at a
+ * lower rate limit.
+ *
+ * IMPORTANT: the `octokit` meta-package bundles @octokit/plugin-retry and
+ * @octokit/plugin-throttling ON by default, with default onRateLimit/
+ * onSecondaryRateLimit handlers that silently SLEEP for GitHub's advertised
+ * Retry-After window (which for an exhausted hourly quota can be tens of
+ * minutes) before even attempting a retry -- confirmed for real: a live smoke
+ * test against an already-rate-limited endpoint hung with zero output rather
+ * than failing fast. That's the opposite of this project's own design (the
+ * daemon's ledger exists so live calls can fail fast and the caller decides
+ * what to do next, not so octokit can unilaterally decide to block for an
+ * indeterminate duration). Both plugins are explicitly disabled below, and
+ * every call carries a hard timeout matching the old hand-rolled HttpClient's.
  */
+import { Octokit } from "octokit";
+import { RequestError } from "@octokit/request-error";
 import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
 import { parsePriority } from "../domain/issue.js";
-import { AuthRequiredError } from "./errors.js";
-import { type FetchLike, HttpClient } from "./http.js";
+import { ApiError, AuthRequiredError, IssueNotFoundError } from "./errors.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
 
 export interface GitHubOptions {
   owner: string;
   repo?: string;
   token?: string;
   baseUrl?: string;
-  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  /** Injected in tests instead of hitting a real network — see @octokit/types' RequestRequestOptions.fetch. */
+  fetchImpl?: typeof fetch;
 }
 
 interface GhUser {
@@ -31,14 +51,14 @@ interface GhIssue {
   html_url: string;
   user: GhUser | null;
   assignee: GhUser | null;
-  labels: GhLabel[];
+  labels: (GhLabel | string)[];
   created_at: string;
   updated_at: string;
   pull_request?: unknown;
 }
 interface GhComment {
   id: number;
-  body: string;
+  body?: string;
   created_at: string;
   updated_at: string;
   user: GhUser | null;
@@ -46,31 +66,32 @@ interface GhComment {
 
 export class GitHubRepository {
   readonly name: string;
-  private readonly http: HttpClient;
+  private readonly client: Octokit;
   private readonly owner: string;
   private repo?: string;
   private readonly readOnly: boolean;
 
+  private readonly timeoutMs: number;
+
   constructor(name: string, opts: GitHubOptions) {
     if (!opts.owner) throw new Error("github: owner is required");
     this.name = name;
     this.owner = opts.owner;
     this.repo = opts.repo;
     this.readOnly = !opts.token;
-    this.http = new HttpClient({
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.client = new Octokit({
+      auth: opts.token,
       baseUrl: opts.baseUrl ?? "https://api.github.com",
-      backend: "github",
-      fetchImpl: opts.fetchImpl,
-      headers: {
-        Accept: "application/vnd.github.v3+json",
-        ...(opts.token ? { Authorization: `token ${opts.token}` } : {}),
-      },
+      retry: { enabled: false },
+      throttle: { onRateLimit: () => false, onSecondaryRateLimit: () => false },
+      ...(opts.fetchImpl ? { request: { fetch: opts.fetchImpl } } : {}),
     });
   }
 
-  private repoPath(): string {
+  private repoName(): string {
     if (!this.repo) throw new Error("github: repo not set — pass repo, or scope via config");
-    return `/repos/${this.owner}/${this.repo}`;
+    return this.repo;
   }
 
   private requireAuth(): void {
@@ -79,52 +100,70 @@ export class GitHubRepository {
 
   async list(filter: ListFilter): Promise<Issue[]> {
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const params = new URLSearchParams({ per_page: String(limit), state: "all" });
-    if (filter.status) params.set("state", mapStatusToGitHub(filter.status));
-    if (filter.assignee) params.set("assignee", filter.assignee);
-    if (filter.labels?.length) params.set("labels", filter.labels.join(","));
-
-    const raw = (await this.http.get<GhIssue[]>(`${this.repoPath()}/issues?${params}`)) ?? [];
-    return raw.filter((i) => !i.pull_request).map(toDomain);
+    const raw = await this.call((signal) =>
+      this.client.rest.issues.listForRepo({
+        owner: this.owner,
+        repo: this.repoName(),
+        per_page: limit,
+        state: filter.status ? mapStatusToGitHub(filter.status) : "all",
+        assignee: filter.assignee,
+        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+        request: { signal },
+      }),
+    );
+    return (raw as GhIssue[]).filter((i) => !i.pull_request).map(toDomain);
   }
 
   async get(key: string): Promise<Issue> {
-    const number = parseIssueNumber(key);
-    const raw = await this.http.get<GhIssue>(`${this.repoPath()}/issues/${number}`);
-    if (!raw) throw new Error(`github: empty response for #${number}`);
-    if (raw.pull_request) throw new Error(`github: #${number} is a pull request, not an issue`);
+    const issue_number = parseIssueNumber(key);
+    const raw = (await this.call((signal) =>
+      this.client.rest.issues.get({ owner: this.owner, repo: this.repoName(), issue_number, request: { signal } }),
+    )) as GhIssue;
+    if (raw.pull_request) throw new Error(`github: #${issue_number} is a pull request, not an issue`);
     return toDomain(raw);
   }
 
   async create(input: CreateInput): Promise<Issue> {
     this.requireAuth();
-    const body: Record<string, unknown> = { title: input.title, body: input.description ?? "" };
-    if (input.labels?.length) body.labels = input.labels;
-    if (input.assignee) body.assignees = [input.assignee];
-    const raw = await this.http.post<GhIssue>(`${this.repoPath()}/issues`, body);
-    if (!raw) throw new Error("github: create returned no body");
+    const raw = (await this.call((signal) =>
+      this.client.rest.issues.create({
+        owner: this.owner,
+        repo: this.repoName(),
+        title: input.title,
+        body: input.description ?? "",
+        labels: input.labels?.length ? input.labels : undefined,
+        assignees: input.assignee ? [input.assignee] : undefined,
+        request: { signal },
+      }),
+    )) as GhIssue;
     return toDomain(raw);
   }
 
   async update(key: string, input: UpdateInput): Promise<Issue> {
     this.requireAuth();
-    const number = parseIssueNumber(key);
-    const body: Record<string, unknown> = {};
-    if (input.title !== undefined) body.title = input.title;
-    if (input.description !== undefined) body.body = input.description;
-    if (input.status !== undefined) body.state = mapStatusToGitHub(input.status);
-    if (input.labels !== undefined) body.labels = input.labels;
-    if (input.assignee !== undefined) body.assignees = input.assignee ? [input.assignee] : [];
-    const raw = await this.http.patch<GhIssue>(`${this.repoPath()}/issues/${number}`, body);
-    if (!raw) throw new Error("github: update returned no body");
+    const issue_number = parseIssueNumber(key);
+    const raw = (await this.call((signal) =>
+      this.client.rest.issues.update({
+        owner: this.owner,
+        repo: this.repoName(),
+        issue_number,
+        title: input.title,
+        body: input.description,
+        state: input.status !== undefined ? mapStatusToGitHub(input.status) : undefined,
+        labels: input.labels,
+        assignees: input.assignee !== undefined ? (input.assignee ? [input.assignee] : []) : undefined,
+        request: { signal },
+      }),
+    )) as GhIssue;
     return toDomain(raw);
   }
 
   async search(query: string, limit = 50): Promise<Issue[]> {
     const scope = this.repo ? `repo:${this.owner}/${this.repo}` : `org:${this.owner}`;
-    const q = encodeURIComponent(`${scope} ${query}`);
-    const result = await this.http.get<{ items: GhIssue[] }>(`/search/issues?q=${q}&per_page=${limit}`);
-    return (result?.items ?? []).filter((i) => !i.pull_request).map(toDomain);
+    const result = (await this.call((signal) =>
+      this.client.rest.search.issuesAndPullRequests({ q: `${scope} ${query}`, per_page: limit, request: { signal } }),
+    )) as { items: GhIssue[] };
+    return result.items.filter((i) => !i.pull_request).map(toDomain);
   }
 
   // GitHub has no native sub-issue relationship exposed via REST v3.
@@ -133,24 +172,60 @@ export class GitHubRepository {
   }
 
   async listComments(key: string): Promise<Comment[]> {
-    const number = parseIssueNumber(key);
-    const raw = (await this.http.get<GhComment[]>(`${this.repoPath()}/issues/${number}/comments`)) ?? [];
+    const issue_number = parseIssueNumber(key);
+    const raw = (await this.call((signal) =>
+      this.client.rest.issues.listComments({ owner: this.owner, repo: this.repoName(), issue_number, request: { signal } }),
+    )) as GhComment[];
     return raw.map(commentToDomain);
   }
 
   async addComment(key: string, body: string): Promise<Comment> {
     this.requireAuth();
-    const number = parseIssueNumber(key);
-    const raw = await this.http.post<GhComment>(`${this.repoPath()}/issues/${number}/comments`, { body });
-    if (!raw) throw new Error("github: add comment returned no body");
+    const issue_number = parseIssueNumber(key);
+    const raw = (await this.call((signal) =>
+      this.client.rest.issues.createComment({ owner: this.owner, repo: this.repoName(), issue_number, body, request: { signal } }),
+    )) as GhComment;
     return commentToDomain(raw);
   }
+
+  /**
+   * Runs an octokit call, unwraps `.data`, and maps RequestError onto this
+   * project's shared error taxonomy. Uses a plain AbortController + setTimeout
+   * (not AbortSignal.timeout()) specifically so the timer can be cleared the
+   * moment the call settles, matching the old hand-rolled HttpClient's
+   * finally-block discipline -- AbortSignal.timeout() has no way to cancel
+   * early once created, and confirmed for real that letting it linger shows
+   * up as measurable delay (each call leaves a live timer sitting in the
+   * event loop until it eventually fires). With retry/throttling disabled
+   * above, a stalled connection or rate-limit response now fails predictably
+   * within `timeoutMs` instead of hanging.
+   */
+  private async call<T>(fn: (signal: AbortSignal) => Promise<{ data: T }>): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fn(controller.signal);
+      return res.data;
+    } catch (err) {
+      if (err instanceof RequestError) {
+        if (err.status === 404) throw new IssueNotFoundError("github", err.request.url);
+        throw new ApiError("github", err.request.method, err.request.url, err.status, redact(err.message));
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
 }
 
-function parseIssueNumber(key: string): string {
+function redact(text: string): string {
+  return text.replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"').slice(0, 2000);
+}
+
+function parseIssueNumber(key: string): number {
   const stripped = key.replace(/^#/, "");
   const idx = stripped.lastIndexOf("#");
-  return idx >= 0 ? stripped.slice(idx + 1) : stripped;
+  return Number(idx >= 0 ? stripped.slice(idx + 1) : stripped);
 }
 
 function mapStatusToGitHub(status: Status): "open" | "closed" {
@@ -161,9 +236,13 @@ function mapStatusFromGitHub(state: string): Status {
   return state.toLowerCase() === "closed" ? "done" : "todo";
 }
 
-function priorityFromLabels(labels: GhLabel[]): ReturnType<typeof parsePriority> {
+function labelName(label: GhLabel | string): string {
+  return typeof label === "string" ? label : label.name;
+}
+
+function priorityFromLabels(labels: (GhLabel | string)[]): ReturnType<typeof parsePriority> {
   for (const l of labels) {
-    const lower = l.name.toLowerCase();
+    const lower = labelName(l).toLowerCase();
     if (lower.includes("urgent") || lower.includes("critical")) return "urgent";
     if (lower.includes("high")) return "high";
     if (lower.includes("medium")) return "medium";
@@ -182,7 +261,7 @@ function toDomain(gh: GhIssue): Issue {
     status: mapStatusFromGitHub(gh.state),
     rawStatus: gh.state,
     priority: priorityFromLabels(gh.labels ?? []),
-    labels: gh.labels?.length ? gh.labels.map((l) => l.name) : undefined,
+    labels: gh.labels?.length ? gh.labels.map(labelName) : undefined,
     assignee: gh.assignee?.login,
     url: gh.html_url,
     createdAt: gh.created_at,
@@ -193,7 +272,7 @@ function toDomain(gh: GhIssue): Issue {
 function commentToDomain(c: GhComment): Comment {
   return {
     id: String(c.id),
-    body: c.body,
+    body: c.body ?? "",
     author: c.user?.login,
     createdAt: c.created_at,
     updatedAt: c.updated_at,

package/src/adapters/gitlab.ts

@@ -1,14 +1,21 @@
 /**
  * GitLab adapter — driven implementation of IssueRepository/CommentCapable against
- * the GitLab REST API v4 (docs: https://docs.gitlab.com/api/issues/).
- * Self-hosted base URLs are validated to reject SSRF-prone targets (private/loopback
- * IPs, non-HTTPS non-localhost) before any request is made.
+ * the GitLab REST API v4, via @gitbeaker/rest (github.com/jdalrymple/gitbeaker)
+ * rather than a hand-rolled HTTP client: a mature, actively-maintained,
+ * TypeScript-native GitLab SDK supporting both gitlab.com and self-managed
+ * instances. Its typed `assignee_ids: number[]` (not a username) matches GitLab's
+ * real write contract exactly — a class of bug this adapter used to have (see
+ * RESEARCH.md): assignee was silently dropped in update() because a hand-rolled
+ * body never resolved a username to the numeric ID GitLab's API actually requires.
+ * Self-hosted base URLs are still validated to reject SSRF-prone targets before
+ * any request is made.
  */
+import { Gitlab } from "@gitbeaker/rest";
+import { GitbeakerRequestError, type RequesterType, type ResourceOptions } from "@gitbeaker/requester-utils";
 import { isIP } from "node:net";
 import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
 import { parsePriority } from "../domain/issue.js";
-import { AuthRequiredError, InvalidUrlError } from "./errors.js";
-import { type FetchLike, HttpClient } from "./http.js";
+import { ApiError, AuthRequiredError, InvalidUrlError, IssueNotFoundError } from "./errors.js";
 
 export interface GitLabOptions {
   projectId: string;
@@ -20,10 +27,13 @@ export interface GitLabOptions {
    */
   tokenType?: "private" | "oauth";
   baseUrl?: string;
-  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  /** Injected in tests instead of a real network call — see @gitbeaker/requester-utils' requesterFn. */
+  requesterFn?: (resourceOptions: ResourceOptions) => RequesterType;
 }
 
 interface GlUser {
+  id: number;
   username: string;
   name: string;
 }
@@ -49,10 +59,11 @@ interface GlNote {
 }
 
 const DEFAULT_URL = "https://gitlab.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
 
 export class GitLabRepository {
   readonly name: string;
-  private readonly http: HttpClient;
+  private readonly client: InstanceType<typeof Gitlab>;
   private readonly projectId: string;
   private readonly readOnly: boolean;
 
@@ -61,17 +72,20 @@ export class GitLabRepository {
     const baseUrl = opts.baseUrl?.trim() || DEFAULT_URL;
     validateUrl(baseUrl);
     this.name = name;
-    this.projectId = encodeURIComponent(opts.projectId);
+    this.projectId = opts.projectId;
     this.readOnly = !opts.token;
-    this.http = new HttpClient({
-      baseUrl,
-      backend: "gitlab",
-      fetchImpl: opts.fetchImpl,
-      headers: opts.token
+    this.client = new Gitlab({
+      host: baseUrl,
+      // gitbeaker generates a fresh AbortSignal.timeout() per request internally when this
+      // is set (confirmed by reading its source), so a stalled call fails predictably
+      // instead of hanging -- same class of gap the octokit adapter needed a manual fix for.
+      queryTimeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      ...(opts.token
         ? opts.tokenType === "oauth"
-          ? { Authorization: `Bearer ${opts.token}` }
-          : { "PRIVATE-TOKEN": opts.token }
-        : {},
+          ? { oauthToken: opts.token }
+          : { token: opts.token }
+        : {}),
+      ...(opts.requesterFn ? { requesterFn: opts.requesterFn } : {}),
     });
   }
 
@@ -81,47 +95,56 @@ export class GitLabRepository {
 
   async list(filter: ListFilter): Promise<Issue[]> {
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const params = new URLSearchParams({ per_page: String(limit) });
-    if (filter.status) params.set("state", mapStatusToGitLab(filter.status));
-    if (filter.assignee) params.set("assignee_username", filter.assignee);
-    if (filter.labels?.length) params.set("labels", filter.labels.join(","));
-
-    const raw = (await this.http.get<GlIssue[]>(`/api/v4/projects/${this.projectId}/issues?${params}`)) ?? [];
+    const raw = await this.call<GlIssue[]>(() =>
+      this.client.Issues.all({
+        projectId: this.projectId,
+        perPage: limit,
+        state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
+        assigneeUsername: filter.assignee ? [filter.assignee] : undefined,
+        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+      }),
+    );
     return raw.map(toDomain);
   }
 
   async get(key: string): Promise<Issue> {
     const iid = parseIid(key);
-    const raw = await this.http.get<GlIssue>(`/api/v4/projects/${this.projectId}/issues/${iid}`);
-    if (!raw) throw new Error(`gitlab: empty response for #${iid}`);
+    const raw = await this.call<GlIssue>(() => this.client.Issues.show(iid, { projectId: this.projectId }));
     return toDomain(raw);
   }
 
   async create(input: CreateInput): Promise<Issue> {
     this.requireAuth();
-    const body: Record<string, unknown> = { title: input.title, description: input.description ?? "" };
-    if (input.labels?.length) body.labels = input.labels.join(",");
-    const raw = await this.http.post<GlIssue>(`/api/v4/projects/${this.projectId}/issues`, body);
-    if (!raw) throw new Error("gitlab: create returned no body");
+    const assigneeIds = input.assignee ? [await this.resolveUserId(input.assignee)] : undefined;
+    const raw = await this.call<GlIssue>(() =>
+      this.client.Issues.create(this.projectId, input.title, {
+        description: input.description ?? "",
+        labels: input.labels?.length ? input.labels.join(",") : undefined,
+        assigneeIds,
+      }),
+    );
     return toDomain(raw);
   }
 
   async update(key: string, input: UpdateInput): Promise<Issue> {
     this.requireAuth();
     const iid = parseIid(key);
-    const body: Record<string, unknown> = {};
-    if (input.title !== undefined) body.title = input.title;
-    if (input.description !== undefined) body.description = input.description;
-    if (input.status !== undefined) body.state_event = mapStatusEventToGitLab(input.status);
-    if (input.labels !== undefined) body.labels = input.labels.join(",");
-    const raw = await this.http.put<GlIssue>(`/api/v4/projects/${this.projectId}/issues/${iid}`, body);
-    if (!raw) throw new Error("gitlab: update returned no body");
+    const options: Record<string, unknown> = {};
+    if (input.title !== undefined) options.title = input.title;
+    if (input.description !== undefined) options.description = input.description;
+    if (input.status !== undefined) options.stateEvent = mapStatusEventToGitLab(input.status);
+    if (input.labels !== undefined) options.labels = input.labels.join(",");
+    if (input.assignee !== undefined) {
+      options.assigneeIds = input.assignee ? [await this.resolveUserId(input.assignee)] : [];
+    }
+    const raw = await this.call<GlIssue>(() => this.client.Issues.edit(this.projectId, iid, options));
     return toDomain(raw);
   }
 
   async search(query: string, limit = 50): Promise<Issue[]> {
-    const params = new URLSearchParams({ search: query, per_page: String(limit) });
-    const raw = (await this.http.get<GlIssue[]>(`/api/v4/projects/${this.projectId}/issues?${params}`)) ?? [];
+    const raw = await this.call<GlIssue[]>(() =>
+      this.client.Issues.all({ projectId: this.projectId, search: query, perPage: limit }),
+    );
     return raw.map(toDomain);
   }
 
@@ -132,21 +155,54 @@ export class GitLabRepository {
 
   async listComments(key: string): Promise<Comment[]> {
     const iid = parseIid(key);
-    const raw = (await this.http.get<GlNote[]>(`/api/v4/projects/${this.projectId}/issues/${iid}/notes`)) ?? [];
+    const raw = await this.call<GlNote[]>(() => this.client.IssueNotes.all(this.projectId, iid));
     return raw.map(noteToDomain);
   }
 
   async addComment(key: string, body: string): Promise<Comment> {
     this.requireAuth();
     const iid = parseIid(key);
-    const raw = await this.http.post<GlNote>(`/api/v4/projects/${this.projectId}/issues/${iid}/notes`, { body });
-    if (!raw) throw new Error("gitlab: add comment returned no body");
+    const raw = await this.call<GlNote>(() => this.client.IssueNotes.create(this.projectId, iid, body));
     return noteToDomain(raw);
   }
+
+  /**
+   * GitLab's assignee write contract takes a numeric user ID, not a username
+   * (`assignee_ids: number[]`, confirmed against @gitbeaker/rest's generated
+   * types) — the exact gap the old hand-rolled adapter had (never resolved
+   * this, never even attempted to set assignee at all). GitLab's own username
+   * filter is an exact match, but we still confirm the returned user's
+   * username matches exactly before trusting its id.
+   */
+  private async resolveUserId(username: string): Promise<number> {
+    const users = await this.call<GlUser[]>(() => this.client.Users.all({ username }));
+    const match = users.find((u) => u.username === username);
+    if (!match) throw new Error(`gitlab: no user found with username "${username}"`);
+    return match.id;
+  }
+
+  /** Runs a gitbeaker call and maps GitbeakerRequestError onto this project's shared error taxonomy. */
+  private async call<T>(fn: () => Promise<unknown>): Promise<T> {
+    try {
+      return (await fn()) as T;
+    } catch (err) {
+      if (err instanceof GitbeakerRequestError) {
+        const status = err.cause?.response?.status ?? 500;
+        const url = err.cause?.request?.url ?? "";
+        if (status === 404) throw new IssueNotFoundError("gitlab", url);
+        throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
+      }
+      throw err;
+    }
+  }
+}
+
+function redact(text: string): string {
+  return text.replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"').slice(0, 2000);
 }
 
-function parseIid(key: string): string {
-  return key.replace(/^#/, "");
+function parseIid(key: string): number {
+  return Number(key.replace(/^#/, ""));
 }
 
 function mapStatusToGitLab(status: Status): "opened" | "closed" {

package/src/adapters/jira.ts

@@ -1,36 +1,52 @@
 /**
- * Jira adapter — driven implementation of IssueRepository/CommentCapable against the
- * Jira Cloud/Server REST API v2 (docs: https://developer.atlassian.com/cloud/jira/platform/rest/v2/).
+ * Jira adapter — driven implementation of IssueRepository/CommentCapable against
+ * the Jira Cloud REST API v2, via jira.js's Version2Client (github.com/MrRefactoring/jira.js)
+ * rather than a hand-rolled HTTP client: a mature, actively-maintained,
+ * TypeScript-native client generated directly from Atlassian's own OpenAPI spec.
  * Status changes go through Jira's workflow transitions, not a direct field PUT —
  * Jira statuses are workflow-owned, so we resolve the transition whose name matches
  * the mapped target status and post to it.
+ *
+ * NOTE: assignee is deliberately NOT handled in create()/update() here — out of
+ * scope for this migration per explicit user direction, even though the mature
+ * client's `UserDetails.accountId` typing would make the fix straightforward
+ * (see RESEARCH.md for the full analysis of the bug this leaves unfixed).
  */
+import { Version2Client } from "jira.js";
+import type { HttpException } from "jira.js";
+import type { AxiosAdapter } from "axios";
 import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
 import { parsePriority } from "../domain/issue.js";
-import { type FetchLike, HttpClient } from "./http.js";
+import { ApiError, IssueNotFoundError } from "./errors.js";
 
 /**
  * Basic-auth mode (email + API token) hits the tenant's own *.atlassian.net
  * domain directly. OAuth 2.0 (3LO) mode (accessToken + cloudId, see
  * auth/jira-oauth.ts) instead goes through api.atlassian.com/ex/jira/{cloudId}
  * with a Bearer token — Atlassian does not accept 3LO tokens against the
- * tenant domain directly. Exactly one of the two auth modes must be given.
+ * tenant domain directly; jira.js resolves that gateway routing itself when
+ * given `authentication.oauth2`. Exactly one of the two auth modes must be given.
  */
 export type JiraOptions = JiraBasicAuthOptions | JiraOAuthOptions;
 
+const DEFAULT_TIMEOUT_MS = 30_000;
+
 export interface JiraBasicAuthOptions {
   baseUrl: string;
   email: string;
   token: string;
   project?: string;
-  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  /** Injected in tests instead of a real network call — see axios's AxiosRequestConfig.adapter. */
+  axiosAdapter?: AxiosAdapter;
 }
 
 export interface JiraOAuthOptions {
   accessToken: string;
   cloudId: string;
   project?: string;
-  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  axiosAdapter?: AxiosAdapter;
 }
 
 function isOAuthOptions(opts: JiraOptions): opts is JiraOAuthOptions {
@@ -58,22 +74,26 @@ interface JiraIssue {
   self: string;
   fields: JiraIssueFields;
 }
-interface JiraTransition {
-  id: string;
-  name: string;
-}
 interface JiraComment {
-  id: string;
-  body: string;
-  created: string;
-  updated: string;
-  author?: { displayName: string };
+  id?: string;
+  comment?: string;
+  created?: string;
+  updated?: string;
+  author?: { displayName?: string };
+}
+interface JiraFieldDetails {
+  id?: string;
+  name?: string;
+  custom?: boolean;
+  schema?: { type: string; items?: string };
 }
 
 export class JiraRepository {
   readonly name: string;
-  private readonly http: HttpClient;
+  private readonly client: Version2Client;
   private readonly project?: string;
+  /** display name (lowercased) -> { fieldId, schema type/items }, populated lazily from client.issueFields.getFields(). */
+  private customFieldCache?: Map<string, { id: string; type: string; items?: string }>;
 
   constructor(name: string, opts: JiraOptions) {
     this.name = name;
@@ -81,23 +101,23 @@ export class JiraRepository {
 
     if (isOAuthOptions(opts)) {
       if (!opts.accessToken || !opts.cloudId) throw new Error("jira: accessToken and cloudId are required for OAuth mode");
-      this.http = new HttpClient({
-        baseUrl: `https://api.atlassian.com/ex/jira/${opts.cloudId}`,
-        backend: "jira",
-        fetchImpl: opts.fetchImpl,
-        headers: { Authorization: `Bearer ${opts.accessToken}` },
+      this.client = new Version2Client({
+        authentication: { oauth2: { accessToken: opts.accessToken, cloudId: opts.cloudId } },
+        // axios's own native, tested timeout handling -- a stalled call fails predictably
+        // instead of hanging (see RESEARCH.md for the octokit throttling-plugin hang this
+        // migration found and fixed; jira.js/axios has no equivalent auto-retry-and-wait
+        // behavior by default, but had no explicit timeout either until now).
+        baseRequestConfig: { timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(opts.axiosAdapter ? { adapter: opts.axiosAdapter } : {}) },
       });
       return;
     }
 
     if (!opts.baseUrl) throw new Error("jira: baseUrl is required");
     if (!opts.email || !opts.token) throw new Error("jira: email and token are required");
-    const basic = Buffer.from(`${opts.email}:${opts.token}`).toString("base64");
-    this.http = new HttpClient({
-      baseUrl: opts.baseUrl,
-      backend: "jira",
-      fetchImpl: opts.fetchImpl,
-      headers: { Authorization: `Basic ${basic}` },
+    this.client = new Version2Client({
+      host: opts.baseUrl,
+      authentication: { basic: { email: opts.email, apiToken: opts.token } },
+      baseRequestConfig: { timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(opts.axiosAdapter ? { adapter: opts.axiosAdapter } : {}) },
     });
   }
 
@@ -113,11 +133,25 @@ export class JiraRepository {
   }
 
   async get(key: string): Promise<Issue> {
-    const raw = await this.http.get<JiraIssue>(`/rest/api/2/issue/${key}`);
-    if (!raw) throw new Error(`jira: empty response for ${key}`);
+    const raw = await this.call<JiraIssue>(() => this.client.issues.getIssue({ issueIdOrKey: key }), key);
     return toDomain(raw);
   }
 
+  /** Runs a jira.js call and maps its HttpException onto this project's shared error taxonomy. */
+  private async call<T>(fn: () => Promise<unknown>, key?: string): Promise<T> {
+    try {
+      return (await fn()) as T;
+    } catch (err) {
+      const status = (err as Partial<HttpException>)?.status;
+      if (typeof status === "number") {
+        if (status === 404) throw new IssueNotFoundError("jira", key ?? "?");
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ApiError("jira", "?", key ?? "?", status, redact(message));
+      }
+      throw err;
+    }
+  }
+
   async create(input: CreateInput): Promise<Issue> {
     const project = input.project ?? this.project;
     if (!project) throw new Error("jira: project is required (pass project or set a default)");
@@ -132,8 +166,8 @@ export class JiraRepository {
     if (input.priority && input.priority !== "none") {
       fields.priority = { name: mapPriorityToJira(input.priority) };
     }
-    const result = await this.http.post<{ key: string }>("/rest/api/2/issue", { fields });
-    if (!result) throw new Error("jira: create returned no body");
+    if (input.customFields) await this.applyCustomFields(fields, input.customFields);
+    const result = await this.call<{ key: string }>(() => this.client.issues.createIssue({ fields } as never));
     return this.get(result.key);
   }
 
@@ -143,8 +177,10 @@ export class JiraRepository {
     if (input.description !== undefined) fields.description = input.description;
     if (input.priority !== undefined) fields.priority = { name: mapPriorityToJira(input.priority) };
     if (input.labels !== undefined) fields.labels = input.labels;
+    if (input.customFields) await this.applyCustomFields(fields, input.customFields);
+    // assignee intentionally not handled here — see file header.
     if (Object.keys(fields).length > 0) {
-      await this.http.put(`/rest/api/2/issue/${key}`, { fields });
+      await this.call(() => this.client.issues.editIssue({ issueIdOrKey: key, fields }), key);
     }
     if (input.status !== undefined) {
       await this.transitionTo(key, input.status, input.resolution);
@@ -163,28 +199,33 @@ export class JiraRepository {
   }
 
   async listComments(key: string): Promise<Comment[]> {
-    const result = await this.http.get<{ comments: JiraComment[] }>(`/rest/api/2/issue/${key}/comment`);
+    const result = await this.call<{ comments?: JiraComment[] }>(
+      () => this.client.issueComments.getComments({ issueIdOrKey: key }),
+      key,
+    );
     return (result?.comments ?? []).map(commentToDomain);
   }
 
   async addComment(key: string, body: string): Promise<Comment> {
-    const raw = await this.http.post<JiraComment>(`/rest/api/2/issue/${key}/comment`, { body });
-    if (!raw) throw new Error("jira: add comment returned no body");
+    const raw = await this.call<JiraComment>(
+      () => this.client.issueComments.addComment({ issueIdOrKey: key, comment: body }),
+      key,
+    );
     return commentToDomain(raw);
   }
 
   private async searchJql(jql: string, limit: number): Promise<Issue[]> {
-    const result = await this.http.post<{ issues: JiraIssue[] }>("/rest/api/2/search", {
-      jql,
-      maxResults: limit,
-    });
+    const result = await this.call<{ issues?: JiraIssue[] }>(() =>
+      this.client.issueSearch.searchForIssuesUsingJqlPost({ jql, maxResults: limit }),
+    );
     return (result?.issues ?? []).map(toDomain);
   }
 
   private async transitionTo(key: string, status: Status, resolution?: string): Promise<void> {
     const target = mapStatusToJira(status);
-    const result = await this.http.get<{ transitions: JiraTransition[] }>(
-      `/rest/api/2/issue/${key}/transitions`,
+    const result = await this.call<{ transitions?: { id: string; name: string }[] }>(
+      () => this.client.issues.getTransitions({ issueIdOrKey: key }),
+      key,
     );
     const transitions = result?.transitions ?? [];
     const match = transitions.find((t) => t.name.toLowerCase() === target.toLowerCase());
@@ -192,10 +233,51 @@ export class JiraRepository {
       const available = transitions.map((t) => t.name).join(", ");
       throw new Error(`jira: no transition matching "${target}" (available: ${available})`);
     }
-    const body: Record<string, unknown> = { transition: { id: match.id } };
-    if (resolution) body.fields = { resolution: { name: resolution } };
-    await this.http.post(`/rest/api/2/issue/${key}/transitions`, body);
+    const fields = resolution ? { resolution: { name: resolution } } : undefined;
+    await this.call(() => this.client.issues.doTransition({ issueIdOrKey: key, transition: { id: match.id }, fields }), key);
+  }
+
+  /**
+   * Resolves each custom field's display name to its `customfield_XXXXX` ID via
+   * client.issueFields.getFields() (GET /rest/api/2/field) -- not a hand-maintained
+   * map -- and coerces the given string value to the shape that field's own Jira
+   * schema type expects (a plain "option"/select field wants `{value}`, an array
+   * field splits on commas, everything else passes through as a raw string).
+   */
+  private async applyCustomFields(fields: Record<string, unknown>, customFields: Record<string, string>): Promise<void> {
+    for (const [displayName, rawValue] of Object.entries(customFields)) {
+      const field = await this.resolveCustomField(displayName);
+      fields[field.id] = coerceCustomFieldValue(field, rawValue);
+    }
+  }
+
+  private async resolveCustomField(displayName: string): Promise<{ id: string; type: string; items?: string }> {
+    if (!this.customFieldCache) {
+      const all = await this.call<JiraFieldDetails[]>(() => this.client.issueFields.getFields());
+      this.customFieldCache = new Map(
+        all
+          .filter((f) => f.custom && f.id && f.name)
+          .map((f) => [f.name!.toLowerCase(), { id: f.id!, type: f.schema?.type ?? "string", items: f.schema?.items }]),
+      );
+    }
+    const field = this.customFieldCache.get(displayName.toLowerCase());
+    if (!field) throw new Error(`jira: unknown custom field "${displayName}"`);
+    return field;
+  }
+}
+
+function coerceCustomFieldValue(field: { type: string; items?: string }, rawValue: string): unknown {
+  if (field.type === "array") {
+    const parts = rawValue.split(",").map((v) => v.trim()).filter(Boolean);
+    return field.items === "option" ? parts.map((v) => ({ value: v })) : parts;
   }
+  if (field.type === "option") return { value: rawValue };
+  if (field.type === "number") return Number(rawValue);
+  return rawValue;
+}
+
+function redact(text: string): string {
+  return text.replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"').slice(0, 2000);
 }
 
 function jqlQuote(value: string): string {
@@ -302,8 +384,8 @@ function toDomain(j: JiraIssue): Issue {
 
 function commentToDomain(c: JiraComment): Comment {
   return {
-    id: c.id,
-    body: c.body,
+    id: c.id ?? "",
+    body: c.comment ?? "",
     author: c.author?.displayName,
     createdAt: c.created,
     updatedAt: c.updated,

package/src/auth/enigma-source.ts

@@ -0,0 +1,65 @@
+/**
+ * Optional credential source: a running Enigma vault (github.com/DanyPops/enigma),
+ * if one happens to be configured on this machine. Purely additive — Tickets
+ * has never imported Enigma's package and never will; this talks to Enigma's
+ * loopback HTTP API using only @danypops/daemon-kit, which Tickets already
+ * depends on for its own daemon plumbing. Enigma's discovery contract is three
+ * stable, documented constants (its state-directory name and its handle/token
+ * filenames), not an import of Enigma's own source.
+ *
+ * Never creates Enigma's handle or token files — those are strictly Enigma's
+ * own job on its first boot. A consumer that could mint them would be a real
+ * security problem, not a convenience. Absence of either file means "Enigma
+ * isn't running or isn't configured for this backend," not an error: every
+ * failure path here resolves `undefined` rather than throwing, and the whole
+ * attempt is time-bounded so a slow or hung Enigma can never stall Tickets'
+ * own startup.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { readDaemonHandle, resolveDaemonPaths } from "@danypops/daemon-kit/paths";
+import { createVaultClient, type RefreshableAccessToken } from "@danypops/daemon-kit/vault";
+
+const ENIGMA_STATE_DIRECTORY_NAME = "enigma";
+const ENIGMA_HANDLE_FILENAME = "handle.json";
+const ENIGMA_TOKEN_FILENAME = "token";
+const ENIGMA_LOOKUP_TIMEOUT_MS = 500;
+
+export interface TryEnigmaCredentialEnv {
+	env?: Record<string, string | undefined>;
+	/** Injectable for tests; production default is the real fetch, bounded by AbortSignal.timeout. */
+	fetchImpl?: typeof fetch;
+}
+
+export type TryEnigmaCredential = (backend: string, opts?: TryEnigmaCredentialEnv) => Promise<RefreshableAccessToken | undefined>;
+
+export const tryEnigmaCredential: TryEnigmaCredential = async (backend, opts = {}) => {
+	const env = opts.env ?? process.env;
+	const paths = resolveDaemonPaths(
+		{ stateDirectoryName: ENIGMA_STATE_DIRECTORY_NAME, handleFilename: ENIGMA_HANDLE_FILENAME, tokenFilename: ENIGMA_TOKEN_FILENAME, databaseFilename: "", systemdUnitName: "" },
+		{ env },
+	);
+
+	const handle = readDaemonHandle(paths.handle);
+	if (!handle) return undefined; // Enigma isn't running -- not an error, just not present
+
+	if (!existsSync(paths.token)) return undefined; // never ensureAuthToken here -- read-only, never mint Enigma's own token
+	let token: string;
+	try {
+		token = readFileSync(paths.token, "utf8").trim();
+	} catch {
+		return undefined;
+	}
+
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const client = createVaultClient({
+		baseUrl: `http://${handle.host}:${handle.port}`,
+		authToken: token,
+		fetchImpl: (url, init) => fetchImpl(url, { ...init, signal: AbortSignal.timeout(ENIGMA_LOOKUP_TIMEOUT_MS) }),
+	});
+
+	try {
+		return await client.getCredentials(backend);
+	} catch {
+		return undefined; // unreachable, timed out, or any other transport failure -- fall through silently
+	}
+};

package/src/config/config.ts

@@ -12,6 +12,7 @@ import { GitLabRepository } from "../adapters/gitlab.js";
 import { JiraRepository } from "../adapters/jira.js";
 import type { IssueRepository } from "../ports/repository.js";
 import { isTokenFresh, loadToken } from "../auth/token-store.js";
+import { type TryEnigmaCredential, tryEnigmaCredential } from "../auth/enigma-source.js";
 
 export interface BackendConfig {
   /** Adapter type: "github" | "gitlab" | "jira". Falls back to the config key when omitted. */
@@ -55,19 +56,27 @@ function resolveToken(cfg: BackendConfig, env: NodeJS.ProcessEnv, envFallback: s
 }
 
 /**
- * Prefers a locally stored, still-fresh delegated OAuth token (see auth/,
- * populated by `tickets auth login`) over a static config/env PAT, per the
- * general "delegated auth over static token" precedence this project follows
- * for GitHub, GitLab, and Jira — see RESEARCH.md for the auth flows each
- * backend actually supports (device flow for GitHub/GitLab, authorization
- * code for Jira, which has no device flow or PKCE).
+ * Resolution order, highest priority first: (1) a running Enigma vault, if
+ * one happens to be configured for this backend — entirely optional, never a
+ * hard dependency, and bounded so Tickets never waits long for it (see
+ * auth/enigma-source.ts); (2) a locally stored, still-fresh delegated OAuth
+ * token (see auth/token-store.ts, populated by `tickets auth login`); (3) a
+ * static config/env PAT. (1) is additive to the pre-Enigma precedence this
+ * project already followed for GitHub, GitLab, and Jira — see RESEARCH.md
+ * for the auth flows each backend actually supports (device flow for
+ * GitHub/GitLab, authorization code for Jira, which has no device flow or
+ * PKCE).
  */
-function preferredAuth(
+export async function preferredAuth(
   name: string,
   cfg: BackendConfig,
   env: NodeJS.ProcessEnv,
   envFallback: string,
-): { token: string | undefined; oauth: boolean; extra?: Record<string, string> } {
+  tryEnigma: TryEnigmaCredential = tryEnigmaCredential,
+): Promise<{ token: string | undefined; oauth: boolean; extra?: Record<string, string> }> {
+  const fromEnigma = await tryEnigma(name, { env });
+  if (fromEnigma) return { token: fromEnigma.accessToken, oauth: true, extra: fromEnigma.extra };
+
   const stored = loadToken(name, { env });
   if (stored && isTokenFresh(stored)) {
     return { token: stored.accessToken, oauth: true, extra: stored.extra };
@@ -80,45 +89,47 @@ function preferredAuth(
  * inferrable purely from environment variables when not present in the config file.
  * Config-file entries take precedence over bare env-var inference for the same name.
  */
-export function buildRepositories(
+export async function buildRepositories(
   config: Config,
   env: NodeJS.ProcessEnv = process.env,
-): Record<string, IssueRepository> {
+  tryEnigma: TryEnigmaCredential = tryEnigmaCredential,
+): Promise<Record<string, IssueRepository>> {
   const repos: Record<string, IssueRepository> = {};
 
   for (const [name, cfg] of Object.entries(config.backends)) {
     const type = cfg.type ?? name;
-    const repo = createRepository(name, type, cfg, env);
+    const repo = await createRepository(name, type, cfg, env, tryEnigma);
     if (repo) repos[name] = repo;
   }
 
   if (!repos.github && (env.GITHUB_OWNER || env.GITHUB_TOKEN)) {
-    const repo = createRepository("github", "github", {}, env);
+    const repo = await createRepository("github", "github", {}, env, tryEnigma);
     if (repo) repos.github = repo;
   }
   if (!repos.gitlab && (env.GITLAB_PROJECT || env.GITLAB_TOKEN)) {
-    const repo = createRepository("gitlab", "gitlab", {}, env);
+    const repo = await createRepository("gitlab", "gitlab", {}, env, tryEnigma);
     if (repo) repos.gitlab = repo;
   }
   if (!repos.jira && env.JIRA_URL) {
-    const repo = createRepository("jira", "jira", {}, env);
+    const repo = await createRepository("jira", "jira", {}, env, tryEnigma);
     if (repo) repos.jira = repo;
   }
 
   return repos;
 }
 
-function createRepository(
+async function createRepository(
   name: string,
   type: string,
   cfg: BackendConfig,
   env: NodeJS.ProcessEnv,
-): IssueRepository | undefined {
+  tryEnigma: TryEnigmaCredential,
+): Promise<IssueRepository | undefined> {
   switch (type) {
     case "github": {
       const owner = cfg.owner ?? env.GITHUB_OWNER;
       if (!owner) return undefined;
-      const auth = preferredAuth(name, cfg, env, "GITHUB_TOKEN");
+      const auth = await preferredAuth(name, cfg, env, "GITHUB_TOKEN", tryEnigma);
       return new GitHubRepository(name, {
         owner,
         repo: cfg.repo ?? env.GITHUB_REPO,
@@ -129,7 +140,7 @@ function createRepository(
     case "gitlab": {
       const project = cfg.project ?? env.GITLAB_PROJECT;
       if (!project) return undefined;
-      const auth = preferredAuth(name, cfg, env, "GITLAB_TOKEN");
+      const auth = await preferredAuth(name, cfg, env, "GITLAB_TOKEN", tryEnigma);
       return new GitLabRepository(name, {
         projectId: project,
         token: auth.token,
@@ -138,7 +149,7 @@ function createRepository(
       });
     }
     case "jira": {
-      const auth = preferredAuth(name, cfg, env, "JIRA_API_TOKEN");
+      const auth = await preferredAuth(name, cfg, env, "JIRA_API_TOKEN", tryEnigma);
       if (auth.oauth && auth.token && auth.extra?.cloudId) {
         return new JiraRepository(name, {
           accessToken: auth.token,

package/src/daemon/bootstrap.ts

@@ -48,14 +48,14 @@ export interface BootstrappedDaemon {
 const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_CHECKPOINT_INTERVAL_MS = 10 * 60_000;
 
-export function bootstrap(opts: BootstrapOptions = {}): BootstrappedDaemon {
+export async function bootstrap(opts: BootstrapOptions = {}): Promise<BootstrappedDaemon> {
   const paths = resolveDaemonPaths(TICKETS_DAEMON_NAMES, opts.pathEnv);
   const token = ensureAuthToken(paths.token, "Tickets");
   const db = openSqliteWithPragmas(paths.database, { migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS] });
   const ledger = new Ledger(db);
   const focusStore = new FocusStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
-  const repos = opts.repos ?? buildRepositories(opts.config ?? loadConfig());
+  const repos = opts.repos ?? (await buildRepositories(opts.config ?? loadConfig()));
   const service = new TicketService(repos);
   const version = opts.version ?? "0.0.0-dev";
 

package/src/daemon/main.ts

@@ -10,7 +10,7 @@ import { readPackageVersion } from "@danypops/daemon-kit/version";
 import { bootstrap } from "./bootstrap.js";
 
 const version = readPackageVersion(new URL("../../package.json", import.meta.url), "Tickets");
-const { options } = bootstrap({ version });
+const { options } = await bootstrap({ version });
 
 runDaemonProcess({
   ...options,

package/src/domain/issue.ts

@@ -79,6 +79,8 @@ export interface CreateInput {
   project?: string;
   issueType?: string;
   parentKey?: string;
+  /** Backend-specific custom fields keyed by display name (e.g. Jira's "QE Priority"), resolved to the backend's own field ID by the adapter. Not every backend supports this (only Jira does today). */
+  customFields?: Record<string, string>;
 }
 
 export interface UpdateInput {
@@ -89,6 +91,8 @@ export interface UpdateInput {
   labels?: string[];
   assignee?: string;
   resolution?: string;
+  /** Backend-specific custom fields keyed by display name (e.g. Jira's "QE Priority"), resolved to the backend's own field ID by the adapter. Not every backend supports this (only Jira does today). */
+  customFields?: Record<string, string>;
 }
 
 export interface ListFilter {

package/src/index.ts

@@ -14,10 +14,12 @@ export {
   configDir,
 } from "./config/config.js";
 export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./daemon/ops.js";
+export type { FocusStatus, TicketFocusState } from "./daemon/focus.js";
 export {
   createTicketsClient,
   ensureDaemonRunning,
   ticketsPaths,
+  type EnsureDaemonOptions,
   type TicketsRpcClient,
 } from "./client/tickets-client.js";