@danypops/tickets 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.12.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";
@@ -265,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:
@@ -419,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

@@ -158,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
@@ -321,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/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;
+  }
+}