@mattstack/rt-client 0.27.0 → 0.28.0

package/dist/commands.d.ts

@@ -247,7 +247,11 @@ export interface HerdStatusData {
         sessionDead: boolean | null;
         lastGateStatus: GateStatus | null;
         lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null;
-        lastGateConsumed: boolean | null;
+        lastGateConsumed: boolean | null; /** The daemon watchdog's escalation ladder for this job: strikes so far and when it last acted. Absent when the job is not on the ladder (healthy, no watchdog wired, or the daemon restarted since). */
+        watchdog?: {
+            strikes: number;
+            lastPokeAt: number | null;
+        };
     }>;
     unread: number;
     lifecycleConnected: boolean;
@@ -486,6 +490,10 @@ export interface ReconcilerStatus {
     herdrReachable: boolean;
     executors: ExecutorView[];
 }
+/** What a claude spawn's folder-trust check established, when one ran:
+    `none` = no dialog was up, `accepted` = one was answered, `stuck` = one is
+    still up and needs a human, `unchecked` = nothing could be established. */
+export type TrustOutcome = "none" | "accepted" | "stuck" | "unchecked";
 export interface AgentRecord {
     id: string;
     repo: string;
@@ -1160,9 +1168,12 @@ export interface Commands {
             handle?: string;
             bg?: boolean;
             subject?: string;
-            yolo?: boolean;
+            yolo?: boolean; /** How long the folder-trust check lets the dialog paint before reading the screen; interactive launches keep the short default, herd:spawn passes its own longer budget. */
+            trustWaitMs?: number;
+        };
+        data: AgentRecord & {
+            trust?: TrustOutcome;
         };
-        data: AgentRecord;
     };
     "agent:resume": {
         payload: {
@@ -1634,6 +1645,7 @@ export interface Commands {
             repo: string;
             session: string;
             hidden?: boolean;
+            callerPane?: string;
         };
         data: {
             herd: string;
@@ -1648,6 +1660,7 @@ export interface Commands {
         payload: {
             herd: string;
             session: string;
+            callerPane?: string;
         };
         data: {
             subscription: string;

package/dist/index.js

@@ -382,6 +382,8 @@ function herdStart(a, o = {}) {
   const payload = { name: a.name, repo: a.repo, session: a.session };
   if (a.hidden !== undefined)
     payload.hidden = a.hidden;
+  if (a.callerPane !== undefined)
+    payload.callerPane = a.callerPane;
   return rtCommand("herd:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60000 });
 }
 function herdSpawn(a, o = {}) {
@@ -425,7 +427,10 @@ function herdList(a = {}, o = {}) {
   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 });
+  const payload = { herd: a.herd, session: a.session };
+  if (a.callerPane !== undefined)
+    payload.callerPane = a.callerPane;
+  return rtCommand("herd:resume", payload, { 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 });
@@ -1605,6 +1610,78 @@ var REGISTRY = [
     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.`
+  },
+  {
+    key: "herd.watchdog.enabled",
+    type: "boolean",
+    scopes: ["machine"],
+    default: true,
+    merge: "replace",
+    description: "Turns the herd watchdog sweep on."
+  },
+  {
+    key: "herd.watchdog.fastMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 2,
+    merge: "replace",
+    description: "Idle minutes before a worker with a pending DM, mention, or answered gate is poked."
+  },
+  {
+    key: "herd.watchdog.shepherdFastMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 5,
+    merge: "replace",
+    description: "Minutes an open human-owned gate in the herd may stay unanswered before the shepherd is poked. Unread DMs and mentions for the shepherd wedge immediately and are not delayed by this key."
+  },
+  {
+    key: "herd.watchdog.backstopMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 15,
+    merge: "replace",
+    description: "Idle minutes before any non-gated active worker is poked."
+  },
+  {
+    key: "herd.watchdog.retryMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 5,
+    merge: "replace",
+    description: "Minutes between escalation strikes while the watchdog keeps poking an unresponsive worker."
+  },
+  {
+    key: "herd.watchdog.notifyQuietMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 30,
+    merge: "replace",
+    description: "Minimum minutes between macOS notifications for the same herd."
+  },
+  {
+    key: "herd.watchdog.nagMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 30,
+    merge: "replace",
+    description: "Minutes a done job may hold its pane before the shepherd is nagged to reclaim it."
+  },
+  {
+    key: "herd.watchdog.notifyHuman",
+    type: "boolean",
+    scopes: ["machine"],
+    default: true,
+    merge: "replace",
+    description: "Whether the watchdog's top escalation rung sends a macOS notification to the human."
+  },
+  {
+    key: "herd.watchdog.midRunTrustAccept",
+    type: "boolean",
+    scopes: ["machine"],
+    default: false,
+    merge: "replace",
+    description: "Whether the watchdog may drive a mid-run folder-trust dialog on a daemon-provisioned tree itself, rather than only parking the job and notifying (RT-196). Off by default: the screen match cannot yet confirm the dialog's folder matches the job's worktree, so a working session showing an unrelated permission prompt with the same shape is a real risk."
   }
 ];
 

package/package.json

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

package/src/client.ts

@@ -561,6 +561,7 @@ export function herdStart(
 ): 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;
+  if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
   return rtCommand<Commands["herd:start"]["data"]>("herd:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 60_000 });
 }
 
@@ -635,7 +636,9 @@ 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 });
+  const payload: Record<string, unknown> = { herd: a.herd, session: a.session };
+  if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
+  return rtCommand<Commands["herd:resume"]["data"]>("herd:resume", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 /** Closes a herdr pane, one CLI call under the runner's own 15s budget. */

package/src/commands.ts

@@ -171,7 +171,7 @@ export interface HerdJobInfo { herd: string; name: string; worktree: string; bra
 /** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: a TERMINAL gate (answered or closed) whose delivery is `dead-pane` is the "worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
   herd: HerdInfo;
-  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */ sessionDead: boolean | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
+  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */ sessionDead: boolean | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null; /** The daemon watchdog's escalation ladder for this job: strikes so far and when it last acted. Absent when the job is not on the ladder (healthy, no watchdog wired, or the daemon restarted since). */ watchdog?: { strikes: number; lastPokeAt: number | null } }>;
   unread: number;
   lifecycleConnected: boolean;
   hiddenUp: boolean | null;
@@ -349,6 +349,11 @@ export interface ReconcilerStatus {
   executors: ExecutorView[];
 }
 
+/** What a claude spawn's folder-trust check established, when one ran:
+    `none` = no dialog was up, `accepted` = one was answered, `stuck` = one is
+    still up and needs a human, `unchecked` = nothing could be established. */
+export type TrustOutcome = "none" | "accepted" | "stuck" | "unchecked";
+
 export interface AgentRecord {
   id: string; repo: string; cwd: string; provider: string;
   surface: AgentSurface; sessionId: string;
@@ -618,7 +623,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; provider?: string; 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; subject?: string; yolo?: boolean }; data: AgentRecord };
+  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; provider?: string; 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; subject?: string; yolo?: boolean; /** How long the folder-trust check lets the dialog paint before reading the screen; interactive launches keep the short default, herd:spawn passes its own longer budget. */ trustWaitMs?: number }; data: AgentRecord & { trust?: TrustOutcome } };
   "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[] } };
@@ -751,8 +756,8 @@ export interface Commands {
   "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:start":  { payload: { name: string; repo: string; session: string; hidden?: boolean; callerPane?: string }; data: { herd: string; room: string; workspace: string; subscription: string; handle: string; hidden: boolean } };
+  "herd:resume": { payload: { herd: string; session: string; callerPane?: 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[] } };

package/src/settings/registry-defs.ts

@@ -751,4 +751,78 @@ export const REGISTRY: readonly SettingDef[] = [
     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.",
   },
+
+  // --- herd (watchdog) ---------------------------------------------------
+  {
+    key: "herd.watchdog.enabled",
+    type: "boolean",
+    scopes: ["machine"],
+    default: true,
+    merge: "replace",
+    description: "Turns the herd watchdog sweep on.",
+  },
+  {
+    key: "herd.watchdog.fastMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 2,
+    merge: "replace",
+    description: "Idle minutes before a worker with a pending DM, mention, or answered gate is poked.",
+  },
+  {
+    key: "herd.watchdog.shepherdFastMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 5,
+    merge: "replace",
+    description: "Minutes an open human-owned gate in the herd may stay unanswered before the shepherd is poked. Unread DMs and mentions for the shepherd wedge immediately and are not delayed by this key.",
+  },
+  {
+    key: "herd.watchdog.backstopMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 15,
+    merge: "replace",
+    description: "Idle minutes before any non-gated active worker is poked.",
+  },
+  {
+    key: "herd.watchdog.retryMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 5,
+    merge: "replace",
+    description: "Minutes between escalation strikes while the watchdog keeps poking an unresponsive worker.",
+  },
+  {
+    key: "herd.watchdog.notifyQuietMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 30,
+    merge: "replace",
+    description: "Minimum minutes between macOS notifications for the same herd.",
+  },
+  {
+    key: "herd.watchdog.nagMins",
+    type: "number",
+    scopes: ["machine"],
+    default: 30,
+    merge: "replace",
+    description: "Minutes a done job may hold its pane before the shepherd is nagged to reclaim it.",
+  },
+  {
+    key: "herd.watchdog.notifyHuman",
+    type: "boolean",
+    scopes: ["machine"],
+    default: true,
+    merge: "replace",
+    description: "Whether the watchdog's top escalation rung sends a macOS notification to the human.",
+  },
+  {
+    key: "herd.watchdog.midRunTrustAccept",
+    type: "boolean",
+    scopes: ["machine"],
+    default: false,
+    merge: "replace",
+    description: "Whether the watchdog may drive a mid-run folder-trust dialog on a daemon-provisioned tree itself, rather than only parking the job and notifying (RT-196). Off by default: the screen match cannot yet confirm the dialog's folder matches the job's worktree, so a working session showing an unrelated permission prompt with the same shape is a real risk.",
+  },
 ];