@danypops/tickets 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",

package/src/adapters/github.ts

@@ -18,10 +18,10 @@
  * 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 { Octokit } from "octokit";
+import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../domain/issue.js";
 import { ApiError, AuthRequiredError, IssueNotFoundError } from "./errors.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;

package/src/adapters/gitlab.ts

@@ -10,11 +10,11 @@
  * 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 { GitbeakerRequestError, type RequesterType, type ResourceOptions } from "@gitbeaker/requester-utils";
+import { Gitlab } from "@gitbeaker/rest";
+import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../domain/issue.js";
 import { ApiError, AuthRequiredError, InvalidUrlError, IssueNotFoundError } from "./errors.js";
 
 export interface GitLabOptions {
@@ -80,11 +80,7 @@ export class GitLabRepository {
       // 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"
-          ? { oauthToken: opts.token }
-          : { token: opts.token }
-        : {}),
+      ...(opts.token ? (opts.tokenType === "oauth" ? { oauthToken: opts.token } : { token: opts.token }) : {}),
       ...(opts.requesterFn ? { requesterFn: opts.requesterFn } : {}),
     });
   }
@@ -144,9 +140,7 @@ export class GitLabRepository {
   // project is accepted for IssueRepository interface parity but ignored --
   // GitLab's scope (projectId) is fixed at construction, not overridable per call.
   async search(query: string, limit = 50, _project?: string): Promise<Issue[]> {
-    const raw = await this.call<GlIssue[]>(() =>
-      this.client.Issues.all({ projectId: this.projectId, search: query, perPage: limit }),
-    );
+    const raw = await this.call<GlIssue[]>(() => this.client.Issues.all({ projectId: this.projectId, search: query, perPage: limit }));
     return raw.map(toDomain);
   }
 
@@ -275,9 +269,7 @@ export function validateUrl(rawUrl: string): void {
     throw new InvalidUrlError(`gitlab: scheme must be http(s) (got ${parsed.protocol})`);
   }
   if (parsed.protocol === "http:" && parsed.hostname !== "localhost") {
-    throw new InvalidUrlError(
-      `gitlab: http:// only allowed for localhost (got ${parsed.hostname}); use https:// for remote instances`,
-    );
+    throw new InvalidUrlError(`gitlab: http:// only allowed for localhost (got ${parsed.hostname}); use https:// for remote instances`);
   }
   if (isIP(parsed.hostname) && isPrivateIp(parsed.hostname)) {
     throw new InvalidUrlError("gitlab: private IP addresses are not allowed (blocks SSRF)");

package/src/adapters/http.ts

@@ -80,7 +80,5 @@ export class HttpClient {
 
 /** Strips anything that looks like a bearer/basic credential from error bodies before logging. */
 function redact(text: string): string {
-  return text
-    .replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"')
-    .slice(0, 2000);
+  return text.replace(/"(token|password|secret|api_key|authorization)"\s*:\s*"[^"]*"/gi, '"$1":"[redacted]"').slice(0, 2000);
 }

package/src/adapters/jira.ts

@@ -12,15 +12,15 @@
  * client's `UserDetails.accountId` typing would make the fix straightforward
  * (see RESEARCH.md for the full analysis of the bug this leaves unfixed).
  */
-import { AgileClient, Version2Client } from "jira.js";
-import type { Config as JiraClientConfig, HttpException } from "jira.js";
+
 import type { AxiosAdapter } from "axios";
-import type { Comment, CreateInput, Issue, IssueLink, ListFilter, Status, UpdateInput } from "../domain/issue.js";
-import { parsePriority } from "../domain/issue.js";
-import { ApiError, IssueNotFoundError } from "./errors.js";
+import type { HttpException, Config as JiraClientConfig } from "jira.js";
+import { AgileClient, Version2Client } from "jira.js";
+import type { Comment, CreateInput, Issue, IssueLink, ListFilter, parsePriority, Status, UpdateInput } from "../domain/issue.js";
 import type { Template } from "../domain/template.js";
 import { buildTemplateBody, extractTemplateSections } from "../domain/template.js";
 import * as manifest from "../manifest/manifest.js";
+import { ApiError, IssueNotFoundError } from "./errors.js";
 
 /**
  * Basic-auth mode (email + API token) hits the tenant's own *.atlassian.net
@@ -39,6 +39,10 @@ export interface JiraBasicAuthOptions {
   email: string;
   token: string;
   project?: string;
+  /** Additional project keys the poller's background sync also pools into the ledger, beyond the single default `project` above -- see buildSyncQuery(). */
+  syncProjects?: string[];
+  /** When true, the poller's background sync also pools everything assigned to the authenticated user (JQL `assignee = currentUser()`), regardless of project -- covers projects not listed in `project`/`syncProjects`. */
+  syncMine?: boolean;
   timeoutMs?: number;
   /** Injected in tests instead of a real network call — see axios's AxiosRequestConfig.adapter. */
   axiosAdapter?: AxiosAdapter;
@@ -55,6 +59,8 @@ export interface JiraOAuthOptions {
   accessToken: string;
   cloudId: string;
   project?: string;
+  syncProjects?: string[];
+  syncMine?: boolean;
   timeoutMs?: number;
   axiosAdapter?: AxiosAdapter;
   configDir?: string;
@@ -125,6 +131,8 @@ export class JiraRepository {
   /** Same auth/host config Version2Client was built from -- reused lazily by agileClient() so the Agile API client (board/quickfilter resolution) authenticates identically without duplicating the OAuth-vs-basic branching in the constructor below. */
   private readonly clientConfig: JiraClientConfig;
   private readonly project?: string;
+  private readonly syncProjects: string[];
+  private readonly syncMine: boolean;
   private readonly configDir?: string;
   /** display name (lowercased) -> { fieldId, schema type/items }, populated lazily from client.issueFields.getFields(). */
   private customFieldCache?: Map<string, { id: string; type: string; items?: string }>;
@@ -136,6 +144,8 @@ export class JiraRepository {
   constructor(name: string, opts: JiraOptions) {
     this.name = name;
     this.project = opts.project;
+    this.syncProjects = opts.syncProjects ?? [];
+    this.syncMine = opts.syncMine ?? false;
     this.configDir = opts.configDir;
 
     if (this.configDir) {
@@ -188,7 +198,11 @@ export class JiraRepository {
     ]);
     const issue = this.toDomain(raw);
     if (remoteLinks.length > 0) {
-      issue.externalLinks = remoteLinks.map((link) => ({ url: link.object?.url ?? "", title: link.object?.title, type: link.application?.name }));
+      issue.externalLinks = remoteLinks.map((link) => ({
+        url: link.object?.url ?? "",
+        title: link.object?.title,
+        type: link.application?.name,
+      }));
     }
     return issue;
   }
@@ -256,18 +270,12 @@ export class JiraRepository {
   }
 
   async listComments(key: string): Promise<Comment[]> {
-    const result = await this.call<{ comments?: JiraComment[] }>(
-      () => this.client.issueComments.getComments({ issueIdOrKey: key }),
-      key,
-    );
+    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.call<JiraComment>(
-      () => this.client.issueComments.addComment({ issueIdOrKey: key, comment: body }),
-      key,
-    );
+    const raw = await this.call<JiraComment>(() => this.client.issueComments.addComment({ issueIdOrKey: key, comment: body }), key);
     return commentToDomain(raw);
   }
 
@@ -276,6 +284,25 @@ export class JiraRepository {
     return this.searchJql(query, limit);
   }
 
+  /**
+   * SyncScopeExpandable -- widens what the poller's own background sync pools
+   * into the local ledger beyond the single default `project` list() falls
+   * back to: every configured project (default plus syncProjects) ORed with
+   * "assignee = currentUser()" when syncMine is set, so issues assigned to
+   * you in a project nobody thought to list still get pooled. Returns
+   * undefined -- letting the poller fall back to plain list() -- when
+   * neither syncProjects nor syncMine adds anything beyond the default
+   * project's own existing behavior.
+   */
+  buildSyncQuery(): string | undefined {
+    const projects = [...new Set([this.project, ...this.syncProjects].filter((p): p is string => Boolean(p)))];
+    if (projects.length <= 1 && !this.syncMine) return undefined;
+    const clauses: string[] = [];
+    if (projects.length > 0) clauses.push(`project in (${projects.map(jqlQuote).join(", ")})`);
+    if (this.syncMine) clauses.push("assignee = currentUser()");
+    return `${clauses.join(" OR ")} ORDER BY created DESC`;
+  }
+
   /**
    * BoardQuickFilterDiscoverable -- resolves a board's quick filter (the same object
    * a board view's `quickFilter=` URL param and a backlog view's `customFilter=`
@@ -526,7 +553,9 @@ function formatCustomFieldValue(raw: unknown): string | undefined {
   if (typeof raw === "string") return raw;
   if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
   if (Array.isArray(raw)) {
-    const names = raw.map((item) => (item && typeof item === "object" && "name" in item ? String((item as { name: unknown }).name) : undefined)).filter((n): n is string => !!n);
+    const names = raw
+      .map((item) => (item && typeof item === "object" && "name" in item ? String((item as { name: unknown }).name) : undefined))
+      .filter((n): n is string => !!n);
     return names.length > 0 ? names.join(", ") : undefined;
   }
   if (raw && typeof raw === "object") {
@@ -538,7 +567,10 @@ function formatCustomFieldValue(raw: unknown): string | undefined {
 
 function coerceCustomFieldValue(field: { type: string; items?: string }, rawValue: string): unknown {
   if (field.type === "array") {
-    const parts = rawValue.split(",").map((v) => v.trim()).filter(Boolean);
+    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 };

package/src/application/service.ts

@@ -14,10 +14,21 @@ import {
   hasFieldDiscovery,
   hasRawQuery,
   hasStatusDiscovery,
+  hasSyncScopeExpansion,
   hasTemplateDiscovery,
   type IssueRepository,
 } from "../ports/repository.js";
 
+export interface BackendCapabilities {
+  readonly name: string;
+  readonly supportsRawQuery: boolean;
+  readonly supportsFieldDiscovery: boolean;
+  readonly supportsStatusDiscovery: boolean;
+  readonly supportsTemplateDiscovery: boolean;
+  readonly supportsBoardQuickFilterDiscovery: boolean;
+  readonly supportsBoardFilterDiscovery: boolean;
+}
+
 export class UnknownBackendError extends Error {
   constructor(backend: string, known: string[]) {
     super(`unknown backend "${backend}" (known: ${known.join(", ") || "none configured"})`);
@@ -39,9 +50,17 @@ export class TicketService {
     return Object.keys(this.repos);
   }
 
-  /** Every configured backend's name plus which optional capabilities its own repository actually implements -- lets a driving adapter (the CLI, pi-tickets) branch on real capability instead of a hardcoded backend name. */
-  backendCapabilities(): { name: string; supportsRawQuery: boolean }[] {
-    return Object.values(this.repos).map((repo) => ({ name: repo.name, supportsRawQuery: hasRawQuery(repo) }));
+  /** Every configured backend's name plus which optional capabilities its own repository actually implements -- lets a driving adapter (the CLI, pi-tickets, the Vehicle tool-availability sync) branch on real capability instead of a hardcoded backend name. */
+  backendCapabilities(): BackendCapabilities[] {
+    return Object.values(this.repos).map((repo) => ({
+      name: repo.name,
+      supportsRawQuery: hasRawQuery(repo),
+      supportsFieldDiscovery: hasFieldDiscovery(repo),
+      supportsStatusDiscovery: hasStatusDiscovery(repo),
+      supportsTemplateDiscovery: hasTemplateDiscovery(repo),
+      supportsBoardQuickFilterDiscovery: hasBoardQuickFilterDiscovery(repo),
+      supportsBoardFilterDiscovery: hasBoardFilterDiscovery(repo),
+    }));
   }
 
   /**
@@ -71,6 +90,25 @@ export class TicketService {
     return this.repo(backend).list(filter);
   }
 
+  /**
+   * Fetches issues for the poller's own background sync pass (see
+   * daemon/poller.ts). Prefers a backend's own expanded sync scope
+   * (SyncScopeExpandable -- Jira: multiple configured projects plus
+   * everything assigned to the authenticated user, unioned into one query)
+   * over its plain default-project list() when one is configured; falls
+   * back to list() otherwise, so a backend with no sync scope configured
+   * (or with no such capability at all, e.g. GitHub/GitLab) behaves exactly
+   * as before.
+   */
+  async syncFetch(backend: string, limit: number): Promise<Issue[]> {
+    const repo = this.repo(backend);
+    if (hasSyncScopeExpansion(repo) && hasRawQuery(repo)) {
+      const query = repo.buildSyncQuery();
+      if (query) return repo.runQuery(query, limit);
+    }
+    return repo.list({ limit });
+  }
+
   async get(ref: string): Promise<Issue> {
     const { backend, key } = parseRef(ref);
     return this.repo(backend).get(key);

package/src/auth/browser.ts

@@ -29,7 +29,13 @@ export function openUrl(url: string, opts: { platform?: NodeJS.Platform; spawner
   const platform = opts.platform ?? process.platform;
   const spawner = opts.spawner ?? defaultSpawner;
 
-  if (platform === "darwin") return spawner("open", [url]);
-  if (platform === "win32") return spawner("cmd", ["/c", "start", '""', url]);
-  return spawner("xdg-open", [url]);
+  if (platform === "darwin") {
+    spawner("open", [url]);
+    return;
+  }
+  if (platform === "win32") {
+    spawner("cmd", ["/c", "start", '""', url]);
+    return;
+  }
+  spawner("xdg-open", [url]);
 }

package/src/auth/device-flow.ts

@@ -54,11 +54,7 @@ export interface DeviceFlowToken {
   refreshToken?: string;
 }
 
-async function postForm(
-  fetchImpl: FetchLike,
-  url: string,
-  params: Record<string, string>,
-): Promise<Record<string, unknown>> {
+async function postForm(fetchImpl: FetchLike, url: string, params: Record<string, string>): Promise<Record<string, unknown>> {
   const res = await fetchImpl(url, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
@@ -80,8 +76,7 @@ export async function requestDeviceAuthorization(config: DeviceFlowConfig): Prom
     deviceCode: body.device_code,
     userCode: body.user_code,
     verificationUri: String(body.verification_uri ?? ""),
-    verificationUriComplete:
-      typeof body.verification_uri_complete === "string" ? body.verification_uri_complete : undefined,
+    verificationUriComplete: typeof body.verification_uri_complete === "string" ? body.verification_uri_complete : undefined,
     expiresInSeconds: Number(body.expires_in ?? 900),
     intervalSeconds: Number(body.interval ?? 5),
   };
@@ -130,8 +125,7 @@ export async function pollForToken(
       accessToken: body.access_token,
       tokenType: String(body.token_type ?? "Bearer"),
       scope: typeof body.scope === "string" ? body.scope : undefined,
-      expiresAt:
-        typeof body.expires_in === "number" ? new Date(Date.now() + body.expires_in * 1000).toISOString() : undefined,
+      expiresAt: typeof body.expires_in === "number" ? new Date(Date.now() + body.expires_in * 1000).toISOString() : undefined,
       refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : undefined,
     };
   }

package/src/auth/gh-cli.ts

@@ -14,9 +14,7 @@
  */
 export type GhCliTokenResult = { ok: true; token: string } | { ok: false; reason: string };
 
-export interface SpawnLike {
-	(command: string[]): { stdout: ReadableStream<Uint8Array> | number; exited: Promise<number> };
-}
+export type SpawnLike = (command: string[]) => { stdout: ReadableStream<Uint8Array> | number; exited: Promise<number> };
 
 const defaultSpawn: SpawnLike = (command) => Bun.spawn(command, { stdout: "pipe" });
 
@@ -26,21 +24,26 @@ const defaultSpawn: SpawnLike = (command) => Bun.spawn(command, { stdout: "pipe"
  * prompts, never falls back to a device flow itself.
  */
 export async function readGhCliToken(user?: string, spawn: SpawnLike = defaultSpawn): Promise<GhCliTokenResult> {
-	const command = user ? ["gh", "auth", "token", "--user", user] : ["gh", "auth", "token"];
-	let proc: ReturnType<SpawnLike>;
-	try {
-		proc = spawn(command);
-	} catch {
-		return { ok: false, reason: "gh CLI not found -- install it (cli.github.com) or use a different login method" };
-	}
-	const [stdout, code] = await Promise.all([
-		proc.stdout instanceof ReadableStream ? new Response(proc.stdout).text() : Promise.resolve(""),
-		proc.exited,
-	]);
-	if (code !== 0) {
-		return { ok: false, reason: user ? `gh CLI has no authenticated account named "${user}" -- run \`gh auth login\` first` : "gh CLI is not authenticated -- run `gh auth login` first" };
-	}
-	const token = stdout.trim();
-	if (!token) return { ok: false, reason: "gh auth token returned no token" };
-	return { ok: true, token };
+  const command = user ? ["gh", "auth", "token", "--user", user] : ["gh", "auth", "token"];
+  let proc: ReturnType<SpawnLike>;
+  try {
+    proc = spawn(command);
+  } catch {
+    return { ok: false, reason: "gh CLI not found -- install it (cli.github.com) or use a different login method" };
+  }
+  const [stdout, code] = await Promise.all([
+    proc.stdout instanceof ReadableStream ? new Response(proc.stdout).text() : Promise.resolve(""),
+    proc.exited,
+  ]);
+  if (code !== 0) {
+    return {
+      ok: false,
+      reason: user
+        ? `gh CLI has no authenticated account named "${user}" -- run \`gh auth login\` first`
+        : "gh CLI is not authenticated -- run `gh auth login` first",
+    };
+  }
+  const token = stdout.trim();
+  if (!token) return { ok: false, reason: "gh auth token returned no token" };
+  return { ok: true, token };
 }

package/src/auth/jira-oauth.ts

@@ -92,7 +92,9 @@ export function startCallbackServer(expectedState: string, port = 0): CallbackSe
       rejectCode?.(new JiraOAuthError("callback missing authorization code"));
       return;
     }
-    res.writeHead(200, { "Content-Type": "text/html" }).end("<html><body>Authorized. You can close this tab and return to the terminal.</body></html>");
+    res
+      .writeHead(200, { "Content-Type": "text/html" })
+      .end("<html><body>Authorized. You can close this tab and return to the terminal.</body></html>");
     resolveCode?.({ code, redirectUri: redirectUriFor() });
   });
 
@@ -118,12 +120,7 @@ export function startCallbackServer(expectedState: string, port = 0): CallbackSe
   };
 }
 
-export function buildAuthorizeUrl(opts: {
-  clientId: string;
-  redirectUri: string;
-  scope: string;
-  state: string;
-}): string {
+export function buildAuthorizeUrl(opts: { clientId: string; redirectUri: string; scope: string; state: string }): string {
   const url = new URL(ATLASSIAN_AUTHORIZE_URL);
   url.searchParams.set("audience", "api.atlassian.com");
   url.searchParams.set("client_id", opts.clientId);

package/src/cli/index.ts

@@ -6,16 +6,16 @@
  * ledger or a backend adapter directly.
  */
 import { Command } from "commander";
-import type { CreateInput, ListFilter, Priority, Status, UpdateInput } from "../domain/issue.js";
-import { parseStatus } from "../domain/issue.js";
-import { createTicketsClient, type TicketsRpcClient } from "../client/tickets-client.js";
 import { openUrl } from "../auth/browser.js";
-import { loginWithGitHubDeviceFlow } from "../auth/github-oauth.js";
 import { readGhCliToken } from "../auth/gh-cli.js";
-import { gitlabDeviceEndpoints, loginWithGitLabDeviceFlow } from "../auth/gitlab-oauth.js";
+import { loginWithGitHubDeviceFlow } from "../auth/github-oauth.js";
+import { loginWithGitLabDeviceFlow } from "../auth/gitlab-oauth.js";
 import { loginWithJiraAuthorizationCode } from "../auth/jira-oauth.js";
-import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
 import { promptMaskedSecret } from "../auth/masked-prompt.js";
+import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
+import { createTicketsClient, type TicketsRpcClient } from "../client/tickets-client.js";
+import type { CreateInput, ListFilter, Priority, Status, UpdateInput } from "../domain/issue.js";
+import { parseStatus } from "../domain/issue.js";
 import { installTicketsService, systemctlTickets, systemdUnitPath } from "./systemd-service.js";
 
 function printJson(value: unknown): void {
@@ -40,7 +40,7 @@ program
   .command("list")
   .description("list issues on a backend")
   .requiredOption("-b, --backend <name>", "backend name")
-  .option("--project <key>", "project key/id override (e.g. reach CNF or OCPBUGS on a Jira backend defaulting to another project)")
+  .option("--project <key>", "project key/id override (e.g. reach ENG or OPS on a Jira backend defaulting to another project)")
   .option("--status <status>", "filter by status")
   .option("--assignee <user>", "filter by assignee")
   .option("--label <label...>", "filter by label(s)")
@@ -109,7 +109,7 @@ program
   .command("search <query>")
   .description("search issues on a backend")
   .requiredOption("-b, --backend <name>", "backend name")
-  .option("--project <key>", "project key/id override (e.g. reach CNF or OCPBUGS on a Jira backend defaulting to another project)")
+  .option("--project <key>", "project key/id override (e.g. reach ENG or OPS on a Jira backend defaulting to another project)")
   .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
   .action(async (query: string, opts) => {
     await withClient((client) => client.call("issue.search", { backend: opts.backend, query, limit: opts.limit, project: opts.project }));
@@ -200,7 +200,9 @@ focus
     await withClient((client) => client.call("focus.clear", {}));
   });
 
-const discoverCmd = program.command("discover").description("discover and persist backend-specific mappings (custom fields, statuses) or a description template");
+const discoverCmd = program
+  .command("discover")
+  .description("discover and persist backend-specific mappings (custom fields, statuses) or a description template");
 
 discoverCmd
   .command("fields")
@@ -227,7 +229,12 @@ discoverCmd
   .option("--sample-size <n>", "how many recent issues to sample", (v) => Number.parseInt(v, 10))
   .action(async (opts) => {
     await withClient((client) =>
-      client.call("discover.template", { backend: opts.backend, project: opts.project, issueType: opts.issueType, sampleSize: opts.sampleSize }),
+      client.call("discover.template", {
+        backend: opts.backend,
+        project: opts.project,
+        issueType: opts.issueType,
+        sampleSize: opts.sampleSize,
+      }),
     );
   });
 
@@ -240,7 +247,9 @@ discoverCmd
     await withClient((client) => client.call("discover.board_filter", { backend: opts.backend, boardId: opts.board }));
   });
 
-const queryCmd = program.command("query").description("save and run named raw backend queries (Jira JQL) -- e.g. a board's sprint or backlog view");
+const queryCmd = program
+  .command("query")
+  .description("save and run named raw backend queries (Jira JQL) -- e.g. a board's sprint or backlog view");
 
 queryCmd
   .command("save <name>")
@@ -249,7 +258,9 @@ queryCmd
   .requiredOption("--jql <jql>", "the raw query string (Jira JQL)")
   .option("--description <text>", "human-readable note about what this query is")
   .action(async (name: string, opts) => {
-    await withClient((client) => client.call("query.save", { name, backend: opts.backend, query: opts.jql, description: opts.description }));
+    await withClient((client) =>
+      client.call("query.save", { name, backend: opts.backend, query: opts.jql, description: opts.description }),
+    );
   });
 
 queryCmd
@@ -276,12 +287,16 @@ queryCmd
 
 discoverCmd
   .command("board_quickfilter")
-  .description("resolve a Jira board's quick filter id to its JQL fragment -- board view's quickFilter=, backlog view's customFilter=, are the same id")
+  .description(
+    "resolve a Jira board's quick filter id to its JQL fragment -- board view's quickFilter=, backlog view's customFilter=, are the same id",
+  )
   .requiredOption("-b, --backend <name>", "backend name")
   .requiredOption("--board <id>", "board id", (v) => Number.parseInt(v, 10))
   .requiredOption("--quick-filter <id>", "quick filter id", (v) => Number.parseInt(v, 10))
   .action(async (opts) => {
-    await withClient((client) => client.call("discover.board_quickfilter", { backend: opts.backend, boardId: opts.board, quickFilterId: opts.quickFilter }));
+    await withClient((client) =>
+      client.call("discover.board_quickfilter", { backend: opts.backend, boardId: opts.board, quickFilterId: opts.quickFilter }),
+    );
   });
 
 const daemon = program.command("daemon").description("manage the tickets daemon process");
@@ -348,7 +363,9 @@ daemon
 
 const service = program
   .command("service")
-  .description("deploy the tickets daemon as a persistent systemd --user service (Linux; survives logout/reboot, unlike `daemon start`'s on-demand spawn)");
+  .description(
+    "deploy the tickets daemon as a persistent systemd --user service (Linux; survives logout/reboot, unlike `daemon start`'s on-demand spawn)",
+  );
 
 service
   .command("install")
@@ -395,7 +412,10 @@ auth
   .option("--client-secret <secret>", "OAuth client secret (Jira only — GitHub/GitLab device flow needs none)")
   .option("--url <baseUrl>", "self-managed GitLab URL (defaults to gitlab.com)")
   .option("--scope <scope>", "space-delimited OAuth scope override")
-  .option("--gh-cli [account]", "github only: reuse an already-authenticated gh CLI session instead of the device flow (omit value for gh's active account)")
+  .option(
+    "--gh-cli [account]",
+    "github only: reuse an already-authenticated gh CLI session instead of the device flow (omit value for gh's active account)",
+  )
   .action(async (opts) => {
     const type = opts.type ?? opts.backend;
     try {
@@ -403,12 +423,20 @@ auth
         const result = await readGhCliToken(opts.ghCli === true ? undefined : opts.ghCli);
         if (!result.ok) throw new Error(result.reason);
         saveToken(opts.backend, { accessToken: result.token });
-        printJson({ backend: opts.backend, status: "authorized", via: "gh-cli", note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token" });
+        printJson({
+          backend: opts.backend,
+          status: "authorized",
+          via: "gh-cli",
+          note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token",
+        });
         return;
       }
       if (type === "github") {
         const clientId = opts.clientId ?? process.env.GITHUB_OAUTH_CLIENT_ID;
-        if (!clientId) throw new Error("--client-id or GITHUB_OAUTH_CLIENT_ID is required (or pass --gh-cli [account] to reuse an already-authenticated gh CLI session instead)");
+        if (!clientId)
+          throw new Error(
+            "--client-id or GITHUB_OAUTH_CLIENT_ID is required (or pass --gh-cli [account] to reuse an already-authenticated gh CLI session instead)",
+          );
         const token = await loginWithGitHubDeviceFlow({
           clientId,
           scope: opts.scope,
@@ -421,7 +449,12 @@ auth
             }
           },
         });
-        saveToken(opts.backend, { accessToken: token.accessToken, refreshToken: token.refreshToken, expiresAt: token.expiresAt, scope: token.scope });
+        saveToken(opts.backend, {
+          accessToken: token.accessToken,
+          refreshToken: token.refreshToken,
+          expiresAt: token.expiresAt,
+          scope: token.scope,
+        });
       } else if (type === "gitlab") {
         const clientId = opts.clientId ?? process.env.GITLAB_OAUTH_CLIENT_ID;
         if (!clientId) throw new Error("--client-id or GITLAB_OAUTH_CLIENT_ID is required");
@@ -439,12 +472,19 @@ auth
             }
           },
         });
-        saveToken(opts.backend, { accessToken: token.accessToken, refreshToken: token.refreshToken, expiresAt: token.expiresAt, scope: token.scope });
+        saveToken(opts.backend, {
+          accessToken: token.accessToken,
+          refreshToken: token.refreshToken,
+          expiresAt: token.expiresAt,
+          scope: token.scope,
+        });
       } else if (type === "jira") {
         const clientId = opts.clientId ?? process.env.JIRA_OAUTH_CLIENT_ID;
         const clientSecret = opts.clientSecret ?? process.env.JIRA_OAUTH_CLIENT_SECRET;
         if (!clientId || !clientSecret) {
-          throw new Error("--client-id/--client-secret or JIRA_OAUTH_CLIENT_ID/JIRA_OAUTH_CLIENT_SECRET are required (Atlassian 3LO has no public-client flow)");
+          throw new Error(
+            "--client-id/--client-secret or JIRA_OAUTH_CLIENT_ID/JIRA_OAUTH_CLIENT_SECRET are required (Atlassian 3LO has no public-client flow)",
+          );
         }
         const token = await loginWithJiraAuthorizationCode({
           clientId,
@@ -494,7 +534,11 @@ auth
       return;
     }
     saveToken(backend, { accessToken: value });
-    printJson({ backend, status: "stored", note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token" });
+    printJson({
+      backend,
+      status: "stored",
+      note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token",
+    });
   });
 
 auth

package/src/client/tickets-client.ts

@@ -7,11 +7,11 @@
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
 import type { DaemonHandle } from "@danypops/vehicle-server/paths";
 import { ensureAuthToken, readDaemonHandle, resolveDaemonPaths } from "@danypops/vehicle-server/paths";
-import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
+import { TICKETS_DAEMON_NAMES, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "../daemon/ops.js";
 import { packageRoot } from "../util/package-root.js";
-import { TICKETS_DAEMON_NAMES, type TicketOpInputs, type TicketOperation, type TicketOpOutputs } from "../daemon/ops.js";
 
 export function ticketsPaths(env?: Record<string, string | undefined>) {
   return resolveDaemonPaths(TICKETS_DAEMON_NAMES, env ? { env } : {});
@@ -58,9 +58,7 @@ export interface EnsureDaemonOptions {
 
 const DEFAULT_SPAWN_TIMEOUT_MS = 4_000;
 
-export async function ensureDaemonRunning(
-  opts: EnsureDaemonOptions = {},
-): Promise<{ baseUrl: string; token: string }> {
+export async function ensureDaemonRunning(opts: EnsureDaemonOptions = {}): Promise<{ baseUrl: string; token: string }> {
   const paths = ticketsPaths();
   const token = ensureAuthToken(paths.token, "Tickets");
 
@@ -70,9 +68,7 @@ export async function ensureDaemonRunning(
   }
 
   if (opts.autoStart === false) {
-    throw new Error(
-      "tickets daemon is not running. Start it with `npm run daemon` (or `bun run src/daemon/main.ts`).",
-    );
+    throw new Error("tickets daemon is not running. Start it with `npm run daemon` (or `bun run src/daemon/main.ts`).");
   }
 
   spawnDaemon();

package/src/config/config.ts

@@ -6,16 +6,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { type TryEnigmaCredential, tryEnigmaCredential } from "@danypops/enigma-client";
 import type { MaintenanceTask } from "@danypops/vehicle-server/daemon";
 import type { Logger } from "@danypops/vehicle-server/logging";
+import { parse as parseYaml } from "yaml";
 import { GitHubRepository } from "../adapters/github.js";
 import { GitLabRepository } from "../adapters/gitlab.js";
 import { JiraRepository } from "../adapters/jira.js";
-import type { IssueRepository } from "../ports/repository.js";
 import type { TicketService } from "../application/service.js";
 import { isTokenFresh, loadToken } from "../auth/token-store.js";
-import { type TryEnigmaCredential, tryEnigmaCredential } from "@danypops/enigma-client";
+import type { IssueRepository } from "../ports/repository.js";
 
 export interface BackendConfig {
   /** Adapter type: "github" | "gitlab" | "jira". Falls back to the config key when omitted. */
@@ -27,6 +27,10 @@ export interface BackendConfig {
   owner?: string;
   project?: string;
   repo?: string;
+  /** Jira only: additional project keys the background poller also pools into the ledger, beyond the single default `project` above. */
+  syncProjects?: string[];
+  /** Jira only: when true, the background poller also pools everything assigned to the authenticated user, regardless of project. */
+  syncMine?: boolean;
 }
 
 export interface Config {
@@ -58,6 +62,22 @@ function resolveToken(cfg: BackendConfig, env: NodeJS.ProcessEnv, envFallback: s
   return env[envFallback];
 }
 
+/** Config wins over the env var; the env var is a comma-separated list (JIRA_SYNC_PROJECTS=ENG,OPS). */
+function resolveSyncProjects(cfg: BackendConfig, env: NodeJS.ProcessEnv): string[] | undefined {
+  if (cfg.syncProjects) return cfg.syncProjects;
+  const raw = env.JIRA_SYNC_PROJECTS;
+  if (!raw) return undefined;
+  return raw
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean);
+}
+
+function resolveSyncMine(cfg: BackendConfig, env: NodeJS.ProcessEnv): boolean {
+  if (cfg.syncMine !== undefined) return cfg.syncMine;
+  return /^(1|true|yes)$/i.test(env.JIRA_SYNC_MINE ?? "");
+}
+
 /**
  * Resolution order, highest priority first: (1) a running Enigma vault, if
  * one happens to be configured for this backend — entirely optional, never a
@@ -142,6 +162,8 @@ export function createBackendRefreshTask(
   buildRepos: BuildRepositories,
   intervalMs: number,
   logger?: Logger,
+  /** Re-syncs Vehicle tool availability (createTicketsVehicleRegistry's syncDiscoverAvailability) against the freshly swapped-in backend set -- called after every successful refresh, so a Jira credential added or removed at runtime flips discover.* tool visibility without a daemon restart. Optional: a caller with no vehicleRegistry yet (tests, injected repos) just skips it. */
+  onRefreshed?: (service: TicketService) => void,
 ): MaintenanceTask {
   return {
     name: "backend-refresh",
@@ -158,6 +180,7 @@ export function createBackendRefreshTask(
         return;
       }
       service.setRepos(fresh);
+      onRefreshed?.(service);
       const after = new Set(Object.keys(fresh));
       const added = [...after].filter((backend) => !before.has(backend));
       const removed = [...before].filter((backend) => !after.has(backend));
@@ -205,6 +228,8 @@ async function createRepository(
           accessToken: auth.token,
           cloudId: auth.extra.cloudId,
           project: cfg.project ?? env.JIRA_PROJECT,
+          syncProjects: resolveSyncProjects(cfg, env),
+          syncMine: resolveSyncMine(cfg, env),
           configDir: configDir(),
         });
       }
@@ -216,6 +241,8 @@ async function createRepository(
         email,
         token: auth.token,
         project: cfg.project ?? env.JIRA_PROJECT,
+        syncProjects: resolveSyncProjects(cfg, env),
+        syncMine: resolveSyncMine(cfg, env),
         configDir: configDir(),
       });
     }

package/src/daemon/bootstrap.ts

@@ -6,20 +6,20 @@
  * root instead of hitting real GitHub/GitLab/Jira or the real home directory.
  */
 import type { Database } from "bun:sqlite";
+import type { StartDaemonOptions } from "@danypops/vehicle-server/daemon";
 import { createLogger, type Logger } from "@danypops/vehicle-server/logging";
 import { ensureAuthToken, type PathEnvironment, resolveDaemonPaths } from "@danypops/vehicle-server/paths";
 import { checkpoint, openSqliteWithPragmas } from "@danypops/vehicle-server/storage";
-import type { StartDaemonOptions } from "@danypops/vehicle-server/daemon";
 import { TicketService } from "../application/service.js";
-import { buildRepositories, type BuildRepositories, type Config, createBackendRefreshTask, loadConfig } from "../config/config.js";
+import { type BuildRepositories, buildRepositories, type Config, createBackendRefreshTask, loadConfig } from "../config/config.js";
 import type { IssueRepository } from "../ports/repository.js";
+import { createTicketsVehicleRegistry, syncDiscoverAvailability } from "../vehicle/tickets-vehicle.js";
 import { FOCUS_MIGRATIONS, FocusStore } from "./focus.js";
-import { Ledger, LEDGER_MIGRATIONS } from "./ledger.js";
-import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "./saved-queries.js";
+import { LEDGER_MIGRATIONS, Ledger } from "./ledger.js";
 import { TICKETS_DAEMON_NAMES } from "./ops.js";
-import { buildApp, type TicketsAppDeps } from "./server.js";
 import { createSyncTask } from "./poller.js";
-import { createTicketsVehicleRegistry } from "../vehicle/tickets-vehicle.js";
+import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "./saved-queries.js";
+import { buildApp, type TicketsAppDeps } from "./server.js";
 
 export interface BootstrapOptions {
   pathEnv?: PathEnvironment;
@@ -79,7 +79,16 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
   // the registry field itself -- createTicketsVehicleRegistry never reads
   // deps.vehicleRegistry, so this ordering is safe (see server.ts's own
   // comment on why the registry is built outside it, not imported into it).
-  const vehicleRegistry = createTicketsVehicleRegistry({ service, ledger, focusStore, queries, token, version, logger, onShutdownRequested } as TicketsAppDeps);
+  const vehicleRegistry = createTicketsVehicleRegistry({
+    service,
+    ledger,
+    focusStore,
+    queries,
+    token,
+    version,
+    logger,
+    onShutdownRequested,
+  } as TicketsAppDeps);
 
   const options: StartDaemonOptions = {
     daemonLabel: "Tickets",
@@ -95,7 +104,16 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
       // Only when repos came from real config/env/Enigma resolution -- an
       // injected test fixture (opts.repos) has no config to re-resolve from.
       ...(opts.repos === undefined
-        ? [createBackendRefreshTask(service, config, buildRepos, opts.backendRefreshIntervalMs ?? DEFAULT_BACKEND_REFRESH_INTERVAL_MS, logger)]
+        ? [
+            createBackendRefreshTask(
+              service,
+              config,
+              buildRepos,
+              opts.backendRefreshIntervalMs ?? DEFAULT_BACKEND_REFRESH_INTERVAL_MS,
+              logger,
+              (refreshedService) => syncDiscoverAvailability(vehicleRegistry, refreshedService),
+            ),
+          ]
         : []),
     ],
     buildApp: () =>

package/src/daemon/ledger.ts

@@ -122,9 +122,10 @@ export class Ledger {
   }
 
   stats(): { backend: string; count: number }[] {
-    const rows = this.db
-      .query("SELECT backend, COUNT(*) as count FROM issues GROUP BY backend ORDER BY backend")
-      .all() as { backend: string; count: number }[];
+    const rows = this.db.query("SELECT backend, COUNT(*) as count FROM issues GROUP BY backend ORDER BY backend").all() as {
+      backend: string;
+      count: number;
+    }[];
     return rows;
   }
 }

package/src/daemon/poller.ts

@@ -5,8 +5,9 @@
  * network, bad creds) is logged and skipped; it never crashes the daemon
  * and never blocks other backends' syncs.
  */
-import type { Logger } from "@danypops/vehicle-server/logging";
+
 import type { MaintenanceTask } from "@danypops/vehicle-server/daemon";
+import type { Logger } from "@danypops/vehicle-server/logging";
 import type { TicketService } from "../application/service.js";
 import type { Ledger } from "./ledger.js";
 
@@ -22,7 +23,7 @@ export async function syncOnce(
   const results: { backend: string; synced: number; error?: string }[] = [];
   for (const backend of backends) {
     try {
-      const issues = await service.list(backend, { limit: DEFAULT_SYNC_LIMIT });
+      const issues = await service.syncFetch(backend, DEFAULT_SYNC_LIMIT);
       const synced = ledger.upsertMany(backend, issues);
       results.push({ backend, synced });
       logger?.debug("ledger sync ok", { backend, synced });
@@ -42,12 +43,7 @@ export async function syncOnce(
  * service is synced on this task's very next run, no daemon restart or
  * task rebuild needed.
  */
-export function createSyncTask(
-  service: TicketService,
-  ledger: Ledger,
-  intervalMs: number,
-  logger?: Logger,
-): MaintenanceTask {
+export function createSyncTask(service: TicketService, ledger: Ledger, intervalMs: number, logger?: Logger): MaintenanceTask {
   return {
     name: "ledger-sync",
     intervalMs,

package/src/daemon/server.ts

@@ -6,16 +6,17 @@
  * stand up. Every operation here has a CLI command (cli/index.ts) and a
  * pi-tickets tool action — no operation exists only for one caller.
  */
-import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBearerToken } from "@danypops/vehicle-server/rpc-http";
-import type { Logger } from "@danypops/vehicle-server/logging";
-import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
+
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
+import type { Logger } from "@danypops/vehicle-server/logging";
+import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBearerToken } from "@danypops/vehicle-server/rpc-http";
 import { AuthRequiredError, IssueNotFoundError } from "../adapters/errors.js";
 import { NotSupportedError, type TicketService, UnknownBackendError } from "../application/service.js";
 import { parseRef } from "../domain/issue.js";
 import { FocusError, type FocusStore } from "./focus.js";
 import type { Ledger } from "./ledger.js";
-import { TICKET_OPERATIONS, type TicketOpInputs, type TicketOperation, type TicketOpOutputs } from "./ops.js";
+import { TICKET_OPERATIONS, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "./ops.js";
 import { SavedQueryNotFoundError, type SavedQueryStore } from "./saved-queries.js";
 
 export interface TicketsAppDeps {

package/src/domain/issue.ts

@@ -15,14 +15,7 @@ export function parsePriority(value: unknown): Priority {
   return (PRIORITIES as readonly string[]).includes(lower) ? (lower as Priority) : "none";
 }
 
-export const STATUSES = [
-  "backlog",
-  "todo",
-  "in_progress",
-  "in_review",
-  "done",
-  "canceled",
-] as const;
+export const STATUSES = ["backlog", "todo", "in_progress", "in_review", "done", "canceled"] as const;
 export type Status = (typeof STATUSES)[number];
 
 export function parseStatus(value: unknown, fallback: Status = "todo"): Status {

package/src/index.ts

@@ -1,35 +1,34 @@
-export * from "./domain/issue.js";
-export * from "./ports/repository.js";
 export * from "./adapters/errors.js";
-export { GitHubRepository, type GitHubOptions } from "./adapters/github.js";
-export { GitLabRepository, type GitLabOptions } from "./adapters/gitlab.js";
-export { JiraRepository, type JiraOptions } from "./adapters/jira.js";
-export { TicketService, UnknownBackendError, NotSupportedError } from "./application/service.js";
-export {
-  type BackendConfig,
-  type Config,
-  loadConfig,
-  buildRepositories,
-  defaultConfigPath,
-  configDir,
-} from "./config/config.js";
-export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./daemon/ops.js";
-export type { FocusStatus, TicketFocusState } from "./daemon/focus.js";
+export { type GitHubOptions, GitHubRepository } from "./adapters/github.js";
+export { type GitLabOptions, GitLabRepository } from "./adapters/gitlab.js";
+export { type JiraOptions, JiraRepository } from "./adapters/jira.js";
+export { NotSupportedError, TicketService, UnknownBackendError } from "./application/service.js";
+export { openUrl } from "./auth/browser.js";
+// Delegated OAuth (device flow for GitHub/GitLab, authorization code for Jira)
+// — see RESEARCH.md for why each backend gets a different flow.
+export * from "./auth/device-flow.js";
+export * from "./auth/github-oauth.js";
+export * from "./auth/gitlab-oauth.js";
+export * from "./auth/jira-oauth.js";
+export * from "./auth/token-store.js";
 export {
   createTicketsClient,
+  type EnsureDaemonOptions,
   ensureDaemonRunning,
   resolveVehicleClientTarget,
-  ticketsPaths,
-  type EnsureDaemonOptions,
   type TicketsRpcClient,
+  ticketsPaths,
   type VehicleClientTarget,
 } from "./client/tickets-client.js";
-
-// Delegated OAuth (device flow for GitHub/GitLab, authorization code for Jira)
-// — see RESEARCH.md for why each backend gets a different flow.
-export * from "./auth/device-flow.js";
-export * from "./auth/token-store.js";
-export { openUrl } from "./auth/browser.js";
-export * from "./auth/github-oauth.js";
-export * from "./auth/gitlab-oauth.js";
-export * from "./auth/jira-oauth.js";
+export {
+  type BackendConfig,
+  buildRepositories,
+  type Config,
+  configDir,
+  defaultConfigPath,
+  loadConfig,
+} from "./config/config.js";
+export type { FocusStatus, TicketFocusState } from "./daemon/focus.js";
+export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./daemon/ops.js";
+export * from "./domain/issue.js";
+export * from "./ports/repository.js";

package/src/ports/repository.ts

@@ -100,3 +100,20 @@ export interface BoardFilterDiscoverable {
 export function hasBoardFilterDiscovery(repo: IssueRepository): repo is IssueRepository & BoardFilterDiscoverable {
   return typeof (repo as Partial<BoardFilterDiscoverable>).discoverBoardFilterJql === "function";
 }
+
+/**
+ * Optional capability — lets a backend widen what the poller's own background
+ * sync pools into the local ledger beyond list()'s single default-project
+ * filter (Jira: additional named projects, plus everything assigned to the
+ * authenticated user, unioned into one JQL string). Returns undefined when
+ * nothing beyond the default scope is configured, so the poller falls back
+ * to plain list() unchanged. Jira only; GitHub/GitLab have no equivalent
+ * multi-project-plus-assignee query language to expand into.
+ */
+export interface SyncScopeExpandable {
+  buildSyncQuery(): string | undefined;
+}
+
+export function hasSyncScopeExpansion(repo: IssueRepository): repo is IssueRepository & SyncScopeExpandable {
+  return typeof (repo as Partial<SyncScopeExpandable>).buildSyncQuery === "function";
+}

package/src/vehicle/tickets-vehicle.ts

@@ -14,10 +14,18 @@
  * daemon.shutdown is deliberately excluded: it's an admin/lifecycle
  * operation, not something an agent should be able to call as a tool.
  */
-import { bindVehicleOperation, defineLooseObjectSchema, defineVehicleOperation, passthroughVehicleSchema, type VehicleEffect, type LooseObjectProperty } from "@danypops/vehicle-core";
+import {
+  bindVehicleOperation,
+  defineLooseObjectSchema,
+  defineVehicleOperation,
+  type LooseObjectProperty,
+  passthroughVehicleSchema,
+  type VehicleEffect,
+} from "@danypops/vehicle-core";
 import { VehicleRegistry } from "@danypops/vehicle-server";
-import { TICKET_OP_HANDLERS, type TicketsAppDeps } from "../daemon/server.js";
+import type { BackendCapabilities, TicketService } from "../application/service.js";
 import type { TicketOperation } from "../daemon/ops.js";
+import { TICKET_OP_HANDLERS, type TicketsAppDeps } from "../daemon/server.js";
 
 const OWNER = "tickets";
 
@@ -52,19 +60,38 @@ function definedEntriesOnly(input: Record<string, unknown>): Record<string, unkn
 }
 
 const OPERATIONS: readonly OperationSpec[] = [
-  { action: "backends.list", description: "Lists every configured backend name (github, gitlab, jira, ...).", effect: "read", properties: {}, required: [] },
+  {
+    action: "backends.list",
+    description: "Lists every configured backend name (github, gitlab, jira, ...).",
+    effect: "read",
+    properties: {},
+    required: [],
+  },
   {
     action: "issue.list",
     description: "Lists issues from one backend, optionally filtered.",
     effect: "read",
-    properties: { backend: stringProp, project: stringProp, status: stringProp, assignee: stringProp, labels: stringArrayProp, limit: numberProp },
+    properties: {
+      backend: stringProp,
+      project: stringProp,
+      status: stringProp,
+      assignee: stringProp,
+      labels: stringArrayProp,
+      limit: numberProp,
+    },
     required: ["backend"],
     mapInput: ({ backend, project, status, assignee, labels, limit }) => ({
       backend,
       filter: definedEntriesOnly({ project, status, assignee, labels, limit }),
     }),
   },
-  { action: "issue.get", description: "Gets one issue by its ref (e.g. \"github:#42\").", effect: "read", properties: { ref: stringProp }, required: ["ref"] },
+  {
+    action: "issue.get",
+    description: 'Gets one issue by its ref (e.g. "github:#42").',
+    effect: "read",
+    properties: { ref: stringProp },
+    required: ["ref"],
+  },
   {
     action: "issue.create",
     description: "Creates a new issue on a live backend -- a real, externally visible write, not a local draft.",
@@ -79,9 +106,27 @@ const OPERATIONS: readonly OperationSpec[] = [
     properties: { ref: stringProp, input: { type: "object" } },
     required: ["ref", "input"],
   },
-  { action: "issue.search", description: "Searches one backend's issues by text query.", effect: "read", properties: { backend: stringProp, query: stringProp, limit: numberProp, project: stringProp }, required: ["backend", "query"] },
-  { action: "issue.children", description: "Lists an issue's child issues.", effect: "read", properties: { ref: stringProp }, required: ["ref"] },
-  { action: "issue.comments", description: "Lists an issue's comments.", effect: "read", properties: { ref: stringProp }, required: ["ref"] },
+  {
+    action: "issue.search",
+    description: "Searches one backend's issues by text query.",
+    effect: "read",
+    properties: { backend: stringProp, query: stringProp, limit: numberProp, project: stringProp },
+    required: ["backend", "query"],
+  },
+  {
+    action: "issue.children",
+    description: "Lists an issue's child issues.",
+    effect: "read",
+    properties: { ref: stringProp },
+    required: ["ref"],
+  },
+  {
+    action: "issue.comments",
+    description: "Lists an issue's comments.",
+    effect: "read",
+    properties: { ref: stringProp },
+    required: ["ref"],
+  },
   {
     action: "issue.comment_add",
     description: "Adds a comment to an issue on its live backend -- a real, externally visible write.",
@@ -89,15 +134,51 @@ const OPERATIONS: readonly OperationSpec[] = [
     properties: { ref: stringProp, body: stringProp },
     required: ["ref", "body"],
   },
-  { action: "ledger.search", description: "Searches the local pooled-issue ledger (no live backend call).", effect: "read", properties: { query: stringProp, limit: numberProp }, required: ["query"] },
-  { action: "ledger.stats", description: "Per-backend counts of issues pooled into the local ledger.", effect: "read", properties: {}, required: [] },
-  { action: "focus.set", description: "Sets the currently focused issue, by ref.", effect: "local-write", properties: { ref: stringProp }, required: ["ref"] },
+  {
+    action: "ledger.search",
+    description: "Searches the local pooled-issue ledger (no live backend call).",
+    effect: "read",
+    properties: { query: stringProp, limit: numberProp },
+    required: ["query"],
+  },
+  {
+    action: "ledger.stats",
+    description: "Per-backend counts of issues pooled into the local ledger.",
+    effect: "read",
+    properties: {},
+    required: [],
+  },
+  {
+    action: "focus.set",
+    description: "Sets the currently focused issue, by ref.",
+    effect: "local-write",
+    properties: { ref: stringProp },
+    required: ["ref"],
+  },
   { action: "focus.get", description: "Gets the currently focused issue, if any.", effect: "read", properties: {}, required: [] },
-  { action: "focus.pause", description: "Pauses focus with an optional reason, without clearing it.", effect: "local-write", properties: { reason: stringProp }, required: [] },
+  {
+    action: "focus.pause",
+    description: "Pauses focus with an optional reason, without clearing it.",
+    effect: "local-write",
+    properties: { reason: stringProp },
+    required: [],
+  },
   { action: "focus.unpause", description: "Resumes a paused focus.", effect: "local-write", properties: {}, required: [] },
   { action: "focus.clear", description: "Clears the currently focused issue.", effect: "local-write", properties: {}, required: [] },
-  { action: "discover.fields", description: "Discovers a backend's custom field display names and IDs (Jira).", effect: "read", properties: { backend: stringProp }, required: ["backend"] },
-  { action: "discover.statuses", description: "Discovers a backend's real status names.", effect: "read", properties: { backend: stringProp }, required: ["backend"] },
+  {
+    action: "discover.fields",
+    description: "Discovers a backend's custom field display names and IDs (Jira).",
+    effect: "read",
+    properties: { backend: stringProp },
+    required: ["backend"],
+  },
+  {
+    action: "discover.statuses",
+    description: "Discovers a backend's real status names.",
+    effect: "read",
+    properties: { backend: stringProp },
+    required: ["backend"],
+  },
   {
     action: "discover.template",
     description: "Samples recent issues for a project/issueType and extracts a reusable description template (Jira).",
@@ -107,27 +188,36 @@ const OPERATIONS: readonly OperationSpec[] = [
   },
   {
     action: "discover.board_quickfilter",
-    description: "Resolves a Jira board's quick filter id to its JQL fragment -- the one-time step to turn a board/backlog view into a saved query.",
+    description:
+      "Resolves a Jira board's quick filter id to its JQL fragment -- the one-time step to turn a board/backlog view into a saved query.",
     effect: "read",
     properties: { backend: stringProp, boardId: numberProp, quickFilterId: numberProp },
     required: ["backend", "boardId", "quickFilterId"],
   },
   {
     action: "discover.board_filter",
-    description: "Resolves a Jira board's own real base scope -- its saved filter's JQL -- rather than assuming it tracks one named project.",
+    description:
+      "Resolves a Jira board's own real base scope -- its saved filter's JQL -- rather than assuming it tracks one named project.",
     effect: "read",
     properties: { backend: stringProp, boardId: numberProp },
     required: ["backend", "boardId"],
   },
   {
     action: "query.save",
-    description: "Saves a raw backend query (Jira JQL) under a name, so it can be run again later without retyping it -- e.g. a board's sprint or backlog view.",
+    description:
+      "Saves a raw backend query (Jira JQL) under a name, so it can be run again later without retyping it -- e.g. a board's sprint or backlog view.",
     effect: "local-write",
     properties: { name: stringProp, backend: stringProp, query: stringProp, description: stringProp },
     required: ["name", "backend", "query"],
   },
   { action: "query.list", description: "Lists every saved query.", effect: "read", properties: {}, required: [] },
-  { action: "query.remove", description: "Removes a saved query by name.", effect: "local-write", properties: { name: stringProp }, required: ["name"] },
+  {
+    action: "query.remove",
+    description: "Removes a saved query by name.",
+    effect: "local-write",
+    properties: { name: stringProp },
+    required: ["name"],
+  },
   {
     action: "query.run",
     description: "Runs a saved query by name against its backend and returns the matching issues.",
@@ -137,6 +227,54 @@ const OPERATIONS: readonly OperationSpec[] = [
   },
 ];
 
+/**
+ * The five discover.* operations only ever succeed against a backend whose
+ * repository implements the matching optional capability (Jira today,
+ * structurally -- never a hardcoded backend name). An operation none of the
+ * currently configured backends could possibly satisfy is marked
+ * unavailable so it never appears in the LLM's callable tool list in the
+ * first place, instead of being offered and then failing with
+ * NotSupportedError on the first real call.
+ */
+const DISCOVER_AVAILABILITY: readonly { action: TicketOperation; capability: keyof BackendCapabilities; reason: string }[] = [
+  { action: "discover.fields", capability: "supportsFieldDiscovery", reason: "no configured backend supports field discovery (Jira only)" },
+  {
+    action: "discover.statuses",
+    capability: "supportsStatusDiscovery",
+    reason: "no configured backend supports status discovery (Jira only)",
+  },
+  {
+    action: "discover.template",
+    capability: "supportsTemplateDiscovery",
+    reason: "no configured backend supports template discovery (Jira only)",
+  },
+  {
+    action: "discover.board_quickfilter",
+    capability: "supportsBoardQuickFilterDiscovery",
+    reason: "no configured backend supports board quick-filter discovery (Jira only)",
+  },
+  {
+    action: "discover.board_filter",
+    capability: "supportsBoardFilterDiscovery",
+    reason: "no configured backend supports board filter discovery (Jira only)",
+  },
+];
+
+/**
+ * Re-syncs the five discover.* operations' availability against the
+ * service's current backend set -- called once right after the registry is
+ * built, and again after every live backend refresh (config.ts's
+ * createBackendRefreshTask), so a Jira credential added or removed at
+ * runtime flips these tools' visibility without a daemon restart.
+ */
+export function syncDiscoverAvailability(registry: VehicleRegistry, service: TicketService): void {
+  const capabilities = service.backendCapabilities();
+  for (const { action, capability, reason } of DISCOVER_AVAILABILITY) {
+    const available = capabilities.some((backend) => backend[capability]);
+    registry.setAvailability(action, 1, available, available ? undefined : reason);
+  }
+}
+
 /**
  * Builds a VehicleRegistry exposing every real ticket operation, backed by
  * the exact same deps shape the daemon's own hand-rolled dispatch already
@@ -145,7 +283,11 @@ const OPERATIONS: readonly OperationSpec[] = [
  * this registry to the same base object afterward).
  */
 export function createTicketsVehicleRegistry(deps: Omit<TicketsAppDeps, "vehicleRegistry">): VehicleRegistry {
-  const registry = new VehicleRegistry({ name: "tickets", version: "1.0.0", description: "Unified issue tracking across GitHub, GitLab, and Jira." });
+  const registry = new VehicleRegistry({
+    name: "tickets",
+    version: "1.0.0",
+    description: "Unified issue tracking across GitHub, GitLab, and Jira.",
+  });
 
   for (const spec of OPERATIONS) {
     const operation = defineVehicleOperation({
@@ -167,5 +309,6 @@ export function createTicketsVehicleRegistry(deps: Omit<TicketsAppDeps, "vehicle
     );
   }
 
+  syncDiscoverAvailability(registry, deps.service);
   return registry;
 }