@mattstack/rt-client 0.19.0 → 0.19.1

package/dist/client.d.ts

@@ -218,7 +218,10 @@ export declare function herdAttend(a: Commands["herd:attend"]["payload"], o?: Rt
 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. */
+/** A cold ensure spawns `herdr server`, waits out bg-service's own 10s
+    readyTimeoutMs, then runs its parity probes sequentially -- the 15s
+    default budget every other rt-client call inherits can lose that race,
+    so this is the one wrapper that widens its own. */
 export 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"]>>;

package/dist/commands.d.ts

@@ -128,6 +128,7 @@ export interface GateAnswer {
     }>;
     by: string;
     answeredAt: number;
+    overridden?: boolean;
 }
 export interface GateRow {
     id: string;
@@ -143,6 +144,8 @@ export interface GateRow {
     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: {
@@ -153,6 +156,8 @@ export interface GateRow {
         at: number;
     } | null;
     released: boolean;
+    owner: string | null;
+    escalatedAt: number | null;
 }
 export interface GateSubscription {
     id: string;
@@ -164,6 +169,8 @@ export interface GateSubscription {
         at: number;
     } | null;
     dead: boolean;
+    scope: "prefix" | "owner";
+    ownerRef: string | null;
 }
 export interface HerdInfo {
     id: string;
@@ -217,6 +224,11 @@ export interface HerdStatusData {
         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"];
+    };
 }
 /**
  * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
@@ -616,9 +628,12 @@ export interface WorktreeCreateData {
 }
 export interface WorktreeDisposeData {
     disposed: 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;
@@ -644,6 +659,7 @@ export interface WorktreeAdoptData {
     refused: Array<{
         tree: string;
         reason: string;
+        detail?: string;
     }>;
 }
 /** Duplicated shape on purpose: mirrors lib/endpoint/store.ts's EndpointClaim. */
@@ -1368,12 +1384,21 @@ 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;
+            session?: string;
+            override?: boolean;
         };
         data: {
             row: GateRow;
@@ -1430,6 +1455,8 @@ export interface Commands {
         payload: {
             subjectPrefix: string;
             session: string;
+            scope?: "owner";
+            ownerRef?: string;
         };
         data: {
             id: string;
@@ -1505,7 +1532,8 @@ export interface Commands {
         };
         data: {
             job: string;
-            status: "closed";
+            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. */

package/dist/index.js

@@ -281,7 +281,11 @@ function gateOpen(a, o = {}) {
   return rtCommand("gate:open", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateAnswer(a, o = {}) {
-  return rtCommand("gate:answer", { id: a.id, answers: a.answers, by: a.by }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+  const payload = { id: a.id, answers: a.answers, by: a.by };
+  for (const k of ["session", "override"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("gate:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateWait(a, o = {}) {
   const payload = { id: a.id };
@@ -303,7 +307,11 @@ function gateClose(a, o = {}) {
   return rtCommand("gate:close", { id: a.id, reason: a.reason }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateSubscribe(a, o = {}) {
-  return rtCommand("gate:subscribe", { subjectPrefix: a.subjectPrefix, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+  const payload = { subjectPrefix: a.subjectPrefix, session: a.session };
+  for (const k of ["scope", "ownerRef"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("gate:subscribe", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function gateUnsubscribe(a, o = {}) {
   return rtCommand("gate:unsubscribe", { id: a.id }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
@@ -383,7 +391,7 @@ 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 });
+  return rtCommand("bg:ensure", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
 }
 function bgStatus(o = {}) {
   return rtCommand("bg:status", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
@@ -705,6 +713,9 @@ function formatPaneRef(paneId, server) {
   if (server === "visible") {
     return paneId;
   }
+  if (paneId.startsWith(BG_PREFIX)) {
+    return paneId;
+  }
   return BG_PREFIX + paneId;
 }
 // src/settings/resolve.ts
@@ -777,7 +788,7 @@ var REGISTRY = [
     merge: "deep",
     repoScoped: true,
     migrated: true,
-    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool); root/branchFormat/ready computed-or-empty in the reader."
+    description: "Per-repo worktree pool config (onDeck size, ready steps, name pool, staleClaimDays); root/branchFormat/ready computed-or-empty in the reader."
   },
   {
     key: "rt.worktreeReadyApproval",
@@ -819,7 +830,7 @@ var REGISTRY = [
     scopes: ["user"],
     default: [],
     merge: "replace",
-    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."
+    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",
@@ -1138,7 +1149,7 @@ var REGISTRY = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists MRs from any author blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
+    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists any author's open MRs carrying a CODE_OWNER rule for the section, until merge/close. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
   },
   {
     key: "board.staleAfterDays",
@@ -1381,6 +1392,14 @@ var REGISTRY = [
     scopes: ["user", "machine"],
     merge: "replace",
     description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch)."
+  },
+  {
+    key: "rt.gates.escalationTtlMinutes",
+    type: "number",
+    scopes: ["user"],
+    default: 10,
+    merge: "replace",
+    description: `Minutes an open herd-owned gate waits before the escalation sweep surfaces it to the human (topic gate/escalated/<id>). Fires on either trigger: the TTL elapses (reason "ttl"), or the owning herd's shepherd subscription is gone or dead before the TTL (reason "owner-dead"). 0 escalates any eligible gate on the first sweep after it opens. A fresh key, not an ownership-latch port, so a default is fine here.`
   }
 ];
 

package/package.json

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

package/src/client.ts

@@ -461,7 +461,9 @@ export function gateAnswer(
   a: Commands["gate:answer"]["payload"],
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["gate:answer"]["data"]>> {
-  return rtCommand<Commands["gate:answer"]["data"]>("gate:answer", { id: a.id, answers: a.answers, by: a.by }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  const payload: Record<string, unknown> = { id: a.id, answers: a.answers, by: a.by };
+  for (const k of ["session", "override"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["gate:answer"]["data"]>("gate:answer", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 /** Daemon clamps its own wait to 240s (gates-store.ts); the client abort
@@ -503,7 +505,9 @@ export function gateSubscribe(
   a: Commands["gate:subscribe"]["payload"],
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["gate:subscribe"]["data"]>> {
-  return rtCommand<Commands["gate:subscribe"]["data"]>("gate:subscribe", { subjectPrefix: a.subjectPrefix, session: a.session }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  const payload: Record<string, unknown> = { subjectPrefix: a.subjectPrefix, session: a.session };
+  for (const k of ["scope", "ownerRef"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["gate:subscribe"]["data"]>("gate:subscribe", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function gateUnsubscribe(
@@ -645,14 +649,17 @@ export function herdStopHidden(
 
 // ─── 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. */
+/** A cold ensure spawns `herdr server`, waits out bg-service's own 10s
+    readyTimeoutMs, then runs its parity probes sequentially -- the 15s
+    default budget every other rt-client call inherits can lose that race,
+    so this is the one wrapper that widens its own. */
 export function bgEnsure(
   a: Commands["bg:ensure"]["payload"] = {},
   o: RtClientOptions = {},
 ): Promise<RtResponse<Commands["bg:ensure"]["data"]>> {
   const payload: Record<string, unknown> = {};
   if (a.claim !== undefined) payload.claim = a.claim;
-  return rtCommand<Commands["bg:ensure"]["data"]>("bg:ensure", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 15_000 });
+  return rtCommand<Commands["bg:ensure"]["data"]>("bg:ensure", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
 }
 
 /** Never ensures/spawns; a plain read of the current state. */

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,8 @@ 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 }
@@ -147,6 +153,8 @@ export interface HerdStatusData {
   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"] };
 }
 
 /**
@@ -405,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 {
@@ -414,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. */
@@ -616,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 } };
@@ -626,7 +643,7 @@ 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). */
@@ -638,7 +655,7 @@ export interface Commands {
   "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" } };
+  "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[] } };

package/src/pane-ref.ts

@@ -24,5 +24,10 @@ 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/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, 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.",
+    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.",
+  },
 ];