@mattstack/rt-client 0.16.0 → 0.19.1

package/dist/index.js

@@ -205,7 +205,7 @@ function eventsList(payload, o = {}) {
 }
 function agentStart(a, o = {}) {
   const payload = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs"]) {
+  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg"]) {
     if (a[k] !== undefined)
       payload[k] = a[k];
   }
@@ -268,7 +268,10 @@ function paneSend(a, o = {}) {
   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 });
+  const payload = { paneId: a.paneId };
+  if (a.callerWorkspace !== undefined)
+    payload.callerWorkspace = a.callerWorkspace;
+  return rtCommand("pane:focus", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateOpen(a, o = {}) {
   const payload = { subject: a.subject, kind: a.kind, questions: a.questions };
@@ -278,7 +281,11 @@ function gateOpen(a, o = {}) {
   return rtCommand("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateAnswer(a, o = {}) {
-  return rtCommand("gate:answer", { id: a.id, answers: a.answers, by: a.by }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+  const payload = { id: a.id, answers: a.answers, by: a.by };
+  for (const k of ["session", "override"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("gate:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateWait(a, o = {}) {
   const payload = { id: a.id };
@@ -300,7 +307,11 @@ function gateClose(a, o = {}) {
   return rtCommand("gate:close", { id: a.id, reason: a.reason }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateSubscribe(a, o = {}) {
-  return rtCommand("gate:subscribe", { subjectPrefix: a.subjectPrefix, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+  const payload = { subjectPrefix: a.subjectPrefix, session: a.session };
+  for (const k of ["scope", "ownerRef"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("gate:subscribe", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateUnsubscribe(a, o = {}) {
   return rtCommand("gate:unsubscribe", { id: a.id }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
@@ -312,6 +323,85 @@ function gateSubscriptions(a, o = {}) {
       payload[k] = a[k];
   return rtCommand("gate:subscriptions", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
+function herdStart(a, o = {}) {
+  const payload = { name: a.name, repo: a.repo, session: a.session };
+  if (a.hidden !== undefined)
+    payload.hidden = a.hidden;
+  return rtCommand("herd:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60000 });
+}
+function herdSpawn(a, o = {}) {
+  const payload = { herd: a.herd, job: a.job };
+  for (const k of ["brief", "dir", "model", "effort", "account", "disposable"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("herd:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60000 });
+}
+function herdAsk(a, o = {}) {
+  const payload = { herd: a.herd, job: a.job, session: a.session, questions: a.questions };
+  for (const k of ["pane", "context"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("herd:ask", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdMilestone(a, o = {}) {
+  const payload = { herd: a.herd, job: a.job, session: a.session, artifact: a.artifact };
+  for (const k of ["pane", "summary"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("herd:milestone", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdAnswer(a, o = {}) {
+  return rtCommand("herd:answer", { gate: a.gate }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdReport(a, o = {}) {
+  return rtCommand("herd:report", { herd: a.herd, job: a.job, body: a.body }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function herdGates(a, o = {}) {
+  return rtCommand("herd:gates", { herd: a.herd }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdStatus(a, o = {}) {
+  return rtCommand("herd:status", { herd: a.herd }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdList(a = {}, o = {}) {
+  const payload = {};
+  if (a.all !== undefined)
+    payload.all = a.all;
+  return rtCommand("herd:list", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdResume(a, o = {}) {
+  return rtCommand("herd:resume", { herd: a.herd, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function herdClose(a, o = {}) {
+  return rtCommand("herd:close", { herd: a.herd, job: a.job }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function herdAttend(a, o = {}) {
+  return rtCommand("herd:attend", { herd: a.herd, job: a.job, callerWorkspace: a.callerWorkspace }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60000 });
+}
+function herdWrapUp(a, o = {}) {
+  const payload = { herd: a.herd };
+  for (const k of ["closePanes", "dispose", "deleteJobDirs", "archiveRoom"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("herd:wrap-up", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 120000 });
+}
+function herdStopHidden(_a, o = {}) {
+  return rtCommand("herd:stop-hidden", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function bgEnsure(a = {}, o = {}) {
+  const payload = {};
+  if (a.claim !== undefined)
+    payload.claim = a.claim;
+  return rtCommand("bg:ensure", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function bgStatus(o = {}) {
+  return rtCommand("bg:status", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function bgStop(o = {}) {
+  return rtCommand("bg:stop", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function bgRelease(a, o = {}) {
+  return rtCommand("bg:release", { claim: a.claim }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
 // src/commands.ts
 var GATE_BY_PANE = "pane";
 function gateOptionValue(o) {
@@ -397,6 +487,20 @@ var COMMAND_NAMES = [
   "gate:subscribe",
   "gate:unsubscribe",
   "gate:subscriptions",
+  "herd:start",
+  "herd:resume",
+  "herd:status",
+  "herd:list",
+  "herd:close",
+  "herd:spawn",
+  "herd:gates",
+  "herd:ask",
+  "herd:milestone",
+  "herd:answer",
+  "herd:report",
+  "herd:attend",
+  "herd:stop-hidden",
+  "herd:wrap-up",
   "hooks:repair",
   "hooks:watch",
   "sdm:catalog",
@@ -410,7 +514,11 @@ var COMMAND_NAMES = [
   "worktree:list",
   "worktree:restore",
   "worktree:freshen",
-  "worktree:adopt"
+  "worktree:adopt",
+  "bg:ensure",
+  "bg:status",
+  "bg:stop",
+  "bg:release"
 ];
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
@@ -587,6 +695,29 @@ async function openSmartPane(herdr, anchorPaneId, opts = {}) {
   }
   return { paneId, placement };
 }
+// src/pane-ref.ts
+var BG_PREFIX = "bg:";
+function parsePaneRef(ref) {
+  if (ref.startsWith(BG_PREFIX)) {
+    return {
+      server: "bg",
+      paneId: ref.slice(BG_PREFIX.length)
+    };
+  }
+  return {
+    server: "visible",
+    paneId: ref
+  };
+}
+function formatPaneRef(paneId, server) {
+  if (server === "visible") {
+    return paneId;
+  }
+  if (paneId.startsWith(BG_PREFIX)) {
+    return paneId;
+  }
+  return BG_PREFIX + paneId;
+}
 // src/settings/resolve.ts
 import { homedir as homedir4 } from "os";
 import { join as join5 } from "path";
@@ -604,6 +735,9 @@ function userSettingsPath() {
 function teamSettingsPath(team) {
   return join3(teamsDir(), team, "mattstack", "settings.team.jsonc");
 }
+function teamLocalPath(team) {
+  return join3(home(), ".mattstack", "rt", "teams", `${team}.json`);
+}
 function machineSettingsPath() {
   return join3(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
 }
@@ -654,7 +788,7 @@ var REGISTRY = [
     merge: "deep",
     repoScoped: true,
     migrated: true,
-    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool); root/branchFormat/ready computed-or-empty in the reader."
+    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool, staleClaimDays); root/branchFormat/ready computed-or-empty in the reader."
   },
   {
     key: "rt.worktreeReadyApproval",
@@ -696,7 +830,7 @@ var REGISTRY = [
     scopes: ["user"],
     default: [],
     merge: "replace",
-    description: "Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload. A fresh key, not an ownership-latch port, so a default is fine here."
+    description: 'Event-bus glob rules that raise a desktop notification: [{pattern, category, title, message, subjectPrefix?, url?, owner?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload\'s first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload\'s subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification\'s Open target; a gate rule should set it. The optional owner field (only literal "human" is valid) suppresses events whose payload.owner starts with "herd:", allowing gate rules to skip herd-owned events. A typical setup pairs a gate/opened rule with owner: "human" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A fresh key, not an ownership-latch port, so a default is fine here.'
   },
   {
     key: "rt.cron",
@@ -1015,7 +1149,7 @@ var REGISTRY = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists MRs from any author blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
+    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists any author's open MRs carrying a CODE_OWNER rule for the section, until merge/close. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
   },
   {
     key: "board.staleAfterDays",
@@ -1258,6 +1392,14 @@ var REGISTRY = [
     scopes: ["user", "machine"],
     merge: "replace",
     description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch)."
+  },
+  {
+    key: "rt.gates.escalationTtlMinutes",
+    type: "number",
+    scopes: ["user"],
+    default: 10,
+    merge: "replace",
+    description: `Minutes an open herd-owned gate waits before the escalation sweep surfaces it to the human (topic gate/escalated/<id>). Fires on either trigger: the TTL elapses (reason "ttl"), or the owning herd's shepherd subscription is gone or dead before the TTL (reason "owner-dead"). 0 escalates any eligible gate on the first sweep after it opens. A fresh key, not an ownership-latch port, so a default is fine here.`
   }
 ];
 
@@ -1712,10 +1854,23 @@ function explainSetting(key, opts = {}) {
   return resolveDef(def, readStores(), opts).rows;
 }
 // src/settings/write.ts
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, renameSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync5, renameSync, unlinkSync, writeFileSync } from "fs";
 import { applyEdits, modify, parseTree } from "jsonc-parser";
 import { randomBytes } from "crypto";
 import { dirname as dirname2 } from "path";
+
+// src/settings/team-local-read.ts
+import { readFileSync as readFileSync4 } from "fs";
+function isJoinedTeam(team) {
+  try {
+    const parsed = JSON.parse(readFileSync4(teamLocalPath(team), "utf8"));
+    return typeof parsed === "object" && parsed !== null && parsed.joinedByRt === true;
+  } catch {
+    return false;
+  }
+}
+
+// src/settings/write.ts
 var FORMAT = { tabSize: 2, insertSpaces: true, eol: `
 ` };
 function refuse(message) {
@@ -1773,6 +1928,11 @@ function migratedFalseMessage(key, def) {
   const legacyPart = def.legacyFile ? ` — it is still read from ${def.legacyFile}` : "";
   return `"${key}" is not writable through the settings resolver yet${legacyPart}`;
 }
+function refuseIfJoined(team) {
+  if (isJoinedTeam(team)) {
+    refuse(`this machine joined "${team}" by invite, so its clone is pull-only and team settings cannot be written here. Ask the team's owner to make this change. Member-proposed changes are tracked in MAT-415.`);
+  }
+}
 function resolveStorePath(scope, opts) {
   if (scope === "user")
     return userSettingsPath();
@@ -1783,6 +1943,7 @@ function resolveStorePath(scope, opts) {
     if (!existsSync3(path)) {
       refuse(`team store for "${opts.team}" does not exist (${path}) — clone/seed it before writing to it`);
     }
+    refuseIfJoined(opts.team);
     return path;
   }
   const teams = listTeams();
@@ -1792,7 +1953,9 @@ function resolveStorePath(scope, opts) {
   if (teams.length > 1) {
     refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
   }
-  return teamSettingsPath(teams[0]);
+  const team = teams[0];
+  refuseIfJoined(team);
+  return teamSettingsPath(team);
 }
 function resolveStorePathForUnset(scope, opts) {
   if (scope === "user")
@@ -1801,7 +1964,10 @@ function resolveStorePathForUnset(scope, opts) {
     return machineSettingsPath();
   if (opts.team !== undefined) {
     const path = teamSettingsPath(opts.team);
-    return existsSync3(path) ? path : null;
+    if (!existsSync3(path))
+      return null;
+    refuseIfJoined(opts.team);
+    return path;
   }
   const teams = listTeams();
   if (teams.length === 0)
@@ -1809,7 +1975,9 @@ function resolveStorePathForUnset(scope, opts) {
   if (teams.length > 1) {
     refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
   }
-  return teamSettingsPath(teams[0]);
+  const team = teams[0];
+  refuseIfJoined(team);
+  return teamSettingsPath(team);
 }
 function seedHeader() {
   return `// rt settings — created by \`rt settings set\`. JSONC: comments and trailing commas are fine.
@@ -1855,7 +2023,7 @@ function findDuplicateKey(node) {
 function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
   let content;
   if (existsSync3(storePath)) {
-    content = readFileSync4(storePath, "utf8");
+    content = readFileSync5(storePath, "utf8");
     if (content.trim() === "") {
       content = seedHeader();
     } else {
@@ -1876,7 +2044,7 @@ function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
   writeTempThenRename(storePath, finalText);
 }
 function removeFromStore(storePath, jsonPath) {
-  const content = readFileSync4(storePath, "utf8");
+  const content = readFileSync5(storePath, "utf8");
   if (content.trim() === "")
     return false;
   assertEditableJsonc(storePath, content);
@@ -1903,7 +2071,7 @@ function writeTempThenRename(storePath, finalText) {
   }
 }
 // src/settings/identity.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6, realpathSync } from "fs";
 
 // src/settings/exec.ts
 async function runCapture(argv, opts = {}) {
@@ -2065,7 +2233,7 @@ async function resolveNameToIdentity(name, reposJsonPath) {
   if (!existsSync4(reposJsonPath))
     return null;
   try {
-    const index = JSON.parse(readFileSync5(reposJsonPath, "utf8"));
+    const index = JSON.parse(readFileSync6(reposJsonPath, "utf8"));
     const path = index[name];
     if (typeof path !== "string")
       return null;
@@ -2090,6 +2258,7 @@ export {
   readMrsByBranch,
   readDiscussions,
   readBranchCache,
+  parsePaneRef,
   parseIdentity,
   paneSpawn,
   paneSend,
@@ -2105,6 +2274,20 @@ export {
   listRuns,
   isMigrated,
   identityFromRemote,
+  herdWrapUp,
+  herdStopHidden,
+  herdStatus,
+  herdStart,
+  herdSpawn,
+  herdResume,
+  herdReport,
+  herdMilestone,
+  herdList,
+  herdGates,
+  herdClose,
+  herdAttend,
+  herdAsk,
+  herdAnswer,
   getSetting,
   getRun,
   getDef,
@@ -2119,6 +2302,7 @@ export {
   gateList,
   gateClose,
   gateAnswer,
+  formatPaneRef,
   explainSetting,
   expandVariables,
   eventsWait,
@@ -2150,6 +2334,10 @@ export {
   chatAway,
   chatArchive,
   chatAck,
+  bgStop,
+  bgStatus,
+  bgRelease,
+  bgEnsure,
   allDefs,
   agentStart,
   agentResume,
@@ -2161,5 +2349,6 @@ export {
   GATE_BY_PANE,
   DEFAULT_WS_URL,
   DEFAULT_SOCK,
-  COMMAND_NAMES
+  COMMAND_NAMES,
+  BG_PREFIX
 };

package/dist/pane-ref.d.ts

@@ -0,0 +1,8 @@
+export declare const BG_PREFIX = "bg:";
+export type PaneServer = "visible" | "bg";
+export interface PaneRef {
+    server: PaneServer;
+    paneId: string;
+}
+export declare function parsePaneRef(ref: string): PaneRef;
+export declare function formatPaneRef(paneId: string, server: PaneServer): string;

package/dist/settings/paths.d.ts

@@ -12,6 +12,14 @@
 export declare function userSettingsPath(): string;
 /** ~/.mattstack/teams/<team>/mattstack/settings.team.jsonc — the team store. */
 export declare function teamSettingsPath(team: string): string;
+/**
+ * ~/.mattstack/rt/teams/<team>.json: the machine-local team record. Mirrored
+ * from repo-tools/lib/team/team-local.ts's teamLocalPath, which is the
+ * authority: rt-client has no dependency on rt's lib/, so this literal is
+ * duplicated here rather than imported (same convention as `teamSettingsPath`
+ * and `userSettingsPath` above).
+ */
+export declare function teamLocalPath(team: string): string;
 /**
  * ~/.mattstack/user/local/<machineKey()>/settings.local.jsonc — the machine
  * store, TRACKED and keyed per machine (path literals legal here only).

package/dist/settings/team-local-read.d.ts

@@ -0,0 +1,7 @@
+/**
+ * One field of the machine-local team record, for the write guard. The record
+ * itself is owned by repo-tools/lib/team/team-local.ts; this reads only what
+ * the guard needs and never writes.
+ */
+/** Unreadable, absent or malformed all read as false, so nothing that predates the field is refused. */
+export declare function isJoinedTeam(team: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.16.0",
+  "version": "0.19.1",
   "type": "module",
   "exports": {
     ".": {

package/src/client.ts

@@ -356,7 +356,7 @@ export function agentStart(
   a: Commands["agent:start"]["payload"], o: RtClientOptions = {},
 ): Promise<RtResponse<AgentRecord>> {
   const payload: Record<string, unknown> = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs"] as const) {
+  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg"] as const) {
     if (a[k] !== undefined) payload[k] = a[k];
   }
   return rtCommand<AgentRecord>("agent:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
@@ -441,7 +441,9 @@ 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 });
+  const payload: Record<string, unknown> = { paneId: a.paneId };
+  if (a.callerWorkspace !== undefined) payload.callerWorkspace = a.callerWorkspace;
+  return rtCommand<Commands["pane:focus"]["data"]>("pane:focus", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 // ─── Gates (BOARD-20/21 gate facility) ─────────────────────────────────────
@@ -459,7 +461,9 @@ export function gateAnswer(
   a: Commands["gate:answer"]["payload"],
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["gate:answer"]["data"]>> {
-  return rtCommand<Commands["gate:answer"]["data"]>("gate:answer", { id: a.id, answers: a.answers, by: a.by }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  const payload: Record<string, unknown> = { id: a.id, answers: a.answers, by: a.by };
+  for (const k of ["session", "override"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["gate:answer"]["data"]>("gate:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 /** Daemon clamps its own wait to 240s (gates-store.ts); the client abort
@@ -501,7 +505,9 @@ export function gateSubscribe(
   a: Commands["gate:subscribe"]["payload"],
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["gate:subscribe"]["data"]>> {
-  return rtCommand<Commands["gate:subscribe"]["data"]>("gate:subscribe", { subjectPrefix: a.subjectPrefix, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  const payload: Record<string, unknown> = { subjectPrefix: a.subjectPrefix, session: a.session };
+  for (const k of ["scope", "ownerRef"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["gate:subscribe"]["data"]>("gate:subscribe", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function gateUnsubscribe(
@@ -519,3 +525,156 @@ export function gateSubscriptions(
   for (const k of ["session", "live"] as const) if (a[k] !== undefined) payload[k] = a[k];
   return rtCommand<Commands["gate:subscriptions"]["data"]>("gate:subscriptions", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
+
+// ─── Herd (shepherd run registry) ───────────────────────────────────────────
+
+/** Provisions the room, workspace and subscription before it answers, so it
+    gets the same 60s budget as a spawn rather than the 10s default. */
+export function herdStart(
+  a: Commands["herd:start"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:start"]["data"]>> {
+  const payload: Record<string, unknown> = { name: a.name, repo: a.repo, session: a.session };
+  if (a.hidden !== undefined) payload.hidden = a.hidden;
+  return rtCommand<Commands["herd:start"]["data"]>("herd:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60_000 });
+}
+
+/** Worktree provision plus agent launch; the 10s default cannot cover it. */
+export function herdSpawn(
+  a: Commands["herd:spawn"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:spawn"]["data"]>> {
+  const payload: Record<string, unknown> = { herd: a.herd, job: a.job };
+  for (const k of ["brief", "dir", "model", "effort", "account", "disposable"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["herd:spawn"]["data"]>("herd:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60_000 });
+}
+
+export function herdAsk(
+  a: Commands["herd:ask"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:ask"]["data"]>> {
+  const payload: Record<string, unknown> = { herd: a.herd, job: a.job, session: a.session, questions: a.questions };
+  for (const k of ["pane", "context"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["herd:ask"]["data"]>("herd:ask", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function herdMilestone(
+  a: Commands["herd:milestone"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:milestone"]["data"]>> {
+  const payload: Record<string, unknown> = { herd: a.herd, job: a.job, session: a.session, artifact: a.artifact };
+  for (const k of ["pane", "summary"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["herd:milestone"]["data"]>("herd:milestone", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function herdAnswer(
+  a: Commands["herd:answer"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:answer"]["data"]>> {
+  return rtCommand<Commands["herd:answer"]["data"]>("herd:answer", { gate: a.gate }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** A disposable job's report also closes its pane, one herdr CLI call under the runner's own 15s budget. */
+export function herdReport(
+  a: Commands["herd:report"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:report"]["data"]>> {
+  return rtCommand<Commands["herd:report"]["data"]>("herd:report", { herd: a.herd, job: a.job, body: a.body }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+export function herdGates(
+  a: Commands["herd:gates"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:gates"]["data"]>> {
+  return rtCommand<Commands["herd:gates"]["data"]>("herd:gates", { herd: a.herd }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function herdStatus(
+  a: Commands["herd:status"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:status"]["data"]>> {
+  return rtCommand<Commands["herd:status"]["data"]>("herd:status", { herd: a.herd }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function herdList(
+  a: Commands["herd:list"]["payload"] = {},
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:list"]["data"]>> {
+  const payload: Record<string, unknown> = {};
+  if (a.all !== undefined) payload.all = a.all;
+  return rtCommand<Commands["herd:list"]["data"]>("herd:list", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function herdResume(
+  a: Commands["herd:resume"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:resume"]["data"]>> {
+  return rtCommand<Commands["herd:resume"]["data"]>("herd:resume", { herd: a.herd, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** Closes a herdr pane, one CLI call under the runner's own 15s budget. */
+export function herdClose(
+  a: Commands["herd:close"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:close"]["data"]>> {
+  return rtCommand<Commands["herd:close"]["data"]>("herd:close", { herd: a.herd, job: a.job }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+/** Three sequential herdr CLI calls (pane get, tab create, pane run), each under the runner's own 15s budget. */
+export function herdAttend(
+  a: Commands["herd:attend"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:attend"]["data"]>> {
+  return rtCommand<Commands["herd:attend"]["data"]>("herd:attend", { herd: a.herd, job: a.job, callerWorkspace: a.callerWorkspace }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60_000 });
+}
+
+/** Closes panes, disposes worktrees and archives the room in one pass; the
+    worktree disposals alone can outrun a spawn's budget. */
+export function herdWrapUp(
+  a: Commands["herd:wrap-up"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:wrap-up"]["data"]>> {
+  const payload: Record<string, unknown> = { herd: a.herd };
+  for (const k of ["closePanes", "dispose", "deleteJobDirs", "archiveRoom"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["herd:wrap-up"]["data"]>("herd:wrap-up", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 120_000 });
+}
+
+/** Runs `herdr session stop`, one CLI call under the runner's own 15s budget. */
+export function herdStopHidden(
+  _a: Commands["herd:stop-hidden"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["herd:stop-hidden"]["data"]>> {
+  return rtCommand<Commands["herd:stop-hidden"]["data"]>("herd:stop-hidden", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+// ─── Background server (daemon-owned background herdr session) ────────────
+
+/** A cold ensure spawns `herdr server`, waits out bg-service's own 10s
+    readyTimeoutMs, then runs its parity probes sequentially -- the 15s
+    default budget every other rt-client call inherits can lose that race,
+    so this is the one wrapper that widens its own. */
+export function bgEnsure(
+  a: Commands["bg:ensure"]["payload"] = {},
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["bg:ensure"]["data"]>> {
+  const payload: Record<string, unknown> = {};
+  if (a.claim !== undefined) payload.claim = a.claim;
+  return rtCommand<Commands["bg:ensure"]["data"]>("bg:ensure", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+/** Never ensures/spawns; a plain read of the current state. */
+export function bgStatus(o: RtClientOptions = {}): Promise<RtResponse<Commands["bg:status"]["data"]>> {
+  return rtCommand<Commands["bg:status"]["data"]>("bg:status", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** Asks the daemon to stop the background server; refuses (ok:false) while any claim is live, naming the owners. */
+export function bgStop(o: RtClientOptions = {}): Promise<RtResponse<Commands["bg:stop"]["data"]>> {
+  return rtCommand<Commands["bg:stop"]["data"]>("bg:stop", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+export function bgRelease(
+  a: Commands["bg:release"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["bg:release"]["data"]>> {
+  return rtCommand<Commands["bg:release"]["data"]>("bg:release", { claim: a.claim }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}