@mattstack/rt-client 0.16.0 → 0.19.0

package/dist/client.d.ts

@@ -195,3 +195,33 @@ export declare function gateClose(a: Commands["gate:close"]["payload"], o?: RtCl
 export declare function gateSubscribe(a: Commands["gate:subscribe"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:subscribe"]["data"]>>;
 export declare function gateUnsubscribe(a: Commands["gate:unsubscribe"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:unsubscribe"]["data"]>>;
 export declare function gateSubscriptions(a: Commands["gate:subscriptions"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:subscriptions"]["data"]>>;
+/** 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 declare function herdStart(a: Commands["herd:start"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:start"]["data"]>>;
+/** Worktree provision plus agent launch; the 10s default cannot cover it. */
+export declare function herdSpawn(a: Commands["herd:spawn"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:spawn"]["data"]>>;
+export declare function herdAsk(a: Commands["herd:ask"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:ask"]["data"]>>;
+export declare function herdMilestone(a: Commands["herd:milestone"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:milestone"]["data"]>>;
+export declare function herdAnswer(a: Commands["herd:answer"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:answer"]["data"]>>;
+/** A disposable job's report also closes its pane, one herdr CLI call under the runner's own 15s budget. */
+export declare function herdReport(a: Commands["herd:report"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:report"]["data"]>>;
+export declare function herdGates(a: Commands["herd:gates"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:gates"]["data"]>>;
+export declare function herdStatus(a: Commands["herd:status"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:status"]["data"]>>;
+export declare function herdList(a?: Commands["herd:list"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:list"]["data"]>>;
+export declare function herdResume(a: Commands["herd:resume"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:resume"]["data"]>>;
+/** Closes a herdr pane, one CLI call under the runner's own 15s budget. */
+export declare function herdClose(a: Commands["herd:close"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:close"]["data"]>>;
+/** Three sequential herdr CLI calls (pane get, tab create, pane run), each under the runner's own 15s budget. */
+export declare function herdAttend(a: Commands["herd:attend"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:attend"]["data"]>>;
+/** Closes panes, disposes worktrees and archives the room in one pass; the
+    worktree disposals alone can outrun a spawn's budget. */
+export declare function herdWrapUp(a: Commands["herd:wrap-up"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:wrap-up"]["data"]>>;
+/** Runs `herdr session stop`, one CLI call under the runner's own 15s budget. */
+export declare function herdStopHidden(_a: Commands["herd:stop-hidden"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:stop-hidden"]["data"]>>;
+/** May spawn `herdr server` and wait for it to bind; budget matches bg-service's own 10s readyTimeoutMs plus margin. */
+export declare function bgEnsure(a?: Commands["bg:ensure"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["bg:ensure"]["data"]>>;
+/** Never ensures/spawns; a plain read of the current state. */
+export declare function bgStatus(o?: RtClientOptions): Promise<RtResponse<Commands["bg:status"]["data"]>>;
+/** Asks the daemon to stop the background server; refuses (ok:false) while any claim is live, naming the owners. */
+export declare function bgStop(o?: RtClientOptions): Promise<RtResponse<Commands["bg:stop"]["data"]>>;
+export declare function bgRelease(a: Commands["bg:release"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["bg:release"]["data"]>>;

package/dist/commands.d.ts

@@ -165,6 +165,59 @@ export interface GateSubscription {
     } | null;
     dead: boolean;
 }
+export interface HerdInfo {
+    id: string;
+    repo: string;
+    room: string;
+    workspace: string;
+    shepherdSession: string;
+    shepherdHandle: string;
+    herdrSocket: string | null;
+    hidden: boolean;
+    status: "active" | "wrapped";
+    createdAt: number;
+    wrappedAt: number | null;
+}
+/** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
+export interface HerdListRow extends HerdInfo {
+    jobs: number;
+}
+export interface HerdJobInfo {
+    herd: string;
+    name: string;
+    worktree: string;
+    branch: string | null;
+    tree: string | null;
+    pane: string | null;
+    agentSession: string | null;
+    agentId: string | null;
+    handle: string;
+    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed";
+    disposable: boolean;
+    lastGate: string | null;
+    lastReport: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. */
+export interface HerdStatusData {
+    herd: HerdInfo;
+    jobs: Array<HerdJobInfo & {
+        openGate: string | null;
+        paneStatus: string | null;
+        lastGateStatus: GateStatus | null;
+        lastGateDelivery: "delivered" | "dead-pane" | null;
+    }>;
+    unread: number;
+    lifecycleConnected: boolean;
+    hiddenUp: boolean | null;
+    /** The shepherd session's own `herd:<id>/` subscription row, or null when none is live. */
+    subscription: {
+        id: string;
+        dead: boolean;
+        lastDelivery: GateSubscription["lastDelivery"];
+    } | null;
+}
 /**
  * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
  * these mirror lib/state/chat-store.ts's types, which rt-client cannot
@@ -285,9 +338,13 @@ export interface PaneSendResult {
     delivered: PaneDelivery;
     reason?: string;
 }
+/** `attendTab` is set only for a `bg:` ref: focus for a background pane IS
+    the attend flow (a visible tab running a terminal attach), and this is
+    that tab's id. */
 export interface PaneFocusResult {
     paneId: string;
     focused: boolean;
+    attendTab?: string;
 }
 export type Attention = {
     needs: boolean;
@@ -1019,6 +1076,10 @@ export interface Commands {
             workspace?: string;
             tab?: string;
             extraArgs?: string;
+            env?: Record<string, string>;
+            herdrSocket?: string;
+            handle?: string;
+            bg?: boolean;
         };
         data: AgentRecord;
     };
@@ -1108,9 +1169,12 @@ export interface Commands {
         };
         data: PaneSendResult;
     };
+    /** `callerWorkspace` (HERDR_WORKSPACE_ID) is required only for a `bg:`
+        ref, whose focus opens an attend tab in the caller's own workspace. */
     "pane:focus": {
         payload: {
             paneId: string;
+            callerWorkspace?: string;
         };
         data: PaneFocusResult;
     };
@@ -1390,6 +1454,179 @@ export interface Commands {
             subscriptions: GateSubscription[];
         };
     };
+    "herd:start": {
+        payload: {
+            name: string;
+            repo: string;
+            session: string;
+            hidden?: boolean;
+        };
+        data: {
+            herd: string;
+            room: string;
+            workspace: string;
+            subscription: string;
+            handle: string;
+            hidden: boolean;
+        };
+    };
+    "herd:resume": {
+        payload: {
+            herd: string;
+            session: string;
+        };
+        data: {
+            subscription: string;
+            gates: GateRow[];
+            unread: number;
+            status: HerdStatusData;
+            handle: string;
+        };
+    };
+    "herd:status": {
+        payload: {
+            herd: string;
+        };
+        data: HerdStatusData;
+    };
+    /** Active herds only unless `all`, so a shepherd's "which herd am I on" question has one answer. */
+    "herd:list": {
+        payload: {
+            all?: boolean;
+        };
+        data: {
+            herds: HerdListRow[];
+        };
+    };
+    "herd:close": {
+        payload: {
+            herd: string;
+            job: string;
+        };
+        data: {
+            job: string;
+            status: "closed";
+        };
+    };
+    /** `brief` is the brief TEXT, not a path: the CLI reads the file. It is stored at `<jobsRoot>/<herd>/<job>/job.md`, so a respawn with `dir` and no `brief` reads it back. */
+    "herd:spawn": {
+        payload: {
+            herd: string;
+            job: string;
+            brief?: string;
+            dir?: string;
+            model?: string;
+            effort?: string;
+            account?: string;
+            disposable?: boolean;
+        };
+        data: {
+            herd: string;
+            job: string;
+            pane: string;
+            worktree: string;
+            branch: string | null;
+            tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */
+            wasOnDeck: boolean | null;
+            agentId: string;
+            sessionId: string;
+            handle: string;
+        };
+    };
+    "herd:gates": {
+        payload: {
+            herd: string;
+        };
+        data: {
+            gates: GateRow[];
+        };
+    };
+    "herd:ask": {
+        payload: {
+            herd: string;
+            job: string;
+            session: string;
+            pane?: string;
+            questions: GateQuestion[];
+            context?: string;
+        };
+        data: {
+            gate: string;
+        };
+    };
+    "herd:milestone": {
+        payload: {
+            herd: string;
+            job: string;
+            session: string;
+            pane?: string;
+            artifact: string;
+            summary?: string;
+        };
+        data: {
+            gate: string;
+            message: number;
+        };
+    };
+    "herd:answer": {
+        payload: {
+            gate: string;
+        };
+        data: {
+            gate: string;
+            status: GateStatus;
+            answer: GateAnswer | null;
+            closedReason: GateRow["closedReason"];
+        };
+    };
+    "herd:report": {
+        payload: {
+            herd: string;
+            job: string;
+            body: string;
+        };
+        data: {
+            message: number;
+        };
+    };
+    /** `callerWorkspace` is the attending session's own HERDR_WORKSPACE_ID: the attached tab opens there, not in the herd's workspace. */
+    "herd:attend": {
+        payload: {
+            herd: string;
+            job: string;
+            callerWorkspace: string;
+        };
+        data: {
+            tab: string;
+            pane: string;
+        };
+    };
+    "herd:stop-hidden": {
+        payload: Record<string, never>;
+        data: {
+            stopped: boolean;
+        };
+    };
+    "herd:wrap-up": {
+        payload: {
+            herd: string;
+            closePanes?: boolean;
+            dispose?: string[];
+            deleteJobDirs?: boolean;
+            archiveRoom?: boolean;
+        };
+        data: {
+            closed: string[];
+            workspaceClosed: boolean;
+            disposed: string[];
+            refused: Array<{
+                tree: string;
+                reason: string;
+            }>;
+            deletedJobDirs: boolean;
+            archived: boolean;
+        };
+    };
     /** 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). */
@@ -1488,6 +1725,46 @@ export interface Commands {
         };
         data: WorktreeAdoptData;
     };
+    "bg:ensure": {
+        payload: {
+            claim?: string;
+        };
+        data: {
+            socket: string;
+            started: boolean;
+            parity: {
+                ok: boolean;
+                drift: string[];
+            } | null;
+        };
+    };
+    "bg:status": {
+        payload: Record<string, never>;
+        data: {
+            up: boolean;
+            socket: string;
+            claims: Array<{
+                owner: string;
+                pane: string | null;
+                createdAt: number;
+            }>;
+        };
+    };
+    /** Rejects (`ok:false`) naming every live claim owner while any claim is held. */
+    "bg:stop": {
+        payload: Record<string, never>;
+        data: {
+            stopped: boolean;
+        };
+    };
+    "bg:release": {
+        payload: {
+            claim: string;
+        };
+        data: {
+            released: boolean;
+        };
+    };
 }
 export type CommandName = keyof Commands;
 export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
-export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, gateOpen, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, gateOpen, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
-export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, ChatClaimOutcome, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, PaneDelivery, PaneSendResult, PaneFocusResult, GateStatus, GateOption, GateOrigin, GateQuestion, GateAnswer, GateRow, GateSubscription, } from "./commands.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, ChatClaimOutcome, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, PaneDelivery, PaneSendResult, PaneFocusResult, GateStatus, GateOption, GateOrigin, GateQuestion, GateAnswer, GateRow, GateSubscription, HerdInfo, HerdListRow, HerdJobInfo, HerdStatusData, } from "./commands.ts";
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";
 export { daemonHealth } from "./health.ts";
 export { repoNameForPath } from "./repos.ts";
 export { decidePlacement, openSmartPane } from "./smart-pane.ts";
 export type { Placement, PlacementOpts, HerdrCall } from "./smart-pane.ts";
+export { BG_PREFIX, parsePaneRef, formatPaneRef } from "./pane-ref.ts";
+export type { PaneServer, PaneRef } from "./pane-ref.ts";
 export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER, setSettingsWarnSink } from "./settings/resolve.ts";
 export type { Scope, Provenance, ResolveOpts, Resolved, InvalidScope, ListedSetting, ExplainRow, ExpandCtx, } from "./settings/resolve.ts";
 export { setSetting, unsetSetting } from "./settings/write.ts";

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 };
@@ -312,6 +315,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 ?? 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) {
@@ -397,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",
@@ -410,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";
@@ -587,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";
@@ -604,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");
 }
@@ -696,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",
@@ -1712,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) {
@@ -1773,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();
@@ -1783,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();
@@ -1792,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")
@@ -1801,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)
@@ -1809,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.
@@ -1855,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 {
@@ -1876,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);
@@ -1903,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 = {}) {
@@ -2065,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;
@@ -2090,6 +2239,7 @@ export {
   readMrsByBranch,
   readDiscussions,
   readBranchCache,
+  parsePaneRef,
   parseIdentity,
   paneSpawn,
   paneSend,
@@ -2105,6 +2255,20 @@ export {
   listRuns,
   isMigrated,
   identityFromRemote,
+  herdWrapUp,
+  herdStopHidden,
+  herdStatus,
+  herdStart,
+  herdSpawn,
+  herdResume,
+  herdReport,
+  herdMilestone,
+  herdList,
+  herdGates,
+  herdClose,
+  herdAttend,
+  herdAsk,
+  herdAnswer,
   getSetting,
   getRun,
   getDef,
@@ -2119,6 +2283,7 @@ export {
   gateList,
   gateClose,
   gateAnswer,
+  formatPaneRef,
   explainSetting,
   expandVariables,
   eventsWait,
@@ -2150,6 +2315,10 @@ export {
   chatAway,
   chatArchive,
   chatAck,
+  bgStop,
+  bgStatus,
+  bgRelease,
+  bgEnsure,
   allDefs,
   agentStart,
   agentResume,
@@ -2161,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.16.0",
+  "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) ─────────────────────────────────────
@@ -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 });
+}

package/src/commands.ts

@@ -134,6 +134,21 @@ export interface GateSubscription {
   dead: boolean;
 }
 
+export interface HerdInfo { id: string; repo: string; room: string; workspace: string; shepherdSession: string; shepherdHandle: string; herdrSocket: string | null; hidden: boolean; status: "active" | "wrapped"; createdAt: number; wrappedAt: number | null }
+/** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
+export interface HerdListRow extends HerdInfo { jobs: number }
+export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. */
+export interface HerdStatusData {
+  herd: HerdInfo;
+  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | null }>;
+  unread: number;
+  lifecycleConnected: boolean;
+  hiddenUp: boolean | null;
+  /** The shepherd session's own `herd:<id>/` subscription row, or null when none is live. */
+  subscription: { id: string; dead: boolean; lastDelivery: GateSubscription["lastDelivery"] } | null;
+}
+
 /**
  * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
  * these mirror lib/state/chat-store.ts's types, which rt-client cannot
@@ -229,7 +244,10 @@ 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 }
+/** `attendTab` is set only for a `bg:` ref: focus for a background pane IS
+    the attend flow (a visible tab running a terminal attach), and this is
+    that tab's id. */
+export interface PaneFocusResult { paneId: string; focused: boolean; attendTab?: string }
 
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
@@ -540,7 +558,7 @@ export interface Commands {
   "chat:dm-open": { payload: { from: string; to: string; sessionId?: string }; data: { room: string; created: boolean } };
 
   // ─── Agent handoff (rt agent) ────────────────────────────────────────────
-  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string }; data: AgentRecord };
+  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string; env?: Record<string, string>; herdrSocket?: string; handle?: string; bg?: boolean }; data: AgentRecord };
   "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface; workspace?: string; tab?: string }; data: AgentRecord };
   "agent:get": { payload: { id: string }; data: AgentRecord };
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
@@ -554,7 +572,9 @@ 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 };
+  /** `callerWorkspace` (HERDR_WORKSPACE_ID) is required only for a `bg:`
+      ref, whose focus opens an attend tab in the caller's own workspace. */
+  "pane:focus": { payload: { paneId: string; callerWorkspace?: string }; data: PaneFocusResult };
 
   // ─── R013/R016 ────────────────────────────────────────────────
   "cache:read": { payload: { branches?: string[]; maxAgeMs?: number; repoIdentity?: string }; data: Record<string, BranchEnrichment> };
@@ -612,6 +632,25 @@ export interface Commands {
    *  onto delivery outcomes (dead marks included). */
   "gate:subscriptions": { payload: { session?: string; live?: boolean }; data: { subscriptions: GateSubscription[] } };
 
+  // ─── Herd (shepherd run registry) ────────────────────────────────────────
+  "herd:start":  { payload: { name: string; repo: string; session: string; hidden?: boolean }; data: { herd: string; room: string; workspace: string; subscription: string; handle: string; hidden: boolean } };
+  "herd:resume": { payload: { herd: string; session: string }; data: { subscription: string; gates: GateRow[]; unread: number; status: HerdStatusData; handle: string } };
+  "herd:status": { payload: { herd: string }; data: HerdStatusData };
+  /** Active herds only unless `all`, so a shepherd's "which herd am I on" question has one answer. */
+  "herd:list":   { payload: { all?: boolean }; data: { herds: HerdListRow[] } };
+  "herd:close":  { payload: { herd: string; job: string }; data: { job: string; status: "closed" } };
+  /** `brief` is the brief TEXT, not a path: the CLI reads the file. It is stored at `<jobsRoot>/<herd>/<job>/job.md`, so a respawn with `dir` and no `brief` reads it back. */
+  "herd:spawn":  { payload: { herd: string; job: string; brief?: string; dir?: string; model?: string; effort?: string; account?: string; disposable?: boolean }; data: { herd: string; job: string; pane: string; worktree: string; branch: string | null; tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */ wasOnDeck: boolean | null; agentId: string; sessionId: string; handle: string } };
+  "herd:gates":  { payload: { herd: string }; data: { gates: GateRow[] } };
+  "herd:ask":       { payload: { herd: string; job: string; session: string; pane?: string; questions: GateQuestion[]; context?: string }; data: { gate: string } };
+  "herd:milestone": { payload: { herd: string; job: string; session: string; pane?: string; artifact: string; summary?: string }; data: { gate: string; message: number } };
+  "herd:answer":    { payload: { gate: string }; data: { gate: string; status: GateStatus; answer: GateAnswer | null; closedReason: GateRow["closedReason"] } };
+  "herd:report":    { payload: { herd: string; job: string; body: string }; data: { message: number } };
+  /** `callerWorkspace` is the attending session's own HERDR_WORKSPACE_ID: the attached tab opens there, not in the herd's workspace. */
+  "herd:attend":      { payload: { herd: string; job: string; callerWorkspace: string }; data: { tab: string; pane: string } };
+  "herd:stop-hidden": { payload: Record<string, never>; data: { stopped: boolean } };
+  "herd:wrap-up": { payload: { herd: string; closePanes?: boolean; dispose?: string[]; deleteJobDirs?: boolean; archiveRoom?: boolean }; data: { closed: string[]; workspaceClosed: boolean; disposed: string[]; refused: Array<{ tree: string; reason: string }>; deletedJobDirs: boolean; archived: boolean } };
+
   /** 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). */
@@ -632,6 +671,13 @@ export interface Commands {
   "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 };
+
+  // ─── Background server (daemon-owned background herdr session) ──────────
+  "bg:ensure": { payload: { claim?: string }; data: { socket: string; started: boolean; parity: { ok: boolean; drift: string[] } | null } };
+  "bg:status": { payload: Record<string, never>; data: { up: boolean; socket: string; claims: Array<{ owner: string; pane: string | null; createdAt: number }> } };
+  /** Rejects (`ok:false`) naming every live claim owner while any claim is held. */
+  "bg:stop": { payload: Record<string, never>; data: { stopped: boolean } };
+  "bg:release": { payload: { claim: string }; data: { released: boolean } };
 }
 
 export type CommandName = keyof Commands;
@@ -715,6 +761,20 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "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",
@@ -729,4 +789,9 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "worktree:restore",
   "worktree:freshen",
   "worktree:adopt",
+
+  "bg:ensure",
+  "bg:status",
+  "bg:stop",
+  "bg:release",
 ];

package/src/index.ts

@@ -54,6 +54,24 @@ export {
   gateSubscribe,
   gateUnsubscribe,
   gateSubscriptions,
+  herdStart,
+  herdSpawn,
+  herdAsk,
+  herdMilestone,
+  herdAnswer,
+  herdReport,
+  herdGates,
+  herdStatus,
+  herdList,
+  herdResume,
+  herdClose,
+  herdAttend,
+  herdWrapUp,
+  herdStopHidden,
+  bgEnsure,
+  bgStatus,
+  bgStop,
+  bgRelease,
 } from "./client.ts";
 
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
@@ -100,6 +118,10 @@ export type {
   GateAnswer,
   GateRow,
   GateSubscription,
+  HerdInfo,
+  HerdListRow,
+  HerdJobInfo,
+  HerdStatusData,
 } from "./commands.ts";
 
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
@@ -112,6 +134,9 @@ export { repoNameForPath } from "./repos.ts";
 export { decidePlacement, openSmartPane } from "./smart-pane.ts";
 export type { Placement, PlacementOpts, HerdrCall } from "./smart-pane.ts";
 
+export { BG_PREFIX, parsePaneRef, formatPaneRef } from "./pane-ref.ts";
+export type { PaneServer, PaneRef } from "./pane-ref.ts";
+
 // ─── Settings (RT-50) ────────────────────────────────────────────────────────
 
 export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER, setSettingsWarnSink } from "./settings/resolve.ts";

package/src/pane-ref.ts

@@ -0,0 +1,28 @@
+export const BG_PREFIX = "bg:";
+
+export type PaneServer = "visible" | "bg";
+
+export interface PaneRef {
+  server: PaneServer;
+  paneId: string;
+}
+
+export function parsePaneRef(ref: string): PaneRef {
+  if (ref.startsWith(BG_PREFIX)) {
+    return {
+      server: "bg",
+      paneId: ref.slice(BG_PREFIX.length),
+    };
+  }
+  return {
+    server: "visible",
+    paneId: ref,
+  };
+}
+
+export function formatPaneRef(paneId: string, server: PaneServer): string {
+  if (server === "visible") {
+    return paneId;
+  }
+  return BG_PREFIX + paneId;
+}

package/src/settings/paths.ts

@@ -27,6 +27,17 @@ export function teamSettingsPath(team: string): string {
   return join(teamsDir(), team, "mattstack", "settings.team.jsonc");
 }
 
+/**
+ * ~/.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 function teamLocalPath(team: string): string {
+  return join(home(), ".mattstack", "rt", "teams", `${team}.json`);
+}
+
 /**
  * ~/.mattstack/user/local/<machineKey()>/settings.local.jsonc — the machine
  * store, TRACKED and keyed per machine (path literals legal here only).

package/src/settings/registry-defs.ts

@@ -85,7 +85,7 @@ export const REGISTRY: readonly SettingDef[] = [
     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",

package/src/settings/team-local-read.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+import { readFileSync } from "fs";
+import { teamLocalPath } from "./paths.ts";
+
+/** Unreadable, absent or malformed all read as false, so nothing that predates the field is refused. */
+export function isJoinedTeam(team: string): boolean {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(teamLocalPath(team), "utf8"));
+    return typeof parsed === "object" && parsed !== null && (parsed as { joinedByRt?: unknown }).joinedByRt === true;
+  } catch {
+    return false;
+  }
+}

package/src/settings/write.ts

@@ -100,6 +100,7 @@ import { dirname } from "path";
 import { machineSettingsPath, teamSettingsPath, userSettingsPath } from "./paths.ts";
 import { getDef, isMigrated, validateValue, type SettingDef, type SettingScope } from "./registry-machinery.ts";
 import { listTeams } from "./stores.ts";
+import { isJoinedTeam } from "./team-local-read.ts";
 
 export interface SetSettingOpts {
   /** Normalized repo identity — required to target a repoScoped key's `repos.<identity>` section. */
@@ -208,6 +209,19 @@ function migratedFalseMessage(key: string, def: SettingDef): string {
   return `"${key}" is not writable through the settings resolver yet${legacyPart}`;
 }
 
+/**
+ * A clone that arrived by redeeming an invite is pull-only, so a write here
+ * would never reach the team AND would leave a tracked file dirty, which is
+ * enough on its own to make the daemon's fast-forward pull fail.
+ */
+function refuseIfJoined(team: string): void {
+  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.`,
+    );
+  }
+}
+
 /** Resolves which store file a write targets, applying the team-selection rule for `scope: "team"`. */
 function resolveStorePath(scope: SettingScope, opts: SetSettingOpts): string {
   if (scope === "user") return userSettingsPath();
@@ -218,6 +232,7 @@ function resolveStorePath(scope: SettingScope, opts: SetSettingOpts): string {
     if (!existsSync(path)) {
       refuse(`team store for "${opts.team}" does not exist (${path}) — clone/seed it before writing to it`);
     }
+    refuseIfJoined(opts.team);
     return path;
   }
 
@@ -228,7 +243,9 @@ function resolveStorePath(scope: SettingScope, opts: SetSettingOpts): string {
   if (teams.length > 1) {
     refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
   }
-  return teamSettingsPath(teams[0] as string);
+  const team = teams[0] as string;
+  refuseIfJoined(team);
+  return teamSettingsPath(team);
 }
 
 /**
@@ -243,7 +260,9 @@ function resolveStorePathForUnset(scope: SettingScope, opts: SetSettingOpts): st
 
   if (opts.team !== undefined) {
     const path = teamSettingsPath(opts.team);
-    return existsSync(path) ? path : null;
+    if (!existsSync(path)) return null;
+    refuseIfJoined(opts.team);
+    return path;
   }
 
   const teams = listTeams();
@@ -251,7 +270,9 @@ function resolveStorePathForUnset(scope: SettingScope, opts: SetSettingOpts): st
   if (teams.length > 1) {
     refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
   }
-  return teamSettingsPath(teams[0] as string);
+  const team = teams[0] as string;
+  refuseIfJoined(team);
+  return teamSettingsPath(team);
 }
 
 /** `// header comment\n{}\n` — see module doc for why the object must be seeded before the first `modify`. */