@mattstack/rt-client 0.15.1 → 0.19.0

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,11 +268,14 @@ 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 };
-  for (const k of ["meta", "agent", "pane", "nudge"])
+  for (const k of ["meta", "agent", "pane", "nudge", "context", "origin"])
     if (a[k] !== undefined)
       payload[k] = a[k];
   return rtCommand("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
@@ -312,8 +315,93 @@ 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 ?? 15000 });
+}
+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) {
+  return typeof o === "string" ? o : o.value;
+}
+function gateOptionLabel(o) {
+  return typeof o === "string" ? o : o.label || o.value;
+}
 var COMMAND_NAMES = [
   "project-mrs:read",
   "discussions:read",
@@ -391,6 +479,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",
@@ -404,7 +506,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";
@@ -581,6 +687,26 @@ 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;
+  }
+  return BG_PREFIX + paneId;
+}
 // src/settings/resolve.ts
 import { homedir as homedir4 } from "os";
 import { join as join5 } from "path";
@@ -598,6 +724,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");
 }
@@ -690,7 +819,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?}]. 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. A fresh key, not an ownership-latch port, so a default is fine here."
   },
   {
     key: "rt.cron",
@@ -1706,10 +1835,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) {
@@ -1767,6 +1909,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();
@@ -1777,6 +1924,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();
@@ -1786,7 +1934,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")
@@ -1795,7 +1945,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)
@@ -1803,7 +1956,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.
@@ -1849,7 +2004,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 {
@@ -1870,7 +2025,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);
@@ -1897,7 +2052,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 = {}) {
@@ -2059,7 +2214,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;
@@ -2084,6 +2239,7 @@ export {
   readMrsByBranch,
   readDiscussions,
   readBranchCache,
+  parsePaneRef,
   parseIdentity,
   paneSpawn,
   paneSend,
@@ -2099,6 +2255,20 @@ export {
   listRuns,
   isMigrated,
   identityFromRemote,
+  herdWrapUp,
+  herdStopHidden,
+  herdStatus,
+  herdStart,
+  herdSpawn,
+  herdResume,
+  herdReport,
+  herdMilestone,
+  herdList,
+  herdGates,
+  herdClose,
+  herdAttend,
+  herdAsk,
+  herdAnswer,
   getSetting,
   getRun,
   getDef,
@@ -2107,10 +2277,13 @@ export {
   gateSubscriptions,
   gateSubscribe,
   gatePark,
+  gateOptionValue,
+  gateOptionLabel,
   gateOpen,
   gateList,
   gateClose,
   gateAnswer,
+  formatPaneRef,
   explainSetting,
   expandVariables,
   eventsWait,
@@ -2142,6 +2315,10 @@ export {
   chatAway,
   chatArchive,
   chatAck,
+  bgStop,
+  bgStatus,
+  bgRelease,
+  bgEnsure,
   allDefs,
   agentStart,
   agentResume,
@@ -2153,5 +2330,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.15.1",
+  "version": "0.19.0",
   "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) ─────────────────────────────────────
@@ -451,7 +453,7 @@ export function gateOpen(
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["gate:open"]["data"]>> {
   const payload: Record<string, unknown> = { subject: a.subject, kind: a.kind, questions: a.questions };
-  for (const k of ["meta", "agent", "pane", "nudge"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  for (const k of ["meta", "agent", "pane", "nudge", "context", "origin"] as const) if (a[k] !== undefined) payload[k] = a[k];
   return rtCommand<Commands["gate:open"]["data"]>("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
@@ -519,3 +521,153 @@ 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) ────────────
+
+/** May spawn `herdr server` and wait for it to bind; budget matches bg-service's own 10s readyTimeoutMs plus margin. */
+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 ?? 15_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 });
+}