@mattstack/rt-client 0.10.0 → 0.11.0

package/dist/index.js

@@ -14,7 +14,7 @@ async function rtCommand(cmd, payload, opts = {}) {
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "X-RT-Client": `rt-client/${process.pid}` },
       body: JSON.stringify(payload),
       signal: AbortSignal.timeout(opts.timeoutMs ?? 15000)
     });
@@ -242,6 +242,9 @@ function paneSend(a, o = {}) {
     payload.callerPane = a.callerPane;
   return rtCommand("pane:send", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
 }
+function paneFocus(a, o = {}) {
+  return rtCommand("pane:focus", { paneId: a.paneId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
 // src/commands.ts
 var COMMAND_NAMES = [
   "project-mrs:read",
@@ -282,7 +285,46 @@ var COMMAND_NAMES = [
   "pane:accounts",
   "pane:directories",
   "pane:spawn",
-  "pane:send"
+  "pane:send",
+  "pane:focus",
+  "cache:read",
+  "branch:enrich",
+  "cache:refresh",
+  "daemon:log-level",
+  "ping",
+  "status",
+  "tray:status",
+  "tcc:check",
+  "repos",
+  "ports",
+  "notifications",
+  "discussions:refresh",
+  "discussions:resolve",
+  "discussions:reply",
+  "discussions:diffs",
+  "mr:action",
+  "mr:fetch-job-detail",
+  "mr:fetch-job-trace",
+  "endpoint:claim",
+  "endpoint:lookup",
+  "endpoint:release",
+  "endpoint:status",
+  "repos:locate",
+  "freshness:reconcile",
+  "hooks:repair",
+  "hooks:watch",
+  "sdm:catalog",
+  "sdm:snapshot",
+  "sdm:recents",
+  "sdm:reconnect",
+  "system-processes",
+  "worktree:provision",
+  "worktree:create",
+  "worktree:dispose",
+  "worktree:list",
+  "worktree:restore",
+  "worktree:freshen",
+  "worktree:adopt"
 ];
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
@@ -409,6 +451,56 @@ function repoNameForPath(repoPath, reposJsonPath) {
     return fromDb;
   return repoNameFromJson(repoPath, jsonPath);
 }
+// src/smart-pane.ts
+var DEFAULT_MIN_COLS = 50;
+var DEFAULT_MIN_ROWS = 14;
+function decidePlacement(rect, opts = {}) {
+  const minCols = opts.minCols ?? DEFAULT_MIN_COLS;
+  const minRows = opts.minRows ?? DEFAULT_MIN_ROWS;
+  if (!rect || rect.width <= 0 || rect.height <= 0)
+    return { kind: "split", direction: "right" };
+  const canRight = rect.width >= 2 * minCols;
+  const canDown = rect.height >= 2 * minRows;
+  if (!canRight && !canDown)
+    return { kind: "tab" };
+  if (canRight && canDown) {
+    return rect.width > 2 * rect.height ? { kind: "split", direction: "right" } : { kind: "split", direction: "down" };
+  }
+  return canRight ? { kind: "split", direction: "right" } : { kind: "split", direction: "down" };
+}
+async function anchorRect(herdr, anchorPaneId) {
+  const r = await herdr("pane.layout", { pane_id: anchorPaneId });
+  if (!r.ok)
+    return null;
+  const pane = (r.result?.layout?.panes ?? []).find((p) => p.pane_id === anchorPaneId);
+  return pane?.rect ? { width: pane.rect.width, height: pane.rect.height } : null;
+}
+async function openSmartPane(herdr, anchorPaneId, opts = {}) {
+  const focus = opts.focus ?? true;
+  const placement = decidePlacement(await anchorRect(herdr, anchorPaneId), opts);
+  let paneId;
+  if (placement.kind === "split") {
+    const s = await herdr("pane.split", { pane_id: anchorPaneId, direction: placement.direction, focus });
+    if (!s.ok)
+      throw new Error(`pane.split failed: ${s.message}`);
+    paneId = s.result?.pane?.pane_id;
+    if (!paneId)
+      throw new Error("pane.split returned no pane_id");
+  } else {
+    const workspaceId = anchorPaneId.split(":")[0];
+    const t = await herdr("tab.create", { workspace_id: workspaceId, focus });
+    if (!t.ok)
+      throw new Error(`tab.create failed: ${t.message}`);
+    paneId = t.result?.root_pane?.pane_id;
+    if (!paneId)
+      throw new Error("tab.create returned no pane_id");
+  }
+  if (opts.command) {
+    await herdr("pane.send_text", { pane_id: paneId, text: opts.command });
+    await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+  }
+  return { paneId, placement };
+}
 // src/settings/resolve.ts
 import { homedir as homedir4 } from "os";
 import { join as join5 } from "path";
@@ -478,6 +570,15 @@ var REGISTRY = [
     migrated: true,
     description: "Per-repo worktree pool config (onDeck size, ready steps, name pool); root/branchFormat/ready computed-or-empty in the reader."
   },
+  {
+    key: "rt.worktreeReadyApproval",
+    type: "string",
+    scopes: ALL_SCOPES,
+    merge: "replace",
+    repoScoped: true,
+    migrated: true,
+    description: "Per-repo user approval of a team-authored `ready` shell ladder, as its content hash (RT-89). The reader trusts only user/machine scopes so a team store can never approve its own shell; a hash mismatch after a team edit re-holds the ladder until `rt worktree ready-approve` records the new one."
+  },
   {
     key: "rt.repoIdentityOverrides",
     type: "object",
@@ -623,6 +724,24 @@ var REGISTRY = [
     migrated: true,
     description: "Age floor in days for the log janitor pruning every surface's rotated log files under ~/.mattstack/rt/logs (default 14). A fresh key, not an ownership-latch port, so a default is fine here."
   },
+  {
+    key: "rt.logLevel",
+    type: "string",
+    scopes: ["machine", "user"],
+    default: "info",
+    merge: "replace",
+    migrated: true,
+    description: "Daemon log level (trace|debug|info|warn|error). RT_LOG_LEVEL env wins, then this setting, then info (lib/daemon-logger.ts resolveDaemonLogLevel). A fresh key, not an ownership-latch port, so a default is fine here."
+  },
+  {
+    key: "rt.apiPort",
+    type: "number",
+    scopes: ["machine", "user"],
+    default: 9401,
+    merge: "replace",
+    migrated: true,
+    description: "TCP port for the daemon's local HTTP/WS API. Escape hatch when 9401 is held: RT_API_PORT env wins, then this setting, then 9401 (lib/daemon-config.ts resolveApiPort(), read at bind time by lib/daemon/api-server.ts)."
+  },
   {
     key: "rt.hooks",
     type: "object",
@@ -632,6 +751,21 @@ var REGISTRY = [
     migrated: true,
     description: "Per-repo git hook enable/disable state ({enabled, hooks: {<hookName>: boolean}}); ownership-latch port of repos/<repo>/hooks.json, store wins per field once it owns the key — including per-hook-name entries inside the nested hooks map, each defaulting to enabled when absent. The installed git-hook shim still greps repos/<repo>/hooks.json with zero process spawns (a hook fires on every git operation); that file is now a DERIVED CACHE this key writes through, kept current by commands/hooks.ts's regenerateHooksCache at every write seam."
   },
+  {
+    key: "rt.daemonPath",
+    type: "string",
+    scopes: ["machine"],
+    merge: "replace",
+    description: "Absolute colon-separated PATH the daemon uses for every child it spawns, instead of probing your login shell. Set this when the daemon can't find node/git/bun/pnpm (e.g. a fish shell, a blocking .zshrc, or PATH exports that live only in .zshrc). Machine-scoped: it never travels to another machine."
+  },
+  {
+    key: "rt.trustedBrowserOrigins",
+    type: "array",
+    scopes: ["user", "machine"],
+    default: [],
+    merge: "replace",
+    description: "Browser Origins (scheme://host:port, exact string match) trusted to read the :9401 daemon API and subscribe to /ws without presenting the local api-token -- e.g. a locally-hosted console or chat-viewer dev server. Empty by default: every current mattstack consumer (the CLI, the Swift tray, rt-client from Bun/Node processes, the VS Code extension) is a non-browser client (sends no Origin header at all) and is unaffected either way."
+  },
   {
     key: "mattstack.integrations",
     type: "object",
@@ -1292,8 +1426,24 @@ function expandCtxFrom(opts) {
     teamsDir: teamsDir()
   };
 }
+var warnSink = null;
+var warnedOnce = new Set;
+function setSettingsWarnSink(sink) {
+  warnSink = sink;
+  warnedOnce.clear();
+}
+function emitSettingsWarning(msg) {
+  if (warnSink) {
+    if (warnedOnce.has(msg))
+      return;
+    warnedOnce.add(msg);
+    warnSink(msg);
+    return;
+  }
+  console.warn(msg);
+}
 function warnInvalid(key, entry) {
-  console.warn(`rt: ignoring "${key}" from the ${entry.scope} scope (${entry.file ?? "no file"}): ${entry.reason}`);
+  emitSettingsWarning(`rt: ignoring "${key}" from the ${entry.scope} scope (${entry.file ?? "no file"}): ${entry.reason}`);
 }
 function getSetting(key, opts = {}) {
   const def = getDef(key);
@@ -1328,7 +1478,7 @@ function listSettings(opts = {}) {
         listed.value = expandVariables(resolution.value, ctx);
       } catch (err) {
         listed.expandError = err.message;
-        console.warn(`rt: showing "${def.key}" unexpanded — ${listed.expandError}`);
+        emitSettingsWarning(`rt: showing "${def.key}" unexpanded — ${listed.expandError}`);
       }
     }
     out.push(listed);
@@ -1356,7 +1506,7 @@ function listUnregistered(stores, opts) {
   scan("machine", stores.machine.file, stores.machine.global);
   scan("machine.repo", stores.machine.file, repoSection(stores.machine));
   return [...found.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, hit]) => {
-    console.warn(`rt: unregistered setting "${key}" in ${hit.file} — ignoring it (this rt may be older than the store)`);
+    emitSettingsWarning(`rt: unregistered setting "${key}" in ${hit.file} — ignoring it (this rt may be older than the store)`);
     return {
       key,
       value: hit.value,
@@ -1581,21 +1731,42 @@ async function runCapture(argv, opts = {}) {
   } catch {
     return { stdout: "", stderr: "", exitCode: -1 };
   }
-  const timer = setTimeout(() => {
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  let killTimer;
+  const term = setTimeout(() => {
     try {
-      proc.kill();
+      proc.kill("SIGTERM");
     } catch {}
-  }, opts.timeoutMs ?? 1e4);
+    killTimer = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {}
+    }, 2000);
+    killTimer.unref?.();
+  }, timeoutMs);
+  const captured = (async () => {
+    try {
+      const stdoutPromise = new Response(proc.stdout).text();
+      const stderrPromise = captureStderr ? new Response(proc.stderr).text() : Promise.resolve("");
+      const [stdout, stderr, exitCode] = await Promise.all([
+        stdoutPromise,
+        stderrPromise,
+        proc.exited
+      ]);
+      return { stdout, stderr, exitCode };
+    } catch {
+      return { stdout: "", stderr: "", exitCode: -1 };
+    }
+  })();
+  let deadlineTimer;
+  const deadline = new Promise((resolve) => {
+    deadlineTimer = setTimeout(() => resolve({ stdout: "", stderr: "", exitCode: -1, timedOut: true }), timeoutMs);
+  });
   try {
-    const stdoutPromise = new Response(proc.stdout).text();
-    const stderrPromise = captureStderr ? new Response(proc.stderr).text() : Promise.resolve("");
-    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
-    const exitCode = await proc.exited;
-    return { stdout, stderr, exitCode };
-  } catch {
-    return { stdout: "", stderr: "", exitCode: -1 };
+    return await Promise.race([captured, deadline]);
   } finally {
-    clearTimeout(timer);
+    clearTimeout(term);
+    clearTimeout(deadlineTimer);
   }
 }
 
@@ -1718,6 +1889,7 @@ export {
   validateValue,
   unsetSetting,
   subscribe,
+  setSettingsWarnSink,
   setSetting,
   serializeIdentity,
   rtCommand,
@@ -1734,8 +1906,10 @@ export {
   paneSend,
   panePeek,
   paneList,
+  paneFocus,
   paneDirectories,
   paneAccounts,
+  openSmartPane,
   normalizeRemote,
   listTeams,
   listSettings,
@@ -1749,6 +1923,7 @@ export {
   expandVariables,
   eventsHead,
   deriveRepoIdentity,
+  decidePlacement,
   daemonHealth,
   createRelay,
   clearIdentityMemo,

package/dist/settings/exec.d.ts

@@ -11,6 +11,8 @@ export interface RunResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /** Set true only when the deadline fired before the child settled. */
+    timedOut?: boolean;
 }
 /**
  * Run argv and capture stdout. Never throws: spawn failures and timeouts

package/dist/settings/resolve.d.ts

@@ -120,6 +120,11 @@ export interface ExpandCtx {
  * mutates its input.
  */
 export declare function expandVariables(value: unknown, ctx: ExpandCtx): unknown;
+/** The daemon binds a deduped log.warn here so a hot-path getSetting on a
+ *  disallowed-scope key warns once, not every tick. Default: console.warn
+ *  (CLI/test behavior unchanged). null restores the default. */
+export declare function setSettingsWarnSink(sink: ((msg: string) => void) | null): void;
+export declare function emitSettingsWarning(msg: string): void;
 /**
  * Resolves one key across the whole ladder. Throws for an unregistered key —
  * an explicit get of something rt has never heard of is a caller bug, not a

package/dist/smart-pane.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Layout-smart herdr pane placement. `decidePlacement` is pure (geometry ->
+ * where a new pane should go); `openSmartPane` reads an anchor pane's real
+ * rect, decides, and performs the herdr call through an injected caller so it
+ * works over any transport (socket API or a CLI adapter).
+ */
+export type Placement = {
+    kind: "split";
+    direction: "right" | "down";
+} | {
+    kind: "tab";
+};
+export interface PlacementOpts {
+    minCols?: number;
+    minRows?: number;
+}
+export interface HerdrCall {
+    (method: string, params: Record<string, unknown>): Promise<{
+        ok: true;
+        result: any;
+    } | {
+        ok: false;
+        code: string;
+        message: string;
+    }>;
+}
+/**
+ * Where to put a new pane relative to an anchor whose rect (in cells) is given.
+ * Cells are ~2:1 (height:width in px), so a pane is visually wider than tall
+ * when width > 2*height; split the longer visual axis so both halves stay
+ * usable. A null/degenerate rect falls back to a right split (old behavior).
+ */
+export declare function decidePlacement(rect: {
+    width: number;
+    height: number;
+} | null, opts?: PlacementOpts): Placement;
+/**
+ * Open a herdr pane placed intelligently next to `anchorPaneId` (split right or
+ * down, or a new tab when crowded). Optionally run `command` in it. Returns the
+ * new pane id and the placement chosen. Throws on a herdr failure.
+ */
+export declare function openSmartPane(herdr: HerdrCall, anchorPaneId: string, opts?: {
+    command?: string;
+    focus?: boolean;
+} & PlacementOpts): Promise<{
+    paneId: string;
+    placement: Placement;
+}>;

package/dist/transport.d.ts

@@ -2,6 +2,13 @@ export interface RtResponse<T = unknown> {
     ok: boolean;
     data?: T;
     error?: string;
+    /** Structured form of `error` on a handler throw (R035): `code` defaults
+     *  to "handler-threw" when the thrown error carries none. Additive; older
+     *  daemons and the reject path never set this. */
+    failure?: {
+        code: string;
+        message: string;
+    };
 }
 export interface RtClientOptions {
     sockPath?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -51,5 +51,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
   }
 }

package/src/client.ts

@@ -388,3 +388,12 @@ export function paneSend(
   if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
   return rtCommand<Commands["pane:send"]["data"]>("pane:send", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
 }
+
+/** Brings a herdr pane to the front. The daemon routes this to the tray, which
+    owns the herdr focus and the native terminal-window raise. */
+export function paneFocus(
+  a: Commands["pane:focus"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["pane:focus"]["data"]>> {
+  return rtCommand<Commands["pane:focus"]["data"]>("pane:focus", { paneId: a.paneId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}

package/src/commands.ts

@@ -4,7 +4,7 @@
  * its functions against this map so a new command only needs an entry here
  * plus one function, never a change to the transport itself.
  */
-import type { PullRequest, MRDetail } from "@mattstack/glance";
+import type { PullRequest, MRDetail, Pipeline } from "@mattstack/glance";
 
 export type Discussion = MRDetail["discussions"][number];
 
@@ -166,6 +166,7 @@ export interface InviteResult { paneId: string; delivered: "accepted" | "queued"
 /** Duplicated shape on purpose: mirrors lib/daemon/inject.ts's InjectResult. */
 export type PaneDelivery = "accepted" | "queued" | "refused";
 export interface PaneSendResult { paneId: string; delivered: PaneDelivery; reason?: string }
+export interface PaneFocusResult { paneId: string; focused: boolean }
 
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
@@ -225,6 +226,127 @@ export interface AgentRecord {
   createdAt: number; lastResumedAt?: number; finishedAt?: number;
 }
 
+// ─── The daemon's remaining out-of-process commands (R013/R016) ──
+// rt CLI <-> daemon, tray <-> daemon, and VS Code extension <-> daemon are
+// all separate OS processes, so any command reachable from one counts as
+// "external" here even when the only known caller today is rt's own CLI.
+
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors lib/daemon/health.ts's HealthSnapshot. */
+export type HealthLevel = "ok" | "degraded" | "unhealthy";
+export interface HealthMetrics { rss: number; heapUsed: number; external: number; uptimeMs: number; wsClients: number; watchers: number }
+export interface HealthEventLoop { maxLagMs: number; lastStallAt: number | null; lastStallCmd: string | null; stalls: number }
+export interface DaemonIdentity { flavor: "dev" | "prod"; version: string; sourceRev: string | null; startedAt: number }
+
+export interface PingData extends DaemonIdentity {
+  uptime: number;
+  pid: number;
+  health: HealthLevel;
+  eventLoop: HealthEventLoop;
+  heartbeatSeq: number;
+  supervision: { bootAttempts: number; lastReadyAt: number | null; recentFailures: unknown[]; lastExit: unknown };
+}
+
+export interface StatusData {
+  pid: number; uptime: number; watchedRepos: number; cacheEntries: number;
+  portsCached: number; portCacheAge: number | null;
+  freshness: unknown; identity: DaemonIdentity;
+  health: { level: HealthLevel; reasons: string[] }; metrics: HealthMetrics; eventLoop: HealthEventLoop;
+  worktreePool: { dormant: true; repos: string[]; message: string } | { dormant: false };
+}
+
+export interface TrayStatusData {
+  pid: number; uptime: number; memoryUsage: number; watchedRepos: number; cacheEntries: number;
+  portsCached: number; portCacheAge: number | null; lastRefresh: number | null;
+  portsByRepo: Record<string, number>; pendingNotifications: number;
+  health: { level: HealthLevel; reasons: string[] }; metrics: HealthMetrics; eventLoop: HealthEventLoop;
+}
+
+/** Duplicated shape on purpose: mirrors lib/port-scanner.ts's PortEntry. */
+export interface PortEntry {
+  port: number; pid: number; command: string; cwd: string;
+  repo: string | null; worktree: string | null; branch: string | null;
+  relativeDir: string; uptime: string;
+}
+
+export interface PortsData {
+  ports: PortEntry[];
+  grouped: Record<string, Record<string, PortEntry[]>>;
+  updatedAt: number;
+  age: number | null;
+}
+
+/** Duplicated shape on purpose: mirrors lib/state/notifier-store.ts's NotificationEvent. */
+export interface RtNotificationEvent {
+  id: string; title: string; message: string; url?: string;
+  category: string; timestamp: number; pids?: number[];
+}
+
+export interface ReposData {
+  repos: Record<string, { path: string; worktrees: Array<{ path: string; branch: string }> }>;
+  watched: string[];
+}
+
+export interface TccCheckData {
+  blocked: Array<{ name: string; path: string; error: string }>;
+  accessible: string[];
+  totalRepos: number;
+  daemonPid: number;
+}
+
+export interface WorktreeTreeRow {
+  name: string; kind: string; state: string; path: string; branch: string | null;
+  repoName: string; mr: { iid: number; state: string; title: string } | null;
+  duplicateBranch?: true;
+  [extra: string]: unknown;
+}
+export interface WorktreeListData {
+  trees: WorktreeTreeRow[];
+  dormant?: true; dormantRepos?: string[]; message?: string;
+  readyHeld?: true; readyHeldRepos?: string[];
+}
+export interface WorktreeProvisionData {
+  tree: string; path: string; branch: string; wasOnDeck: boolean;
+  readyAt: string | null; branchState: "new" | "tracking-remote" | "existing-clean" | "diverged" | "behind";
+  readyFailed?: true; failedStep?: string;
+}
+export interface WorktreeCreateData { tree: string; path: string }
+export interface WorktreeDisposeData {
+  disposed: string[];
+  refused: Array<{ tree: string; reason: string }>;
+  recoverable: Array<{ tree: string; path: string; until: string }>;
+}
+export interface WorktreeRestoreData {
+  restored: true; path: string; tree: string; readyFailed?: true; failedStep?: string;
+}
+export interface WorktreeFreshenData { ran: string[] }
+export interface WorktreeAdoptData {
+  main: string; claimed: string[]; unmanaged: string[]; disposed: string[];
+  refused: Array<{ tree: string; reason: string }>;
+}
+
+/** Duplicated shape on purpose: mirrors lib/endpoint/store.ts's EndpointClaim. */
+export interface EndpointClaim { worktree: string; role: string; port: number; ts: number }
+export interface EndpointRoleRef { port: number; url: string; running: boolean }
+export interface EndpointClaimData { role: string; port: number; url: string; refs: Record<string, EndpointRoleRef> }
+export interface EndpointLookupData { claimed: boolean; port: number | null; url: string | null; running: boolean }
+export interface EndpointReleaseData { released: number }
+export interface EndpointStatusData { repos: Record<string, Array<EndpointClaim & { running: boolean }>> }
+
+/**
+ * Duplicated shape on purpose: mirrors @mattstack/glance's `JobDetail`
+ * (types.ts), which the package does not re-export from its index.
+ */
+export type MrJobDetail = { type: "trace"; content: string } | { type: "bridge"; downstreamPipeline: Pipeline };
+
+export interface DiscussionsWriteData { discussions: Discussion[]; fetchedAt: number }
+export interface DiscussionsDiffsData { diffs: Array<{ newPath: string; diff: string }>; truncated: boolean }
+
+export type MRActionName =
+  | "merge" | "rebase" | "approve" | "unapprove"
+  | "setAutoMerge" | "cancelAutoMerge"
+  | "retryJob" | "retryPipeline"
+  | "toggleDraft" | "requestReReview";
+
 export interface Commands {
   "project-mrs:read": { payload: { repoName: string; maxAgeMs?: number; demand?: DemandDecl }; data: ProjectMRsData };
   "discussions:read": { payload: { repoName: string; iid: number }; data: DiscussionsData };
@@ -353,6 +475,61 @@ export interface Commands {
     data: { pane: ChatPane; ready: boolean };
   };
   "pane:send": { payload: { paneId: string; text: string; callerPane?: string }; data: PaneSendResult };
+  "pane:focus": { payload: { paneId: string }; data: PaneFocusResult };
+
+  // ─── R013/R016 ────────────────────────────────────────────────
+  "cache:read": { payload: { branches?: string[]; maxAgeMs?: number; repoIdentity?: string }; data: Record<string, BranchEnrichment> };
+  /** `source` ("cache"|"fresh"|"empty") rides alongside `data` on the wire, not nested under it. */
+  "branch:enrich": { payload: { branch: string; repoPath?: string; remoteUrl?: string; repoIdentity?: string }; data: BranchEnrichment | null };
+  /** Fire-and-forget kickoff; wire reply is `{ok, message}`, not `{ok,data}`. */
+  "cache:refresh": { payload: Record<string, never>; data: { message: string } };
+  "daemon:log-level": { payload: { level?: "trace" | "debug" | "info" | "warn" | "error" }; data: { level: string } };
+  "ping": { payload: Record<string, never>; data: PingData };
+  "status": { payload: Record<string, never>; data: StatusData };
+  "tray:status": { payload: Record<string, never>; data: TrayStatusData };
+  "tcc:check": { payload: Record<string, never>; data: TccCheckData };
+  "repos": { payload: Record<string, never>; data: ReposData };
+  "ports": { payload: { repo?: string; refresh?: boolean }; data: PortsData };
+  "notifications": { payload: Record<string, never>; data: RtNotificationEvent[] };
+
+  "discussions:refresh": { payload: { repoName: string; iid: number }; data: DiscussionsWriteData };
+  "discussions:resolve": { payload: { repoName: string; iid: number; discussionId: string; resolved?: boolean }; data: DiscussionsWriteData };
+  "discussions:reply": { payload: { repoName: string; iid: number; discussionId: string; body: string }; data: DiscussionsWriteData };
+  "discussions:diffs": { payload: { repoName: string; iid: number }; data: DiscussionsDiffsData };
+
+  /** Wire reply is `{ok:true}` on success (no `data`); a failure is `{ok:false,error}`. */
+  "mr:action": { payload: { repoName: string; iid: number; action: MRActionName; args?: unknown[] }; data: Record<string, never> };
+  "mr:fetch-job-detail": { payload: { repoName: string; iid: number; jobId: number; pipelineId?: number }; data: MrJobDetail };
+  "mr:fetch-job-trace": { payload: { repoName: string; iid: number; jobId: number }; data: string };
+
+  "endpoint:claim": { payload: { repo: string; worktree: string; role: string; pid?: number }; data: EndpointClaimData };
+  "endpoint:lookup": { payload: { repo: string; worktree: string; role: string }; data: EndpointLookupData };
+  "endpoint:release": { payload: { repo: string; worktree: string; role?: string }; data: EndpointReleaseData };
+  "endpoint:status": { payload: { repo?: string }; data: EndpointStatusData };
+
+  "repos:locate": { payload: { newPath: string; repo?: string; dryRun?: boolean }; data: unknown };
+  "freshness:reconcile": { payload: Record<string, never>; data: unknown };
+
+  /** Wire reply on success is always `{ok:true, repaired}` (no `data`
+   *  wrapper) — `data` here documents the extra field the same way PingData
+   *  does for `ping`, not the literal wire nesting (R3). */
+  "hooks:repair": { payload: { repo: string }; data: { repaired: boolean } };
+  "hooks:watch": { payload: { repo: string }; data: Record<string, never> };
+
+  "sdm:catalog": { payload: { refresh?: boolean }; data: unknown };
+  "sdm:snapshot": { payload: { force?: boolean }; data: unknown };
+  "sdm:recents": { payload: Record<string, never>; data: unknown };
+  "sdm:reconnect": { payload: { key: string }; data: unknown };
+
+  "system-processes": { payload: Record<string, never>; data: unknown };
+
+  "worktree:provision": { payload: { repoName: string; branch?: string; ticket?: string; ticketTitle?: string; disposal?: "job" | "merge"; owner?: string }; data: WorktreeProvisionData };
+  "worktree:create": { payload: { repoName: string; onDeck?: boolean }; data: WorktreeCreateData };
+  "worktree:dispose": { payload: { repoName?: string; owner?: string; tree?: string; force?: boolean; callerPid?: number }; data: WorktreeDisposeData };
+  "worktree:list": { payload: { repoName?: string }; data: WorktreeListData };
+  "worktree:restore": { payload: { repoName: string; tree: string }; data: WorktreeRestoreData };
+  "worktree:freshen": { payload: { repoName?: string; tree?: string }; data: WorktreeFreshenData };
+  "worktree:adopt": { payload: { repoName: string; claim?: boolean }; data: WorktreeAdoptData };
 }
 
 export type CommandName = keyof Commands;
@@ -397,4 +574,45 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "pane:directories",
   "pane:spawn",
   "pane:send",
+  "pane:focus",
+
+  // ─── R013/R016 ────────────────────────────────────────────────
+  "cache:read",
+  "branch:enrich",
+  "cache:refresh",
+  "daemon:log-level",
+  "ping",
+  "status",
+  "tray:status",
+  "tcc:check",
+  "repos",
+  "ports",
+  "notifications",
+  "discussions:refresh",
+  "discussions:resolve",
+  "discussions:reply",
+  "discussions:diffs",
+  "mr:action",
+  "mr:fetch-job-detail",
+  "mr:fetch-job-trace",
+  "endpoint:claim",
+  "endpoint:lookup",
+  "endpoint:release",
+  "endpoint:status",
+  "repos:locate",
+  "freshness:reconcile",
+  "hooks:repair",
+  "hooks:watch",
+  "sdm:catalog",
+  "sdm:snapshot",
+  "sdm:recents",
+  "sdm:reconnect",
+  "system-processes",
+  "worktree:provision",
+  "worktree:create",
+  "worktree:dispose",
+  "worktree:list",
+  "worktree:restore",
+  "worktree:freshen",
+  "worktree:adopt",
 ];