@danypops/tickets 0.10.1 → 0.10.4

package/README.md

@@ -18,11 +18,12 @@ GitHub/GitLab/Jira or opens the SQLite ledger directly. See
 ## Requirements
 
 - **[Bun](https://bun.sh) 1.1+.** The daemon uses `bun:sqlite` and
-  `Bun.serve` (via `@danypops/daemon-kit`); the CLI, library, and pi-tickets
-  extension are plain TypeScript but currently ship as source, run through
-  Bun rather than a compiled Node build.
-- `@danypops/daemon-kit` comes from the public npm registry (`^0.2.1`) —
-  no local checkout or `file:` path needed, `bun install` fetches it directly.
+  `Bun.serve` through `@danypops/vehicle-server`; the CLI, library, and
+  pi-tickets extension are plain TypeScript but currently ship as source and
+  run through Bun rather than a compiled Node build.
+- The published `@danypops/vehicle-*` packages provide the daemon, authenticated
+  RPC/Vehicle contracts, resilient client, Pi projection, and Armada service
+  integration. No local Vehicle checkout or `file:` dependency is required.
 
 ## Install
 
@@ -76,25 +77,25 @@ bun run src/cli/index.ts discover statuses -b jira
 bun run src/cli/index.ts discover template -b jira --project PROJ --issue-type Bug
 ```
 
-### Running the daemon persistently (systemd --user)
+### Running the daemon persistently (Armada)
 
-`daemon start` spawns the daemon on demand and it lives only as long as
-something keeps it alive. For a daemon that survives logout/reboot, install
-it as a systemd `--user` service instead (Linux only):
+`daemon start` is the on-demand path. For a daemon owned by the native service
+manager and reconciled from desired state, register it with Armada:
 
 ```bash
-bun run src/cli/index.ts service install   # writes + enables + (re)starts the unit
+bun run src/cli/index.ts service install    # Armada upsert + reconcile
+bun run src/cli/index.ts service uninstall  # Armada remove
+
+# Direct lifecycle actions currently target systemd --user (Linux):
 bun run src/cli/index.ts service status
 bun run src/cli/index.ts service stop
 bun run src/cli/index.ts service restart
-bun run src/cli/index.ts service path      # where the unit file lives
 ```
 
-`service install` points `ExecStart` at the exact `bun` binary and package
-checkout currently running the CLI, so re-running it after an upgrade (a new
-`npm`/`bun` global install, or a fresh checkout) picks up the new path
-immediately via `daemon-reload` + `enable` + `restart` — no manual `stop`
-needed first.
+`service install` records the exact Bun binary, CLI entry path, version, handle
+path, restart policy, and readiness probe in Armada's fleet manifest. Armada
+then projects that declaration through systemd, launchd, or Windows Task
+Scheduler. Re-run `service install` after upgrading or moving the package.
 
 Once installed as a package, the same commands are available as `tickets`
 and `tickets-daemon` (see `bin` in `package.json`).
@@ -273,13 +274,13 @@ member directory instead: `{ "packages": ["/path/to/tickets/packages/pi-tickets"
 ```bash
 bun install                # from the repo root -- links both workspace members
 bun run typecheck          # both packages
-bun test                   # both packages
+bun run test               # both packages, sequential isolated test processes
 ```
 
-Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take an
-injectable `fetchImpl`, and the daemon tests (`test/rpc/`, `test/sqlite/`, `test/process/`) run the real
-`@danypops/daemon-kit` `startDaemon()`/SQLite/HTTP stack against a scratch
-XDG root with a fake `IssueRepository`.
+Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take injectable
+transport implementations, and the daemon tests (`test/rpc/`, `test/sqlite/`,
+`test/process/`) run the real `@danypops/vehicle-server` daemon/SQLite/HTTP
+stack against a scratch XDG root with a fake `IssueRepository`.
 
 ## Architecture
 
@@ -292,13 +293,14 @@ Driver (inbound)              Application              Driven (outbound)
 └───────────────┘        │   + Ledger      │───────▶│ SQLite (Ledger)  │
                           │   + Poller)     │        └──────────────────┘
                           └─────────────────┘
-                          built on @danypops/daemon-kit
-                          (paths, storage, http, logging, daemon, rpc-client)
+                          built on @danypops/vehicle-server
+                          (Vehicle registry, paths, storage, HTTP, logging,
+                           daemon lifecycle, Armada service integration)
 ```
 
 Hexagonal architecture: `src/domain` has zero I/O, `src/ports` defines the
 outbound contract, `src/adapters` implement it per backend, `src/application`
 orchestrates by parsing `backend:key` refs and routing to the named
 repository, and `src/daemon` is the only place that owns the SQLite ledger,
-wraps it in a Bearer-authenticated HTTP RPC surface, and runs the pooling
-poller as a `daemon-kit` maintenance task.
+wraps it in a Bearer-authenticated HTTP/Vehicle surface, and runs the pooling
+poller as a Vehicle maintenance task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.10.1",
+  "version": "0.10.4",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/vehicle-core": "^0.12.3",
-    "@danypops/vehicle-server": "^0.17.1",
-    "@danypops/vehicle-client": "^0.5.0",
+    "@danypops/vehicle-core": "^0.12.5",
+    "@danypops/vehicle-server": "^0.18.2",
+    "@danypops/vehicle-client": "^0.7.0",
     "@danypops/enigma-client": "^0.6.1",
     "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.0",

package/src/agent-tools/error-mapping.ts

@@ -0,0 +1,122 @@
+import { isVehicleError, VehicleError } from "@danypops/vehicle-core";
+import { ApiError, AuthRequiredError, BackendConfigurationError, BackendConnectionError, InvalidUrlError } from "../issue/errors.js";
+import { statusForKnownTicketError } from "../rpc/error-status.js";
+
+function apiErrorToVehicle(error: ApiError): VehicleError {
+  const details = { backend: error.backend, status: error.status };
+
+  if (error.status === 401 || error.status === 403) {
+    return new VehicleError("backend-authentication-failed", `${error.backend}: authentication or authorization was rejected`, {
+      category: "authorization",
+      details,
+      recovery: { message: "Check the configured credential and its backend permissions, then retry." },
+      cause: error,
+    });
+  }
+  if (error.status === 408) {
+    return new VehicleError("backend-timeout", `${error.backend}: backend request timed out`, {
+      category: "timeout",
+      retryable: true,
+      details,
+      recovery: { message: "Retry after backend connectivity recovers." },
+      cause: error,
+    });
+  }
+  if (error.status === 409) {
+    return new VehicleError("backend-conflict", `${error.backend}: backend rejected the request because its state changed`, {
+      category: "conflict",
+      details,
+      recovery: { message: "Refresh the issue and retry against its current state." },
+      cause: error,
+    });
+  }
+  if (error.status === 429) {
+    return new VehicleError("backend-rate-limited", `${error.backend}: backend API rate limit exceeded`, {
+      category: "capacity",
+      retryable: true,
+      details,
+      recovery: { message: "Retry after the backend rate limit resets; cached ledger reads remain available." },
+      cause: error,
+    });
+  }
+  if (error.status >= 500) {
+    return new VehicleError("backend-unavailable", `${error.backend}: backend API is unavailable (${error.status})`, {
+      category: "unavailable",
+      retryable: true,
+      details,
+      recovery: { message: "Retry later; for reads, use ledger.search while the live backend is unavailable." },
+      cause: error,
+    });
+  }
+  return new VehicleError("backend-request-rejected", `${error.backend}: backend rejected the request (${error.status})`, {
+    category: "validation",
+    details,
+    recovery: { message: "Check the operation input and backend-specific constraints, then retry." },
+    cause: error,
+  });
+}
+
+/** Converts reviewed Tickets failures into actionable, wire-safe Vehicle failures. */
+export function toTicketsVehicleError(error: unknown): VehicleError {
+  if (isVehicleError(error)) return error;
+
+  if (error instanceof BackendConfigurationError) {
+    return new VehicleError("backend-not-configured", error.message, {
+      category: "validation",
+      recovery: { message: error.recovery },
+      cause: error,
+    });
+  }
+  if (error instanceof BackendConnectionError) {
+    return new VehicleError(error.kind === "timeout" ? "backend-timeout" : "backend-unavailable", error.message, {
+      category: error.kind === "timeout" ? "timeout" : "unavailable",
+      retryable: true,
+      details: { backend: error.backend },
+      recovery: {
+        message: "Check the configured URL and network, VPN, or DNS connectivity; cached ledger reads remain available.",
+      },
+      cause: error,
+    });
+  }
+  if (error instanceof ApiError) return apiErrorToVehicle(error);
+  if (error instanceof InvalidUrlError) {
+    return new VehicleError("invalid-backend-url", "Backend URL configuration is invalid", {
+      category: "validation",
+      recovery: { message: "Use an HTTPS backend URL (HTTP is accepted only for localhost), then restart the daemon." },
+      cause: error,
+    });
+  }
+  if (error instanceof AuthRequiredError) {
+    return new VehicleError("backend-authentication-required", error.message, {
+      category: "authorization",
+      recovery: { message: "Configure the backend credential, restart the daemon if needed, and retry." },
+      cause: error,
+    });
+  }
+
+  const status = statusForKnownTicketError(error);
+  if (status === 404) {
+    return new VehicleError("not-found", (error as Error).message, { category: "not_found", cause: error });
+  }
+  if (status === 400) {
+    return new VehicleError("operation-rejected", (error as Error).message, { category: "validation", cause: error });
+  }
+  if (status === 422) {
+    return new VehicleError("operation-rejected", (error as Error).message, { category: "authorization", cause: error });
+  }
+
+  // Unknown exceptions stay opaque: only reviewed domain/config/transport errors above
+  // may cross the daemon boundary with their original message.
+  return new VehicleError("handler-failed", "Tickets operation failed unexpectedly", {
+    category: "internal",
+    cause: error,
+  });
+}
+
+export async function withTicketsErrorParity<T>(run: () => T | Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    throw toTicketsVehicleError(error);
+  }
+}

package/src/agent-tools/tickets-vehicle.ts

@@ -16,7 +16,6 @@
  */
 import {
   bindVehicleOperation,
-  defineErrorMapping,
   defineLooseObjectSchema,
   defineVehicleOperation,
   type LooseObjectProperty,
@@ -25,21 +24,12 @@ import {
 } from "@danypops/vehicle-core";
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { BackendCapabilities, TicketService } from "../issue/service.js";
-import { statusForKnownTicketError } from "../rpc/error-status.js";
 import type { TicketOperation } from "../rpc/ops.js";
 import { TICKET_OP_HANDLERS, type TicketsAppDeps } from "../rpc/server.js";
+import { withTicketsErrorParity } from "./error-mapping.js";
 
 const OWNER = "tickets";
 
-const withTicketsErrorParity = defineErrorMapping(
-  [
-    { matches: (error) => statusForKnownTicketError(error) === 404, category: "not_found" },
-    { matches: (error) => statusForKnownTicketError(error) === 400, category: "validation" },
-    { matches: (error) => statusForKnownTicketError(error) === 422, category: "authorization" },
-  ],
-  { fallbackCategory: "internal", fallbackCode: "handler-failed", fallbackMessage: "Tickets operation failed" },
-);
-
 const LIMITS = { defaultTimeoutMs: 10_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 const stringProp: LooseObjectProperty = { type: "string" };

package/src/cli/index.ts

@@ -15,8 +15,9 @@ import { promptMaskedSecret } from "../auth/masked-prompt.js";
 import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
 import type { CreateInput, ListFilter, Priority, Status, UpdateInput } from "../issue/issue.js";
 import { parseStatus } from "../issue/issue.js";
+import { serveMain } from "../process/main.js";
 import type { StagePatchFields, StagePayload } from "../stage/store.js";
-import { installTicketsService, systemctlTickets, systemdUnitPath } from "./systemd-service.js";
+import { ticketsServiceCli } from "./systemd-service.js";
 import { createTicketsClient, type TicketsRpcClient } from "./tickets-client.js";
 
 function printJson(value: unknown): void {
@@ -489,32 +490,53 @@ daemon
     }
   });
 
+program
+  .command("serve")
+  .description("run the tickets daemon in the foreground -- Armada's service spec launches exactly this (see ./systemd-service.js)")
+  .action(async () => {
+    await serveMain();
+  });
+
 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)",
+    "register the tickets daemon with Armada's cross-platform desired-state fleet (direct start/stop/restart/status actions currently require systemd --user)",
   );
 
 service
   .command("install")
-  .description("write, enable, and (re)start a tickets-daemon.service systemd --user unit pointed at this install")
+  .description("register this install with Armada as the tickets vehicle and reconcile it through the native service manager")
   .action(() => {
-    try {
-      const { unitPath } = installTicketsService();
-      printJson({ status: "installed", unitPath });
-    } catch (err) {
-      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    const cli = ticketsServiceCli();
+    const result = cli.install();
+    if (!result.installed) {
+      process.stderr.write(`error: ${result.reason}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    printJson({ status: "installed", unitName: cli.unitName, via: "armada" });
+  });
+
+service
+  .command("uninstall")
+  .description("remove this vehicle from Armada's fleet (stops and un-enrolls the tickets-daemon service)")
+  .action(() => {
+    const result = ticketsServiceCli().uninstall();
+    if (!result.installed) {
+      process.stderr.write(`error: ${result.reason}\n`);
       process.exitCode = 1;
+      return;
     }
+    printJson({ status: "uninstalled", via: "armada" });
   });
 
 for (const action of ["start", "stop", "restart", "status"] as const) {
   service
     .command(action)
-    .description(`systemctl --user ${action} tickets-daemon.service`)
+    .description(`systemctl --user ${action} the Armada-managed tickets unit`)
     .action(() => {
       try {
-        systemctlTickets(action);
+        ticketsServiceCli().action(action);
       } catch (err) {
         process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
         process.exitCode = 1;
@@ -522,13 +544,6 @@ for (const action of ["start", "stop", "restart", "status"] as const) {
     });
 }
 
-service
-  .command("path")
-  .description("print where the systemd unit file would be written")
-  .action(() => {
-    printJson({ unitPath: systemdUnitPath() });
-  });
-
 const auth = program.command("auth").description("delegated OAuth login (device flow for GitHub/GitLab, authorization code for Jira)");
 
 auth

package/src/cli/systemd-service.ts

@@ -1,97 +1,36 @@
 /**
- * Deploys the tickets daemon as a persistent systemd --user service, so it
- * survives logout/reboot instead of only existing for as long as some CLI
- * command's on-demand auto-spawn keeps it alive. Mirrors papyrus's own
- * `papyrus service <install|start|stop|restart|status>` pattern exactly
- * (see ~/Projects/papyrus/src/cli.ts) -- same shape, same systemctl --user
- * verbs, same install order (write unit -> daemon-reload -> enable ->
- * restart). Every side effect (file write, directory creation, systemctl
- * invocation) is injectable so this is fully testable without touching a
- * real filesystem or spawning a real systemctl process.
+ * Deploys the tickets daemon as an Armada-supervised service. Builds the
+ * spec; createServiceCli (vehicle-server) owns install/uninstall/systemctl
+ * wiring shared by every Vehicle-backed daemon's CLI.
  */
-import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServiceCli, type ServiceCli, type ServiceSpec } from "@danypops/vehicle-server/service";
+import { readPackageVersion } from "@danypops/vehicle-server/version";
 import { TICKETS_DAEMON_NAMES } from "../rpc/ops.js";
-import { resolveDaemonEntryPath } from "./tickets-client.js";
+import { ticketsPaths } from "./tickets-client.js";
 
-export interface SystemdUnitOptions {
-  bunBin: string;
-  daemonMainPath: string;
+export interface TicketsServiceSpecOptions {
+  version?: string;
+  /** Overridden in tests. */
+  cliEntryPath?: string;
 }
 
-export function renderSystemdUnit(options: SystemdUnitOptions): string {
-  return `[Unit]
-Description=Tickets daemon -- unified GitHub/GitLab/Jira issue tracking
-After=default.target
-
-[Service]
-Type=simple
-ExecStart=${options.bunBin} run ${options.daemonMainPath}
-Restart=always
-RestartSec=2
-
-[Install]
-WantedBy=default.target
-`;
-}
-
-/** XDG_CONFIG_HOME/systemd/user/tickets-daemon.service, falling back to ~/.config like systemd itself does. */
-export function systemdUnitPath(env: Record<string, string | undefined> = process.env): string {
-  const configHome = env.XDG_CONFIG_HOME ?? join(env.HOME ?? "", ".config");
-  return join(configHome, "systemd", "user", TICKETS_DAEMON_NAMES.systemdUnitName);
-}
-
-export type CommandRunner = (command: string, args: string[]) => void;
-
-const defaultRunner: CommandRunner = (command, args) => {
-  try {
-    execFileSync(command, args, { stdio: "inherit" });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`${command} ${args.join(" ")} failed (is systemd --user available? this feature is Linux-only): ${message}`);
-  }
-};
-
-export type SystemctlAction = "start" | "stop" | "restart" | "status" | "enable" | "daemon-reload";
-
-/** Always targets the tickets unit name under --user scope; daemon-reload takes no unit argument. */
-export function systemctlTickets(action: SystemctlAction, runner: CommandRunner = defaultRunner): void {
-  const args = action === "daemon-reload" ? ["--user", "daemon-reload"] : ["--user", action, TICKETS_DAEMON_NAMES.systemdUnitName];
-  runner("systemctl", args);
-}
-
-export interface InstallOptions {
-  bunBin?: string;
-  daemonMainPath?: string;
-  env?: Record<string, string | undefined>;
-  runner?: CommandRunner;
-  writeFile?: (path: string, content: string) => void;
-  ensureDir?: (path: string) => void;
+/** The daemon is launched as `<bin> <this CLI's entry path> serve`. */
+export function ticketsServiceSpec(opts: TicketsServiceSpecOptions = {}): ServiceSpec {
+  const cliEntryPath = opts.cliEntryPath ?? fileURLToPath(new URL("./index.js", import.meta.url));
+  const version = opts.version ?? readPackageVersion(new URL("../../package.json", import.meta.url), "Tickets");
+  return {
+    name: TICKETS_DAEMON_NAMES.stateDirectoryName,
+    displayName: "Tickets daemon",
+    version,
+    binPath: process.execPath,
+    args: [cliEntryPath, "serve"],
+    handlePath: ticketsPaths().handle,
+    restartOnFailure: true,
+    restartSec: 2,
+  };
 }
 
-/**
- * Writes the unit file, then daemon-reload -> enable -> restart, in that
- * order -- systemd must see the file before enable/restart can act on it,
- * and restart (not start) so re-running install after an upgrade picks up
- * a changed ExecStart path immediately rather than requiring a manual stop.
- */
-export function installTicketsService(opts: InstallOptions = {}): { unitPath: string } {
-  const unitPath = systemdUnitPath(opts.env);
-  const ensureDir = opts.ensureDir ?? ((dir: string) => mkdirSync(dir, { recursive: true }));
-  const writeFile = opts.writeFile ?? writeFileSync;
-  const runner = opts.runner ?? defaultRunner;
-
-  ensureDir(dirname(unitPath));
-  writeFile(
-    unitPath,
-    renderSystemdUnit({
-      bunBin: opts.bunBin ?? process.execPath,
-      daemonMainPath: opts.daemonMainPath ?? resolveDaemonEntryPath(),
-    }),
-  );
-  systemctlTickets("daemon-reload", runner);
-  systemctlTickets("enable", runner);
-  systemctlTickets("restart", runner);
-  return { unitPath };
+export function ticketsServiceCli(opts: TicketsServiceSpecOptions = {}): ServiceCli {
+  return createServiceCli(ticketsServiceSpec(opts));
 }

package/src/github/github.ts

@@ -21,7 +21,7 @@
 
 import { RequestError } from "@octokit/request-error";
 import { Octokit } from "octokit";
-import { ApiError, AuthRequiredError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, AuthRequiredError, BackendConfigurationError, BackendConnectionError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -90,7 +90,13 @@ export class GitHubRepository {
   }
 
   private repoName(): string {
-    if (!this.repo) throw new Error("github: repo not set — pass repo, or scope via config");
+    if (!this.repo) {
+      throw new BackendConfigurationError(
+        "github",
+        "repository is not configured; set GITHUB_REPO (or the backend's repo setting) and restart the tickets daemon",
+        "Set GITHUB_REPO (or the backend's repo setting), then restart the tickets daemon.",
+      );
+    }
     return this.repo;
   }
 
@@ -209,11 +215,13 @@ export class GitHubRepository {
       const res = await fn(controller.signal);
       return res.data;
     } catch (err) {
+      if (err instanceof BackendConfigurationError) throw 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;
+      if (err instanceof DOMException && err.name === "AbortError") throw new BackendConnectionError("github", "timeout", err);
+      throw new BackendConnectionError("github", "unreachable", err);
     } finally {
       clearTimeout(timer);
     }

package/src/gitlab/gitlab.ts

@@ -14,7 +14,7 @@
 import { isIP } from "node:net";
 import { GitbeakerRequestError, type RequesterType, type ResourceOptions } from "@gitbeaker/requester-utils";
 import { Gitlab } from "@gitbeaker/rest";
-import { ApiError, AuthRequiredError, InvalidUrlError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, AuthRequiredError, BackendConnectionError, InvalidUrlError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 
 export interface GitLabOptions {
@@ -183,12 +183,13 @@ export class GitLabRepository {
       return (await fn()) as T;
     } catch (err) {
       if (err instanceof GitbeakerRequestError) {
-        const status = err.cause?.response?.status ?? 500;
+        const status = err.cause?.response?.status;
         const url = err.cause?.request?.url ?? "";
+        if (status === undefined) throw new BackendConnectionError("gitlab", "unreachable", err);
         if (status === 404) throw new IssueNotFoundError("gitlab", url);
         throw new ApiError("gitlab", err.cause?.request?.method ?? "?", url, status, redact(err.message));
       }
-      throw err;
+      throw new BackendConnectionError("gitlab", "unreachable", err);
     }
   }
 }

package/src/issue/errors.ts

@@ -12,6 +12,35 @@ export class AuthRequiredError extends Error {
   }
 }
 
+/** A reviewed, user-actionable backend setup failure safe to expose to clients. */
+export class BackendConfigurationError extends Error {
+  constructor(
+    public readonly backend: string,
+    message: string,
+    public readonly recovery: string,
+  ) {
+    super(`${backend}: ${message}`);
+    this.name = "BackendConfigurationError";
+  }
+}
+
+/** A transport failure with no trustworthy HTTP response (DNS, VPN, connection, or timeout). */
+export class BackendConnectionError extends Error {
+  constructor(
+    public readonly backend: string,
+    public readonly kind: "unreachable" | "timeout" = "unreachable",
+    cause?: unknown,
+  ) {
+    super(
+      kind === "timeout"
+        ? `${backend}: backend request timed out; retry or check backend connectivity`
+        : `${backend}: unable to reach the backend API; check the configured URL and network, VPN, or DNS connectivity`,
+      { cause },
+    );
+    this.name = "BackendConnectionError";
+  }
+}
+
 export class ApiError extends Error {
   constructor(
     public readonly backend: string,

package/src/jira/jira.ts

@@ -16,7 +16,7 @@
 import type { AxiosAdapter } from "axios";
 import type { HttpException, Config as JiraClientConfig } from "jira.js";
 import { AgileClient, Version2Client } from "jira.js";
-import { ApiError, IssueNotFoundError } from "../issue/errors.js";
+import { ApiError, BackendConfigurationError, BackendConnectionError, IssueNotFoundError } from "../issue/errors.js";
 import type { Comment, CreateInput, Issue, IssueLink, ListFilter, parsePriority, Status, UpdateInput } from "../issue/issue.js";
 import type { Template } from "../issue/template.js";
 import { buildTemplateBody, extractTemplateSections } from "../issue/template.js";
@@ -39,9 +39,9 @@ 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(). */
+  /** Additional default project keys, beyond the single `project` above -- widens list()/search()'s own default scope (no explicit project given) as well as the background poller's sync, both via defaultProjects(). 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`. */
+  /** 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`. list()/search() are unaffected -- pass an explicit assignee filter for that. */
   syncMine?: boolean;
   timeoutMs?: number;
   /** Injected in tests instead of a real network call — see axios's AxiosRequestConfig.adapter. */
@@ -180,15 +180,21 @@ export class JiraRepository {
     this.client = new Version2Client(this.clientConfig);
   }
 
+  /**
+   * An explicit filter.project always wins and narrows to exactly that one
+   * project; with none given, defaults to every project this repository
+   * cares about (defaultProjects() -- the same set buildSyncQuery() pools in
+   * the background), not just the single legacy `project` config field.
+   */
   async list(filter: ListFilter): Promise<Issue[]> {
-    const project = filter.project ?? this.project;
+    const projects = filter.project ? [filter.project] : this.defaultProjects();
     const clauses: string[] = [];
-    if (project) clauses.push(`project = ${jqlQuote(project)}`);
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
     if (filter.status) clauses.push(`status = ${jqlQuote(mapStatusToJira(filter.status))}`);
     if (filter.assignee) clauses.push(`assignee = ${jqlQuote(filter.assignee)}`);
     for (const label of filter.labels ?? []) clauses.push(`labels = ${jqlQuote(label)}`);
-    const jql = `${clauses.join(" AND ")} ORDER BY created DESC`.trim();
-    return this.searchJql(jql, filter.limit ?? 50);
+    return this.searchJql(buildJql(clauses, "AND"), filter.limit ?? 50);
   }
 
   async get(key: string): Promise<Issue> {
@@ -218,13 +224,19 @@ export class JiraRepository {
         const message = err instanceof Error ? err.message : String(err);
         throw new ApiError("jira", "?", key ?? "?", status, redact(message));
       }
-      throw err;
+      throw new BackendConnectionError("jira", err instanceof DOMException && err.name === "AbortError" ? "timeout" : "unreachable", 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)");
+    if (!project) {
+      throw new BackendConfigurationError(
+        "jira",
+        "project is required to create an issue; pass input.project or configure JIRA_PROJECT",
+        "Pass input.project or set JIRA_PROJECT (or the backend's project setting), then retry.",
+      );
+    }
     const fields: Record<string, unknown> = {
       project: { key: project },
       summary: input.title,
@@ -259,10 +271,12 @@ export class JiraRepository {
   }
 
   async search(query: string, limit = 50, project?: string): Promise<Issue[]> {
-    const effectiveProject = project ?? this.project;
-    const scope = effectiveProject ? `project = ${jqlQuote(effectiveProject)} AND ` : "";
-    const jql = `${scope}text ~ ${jqlQuote(query)} ORDER BY created DESC`;
-    return this.searchJql(jql, limit);
+    const projects = project ? [project] : this.defaultProjects();
+    const clauses: string[] = [];
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
+    clauses.push(`text ~ ${jqlQuote(query)}`);
+    return this.searchJql(buildJql(clauses, "AND"), limit);
   }
 
   async listChildren(key: string): Promise<Issue[]> {
@@ -284,23 +298,33 @@ export class JiraRepository {
     return this.searchJql(query, limit);
   }
 
+  /**
+   * Every project this repository defaults to when a caller doesn't name one
+   * explicitly -- the single `project` config plus `syncProjects`, deduped.
+   * Shared by list()/search()'s own default-scope resolution and by
+   * buildSyncQuery() below, so "which projects do we care about" is answered
+   * in exactly one place instead of once per method.
+   */
+  private defaultProjects(): string[] {
+    return [...new Set([this.project, ...this.syncProjects].filter((p): p is string => Boolean(p)))];
+  }
+
   /**
    * 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
+   * into the local ledger beyond defaultProjects() alone: ORs in
    * "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.
+   * you in a project nobody listed still get pooled. Returns undefined --
+   * letting the poller fall back to plain list() -- when syncMine adds
+   * nothing beyond what list() already does with 0-1 default projects.
    */
   buildSyncQuery(): string | undefined {
-    const projects = [...new Set([this.project, ...this.syncProjects].filter((p): p is string => Boolean(p)))];
+    const projects = this.defaultProjects();
     if (projects.length <= 1 && !this.syncMine) return undefined;
     const clauses: string[] = [];
-    if (projects.length > 0) clauses.push(`project in (${projects.map(jqlQuote).join(", ")})`);
+    const scope = projectClause(projects);
+    if (scope) clauses.push(scope);
     if (this.syncMine) clauses.push("assignee = currentUser()");
-    return `${clauses.join(" OR ")} ORDER BY created DESC`;
+    return buildJql(clauses, "OR");
   }
 
   /**
@@ -586,6 +610,18 @@ function jqlQuote(value: string): string {
   return `"${value.replace(/"/g, '\\"')}"`;
 }
 
+/** Shared by list()/search()/buildSyncQuery() -- `project = X` for one project, `project in (...)` for several, undefined for none. */
+function projectClause(projects: readonly string[]): string | undefined {
+  if (projects.length === 0) return undefined;
+  if (projects.length === 1) return `project = ${jqlQuote(projects[0]!)}`;
+  return `project in (${projects.map(jqlQuote).join(", ")})`;
+}
+
+/** Shared by list()/search()/buildSyncQuery() -- clauses joined by `joiner`, always ordered by `orderBy`. An empty clause list still yields valid JQL ("ORDER BY ..."), matching every one of this file's own pre-existing unscoped queries. */
+function buildJql(clauses: readonly string[], joiner: "AND" | "OR", orderBy = "created DESC"): string {
+  return `${clauses.join(` ${joiner} `)} ORDER BY ${orderBy}`.trim();
+}
+
 function mapStatusToJira(status: Status): string {
   switch (status) {
     case "backlog":

package/src/process/main.ts

@@ -1,20 +1,28 @@
 #!/usr/bin/env bun
 /**
  * The real tickets-daemon binary. Requires Bun (bun:sqlite, Bun.serve via
- * vehicle-server). Everything else in this package (the library, the CLI, the
- * pi-tickets extension) is plain Node-compatible TypeScript and talks to
- * this process only over the loopback HTTP RPC surface — see client.ts.
+ * vehicle-server). Everything else in this package talks to this process
+ * only over the loopback HTTP RPC surface — see client.ts.
+ *
+ * serveMain() is also what `tickets serve` (cli/index.ts) runs directly --
+ * that's the command Armada's ServiceSpec launches.
  */
 import { runDaemonProcess } from "@danypops/vehicle-server/daemon";
 import { readPackageVersion } from "@danypops/vehicle-server/version";
 import { bootstrap } from "./bootstrap.js";
 
-const version = readPackageVersion(new URL("../../package.json", import.meta.url), "Tickets");
-const { options } = await bootstrap({ version });
+export async function serveMain(): Promise<void> {
+  const version = readPackageVersion(new URL("../../package.json", import.meta.url), "Tickets");
+  const { options } = await bootstrap({ version });
 
-runDaemonProcess({
-  ...options,
-  onListen: (info) => {
-    options.logger?.info("tickets daemon listening", { host: info.host, port: info.port, version });
-  },
-});
+  runDaemonProcess({
+    ...options,
+    onListen: (info) => {
+      options.logger?.info("tickets daemon listening", { host: info.host, port: info.port, version });
+    },
+  });
+}
+
+if (import.meta.main) {
+  await serveMain();
+}