@danypops/tickets 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/vehicle-core": "^0.13.0",
-    "@danypops/vehicle-server": "^0.18.4",
-    "@danypops/vehicle-client": "^0.7.1",
+    "@danypops/vehicle-core": "^0.15.0",
+    "@danypops/vehicle-server": "^0.21.1",
+    "@danypops/vehicle-client": "^0.8.1",
     "@danypops/enigma-client": "^0.6.1",
     "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.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

@@ -16,11 +16,14 @@ import type { IssueRepository } from "../issue/repository.js";
 import { TicketService } from "../issue/service.js";
 import { TICKETS_DAEMON_NAMES } from "../rpc/ops.js";
 import { buildApp, type TicketsAppDeps } from "../rpc/server.js";
-import { FOCUS_MIGRATIONS, FocusStore } from "../sqlite/focus.js";
+import { FOCUS_MIGRATIONS, FOCUS_STALE_AFTER_MS, FocusStore } from "../sqlite/focus.js";
 import { LEDGER_MIGRATIONS, Ledger } from "../sqlite/ledger.js";
 import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "../sqlite/saved-queries.js";
+import { SESSION_IDENTITY_MIGRATIONS, SqliteSessionIdentityStore } from "../sqlite/session-identity.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 +42,12 @@ 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;
+  /** How often stale (untouched for FOCUS_STALE_AFTER_MS) Focus scopes are reaped. Defaults to DEFAULT_FOCUS_REAP_INTERVAL_MS. */
+  focusReapIntervalMs?: number;
   /**
    * Overrides the daemon.shutdown op's effect. Defaults to sending this
    * process SIGTERM, which vehicle-server's runDaemonProcess already handles
@@ -54,6 +63,8 @@ export interface BootstrappedDaemon {
   focusStore: FocusStore;
   queries: SavedQueryStore;
   stageStore: StageStore;
+  watches: WatchStore;
+  sessionIdentity: SqliteSessionIdentityStore;
   service: TicketService;
   options: StartDaemonOptions;
 }
@@ -61,15 +72,26 @@ 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;
+/** Focus scopes are session-lifetime pointers, not hot state -- reaping once an hour is plenty prompt against FOCUS_STALE_AFTER_MS's own 30-day window. */
+const DEFAULT_FOCUS_REAP_INTERVAL_MS = 60 * 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, ...SESSION_IDENTITY_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 sessionIdentity = new SqliteSessionIdentityStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
   const config = opts.config ?? loadConfig();
   const buildRepos = opts.buildRepositories ?? buildRepositories;
@@ -88,6 +110,8 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     focusStore,
     queries,
     stageStore,
+    watches,
+    sessionIdentity,
     token,
     version,
     logger,
@@ -100,11 +124,21 @@ 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,
         run: () => checkpoint(db),
       },
+      {
+        name: "focus-reap-stale",
+        intervalMs: opts.focusReapIntervalMs ?? DEFAULT_FOCUS_REAP_INTERVAL_MS,
+        run: () => {
+          const removed = focusStore.reapStale(new Date(Date.now() - FOCUS_STALE_AFTER_MS).toISOString());
+          if (removed > 0) logger.debug("reaped stale focus scopes", { removed });
+        },
+      },
       // Only when repos came from real config/env/Enigma resolution -- an
       // injected test fixture (opts.repos) has no config to re-resolve from.
       ...(opts.repos === undefined
@@ -127,6 +161,8 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
         focusStore,
         queries,
         stageStore,
+        watches,
+        sessionIdentity,
         token,
         version,
         logger,
@@ -138,5 +174,5 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     },
   };
 
-  return { db, ledger, focusStore, queries, stageStore, service, options };
+  return { db, ledger, focusStore, queries, stageStore, watches, sessionIdentity, 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/error-status.ts

@@ -2,6 +2,7 @@ import { AuthRequiredError, IssueNotFoundError } from "../issue/errors.js";
 import { NotSupportedError, UnknownBackendError } from "../issue/service.js";
 import { FocusError } from "../sqlite/focus.js";
 import { SavedQueryNotFoundError } from "../sqlite/saved-queries.js";
+import { SessionAuthError } from "../sqlite/session-identity.js";
 import { StagedItemNotFoundError } from "../stage/store.js";
 
 /** Returns the legacy HTTP status only for reviewed business errors; unknown failures stay unclassified. */
@@ -10,5 +11,6 @@ export function statusForKnownTicketError(error: unknown): number | undefined {
     return 404;
   if (error instanceof UnknownBackendError || error instanceof NotSupportedError || error instanceof FocusError) return 400;
   if (error instanceof AuthRequiredError) return 422;
+  if (error instanceof SessionAuthError) return 401;
   return undefined;
 }

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 =
@@ -31,6 +32,8 @@ export type TicketOperation =
   | "focus.pause"
   | "focus.unpause"
   | "focus.clear"
+  | "session.register"
+  | "session.release"
   | "discover.fields"
   | "discover.statuses"
   | "discover.template"
@@ -40,6 +43,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"
@@ -63,11 +73,31 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "issue.merge": { ref: string; method?: "merge" | "squash" | "rebase" };
   "ledger.search": { query: string; limit?: number; backend?: string };
   "ledger.stats": Record<string, never>;
-  "focus.set": { ref: string };
-  "focus.get": Record<string, never>;
-  "focus.pause": { reason?: string };
-  "focus.unpause": Record<string, never>;
-  "focus.clear": Record<string, never>;
+  /**
+   * sessionId: optional explicit scope override (see sqlite/focus.ts's own normalizeFocusScope) --
+   * defaults to callContext?.callerSessionId, then "global", the same input-wins-over-callContext
+   * precedence issue.subscribe/query.subscribe already established. sessionSecret authorizes an
+   * EXPLICIT sessionId claim against session.register's own identity store (see
+   * sqlite/session-identity.ts) -- never required, and never even read, for the implicit
+   * callContext.callerSessionId default, since a Vehicle-projected tool call's own
+   * callerSessionId is host-derived, not model-settable.
+   */
+  "focus.set": { ref: string; sessionId?: string; sessionSecret?: string };
+  "focus.get": { sessionId?: string };
+  "focus.pause": { reason?: string; sessionId?: string; sessionSecret?: string };
+  "focus.unpause": { sessionId?: string; sessionSecret?: string };
+  "focus.clear": { sessionId?: string; sessionSecret?: string };
+  /**
+   * No CLI command, and excluded from Vehicle tool projection (see agent-tools/tickets-vehicle.ts's
+   * own OWNER/OPERATIONS list) -- a pure client<->daemon handshake pi-tickets' own extension code
+   * calls directly (see pi-tickets' tui.ts), never a human- or model-meaningful action the way
+   * every other operation here is. daemon.shutdown is the one other operation with no Pi tool for
+   * a similar reason, but it at least keeps a human-facing CLI command (`daemon stop`); these two
+   * have no comparable human verb at all.
+   */
+  "session.register": { sessionId: string };
+  "session.release": { sessionId: string; sessionSecret?: string };
+
   "discover.fields": { backend: string };
   "discover.statuses": { backend: string };
   "discover.template": { backend: string; project: string; issueType: string; sampleSize?: number };
@@ -77,6 +107,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 };
@@ -109,6 +146,9 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "focus.pause": { focus: TicketFocusState };
   "focus.unpause": { focus: TicketFocusState };
   "focus.clear": { cleared: boolean };
+  /** secret: shown once, plaintext, on register -- never persisted or logged by the client, mirroring vehicle-server/session-identity's own contract. */
+  "session.register": { sessionId: string; secret: string };
+  "session.release": { released: true };
   "discover.fields": { mappings: Record<string, string> };
   "discover.statuses": { mappings: Record<string, string> };
   "discover.template": { template: Template | null };
@@ -118,6 +158,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 };
@@ -147,6 +194,8 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "focus.pause",
   "focus.unpause",
   "focus.clear",
+  "session.register",
+  "session.release",
   "discover.fields",
   "discover.statuses",
   "discover.template",
@@ -156,6 +205,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",