@mattstack/rt-client 0.15.1 → 0.19.0

package/src/commands.ts

@@ -95,11 +95,27 @@ export interface EventsBusEvent { id: number; topic: string; payload: unknown; e
 export const GATE_BY_PANE = "pane";
 
 export type GateStatus = "open" | "answered" | "parked" | "closed";
-export interface GateQuestion { id: string; label: string; multi: boolean; options: string[] }
+export type GateOption = string | { value: string; label: string };
+export interface GateOrigin {
+  paneId?: string;
+  tabId?: string;
+  runId?: string;
+  worktree?: string;
+  presentation?: "form" | "wait";
+}
+export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[] }
+export function gateOptionValue(o: GateOption): string {
+  return typeof o === "string" ? o : o.value;
+}
+export function gateOptionLabel(o: GateOption): string {
+  return typeof o === "string" ? o : (o.label || o.value);
+}
 export interface GateAnswer { answers: Record<string, string | string[] | { value: string | string[]; note?: string }>; by: string; answeredAt: number }
 export interface GateRow {
   id: string; subject: string; kind: string;
   questions: GateQuestion[]; meta: Record<string, unknown> | null;
+  context?: string | null;
+  origin?: GateOrigin | null;
   status: GateStatus; answer: GateAnswer | null;
   openedAt: number; parkedAt: number | null; closedAt: number | null;
   closedReason: "abandoned" | "superseded" | "pruned" | null;
@@ -118,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
@@ -213,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.
@@ -524,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[] } };
@@ -538,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> };
@@ -574,7 +610,7 @@ export interface Commands {
   "freshness:reconcile": { payload: Record<string, never>; data: unknown };
 
   // ─── Gate facility (BOARD-20/21) ─────────────────────────────────────────
-  "gate:open": { payload: { subject: string; kind: string; questions: GateQuestion[]; meta?: Record<string, unknown>; agent?: string; pane?: string; nudge?: { session: string } }; data: { id: string; supersededId: string | null } };
+  "gate:open": { payload: { subject: string; kind: string; questions: GateQuestion[]; meta?: Record<string, unknown>; agent?: string; pane?: string; nudge?: { session: string }; context?: string; origin?: GateOrigin }; data: { id: string; supersededId: string | null } };
   /**
    * A CAS loss is a DEFINED OUTCOME, not an error: `ok:true` with
    * `conflict:true` and the WINNING row, so every consumer gets the winner
@@ -596,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). */
@@ -616,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;
@@ -699,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",
@@ -713,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,9 +54,27 @@ 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 } from "./commands.ts";
+export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
 export type {
   Discussion,
   DemandDecl,
@@ -94,10 +112,16 @@ export type {
   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";
@@ -110,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`. */