@mattstack/rt-client 0.16.0 → 0.19.1

package/src/commands.ts

@@ -110,7 +110,7 @@ export function gateOptionValue(o: GateOption): string {
 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 GateAnswer { answers: Record<string, string | string[] | { value: string | string[]; note?: string }>; by: string; answeredAt: number; overridden?: boolean }
 export interface GateRow {
   id: string; subject: string; kind: string;
   questions: GateQuestion[]; meta: Record<string, unknown> | null;
@@ -119,10 +119,14 @@ export interface GateRow {
   status: GateStatus; answer: GateAnswer | null;
   openedAt: number; parkedAt: number | null; closedAt: number | null;
   closedReason: "abandoned" | "superseded" | "pruned" | null;
+  /** Set only when `closedReason` is "superseded": the id of the gate that superseded this one. */
+  supersededBy: string | null;
   agent: string | null; pane: string | null;
   nudge: { session: string } | null;
   delivery: { outcome: "delivered" | "dead-pane"; at: number } | null;
   released: boolean;
+  owner: string | null;
+  escalatedAt: number | null;
 }
 
 export interface GateSubscription {
@@ -132,6 +136,25 @@ export interface GateSubscription {
   createdAt: number;
   lastDelivery: { outcome: "delivered" | "failed"; at: number } | null;
   dead: boolean;
+  scope: "prefix" | "owner";
+  ownerRef: string | null;
+}
+
+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;
+  /** Whether the shepherd session's own inbox socket is reachable right now, probed fresh on every status call -- honest liveness, not the subscription row's bookkeeping. */
+  push: { state: "reachable" | "unreachable"; lastDelivery: GateSubscription["lastDelivery"] };
 }
 
 /**
@@ -229,7 +252,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.
@@ -387,7 +413,9 @@ export interface WorktreeProvisionData {
 export interface WorktreeCreateData { tree: string; path: string }
 export interface WorktreeDisposeData {
   disposed: string[];
-  refused: Array<{ tree: string; reason: string }>;
+  /** `detail` is set only for a refusal whose bare `reason` code can't name
+      what a human needs to act on it (the run id and stage for `running-run`). */
+  refused: Array<{ tree: string; reason: string; detail?: string }>;
   recoverable: Array<{ tree: string; path: string; until: string }>;
 }
 export interface WorktreeRestoreData {
@@ -396,7 +424,7 @@ export interface WorktreeRestoreData {
 export interface WorktreeFreshenData { ran: string[] }
 export interface WorktreeAdoptData {
   main: string; claimed: string[]; unmanaged: string[]; disposed: string[];
-  refused: Array<{ tree: string; reason: string }>;
+  refused: Array<{ tree: string; reason: string; detail?: string }>;
 }
 
 /** Duplicated shape on purpose: mirrors lib/endpoint/store.ts's EndpointClaim. */
@@ -540,7 +568,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 +582,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> };
@@ -596,8 +626,15 @@ export interface Commands {
    * `conflict:true` and the WINNING row, so every consumer gets the winner
    * typed with no envelope hacks. `ok:false` is reserved for
    * not-found/closed/validation failures.
+   *
+   * Owner enforcement adds two structured rejections beyond the plain
+   * `{ok:false, error:string}` shape (see `GateAnswerResult` in
+   * `lib/daemon/handlers/gate.ts`): a herd-owned gate answered by anyone but
+   * the owning shepherd's session, the answering pane, or an explicit human
+   * `override` returns `{ok:false, error:"owned-by", owner}`; a closed gate
+   * returns `{ok:false, error:"gate-closed", reason, supersededBy?}`.
    */
-  "gate:answer": { payload: { id: string; answers: GateAnswer["answers"]; by: string }; data: { row: GateRow; conflict?: true } };
+  "gate:answer": { payload: { id: string; answers: GateAnswer["answers"]; by: string; session?: string; override?: boolean }; data: { row: GateRow; conflict?: true } };
   /** `ok:false "not-found"` on an unknown id is terminal; the CLI loop must not re-enter on it.
    *  `timeout` carries no row (nothing settled); `answered`/`closed` always carry the settled row. */
   "gate:wait": { payload: { id: string; waitMs?: number }; data: { status: "timeout" } | { status: "answered" | "closed"; row: GateRow } };
@@ -606,12 +643,31 @@ export interface Commands {
   "gate:list": { payload: { open?: boolean; subjectPrefix?: string; kind?: string; limit?: number; cursor?: number }; data: { gates: GateRow[]; cursor: number } };
   "gate:park": { payload: { id: string }; data: { ok: true } };
   "gate:close": { payload: { id: string; reason: "abandoned" | "superseded" | "pruned" }; data: { ok: true } };
-  "gate:subscribe": { payload: { subjectPrefix: string; session: string }; data: { id: string } };
+  "gate:subscribe": { payload: { subjectPrefix: string; session: string; scope?: "owner"; ownerRef?: string }; data: { id: string } };
   "gate:unsubscribe": { payload: { id: string }; data: { removed: boolean } };
   /** The shepherd's gap-recovery liveness check and the observability window
    *  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"; /** Advisory: a resumable run can still write into this job's worktree after close, so this warns rather than blocking. */ warning?: string } };
+  /** `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 +688,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 +778,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 +806,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,33 @@
+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;
+  }
+  // Idempotent: herdr pane ids (w<N>:p<N>) can never start with "bg:", so an
+  // already-formatted ref passes through unchanged instead of nesting.
+  if (paneId.startsWith(BG_PREFIX)) {
+    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

@@ -42,7 +42,7 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "deep",
     repoScoped: true,
     migrated: true,
-    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool); root/branchFormat/ready computed-or-empty in the reader.",
+    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool, staleClaimDays); root/branchFormat/ready computed-or-empty in the reader.",
   },
   {
     key: "rt.worktreeReadyApproval",
@@ -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?, owner?}]. pattern is matched against the events-bus topic (Bun.Glob semantics); title/message may interpolate `{field}` from the event payload, plus the computed `{question}` field (the event payload's first question label, `payload.questions[0].label`, empty string when absent); optional subjectPrefix matches the event payload's subject as a prefix. The optional url is interpolated the same way as title/message and becomes the notification's Open target; a gate rule should set it. The optional owner field (only literal \"human\" is valid) suppresses events whose payload.owner starts with \"herd:\", allowing gate rules to skip herd-owned events. A typical setup pairs a gate/opened rule with owner: \"human\" (human-owned gates notify) and a gate/escalated rule without owner (all escalations notify, whether human or herd). A fresh key, not an ownership-latch port, so a default is fine here.",
   },
   {
     key: "rt.cron",
@@ -427,7 +427,7 @@ export const REGISTRY: readonly SettingDef[] = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists MRs from any author blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here).",
+    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists any author's open MRs carrying a CODE_OWNER rule for the section, until merge/close. Absent = one implicit authors tab (fallback lives in the board reader, never here).",
   },
 
   // --- board (user) ----------------------------------------------------------
@@ -687,4 +687,14 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "replace",
     description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch).",
   },
+
+  // --- gates (escalation) ----------------------------------------------------
+  {
+    key: "rt.gates.escalationTtlMinutes",
+    type: "number",
+    scopes: ["user"],
+    default: 10,
+    merge: "replace",
+    description: "Minutes an open herd-owned gate waits before the escalation sweep surfaces it to the human (topic gate/escalated/<id>). Fires on either trigger: the TTL elapses (reason \"ttl\"), or the owning herd's shepherd subscription is gone or dead before the TTL (reason \"owner-dead\"). 0 escalates any eligible gate on the first sweep after it opens. A fresh key, not an ownership-latch port, so a default is fine here.",
+  },
 ];

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`. */