@danypops/tickets 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -24,8 +24,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/vehicle-core": "^0.13.0",
-    "@danypops/vehicle-server": "^0.18.4",
+    "@danypops/vehicle-core": "^0.15.0",
+    "@danypops/vehicle-server": "^0.21.0",
     "@danypops/vehicle-client": "^0.7.1",
     "@danypops/enigma-client": "^0.6.1",
     "@gitbeaker/rest": "^43.8.0",

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

@@ -25,7 +25,7 @@ import {
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { BackendCapabilities, TicketService } from "../issue/service.js";
 import type { TicketOperation } from "../rpc/ops.js";
-import { TICKET_OP_HANDLERS, type TicketsAppDeps } from "../rpc/server.js";
+import { type HandlerCallContext, TICKET_OP_HANDLERS, type TicketsAppDeps } from "../rpc/server.js";
 import { withTicketsErrorParity } from "./error-mapping.js";
 
 const OWNER = "tickets";
@@ -34,6 +34,7 @@ const LIMITS = { defaultTimeoutMs: 10_000, maxTimeoutMs: 30_000, maxRequestBytes
 
 const stringProp: LooseObjectProperty = { type: "string" };
 const numberProp: LooseObjectProperty = { type: "number" };
+const booleanProp: LooseObjectProperty = { type: "boolean" };
 
 interface OperationSpec {
   readonly action: TicketOperation;
@@ -71,7 +72,8 @@ const OPERATIONS: readonly OperationSpec[] = [
   },
   {
     action: "issue.list",
-    description: "Lists issues from one backend, optionally filtered.",
+    description:
+      "Lists issues from one backend, optionally filtered. reportedByMe/assignedToMe/reviewRequestedOfMe/qaContactIsMe filter to the caller's own tickets using each backend's own identity (no username needed); set more than one to OR them together. reviewRequestedOfMe is GitHub/GitLab-only (PR/MR reviewer requests); qaContactIsMe is Jira-only (its discovered 'QA Contact' field) -- an unsupported flag on a given backend throws rather than being silently ignored.",
     effect: "read",
     properties: {
       backend: stringProp,
@@ -80,11 +82,25 @@ const OPERATIONS: readonly OperationSpec[] = [
       assignee: stringProp,
       labels: stringArrayProp,
       limit: numberProp,
+      reportedByMe: booleanProp,
+      assignedToMe: booleanProp,
+      reviewRequestedOfMe: booleanProp,
+      qaContactIsMe: booleanProp,
     },
     required: ["backend"],
-    mapInput: ({ backend, project, status, assignee, labels, limit }) => ({
+    mapInput: ({ backend, project, status, assignee, labels, limit, reportedByMe, assignedToMe, reviewRequestedOfMe, qaContactIsMe }) => ({
       backend,
-      filter: definedEntriesOnly({ project, status, assignee, labels, limit }),
+      filter: definedEntriesOnly({
+        project,
+        status,
+        assignee,
+        labels,
+        limit,
+        reportedByMe,
+        assignedToMe,
+        reviewRequestedOfMe,
+        qaContactIsMe,
+      }),
     }),
   },
   {
@@ -249,6 +265,61 @@ const OPERATIONS: readonly OperationSpec[] = [
     properties: { name: stringProp, limit: numberProp },
     required: ["name"],
   },
+  {
+    action: "issue.subscribe",
+    description:
+      "Has the daemon keep watching one issue in the background -- comments, status, and other field changes are reported through watch_events, no manual re-checking needed. Idempotent. subscriberId scopes this watch to one caller (defaults to this calling Pi session's own real session id, then a shared anonymous subscriber for a raw RPC client with no session at all); scheduleMs bounds how often that subscriber's watch is refreshed, in milliseconds (omit to refresh on every background sync tick). projectRoot attributes this subscription to a project -- defaults to this calling session's own cwd; rarely needs to be passed explicitly.",
+    effect: "local-write",
+    properties: { ref: stringProp, subscriberId: stringProp, scheduleMs: numberProp, projectRoot: stringProp },
+    required: ["ref"],
+  },
+  {
+    action: "issue.unsubscribe",
+    description:
+      "Stops the daemon watching one issue in the background. Idempotent -- no error if it wasn't subscribed. subscriberId removes only that one caller's watch, leaving any other subscriber's own watch on the same issue intact.",
+    effect: "local-write",
+    properties: { ref: stringProp, subscriberId: stringProp },
+    required: ["ref"],
+  },
+  {
+    action: "issue.subscribed",
+    description:
+      "Every issue this subscriber is currently watching -- never a live backend call, cheap to call frequently. subscriberId defaults to this calling Pi session's own real session id.",
+    effect: "read",
+    properties: { subscriberId: stringProp },
+    required: [],
+  },
+  {
+    action: "query.subscribe",
+    description:
+      "Has the daemon keep re-running one saved query in the background -- new matching items or items that drop out are reported through watch_events, no manual re-checking needed. Idempotent. subscriberId/scheduleMs/projectRoot behave exactly like issue.subscribe's own.",
+    effect: "local-write",
+    properties: { name: stringProp, subscriberId: stringProp, scheduleMs: numberProp, projectRoot: stringProp },
+    required: ["name"],
+  },
+  {
+    action: "query.unsubscribe",
+    description: "Stops the daemon re-running one saved query in the background. Idempotent -- no error if it wasn't subscribed.",
+    effect: "local-write",
+    properties: { name: stringProp, subscriberId: stringProp },
+    required: ["name"],
+  },
+  {
+    action: "query.subscribed",
+    description:
+      "Every saved query this subscriber is currently watching -- never a live backend call, cheap to call frequently. subscriberId defaults to this calling Pi session's own real session id.",
+    effect: "read",
+    properties: { subscriberId: stringProp },
+    required: [],
+  },
+  {
+    action: "watch.events",
+    description:
+      "New change events (comments, status, label/field changes, saved-query membership changes) for everything this subscriber currently watches, since sinceId -- cheaper than re-fetching every watched issue/query yourself. Pass the previous call's lastId as sinceId to page forward; omit it once to start from 'now' without replaying history.",
+    effect: "read",
+    properties: { subscriberId: stringProp, sinceId: numberProp, limit: numberProp },
+    required: [],
+  },
   {
     action: "stage.add",
     description:
@@ -403,7 +474,17 @@ export function createTicketsVehicleRegistry(deps: Omit<TicketsAppDeps, "vehicle
       bindVehicleOperation(
         operation,
         () => async (context) =>
-          withTicketsErrorParity<unknown>(() => handler(deps, mapInput(context.input as Record<string, unknown>) as never)),
+          withTicketsErrorParity<unknown>(() => {
+            // Threaded through unconditionally -- harmless for the vast majority of handlers that
+            // never read it; issue.subscribe/query.subscribe (and their siblings) use it to default
+            // subscriberId/projectRoot from this real call's own session identity, mirroring
+            // @danypops/pipes' own ci.subscribe. See HandlerCallContext's own doc comment.
+            const callContext: HandlerCallContext = {
+              callerSessionId: context.callerSessionId,
+              callerProjectRoot: context.callerProjectRoot,
+            };
+            return handler(deps, mapInput(context.input as Record<string, unknown>) as never, callContext);
+          }),
       ),
     );
   }

package/src/cli/index.ts

@@ -47,6 +47,10 @@ program
   .option("--assignee <user>", "filter by assignee")
   .option("--label <label...>", "filter by label(s)")
   .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .option("--reported-by-me", "only issues reported/authored by you (Jira reporter / GitHub PR author / GitLab issue author)")
+  .option("--assigned-to-me", "only issues assigned to you")
+  .option("--review-requested-of-me", "only PRs/MRs where you're requested as a reviewer (GitHub/GitLab only)")
+  .option("--qa-contact-is-me", "only issues where you're the QA Contact (Jira only)")
   .action(async (opts) => {
     const filter: ListFilter = {
       project: opts.project,
@@ -54,6 +58,10 @@ program
       assignee: opts.assignee,
       labels: opts.label,
       limit: opts.limit,
+      reportedByMe: opts.reportedByMe,
+      assignedToMe: opts.assignedToMe,
+      reviewRequestedOfMe: opts.reviewRequestedOfMe,
+      qaContactIsMe: opts.qaContactIsMe,
     };
     await withClient((client) => client.call("issue.list", { backend: opts.backend, filter }));
   });
@@ -150,6 +158,37 @@ program
     await withClient((client) => client.call("issue.merge", { ref, method: opts.method }));
   });
 
+program
+  .command("subscribe <ref>")
+  .description("watch one issue in the background -- comments, status, and other field changes are reported via `watch-events`")
+  .option("--schedule-ms <ms>", "minimum check cadence for this subscription, in milliseconds", (v) => Number.parseInt(v, 10))
+  .action(async (ref: string, opts) => {
+    await withClient((client) => client.call("issue.subscribe", { ref, scheduleMs: opts.scheduleMs }));
+  });
+
+program
+  .command("unsubscribe <ref>")
+  .description("stop watching one issue")
+  .action(async (ref: string) => {
+    await withClient((client) => client.call("issue.unsubscribe", { ref }));
+  });
+
+program
+  .command("subscribed")
+  .description("list every issue you're currently watching")
+  .action(async () => {
+    await withClient((client) => client.call("issue.subscribed", {}));
+  });
+
+program
+  .command("watch-events")
+  .description("new change events for everything you're currently watching (issues and saved queries), since --since-id")
+  .option("--since-id <id>", "only events after this event id", (v) => Number.parseInt(v, 10))
+  .option("--limit <n>", "max events", (v) => Number.parseInt(v, 10))
+  .action(async (opts) => {
+    await withClient((client) => client.call("watch.events", { sinceId: opts.sinceId, limit: opts.limit }));
+  });
+
 const comment = program.command("comment").description("comment operations");
 
 comment
@@ -313,6 +352,28 @@ queryCmd
     await withClient((client) => client.call("query.run", { name, limit: opts.limit }));
   });
 
+queryCmd
+  .command("subscribe <name>")
+  .description("watch one saved query in the background -- new/dropped items are reported via `watch-events`")
+  .option("--schedule-ms <ms>", "minimum check cadence for this subscription, in milliseconds", (v) => Number.parseInt(v, 10))
+  .action(async (name: string, opts) => {
+    await withClient((client) => client.call("query.subscribe", { name, scheduleMs: opts.scheduleMs }));
+  });
+
+queryCmd
+  .command("unsubscribe <name>")
+  .description("stop watching one saved query")
+  .action(async (name: string) => {
+    await withClient((client) => client.call("query.unsubscribe", { name }));
+  });
+
+queryCmd
+  .command("subscribed")
+  .description("list every saved query you're currently watching")
+  .action(async () => {
+    await withClient((client) => client.call("query.subscribed", {}));
+  });
+
 discoverCmd
   .command("board_quickfilter")
   .description(

package/src/github/github.ts

@@ -165,19 +165,34 @@ export class GitHubRepository {
   }
 
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.qaContactIsMe) throw new Error('github: "qaContactIsMe" is a Jira-only concept, not supported on the github backend');
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const raw = await this.call((signal) =>
-      this.client.rest.issues.listForRepo({
-        owner: this.owner,
-        repo: this.repoName(),
-        per_page: limit,
-        state: filter.status ? mapStatusToGitHub(filter.status) : "all",
-        assignee: filter.assignee,
-        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
-        request: { signal },
-      }),
-    );
-    return (raw as GhIssue[]).map((i) => toDomain(i));
+    const meQualifiers = buildMeQualifiers(filter);
+    if (meQualifiers.length === 0) {
+      const raw = await this.call((signal) =>
+        this.client.rest.issues.listForRepo({
+          owner: this.owner,
+          repo: this.repoName(),
+          per_page: limit,
+          state: filter.status ? mapStatusToGitHub(filter.status) : "all",
+          assignee: filter.assignee,
+          labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+          request: { signal },
+        }),
+      );
+      return (raw as GhIssue[]).map((i) => toDomain(i));
+    }
+    // Any "me" flag routes through the Search API instead of listForRepo: it's the only GitHub
+    // surface with a review-requested filter at all (confirmed against GitHub's own REST docs --
+    // listForRepo has no such parameter), and it happens to support author/assignee "me" qualifiers
+    // too, so one call covers every combination of the three flags. Response items are Issue-shaped
+    // (same pull_request: {merged_at} stub as listForRepo's own entries -- confirmed against
+    // @octokit/openapi-types' issue-search-result-item schema), so toDomain() applies unchanged.
+    const q = buildMeSearchQuery(this.owner, this.repoName(), filter, meQualifiers);
+    const result = (await this.call((signal) =>
+      this.client.rest.search.issuesAndPullRequests({ q, per_page: limit, request: { signal } }),
+    )) as { items: GhIssue[] };
+    return result.items.map((i) => toDomain(i));
   }
 
   async get(key: string): Promise<Issue> {
@@ -362,6 +377,24 @@ function mapStatusToGitHub(status: Status): "open" | "closed" {
   return status === "done" || status === "canceled" ? "closed" : "open";
 }
 
+/** ListFilter.{reportedByMe,assignedToMe,reviewRequestedOfMe} -> GitHub Search API qualifiers -- see ListFilter's own doc comment. */
+function buildMeQualifiers(filter: ListFilter): string[] {
+  const qualifiers: string[] = [];
+  if (filter.reportedByMe) qualifiers.push("author:@me");
+  if (filter.assignedToMe) qualifiers.push("assignee:@me");
+  if (filter.reviewRequestedOfMe) qualifiers.push("user-review-requested:@me");
+  return qualifiers;
+}
+
+/** Composes a full Search API `q` string: repo scope + status/labels (AND, matching list()'s own semantics) + the "me" qualifiers (OR'd together). */
+function buildMeSearchQuery(owner: string, repo: string, filter: ListFilter, meQualifiers: readonly string[]): string {
+  const parts = [`repo:${owner}/${repo}`];
+  if (filter.status) parts.push(`is:${mapStatusToGitHub(filter.status)}`);
+  for (const label of filter.labels ?? []) parts.push(`label:"${label.replace(/"/g, '\\"')}"`);
+  parts.push(meQualifiers.length === 1 ? meQualifiers[0]! : `(${meQualifiers.join(" OR ")})`);
+  return parts.join(" ");
+}
+
 function mapStatusFromGitHub(state: string): Status {
   return state.toLowerCase() === "closed" ? "done" : "todo";
 }

package/src/gitlab/gitlab.ts

@@ -166,17 +166,54 @@ export class GitLabRepository {
   }
 
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.qaContactIsMe) throw new Error('gitlab: "qaContactIsMe" is a Jira-only concept, not supported on the gitlab backend');
+    if (filter.reviewRequestedOfMe) {
+      throw new Error(
+        'gitlab: "reviewRequestedOfMe" is a merge-request-only concept (scope=reviews_for_me) that list()\'s Issues-only scope can\'t express -- see get()\'s "!<iid>" convention for merge requests',
+      );
+    }
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const raw = await this.call<GlIssue[]>(() =>
-      this.client.Issues.all({
-        projectId: this.projectId,
-        perPage: limit,
-        state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
-        assigneeUsername: filter.assignee ? [filter.assignee] : undefined,
-        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
-      }),
+    const scopes = meScopes(filter);
+    if (scopes.length <= 1) {
+      const raw = await this.call<GlIssue[]>(() =>
+        this.client.Issues.all({
+          projectId: this.projectId,
+          perPage: limit,
+          state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
+          assigneeUsername: filter.assignee ? [filter.assignee] : undefined,
+          labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+          ...(scopes[0] ? { scope: scopes[0] } : {}),
+        }),
+      );
+      return raw.map(toDomain);
+    }
+    // Both reportedByMe and assignedToMe: GitLab's own `scope` param takes exactly one value per
+    // call (no server-side OR across scopes), so the OR-of-roles group ListFilter's own doc comment
+    // describes is executed here as two calls, deduped client-side by ref -- the one place in this
+    // adapter an OR of "me" flags genuinely costs more than one request (Jira/GitHub both express
+    // it in a single native query).
+    const results = await Promise.all(
+      scopes.map((scope) =>
+        this.call<GlIssue[]>(() =>
+          this.client.Issues.all({
+            projectId: this.projectId,
+            perPage: limit,
+            state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
+            labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+            scope,
+          }),
+        ),
+      ),
     );
-    return raw.map(toDomain);
+    const seen = new Set<string>();
+    const merged: Issue[] = [];
+    for (const raw of results.flat()) {
+      const issue = toDomain(raw);
+      if (seen.has(issue.ref)) continue;
+      seen.add(issue.ref);
+      merged.push(issue);
+    }
+    return merged.slice(0, limit);
   }
 
   async get(key: string): Promise<Issue> {
@@ -372,6 +409,14 @@ function mapStatusToGitLab(status: Status): "opened" | "closed" {
   return status === "done" || status === "canceled" ? "closed" : "opened";
 }
 
+/** ListFilter.{reportedByMe,assignedToMe} -> GitLab Issues API `scope` values -- see ListFilter's own doc comment. */
+function meScopes(filter: ListFilter): ("created_by_me" | "assigned_to_me")[] {
+  const scopes: ("created_by_me" | "assigned_to_me")[] = [];
+  if (filter.reportedByMe) scopes.push("created_by_me");
+  if (filter.assignedToMe) scopes.push("assigned_to_me");
+  return scopes;
+}
+
 function mapStatusEventToGitLab(status: Status): "close" | "reopen" {
   return status === "done" || status === "canceled" ? "close" : "reopen";
 }

package/src/issue/issue.ts

@@ -178,6 +178,30 @@ export interface ListFilter {
   assignee?: string;
   query?: string;
   limit?: number;
+  /**
+   * "Mine" filtering -- deliberately a small set of named, orthogonal boolean flags rather than
+   * either a hardcoded single `mine` concept or a generic cross-backend query language (see the
+   * research Doc "Tickets 'mine' filtering: grounded API research" for why both alternatives were
+   * rejected). Every backend maps each flag to its own native "current user" mechanism (Jira's JQL
+   * currentUser(), GitHub's Search API @me qualifiers, GitLab's scope=*_me) -- never a resolved
+   * literal username. Setting more than one of these ORs them together ("assignee OR reporter"),
+   * AND'd with every other ListFilter field exactly like today's plain fields. A backend that has
+   * no native equivalent for a given flag throws rather than silently ignoring it (e.g.
+   * reviewRequestedOfMe on Jira, qaContactIsMe on GitHub/GitLab) -- a silently-dropped role would
+   * make an incomplete result look complete.
+   */
+  /** Jira: `reporter = currentUser()`. GitHub: `author:@me` (Search API). GitLab: `scope=created_by_me` (Issues API). */
+  reportedByMe?: boolean;
+  /** Jira: `assignee = currentUser()`. GitHub: `assignee:@me` (Search API). GitLab: `scope=assigned_to_me` (Issues API). */
+  assignedToMe?: boolean;
+  /**
+   * GitHub: `user-review-requested:@me` (Search API, PRs only). GitLab: `scope=reviews_for_me` --
+   * a merge-request-only concept list()'s Issues-only scope can't express, so GitLab throws. Jira
+   * has no reviewer concept on plain issues, so Jira throws too.
+   */
+  reviewRequestedOfMe?: boolean;
+  /** Jira only, via the discovered "QA Contact" custom field (auto-discovers if never run). GitHub/GitLab throw -- no equivalent concept. */
+  qaContactIsMe?: boolean;
 }
 
 /** "backend:key" ref parsing, split on the first colon only (keys may contain colons). */

package/src/jira/jira.ts

@@ -204,6 +204,11 @@ export class JiraRepository {
    * the background), not just the single legacy `project` config field.
    */
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.reviewRequestedOfMe) {
+      throw new Error(
+        'jira: "reviewRequestedOfMe" has no meaning on Jira issues (no reviewer concept) -- omit this filter for the jira backend',
+      );
+    }
     const projects = filter.project ? [filter.project] : this.defaultProjects();
     const clauses: string[] = [];
     const scope = projectClause(projects);
@@ -211,9 +216,30 @@ export class JiraRepository {
     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 meClauses = await this.buildMeClauses(filter);
+    if (meClauses.length > 0) clauses.push(meClauses.length === 1 ? meClauses[0]! : `(${meClauses.join(" OR ")})`);
     return this.searchJql(buildJql(clauses, "AND"), filter.limit ?? 50);
   }
 
+  /**
+   * Builds the OR'd group of "me" role clauses for list()'s ListFilter.{reportedByMe,assignedToMe,
+   * qaContactIsMe} flags -- see ListFilter's own doc comment for why this is a small set of named
+   * flags rather than a hardcoded single "mine" concept or a generic query language. "QA Contact"
+   * resolves through the same discoverFields()-backed manifest applyCustomFields() already uses
+   * (auto-discovering on first use), so an instance without that field throws a clear "unknown
+   * custom field" error rather than silently omitting the clause.
+   */
+  private async buildMeClauses(filter: ListFilter): Promise<string[]> {
+    const clauses: string[] = [];
+    if (filter.assignedToMe) clauses.push("assignee = currentUser()");
+    if (filter.reportedByMe) clauses.push("reporter = currentUser()");
+    if (filter.qaContactIsMe) {
+      await this.resolveCustomField("QA Contact");
+      clauses.push('"QA Contact" = currentUser()');
+    }
+    return clauses;
+  }
+
   async get(key: string): Promise<Issue> {
     const [raw, remoteLinks] = await Promise.all([
       this.call<JiraIssue>(() => this.client.issues.getIssue({ issueIdOrKey: key }), key),

package/src/process/bootstrap.ts

@@ -19,8 +19,10 @@ import { buildApp, type TicketsAppDeps } from "../rpc/server.js";
 import { FOCUS_MIGRATIONS, FocusStore } from "../sqlite/focus.js";
 import { LEDGER_MIGRATIONS, Ledger } from "../sqlite/ledger.js";
 import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "../sqlite/saved-queries.js";
+import { WATCH_MIGRATIONS, WatchStore } from "../sqlite/watches.js";
 import { StageStore } from "../stage/store.js";
 import { createSyncTask } from "./poller.js";
+import { createIssueWatchSyncTask, createQueryWatchSyncTask } from "./watch-sync.js";
 
 export interface BootstrapOptions {
   pathEnv?: PathEnvironment;
@@ -39,6 +41,10 @@ export interface BootstrapOptions {
   checkpointIntervalMs?: number;
   /** How often the live backend set re-resolves from config/env/Enigma. Ignored when repos is injected. */
   backendRefreshIntervalMs?: number;
+  /** How often every subscribed issue is re-fetched and diffed. Defaults to DEFAULT_ISSUE_WATCH_INTERVAL_MS. */
+  issueWatchIntervalMs?: number;
+  /** How often every subscribed saved query is re-run and diffed. Defaults to DEFAULT_QUERY_WATCH_INTERVAL_MS. */
+  queryWatchIntervalMs?: number;
   /**
    * Overrides the daemon.shutdown op's effect. Defaults to sending this
    * process SIGTERM, which vehicle-server's runDaemonProcess already handles
@@ -54,6 +60,7 @@ export interface BootstrappedDaemon {
   focusStore: FocusStore;
   queries: SavedQueryStore;
   stageStore: StageStore;
+  watches: WatchStore;
   service: TicketService;
   options: StartDaemonOptions;
 }
@@ -61,15 +68,23 @@ export interface BootstrappedDaemon {
 const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_CHECKPOINT_INTERVAL_MS = 10 * 60_000;
 const DEFAULT_BACKEND_REFRESH_INTERVAL_MS = 30_000;
+/** Deliberately coarser than pipes' own 30s RUN_POOL_SYNC_INTERVAL_MS -- a CI run's status changes
+ * on the order of seconds/minutes; an issue's comments/status change on the order of minutes/hours,
+ * so polling that fast would only waste API quota against GitHub/GitLab/Jira's own rate limits. */
+const DEFAULT_ISSUE_WATCH_INTERVAL_MS = 60_000;
+const DEFAULT_QUERY_WATCH_INTERVAL_MS = 60_000;
 
 export async function bootstrap(opts: BootstrapOptions = {}): Promise<BootstrappedDaemon> {
   const paths = resolveDaemonPaths(TICKETS_DAEMON_NAMES, opts.pathEnv);
   const token = ensureAuthToken(paths.token, "Tickets");
-  const db = openSqliteWithPragmas(paths.database, { migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS, ...SAVED_QUERY_MIGRATIONS] });
+  const db = openSqliteWithPragmas(paths.database, {
+    migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS, ...SAVED_QUERY_MIGRATIONS, ...WATCH_MIGRATIONS],
+  });
   const ledger = new Ledger(db);
   const focusStore = new FocusStore(db);
   const queries = new SavedQueryStore(db);
   const stageStore = new StageStore();
+  const watches = new WatchStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
   const config = opts.config ?? loadConfig();
   const buildRepos = opts.buildRepositories ?? buildRepositories;
@@ -88,6 +103,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     focusStore,
     queries,
     stageStore,
+    watches,
     token,
     version,
     logger,
@@ -100,6 +116,8 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     logger,
     maintenanceTasks: [
       createSyncTask(service, ledger, opts.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, logger),
+      createIssueWatchSyncTask(service, watches, opts.issueWatchIntervalMs ?? DEFAULT_ISSUE_WATCH_INTERVAL_MS, logger),
+      createQueryWatchSyncTask(service, queries, watches, opts.queryWatchIntervalMs ?? DEFAULT_QUERY_WATCH_INTERVAL_MS, logger),
       {
         name: "checkpoint",
         intervalMs: opts.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS,
@@ -127,6 +145,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
         focusStore,
         queries,
         stageStore,
+        watches,
         token,
         version,
         logger,
@@ -138,5 +157,5 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     },
   };
 
-  return { db, ledger, focusStore, queries, stageStore, service, options };
+  return { db, ledger, focusStore, queries, stageStore, watches, service, options };
 }

package/src/process/watch-sync.ts

@@ -0,0 +1,204 @@
+/**
+ * Watch sync — the tickets daemon's own analog of @danypops/pipes' run/monitor.ts's syncRunPool,
+ * for individual issues and saved queries instead of CI jobs. Two independent maintenance tasks
+ * (createIssueWatchSyncTask / createQueryWatchSyncTask, wired in process/bootstrap.ts), same
+ * shape as pipes': read the current subscription list fresh from SQLite every tick, group by key
+ * (so N subscribers on the same ref/query share one live fetch), skip anything not yet due per its
+ * own scheduleMs, fetch once per due group, diff against the last-cached snapshot, and only
+ * persist a WatchEvent (via WatchStore.recordEvent) on a real, human-describable change.
+ *
+ * Deliberately never unsubscribes anything on its own (see watches.ts's own doc comment) -- a
+ * failed fetch for one key is logged and skipped, retried next tick, exactly like pipes' own
+ * per-group isolation.
+ */
+import type { MaintenanceTask } from "@danypops/vehicle-server/daemon";
+import type { Logger } from "@danypops/vehicle-server/logging";
+import type { TicketService } from "../issue/service.js";
+import type { SavedQueryStore } from "../sqlite/saved-queries.js";
+import type { IssueWatchSubscription, QueryWatchSubscription, WatchStore } from "../sqlite/watches.js";
+
+const NOOP_LOGGER: Logger = { debug() {}, info() {}, warn() {}, error() {} };
+
+const DEFAULT_QUERY_WATCH_LIMIT = 50;
+
+/** True if this subscription's own cadence has elapsed since it was last checked -- always true for a subscription with no scheduleMs, matching pipes' own isDue. */
+function isDue(subscription: { scheduleMs?: number; lastCheckedAt?: Date }, nowMs: number): boolean {
+  if (subscription.scheduleMs === undefined) return true;
+  if (subscription.lastCheckedAt === undefined) return true;
+  return nowMs - subscription.lastCheckedAt.getTime() >= subscription.scheduleMs;
+}
+
+function groupBy<T, K>(items: T[], key: (item: T) => K): Map<K, T[]> {
+  const groups = new Map<K, T[]>();
+  for (const item of items) {
+    const k = key(item);
+    const existing = groups.get(k);
+    if (existing) existing.push(item);
+    else groups.set(k, [item]);
+  }
+  return groups;
+}
+
+/**
+ * Best-effort comment count: undefined (never diffed on) for a backend that doesn't support
+ * comments at all (NotSupportedError) or a transient failure fetching them -- a missing comment
+ * count must never itself look like "0 comments" and falsely report "N new comments" once support
+ * (or connectivity) returns.
+ */
+async function tryCommentCount(service: TicketService, ref: string): Promise<number | undefined> {
+  try {
+    return (await service.comments(ref)).length;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Human-readable diffs between two issue snapshots, most specific first. Empty means "no real, describable change" even if fetched_at moved. */
+function diffIssueSnapshot(
+  previous: { status: string; updatedAt?: string; commentCount?: number } | undefined,
+  current: { status: string; updatedAt?: string; commentCount?: number },
+): string[] {
+  if (!previous) return [];
+  const changes: string[] = [];
+  if (current.status !== previous.status) changes.push(`status: ${previous.status} -> ${current.status}`);
+  if (current.commentCount !== undefined && previous.commentCount !== undefined && current.commentCount > previous.commentCount) {
+    const added = current.commentCount - previous.commentCount;
+    changes.push(`${added} new comment${added === 1 ? "" : "s"}`);
+  }
+  // A generic fallback for a backend-reported update this diff can't further characterize (a field
+  // edit, a label/assignee change, ...) -- only surfaced when nothing more specific already explains
+  // it, so a status change never also reports a redundant "updated".
+  if (changes.length === 0 && current.updatedAt !== undefined && current.updatedAt !== previous.updatedAt) {
+    changes.push("updated");
+  }
+  return changes;
+}
+
+export interface IssueWatchChange {
+  ref: string;
+  changes: string[];
+}
+
+/** One tick: fetches every due watched issue once (deduped across subscribers), diffs, and records a WatchEvent per real change. */
+export async function syncIssueWatches(
+  service: TicketService,
+  watches: WatchStore,
+  logger: Logger = NOOP_LOGGER,
+  onChange?: (change: IssueWatchChange) => void,
+  now: () => number = Date.now,
+): Promise<void> {
+  const groups = groupBy(watches.issueSubscriptions(), (s: IssueWatchSubscription) => s.ref);
+  const nowMs = now();
+  const due = [...groups.entries()].filter(([, subs]) => subs.some((s) => isDue(s, nowMs)));
+
+  await Promise.all(
+    due.map(async ([ref, subs]) => {
+      try {
+        const issue = await service.get(ref);
+        const commentCount = await tryCommentCount(service, ref);
+        const previous = watches.getIssueSnapshot(ref);
+        const fetchedAt = new Date(nowMs);
+        watches.upsertIssueSnapshot({ ref, status: issue.status, updatedAt: issue.updatedAt, commentCount: commentCount ?? 0, fetchedAt });
+
+        const changes = diffIssueSnapshot(
+          previous ? { status: previous.status, updatedAt: previous.updatedAt, commentCount: previous.commentCount } : undefined,
+          { status: issue.status, updatedAt: issue.updatedAt, commentCount },
+        );
+        if (changes.length > 0) {
+          const message = `${ref} (${issue.title}): ${changes.join(", ")}`;
+          watches.recordEvent("issue", ref, message, fetchedAt);
+          onChange?.({ ref, changes });
+        }
+        for (const subscription of subs) watches.markIssueChecked(ref, subscription.subscriberId, fetchedAt);
+      } catch (error) {
+        logger.warn("issue watch sync failed for one ref", { ref, error: error instanceof Error ? error.message : String(error) });
+      }
+    }),
+  );
+}
+
+export interface QueryWatchChange {
+  name: string;
+  added: string[];
+  removed: string[];
+}
+
+/** One tick: re-runs every due watched saved query once, diffs the *set* of matching refs against last time, and records a WatchEvent when items appeared or dropped out. */
+export async function syncQueryWatches(
+  service: TicketService,
+  queries: SavedQueryStore,
+  watches: WatchStore,
+  logger: Logger = NOOP_LOGGER,
+  onChange?: (change: QueryWatchChange) => void,
+  now: () => number = Date.now,
+): Promise<void> {
+  const groups = groupBy(watches.queryWatchSubscriptions(), (s: QueryWatchSubscription) => s.name);
+  const nowMs = now();
+  const due = [...groups.entries()].filter(([, subs]) => subs.some((s) => isDue(s, nowMs)));
+
+  await Promise.all(
+    due.map(async ([name, subs]) => {
+      try {
+        const saved = queries.get(name);
+        if (!saved) {
+          logger.warn("watched saved query no longer exists", { name });
+          return;
+        }
+        const issues = await service.runQuery(saved.backend, saved.query, DEFAULT_QUERY_WATCH_LIMIT);
+        const refs = issues.map((issue) => issue.ref);
+        const previous = watches.getQuerySnapshot(name);
+        const fetchedAt = new Date(nowMs);
+        watches.upsertQuerySnapshot({ name, refs, fetchedAt });
+
+        if (previous) {
+          const previousSet = new Set(previous.refs);
+          const currentSet = new Set(refs);
+          const added = refs.filter((ref) => !previousSet.has(ref));
+          const removed = previous.refs.filter((ref) => !currentSet.has(ref));
+          if (added.length > 0 || removed.length > 0) {
+            const parts: string[] = [];
+            if (added.length > 0) parts.push(`${added.length} new: ${added.join(", ")}`);
+            if (removed.length > 0) parts.push(`${removed.length} dropped out: ${removed.join(", ")}`);
+            const message = `"${name}": ${parts.join("; ")}`;
+            watches.recordEvent("query", name, message, fetchedAt);
+            onChange?.({ name, added, removed });
+          }
+        }
+        for (const subscription of subs) watches.markQueryChecked(name, subscription.subscriberId, fetchedAt);
+      } catch (error) {
+        logger.warn("query watch sync failed for one saved query", { name, error: error instanceof Error ? error.message : String(error) });
+      }
+    }),
+  );
+}
+
+/** MaintenanceTask wrapper for syncIssueWatches -- reads watches.issueSubscriptions() fresh every tick, so an empty watch list means this tick does no live fetches at all (see this module's own doc comment). */
+export function createIssueWatchSyncTask(
+  service: TicketService,
+  watches: WatchStore,
+  intervalMs: number,
+  logger?: Logger,
+  onChange?: (change: IssueWatchChange) => void,
+): MaintenanceTask {
+  return {
+    name: "issue-watch-sync",
+    intervalMs,
+    run: () => syncIssueWatches(service, watches, logger, onChange),
+  };
+}
+
+/** MaintenanceTask wrapper for syncQueryWatches -- same empty-watch-list-is-a-no-op shape as createIssueWatchSyncTask. */
+export function createQueryWatchSyncTask(
+  service: TicketService,
+  queries: SavedQueryStore,
+  watches: WatchStore,
+  intervalMs: number,
+  logger?: Logger,
+  onChange?: (change: QueryWatchChange) => void,
+): MaintenanceTask {
+  return {
+    name: "query-watch-sync",
+    intervalMs,
+    run: () => syncQueryWatches(service, queries, watches, logger, onChange),
+  };
+}

package/src/rpc/ops.ts

@@ -9,6 +9,7 @@ import type { BackendCapabilities } from "../issue/service.js";
 import type { Template } from "../issue/template.js";
 import type { TicketFocusState } from "../sqlite/focus.js";
 import type { SavedQuery } from "../sqlite/saved-queries.js";
+import type { IssueWatchSubscription, QueryWatchSubscription, WatchEvent } from "../sqlite/watches.js";
 import type { StagedItem, StagePatchFields, StagePayload } from "../stage/store.js";
 
 export type TicketOperation =
@@ -40,6 +41,13 @@ export type TicketOperation =
   | "query.list"
   | "query.remove"
   | "query.run"
+  | "issue.subscribe"
+  | "issue.unsubscribe"
+  | "issue.subscribed"
+  | "query.subscribe"
+  | "query.unsubscribe"
+  | "query.subscribed"
+  | "watch.events"
   | "stage.add"
   | "stage.list"
   | "stage.show"
@@ -77,6 +85,13 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "query.list": Record<string, never>;
   "query.remove": { name: string };
   "query.run": { name: string; limit?: number };
+  "issue.subscribe": { ref: string; subscriberId?: string; scheduleMs?: number; projectRoot?: string };
+  "issue.unsubscribe": { ref: string; subscriberId?: string };
+  "issue.subscribed": { subscriberId?: string };
+  "query.subscribe": { name: string; subscriberId?: string; scheduleMs?: number; projectRoot?: string };
+  "query.unsubscribe": { name: string; subscriberId?: string };
+  "query.subscribed": { subscriberId?: string };
+  "watch.events": { subscriberId?: string; sinceId?: number; limit?: number };
   "stage.add": { payload: StagePayload };
   "stage.list": Record<string, never>;
   "stage.show": { id: string };
@@ -118,6 +133,13 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "query.list": { queries: SavedQuery[] };
   "query.remove": { removed: boolean };
   "query.run": { issues: Issue[] };
+  "issue.subscribe": { subscribed: true };
+  "issue.unsubscribe": { unsubscribed: true };
+  "issue.subscribed": { watches: IssueWatchSubscription[] };
+  "query.subscribe": { subscribed: true };
+  "query.unsubscribe": { unsubscribed: true };
+  "query.subscribed": { watches: QueryWatchSubscription[] };
+  "watch.events": { events: WatchEvent[]; lastId: number };
   "stage.add": { item: StagedItem };
   "stage.list": { items: StagedItem[] };
   "stage.show": { item: StagedItem };
@@ -156,6 +178,13 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "query.list",
   "query.remove",
   "query.run",
+  "issue.subscribe",
+  "issue.unsubscribe",
+  "issue.subscribed",
+  "query.subscribe",
+  "query.unsubscribe",
+  "query.subscribed",
+  "watch.events",
   "stage.add",
   "stage.list",
   "stage.show",

package/src/rpc/server.ts

@@ -16,6 +16,7 @@ import type { TicketService } from "../issue/service.js";
 import { FocusError, type FocusStore } from "../sqlite/focus.js";
 import type { Ledger } from "../sqlite/ledger.js";
 import { SavedQueryNotFoundError, type SavedQueryStore } from "../sqlite/saved-queries.js";
+import type { WatchStore } from "../sqlite/watches.js";
 import type { StagePayload, StageStore } from "../stage/store.js";
 import { statusForKnownTicketError } from "./error-status.js";
 import { type StagePushResult, TICKET_OPERATIONS, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "./ops.js";
@@ -45,6 +46,20 @@ export interface TicketsAppDeps {
    */
   vehicleRegistry: VehicleRegistry;
   stageStore: StageStore;
+  watches: WatchStore;
+}
+
+/**
+ * The subset of a Vehicle call's own identity a handful of handlers read for a sensible default --
+ * see issue.subscribe/query.subscribe below, which default subscriberId/projectRoot from these
+ * when the caller doesn't pass them explicitly, mirroring @danypops/pipes' own ci.subscribe.
+ * Always undefined-safe: absent entirely for the raw HTTP /api/v1/ops dispatch (which has no Pi
+ * session behind it), present when the call came through agent-tools/tickets-vehicle.ts's
+ * Vehicle registration (see its own VehicleOperationContext.callerSessionId/callerProjectRoot).
+ */
+export interface HandlerCallContext {
+  callerSessionId?: string;
+  callerProjectRoot?: string;
 }
 
 // Narrower than TicketsAppDeps on purpose: no real handler reads
@@ -53,6 +68,7 @@ export interface TicketsAppDeps {
 export type Handler<Op extends TicketOperation> = (
   deps: Omit<TicketsAppDeps, "vehicleRegistry">,
   input: TicketOpInputs[Op],
+  callContext?: HandlerCallContext,
 ) => Promise<TicketOpOutputs[Op]>;
 
 /**
@@ -109,6 +125,37 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
     if (!saved) throw new SavedQueryNotFoundError(input.name);
     return { issues: await deps.service.runQuery(saved.backend, saved.query, input.limit) };
   },
+  "issue.subscribe": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const projectRoot = input.projectRoot ?? callContext?.callerProjectRoot;
+    deps.watches.subscribeIssue(input.ref, { subscriberId, scheduleMs: input.scheduleMs, projectRoot });
+    return { subscribed: true };
+  },
+  "issue.unsubscribe": async (deps, input, callContext) => {
+    deps.watches.unsubscribeIssue(input.ref, input.subscriberId ?? callContext?.callerSessionId ?? "");
+    return { unsubscribed: true };
+  },
+  "issue.subscribed": async (deps, input, callContext) => ({
+    watches: deps.watches.issueSubscriptionsFor(input.subscriberId ?? callContext?.callerSessionId ?? ""),
+  }),
+  "query.subscribe": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const projectRoot = input.projectRoot ?? callContext?.callerProjectRoot;
+    deps.watches.subscribeQuery(input.name, { subscriberId, scheduleMs: input.scheduleMs, projectRoot });
+    return { subscribed: true };
+  },
+  "query.unsubscribe": async (deps, input, callContext) => {
+    deps.watches.unsubscribeQuery(input.name, input.subscriberId ?? callContext?.callerSessionId ?? "");
+    return { unsubscribed: true };
+  },
+  "query.subscribed": async (deps, input, callContext) => ({
+    watches: deps.watches.queryWatchSubscriptionsFor(input.subscriberId ?? callContext?.callerSessionId ?? ""),
+  }),
+  "watch.events": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const events = deps.watches.eventsSince(subscriberId, input.sinceId ?? 0, input.limit);
+    return { events, lastId: events.at(-1)?.id ?? input.sinceId ?? 0 };
+  },
   "stage.add": async (deps, input) => ({ item: deps.stageStore.add(input.payload) }),
   "stage.list": async (deps) => ({ items: deps.stageStore.list() }),
   "stage.show": async (deps, input) => ({ item: deps.stageStore.show(input.id) }),

package/src/sqlite/watches.ts

@@ -0,0 +1,355 @@
+/**
+ * Watches — the daemon's local subscription + last-known-snapshot store for individual issues
+ * and saved queries, mirroring @danypops/pipes' own job_watches/run_snapshots split
+ * (packages/pipes/src/sqlite/run-pool.ts) one domain over: `issue_watches`/`query_watches` are
+ * the authoritative subscription lists the background sync tasks (process/watch-sync.ts) iterate;
+ * `issue_watch_snapshots`/`query_watch_snapshots` hold each watched key's last-observed state,
+ * independent of subscriptions, so a sync tick can tell "did this actually change" apart from
+ * "this is the first time we've ever looked." `watch_events` is the append-only, cursor-readable
+ * change log a client polls (watch.events) instead of re-deriving a diff itself.
+ *
+ * Deliberately does NOT auto-unsubscribe on any kind of "terminal" state the way run_snapshots
+ * does for a finished CI run: an issue can be reopened and a saved query's result set has no
+ * notion of "done" at all, so nothing here is a permanent completion signal worth stopping a
+ * background poll over. A subscription only ever ends via an explicit issue.unsubscribe/
+ * query.unsubscribe call.
+ */
+import type { Database } from "bun:sqlite";
+import type { Migration } from "@danypops/vehicle-server/storage";
+
+export const WATCH_MIGRATIONS: Migration[] = [
+  {
+    version: 4,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE issue_watches (
+          ref TEXT NOT NULL,
+          subscriber_id TEXT NOT NULL DEFAULT '',
+          schedule_ms INTEGER,
+          last_checked_at INTEGER,
+          project_root TEXT,
+          PRIMARY KEY (ref, subscriber_id)
+        );
+        CREATE TABLE issue_watch_snapshots (
+          ref TEXT PRIMARY KEY,
+          status TEXT NOT NULL,
+          updated_at TEXT,
+          comment_count INTEGER NOT NULL DEFAULT 0,
+          fetched_at INTEGER NOT NULL
+        );
+        CREATE TABLE query_watches (
+          name TEXT NOT NULL,
+          subscriber_id TEXT NOT NULL DEFAULT '',
+          schedule_ms INTEGER,
+          last_checked_at INTEGER,
+          project_root TEXT,
+          PRIMARY KEY (name, subscriber_id)
+        );
+        CREATE TABLE query_watch_snapshots (
+          name TEXT PRIMARY KEY,
+          refs_json TEXT NOT NULL,
+          fetched_at INTEGER NOT NULL
+        );
+        CREATE TABLE watch_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          kind TEXT NOT NULL,
+          key TEXT NOT NULL,
+          message TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        CREATE INDEX watch_events_kind_key_idx ON watch_events(kind, key);
+      `);
+    },
+  },
+];
+
+export interface IssueWatchSubscription {
+  ref: string;
+  subscriberId: string;
+  scheduleMs?: number;
+  lastCheckedAt?: Date;
+  projectRoot?: string;
+}
+
+export interface QueryWatchSubscription {
+  name: string;
+  subscriberId: string;
+  scheduleMs?: number;
+  lastCheckedAt?: Date;
+  projectRoot?: string;
+}
+
+export interface IssueWatchSnapshot {
+  ref: string;
+  status: string;
+  updatedAt?: string;
+  commentCount: number;
+  fetchedAt: Date;
+}
+
+export interface QueryWatchSnapshot {
+  name: string;
+  refs: string[];
+  fetchedAt: Date;
+}
+
+export type WatchEventKind = "issue" | "query";
+
+export interface WatchEvent {
+  id: number;
+  kind: WatchEventKind;
+  /** The watched issue's ref, or the watched query's name. */
+  key: string;
+  message: string;
+  createdAt: Date;
+}
+
+interface IssueWatchRow {
+  ref: string;
+  subscriber_id: string;
+  schedule_ms: number | null;
+  last_checked_at: number | null;
+  project_root: string | null;
+}
+
+interface QueryWatchRow {
+  name: string;
+  subscriber_id: string;
+  schedule_ms: number | null;
+  last_checked_at: number | null;
+  project_root: string | null;
+}
+
+function toIssueSubscription(row: IssueWatchRow): IssueWatchSubscription {
+  return {
+    ref: row.ref,
+    subscriberId: row.subscriber_id,
+    scheduleMs: row.schedule_ms ?? undefined,
+    lastCheckedAt: row.last_checked_at !== null ? new Date(row.last_checked_at) : undefined,
+    projectRoot: row.project_root ?? undefined,
+  };
+}
+
+function toQuerySubscription(row: QueryWatchRow): QueryWatchSubscription {
+  return {
+    name: row.name,
+    subscriberId: row.subscriber_id,
+    scheduleMs: row.schedule_ms ?? undefined,
+    lastCheckedAt: row.last_checked_at !== null ? new Date(row.last_checked_at) : undefined,
+    projectRoot: row.project_root ?? undefined,
+  };
+}
+
+export class WatchStore {
+  constructor(private readonly db: Database) {}
+
+  // ---- issue watches ----
+
+  subscribeIssue(ref: string, options?: { subscriberId?: string; scheduleMs?: number; projectRoot?: string }): void {
+    const subscriberId = options?.subscriberId ?? "";
+    this.db
+      .query(
+        `INSERT INTO issue_watches (ref, subscriber_id, schedule_ms, project_root)
+         VALUES ($ref, $subscriberId, $scheduleMs, $projectRoot)
+         ON CONFLICT(ref, subscriber_id) DO UPDATE SET schedule_ms = excluded.schedule_ms, project_root = excluded.project_root`,
+      )
+      .run({
+        $ref: ref,
+        $subscriberId: subscriberId,
+        $scheduleMs: options?.scheduleMs ?? null,
+        $projectRoot: options?.projectRoot ?? null,
+      });
+  }
+
+  unsubscribeIssue(ref: string, subscriberId = ""): void {
+    this.db
+      .query("DELETE FROM issue_watches WHERE ref = $ref AND subscriber_id = $subscriberId")
+      .run({ $ref: ref, $subscriberId: subscriberId });
+  }
+
+  isIssueSubscribed(ref: string, subscriberId = ""): boolean {
+    return (
+      this.db.query("SELECT 1 FROM issue_watches WHERE ref = $ref AND subscriber_id = $subscriberId").get({
+        $ref: ref,
+        $subscriberId: subscriberId,
+      }) !== null
+    );
+  }
+
+  /** Every individual issue subscription -- what the sync task iterates. */
+  issueSubscriptions(): IssueWatchSubscription[] {
+    const rows = this.db.query("SELECT * FROM issue_watches").all() as IssueWatchRow[];
+    return rows.map(toIssueSubscription);
+  }
+
+  /** Subscriptions scoped to one subscriber -- what issue.subscribed returns. */
+  issueSubscriptionsFor(subscriberId: string): IssueWatchSubscription[] {
+    const rows = this.db.query("SELECT * FROM issue_watches WHERE subscriber_id = $subscriberId").all({
+      $subscriberId: subscriberId,
+    }) as IssueWatchRow[];
+    return rows.map(toIssueSubscription);
+  }
+
+  markIssueChecked(ref: string, subscriberId: string, at: Date): void {
+    this.db
+      .query("UPDATE issue_watches SET last_checked_at = $at WHERE ref = $ref AND subscriber_id = $subscriberId")
+      .run({ $at: at.getTime(), $ref: ref, $subscriberId: subscriberId });
+  }
+
+  getIssueSnapshot(ref: string): IssueWatchSnapshot | undefined {
+    const row = this.db.query("SELECT * FROM issue_watch_snapshots WHERE ref = $ref").get({ $ref: ref }) as {
+      ref: string;
+      status: string;
+      updated_at: string | null;
+      comment_count: number;
+      fetched_at: number;
+    } | null;
+    if (!row) return undefined;
+    return {
+      ref: row.ref,
+      status: row.status,
+      updatedAt: row.updated_at ?? undefined,
+      commentCount: row.comment_count,
+      fetchedAt: new Date(row.fetched_at),
+    };
+  }
+
+  upsertIssueSnapshot(snapshot: IssueWatchSnapshot): void {
+    this.db
+      .query(
+        `INSERT INTO issue_watch_snapshots (ref, status, updated_at, comment_count, fetched_at)
+         VALUES ($ref, $status, $updatedAt, $commentCount, $fetchedAt)
+         ON CONFLICT(ref) DO UPDATE SET status = excluded.status, updated_at = excluded.updated_at, comment_count = excluded.comment_count, fetched_at = excluded.fetched_at`,
+      )
+      .run({
+        $ref: snapshot.ref,
+        $status: snapshot.status,
+        $updatedAt: snapshot.updatedAt ?? null,
+        $commentCount: snapshot.commentCount,
+        $fetchedAt: snapshot.fetchedAt.getTime(),
+      });
+  }
+
+  // ---- query watches ----
+
+  subscribeQuery(name: string, options?: { subscriberId?: string; scheduleMs?: number; projectRoot?: string }): void {
+    const subscriberId = options?.subscriberId ?? "";
+    this.db
+      .query(
+        `INSERT INTO query_watches (name, subscriber_id, schedule_ms, project_root)
+         VALUES ($name, $subscriberId, $scheduleMs, $projectRoot)
+         ON CONFLICT(name, subscriber_id) DO UPDATE SET schedule_ms = excluded.schedule_ms, project_root = excluded.project_root`,
+      )
+      .run({
+        $name: name,
+        $subscriberId: subscriberId,
+        $scheduleMs: options?.scheduleMs ?? null,
+        $projectRoot: options?.projectRoot ?? null,
+      });
+  }
+
+  unsubscribeQuery(name: string, subscriberId = ""): void {
+    this.db
+      .query("DELETE FROM query_watches WHERE name = $name AND subscriber_id = $subscriberId")
+      .run({ $name: name, $subscriberId: subscriberId });
+  }
+
+  isQuerySubscribed(name: string, subscriberId = ""): boolean {
+    return (
+      this.db.query("SELECT 1 FROM query_watches WHERE name = $name AND subscriber_id = $subscriberId").get({
+        $name: name,
+        $subscriberId: subscriberId,
+      }) !== null
+    );
+  }
+
+  queryWatchSubscriptions(): QueryWatchSubscription[] {
+    const rows = this.db.query("SELECT * FROM query_watches").all() as QueryWatchRow[];
+    return rows.map(toQuerySubscription);
+  }
+
+  queryWatchSubscriptionsFor(subscriberId: string): QueryWatchSubscription[] {
+    const rows = this.db.query("SELECT * FROM query_watches WHERE subscriber_id = $subscriberId").all({
+      $subscriberId: subscriberId,
+    }) as QueryWatchRow[];
+    return rows.map(toQuerySubscription);
+  }
+
+  markQueryChecked(name: string, subscriberId: string, at: Date): void {
+    this.db
+      .query("UPDATE query_watches SET last_checked_at = $at WHERE name = $name AND subscriber_id = $subscriberId")
+      .run({ $at: at.getTime(), $name: name, $subscriberId: subscriberId });
+  }
+
+  getQuerySnapshot(name: string): QueryWatchSnapshot | undefined {
+    const row = this.db.query("SELECT * FROM query_watch_snapshots WHERE name = $name").get({ $name: name }) as {
+      name: string;
+      refs_json: string;
+      fetched_at: number;
+    } | null;
+    if (!row) return undefined;
+    return { name: row.name, refs: JSON.parse(row.refs_json) as string[], fetchedAt: new Date(row.fetched_at) };
+  }
+
+  upsertQuerySnapshot(snapshot: QueryWatchSnapshot): void {
+    this.db
+      .query(
+        `INSERT INTO query_watch_snapshots (name, refs_json, fetched_at)
+         VALUES ($name, $refsJson, $fetchedAt)
+         ON CONFLICT(name) DO UPDATE SET refs_json = excluded.refs_json, fetched_at = excluded.fetched_at`,
+      )
+      .run({ $name: snapshot.name, $refsJson: JSON.stringify(snapshot.refs), $fetchedAt: snapshot.fetchedAt.getTime() });
+  }
+
+  // ---- change events ----
+
+  /** Appends one change event -- called only by the sync tasks, once per real diff. */
+  recordEvent(kind: WatchEventKind, key: string, message: string, at: Date = new Date()): void {
+    this.db
+      .query("INSERT INTO watch_events (kind, key, message, created_at) VALUES ($kind, $key, $message, $createdAt)")
+      .run({ $kind: kind, $key: key, $message: message, $createdAt: at.getTime() });
+  }
+
+  /**
+   * Events since `sinceId` (exclusive), newest-last, bounded by `limit`, scoped to keys the given
+   * subscriber is *currently* subscribed to (an EXISTS join against issue_watches/query_watches --
+   * same scoping shape run-pool.ts's watchedRunsWithProjectLabels already uses for subscriberId).
+   * An event for a key this subscriber never subscribed to, or already unsubscribed from, never
+   * appears here -- avoids a global firehose leaking one session's watches into another's.
+   */
+  eventsSince(subscriberId: string, sinceId: number, limit = 100): WatchEvent[] {
+    const bounded = Math.max(1, Math.min(500, Math.floor(limit)));
+    const rows = this.db
+      .query(
+        `SELECT * FROM watch_events
+         WHERE id > $sinceId
+           AND (
+             (kind = 'issue' AND EXISTS (SELECT 1 FROM issue_watches WHERE issue_watches.ref = watch_events.key AND issue_watches.subscriber_id = $subscriberId))
+             OR
+             (kind = 'query' AND EXISTS (SELECT 1 FROM query_watches WHERE query_watches.name = watch_events.key AND query_watches.subscriber_id = $subscriberId))
+           )
+         ORDER BY id ASC
+         LIMIT $limit`,
+      )
+      .all({ $sinceId: sinceId, $subscriberId: subscriberId, $limit: bounded }) as Array<{
+      id: number;
+      kind: string;
+      key: string;
+      message: string;
+      created_at: number;
+    }>;
+    return rows.map((row) => ({
+      id: row.id,
+      kind: row.kind as WatchEventKind,
+      key: row.key,
+      message: row.message,
+      createdAt: new Date(row.created_at),
+    }));
+  }
+
+  /** The highest event id recorded so far, or 0 if none -- lets a fresh subscriber start its cursor at "now" instead of replaying every historical event. */
+  latestEventId(): number {
+    const row = this.db.query("SELECT MAX(id) as max_id FROM watch_events").get() as { max_id: number | null } | null;
+    return row?.max_id ?? 0;
+  }
+}