@mattstack/rt-client 0.5.0 → 0.6.1

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { RtResponse, RtClientOptions } from "./transport.ts";
-import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, BranchEnrichment, ForgeSlug, ForgeTokenData, RunSummary, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary } from "./commands.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, BranchEnrichment, ForgeSlug, ForgeTokenData, RunSummary, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow } from "./commands.ts";
 /**
  * One repo's project open-MR store. A cold repo forces a full paginated sync
  * on the daemon side when maxAgeMs demands it, which can run tens of seconds
@@ -58,6 +58,7 @@ export declare function chatPost(a: {
     room: string;
     handle: string;
     body: string;
+    mentions?: string[];
 }, o?: RtClientOptions): Promise<RtResponse<{
     id: number;
     recipients: string[];
@@ -97,12 +98,15 @@ export declare function chatMessages(a: {
 export declare function chatArm(a: {
     handle: string;
     room?: string;
+    sessionId?: string;
 }, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
 export declare function chatTouch(a: {
     handle: string;
+    sessionId?: string;
 }, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
 export declare function chatDisarm(a: {
     handle: string;
+    sessionId?: string;
 }, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
 export declare function chatUnreadWaking(a: {
     handle: string;
@@ -115,6 +119,57 @@ export declare function chatUnreadWaking(a: {
         maxId: number;
     }[];
 }>>;
+export declare function chatSignIn(a: {
+    sessionId: string;
+    baseHandle: string;
+    cwd?: string;
+    repo?: string;
+    branch?: string;
+    pane?: string;
+    statusText?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    handle: string;
+    reclaimed: boolean;
+}>>;
+export declare function chatSignOut(a: {
+    sessionId: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatAway(a: {
+    sessionId: string;
+    text: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatBack(a: {
+    sessionId: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatBuddies(o?: RtClientOptions): Promise<RtResponse<{
+    buddies: Array<PresenceRow & {
+        status: BuddyStatus;
+    }>;
+}>>;
+export declare function chatPulse(a: {
+    sessionId: string;
+    cwd?: string;
+    repo?: string;
+    branch?: string;
+    pane?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    unread: {
+        dms: number;
+        mentions: number;
+        rooms: number;
+    };
+    status: BuddyStatus;
+}>>;
+export declare function chatDm(a: {
+    from: string;
+    to: string;
+    body: string;
+    sessionId?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    room: string;
+    id: number;
+    recipients: string[];
+}>>;
 export declare function eventsHead(o?: RtClientOptions): Promise<RtResponse<{
     cursor: number;
 }>>;

package/dist/commands.d.ts

@@ -103,6 +103,8 @@ export interface ChatMember {
     armedAt?: number;
     cwd?: string;
     pane?: string;
+    /** Presence-joined by chat:who's handler — the only place this type is ever returned, and it always attaches one. */
+    status: BuddyStatus;
 }
 export interface ChatMessage {
     id: number;
@@ -119,6 +121,35 @@ export interface RoomSummary {
     unread: number;
     mentions: number;
     lastPostedAt?: number;
+    /** Set only by chat:rooms's left join against chat_dms. */
+    kind?: "dm";
+    participants?: {
+        a: string;
+        b: string;
+    };
+    /** Set only by chat:rooms's left join against chat_room_defaults; undefined for a room never stamped a default (every DM room included). */
+    defaultWake?: WakeMode;
+}
+/**
+ * Duplicated shape on purpose, same reasoning as ChatMember/ChatMessage
+ * above: mirrors lib/state/presence-store.ts's types, which rt-client
+ * cannot import.
+ */
+export type BuddyStatus = "live" | "idle" | "deaf" | "offline";
+export interface PresenceRow {
+    sessionId: string;
+    handle: string;
+    baseHandle: string;
+    cwd?: string;
+    repo?: string;
+    branch?: string;
+    pane?: string;
+    statusText?: string;
+    signedInAt: number;
+    lastSeenAt: number;
+    tailSeenAt?: number;
+    armedAt?: number;
+    signedOutAt?: number;
 }
 export type Attention = {
     needs: boolean;
@@ -156,6 +187,7 @@ export interface RunSummary {
     stages?: {
         name: string;
         status: string;
+        started_at: number | null;
     }[];
 }
 export interface RunAgent {
@@ -359,6 +391,7 @@ export interface Commands {
             room: string;
             handle: string;
             body: string;
+            mentions?: string[];
         };
         data: {
             id: number;
@@ -416,18 +449,21 @@ export interface Commands {
         payload: {
             handle: string;
             room?: string;
+            sessionId?: string;
         };
         data: Record<string, never>;
     };
     "chat:touch": {
         payload: {
             handle: string;
+            sessionId?: string;
         };
         data: Record<string, never>;
     };
     "chat:disarm": {
         payload: {
             handle: string;
+            sessionId?: string;
         };
         data: Record<string, never>;
     };
@@ -445,6 +481,79 @@ export interface Commands {
             }[];
         };
     };
+    "chat:sign-in": {
+        payload: {
+            sessionId: string;
+            baseHandle: string;
+            cwd?: string;
+            repo?: string;
+            branch?: string;
+            pane?: string;
+            statusText?: string;
+        };
+        data: {
+            handle: string;
+            reclaimed: boolean;
+        };
+    };
+    "chat:sign-out": {
+        payload: {
+            sessionId: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:away": {
+        payload: {
+            sessionId: string;
+            text: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:back": {
+        payload: {
+            sessionId: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:buddies": {
+        payload: Record<string, never>;
+        data: {
+            buddies: Array<PresenceRow & {
+                status: BuddyStatus;
+            }>;
+        };
+    };
+    /** `unread`'s three fields are disjoint and sum to the true total: `dms` is DM-room waking count; `mentions` is non-DM waking mentions; `rooms` is non-DM waking count minus those mentions (never negative). */
+    "chat:pulse": {
+        payload: {
+            sessionId: string;
+            cwd?: string;
+            repo?: string;
+            branch?: string;
+            pane?: string;
+        };
+        data: {
+            unread: {
+                dms: number;
+                mentions: number;
+                rooms: number;
+            };
+            status: BuddyStatus;
+        };
+    };
+    "chat:dm": {
+        payload: {
+            from: string;
+            to: string;
+            body: string;
+            sessionId?: string;
+        };
+        data: {
+            room: string;
+            id: number;
+            recipients: string[];
+        };
+    };
 }
 export type CommandName = keyof Commands;
 export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/health.d.ts

@@ -0,0 +1,11 @@
+import type { RtClientOptions } from "./transport.ts";
+/**
+ * A daemon-down result is a successful probe, not a failure of this call —
+ * eventsHead already never throws (transport.ts degrades every fetch to
+ * `{ ok: false, error }`), so this only reshapes that envelope for callers
+ * who want a boolean, not `{ ok, data, error }`.
+ */
+export declare function daemonHealth(opts?: RtClientOptions): Promise<{
+    reachable: boolean;
+    error?: string;
+}>;

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 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, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatArm, chatTouch, chatDisarm, chatUnreadWaking, eventsHead, } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatArm, chatTouch, chatDisarm, chatUnreadWaking, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatPulse, chatDm, eventsHead, } from "./client.ts";
 export { COMMAND_NAMES } 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, RoomSummary, } from "./commands.ts";
-export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow, } 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 { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER } from "./settings/resolve.ts";
 export type { Scope, Provenance, ResolveOpts, Resolved, InvalidScope, ListedSetting, ExplainRow, ExpandCtx, } from "./settings/resolve.ts";

package/dist/index.js

@@ -73,13 +73,16 @@ function chatJoin(a, o = {}) {
     payload.cwd = a.cwd;
   if (a.pane !== undefined)
     payload.pane = a.pane;
-  return rtCommand("chat:join", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:join", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatLeave(a, o = {}) {
-  return rtCommand("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatPost(a, o = {}) {
-  return rtCommand("chat:post", { room: a.room, handle: a.handle, body: a.body }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  const payload = { room: a.room, handle: a.handle, body: a.body };
+  if (a.mentions !== undefined)
+    payload.mentions = a.mentions;
+  return rtCommand("chat:post", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatRead(a, o = {}) {
   const payload = { handle: a.handle };
@@ -89,19 +92,19 @@ function chatRead(a, o = {}) {
     payload.limit = a.limit;
   if (a.sinceMs !== undefined)
     payload.sinceMs = a.sinceMs;
-  return rtCommand("chat:read", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:read", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatRooms(a, o = {}) {
-  return rtCommand("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatWho(a, o = {}) {
-  return rtCommand("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatMark(a, o = {}) {
   const payload = { handle: a.handle };
   if (a.room !== undefined)
     payload.room = a.room;
-  return rtCommand("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatMessages(a, o = {}) {
   const payload = { room: a.room };
@@ -109,28 +112,80 @@ function chatMessages(a, o = {}) {
     payload.before = a.before;
   if (a.limit !== undefined)
     payload.limit = a.limit;
-  return rtCommand("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatArm(a, o = {}) {
   const payload = { handle: a.handle };
   if (a.room !== undefined)
     payload.room = a.room;
-  return rtCommand("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
+  return rtCommand("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatTouch(a, o = {}) {
-  return rtCommand("chat:touch", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  const payload = { handle: a.handle };
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
+  return rtCommand("chat:touch", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatDisarm(a, o = {}) {
-  return rtCommand("chat:disarm", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  const payload = { handle: a.handle };
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
+  return rtCommand("chat:disarm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function chatUnreadWaking(a, o = {}) {
   const payload = { handle: a.handle };
   if (a.room !== undefined)
     payload.room = a.room;
-  return rtCommand("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatSignIn(a, o = {}) {
+  const payload = { sessionId: a.sessionId, baseHandle: a.baseHandle };
+  if (a.cwd !== undefined)
+    payload.cwd = a.cwd;
+  if (a.repo !== undefined)
+    payload.repo = a.repo;
+  if (a.branch !== undefined)
+    payload.branch = a.branch;
+  if (a.pane !== undefined)
+    payload.pane = a.pane;
+  if (a.statusText !== undefined)
+    payload.statusText = a.statusText;
+  return rtCommand("chat:sign-in", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatSignOut(a, o = {}) {
+  return rtCommand("chat:sign-out", { sessionId: a.sessionId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatAway(a, o = {}) {
+  return rtCommand("chat:away", { sessionId: a.sessionId, text: a.text }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatBack(a, o = {}) {
+  return rtCommand("chat:back", { sessionId: a.sessionId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatBuddies(o = {}) {
+  return rtCommand("chat:buddies", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatPulse(a, o = {}) {
+  const payload = { sessionId: a.sessionId };
+  if (a.cwd !== undefined)
+    payload.cwd = a.cwd;
+  if (a.repo !== undefined)
+    payload.repo = a.repo;
+  if (a.branch !== undefined)
+    payload.branch = a.branch;
+  if (a.pane !== undefined)
+    payload.pane = a.pane;
+  return rtCommand("chat:pulse", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatDm(a, o = {}) {
+  const payload = { from: a.from, to: a.to, body: a.body };
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
+  return rtCommand("chat:dm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 function eventsHead(o = {}) {
-  return rtCommand("events:head", {}, { sockPath: o.sockPath, timeoutMs: 1e4 });
+  return rtCommand("events:head", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
 // src/commands.ts
 var COMMAND_NAMES = [
@@ -157,7 +212,14 @@ var COMMAND_NAMES = [
   "chat:arm",
   "chat:touch",
   "chat:disarm",
-  "chat:unread-waking"
+  "chat:unread-waking",
+  "chat:sign-in",
+  "chat:sign-out",
+  "chat:away",
+  "chat:back",
+  "chat:buddies",
+  "chat:pulse",
+  "chat:dm"
 ];
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
@@ -202,6 +264,25 @@ function subscribe(onEvent, opts = {}) {
     } catch {}
   };
 }
+function createRelay(cfg, opts = {}) {
+  const doSubscribe = opts.subscribeImpl ?? subscribe;
+  return doSubscribe((type, data) => {
+    if (type !== "event")
+      return;
+    const frame = data;
+    if (typeof frame?.topic !== "string" || !cfg.match(frame.topic))
+      return;
+    const payload = JSON.stringify(data);
+    try {
+      cfg.publish(cfg.topic, payload);
+    } catch {}
+  }, opts);
+}
+// src/health.ts
+async function daemonHealth(opts = {}) {
+  const res = await eventsHead(opts);
+  return { reachable: res.ok, error: res.ok ? undefined : res.error };
+}
 // src/repos.ts
 import { existsSync, readFileSync } from "fs";
 import { homedir as homedir2 } from "os";
@@ -509,6 +590,13 @@ var REGISTRY = [
     merge: "replace",
     description: "Absolute path to the installed mattstack.app bundle, written by the app at launch so rt stops hardcoding ~/Applications."
   },
+  {
+    key: "mattstack.mode",
+    type: "string",
+    scopes: ["machine"],
+    merge: "replace",
+    description: 'The machine\'s intended flavor, "dev" or "prod". Normally written by `rt settings dev-mode` after a successful handoff; a manual `rt settings set` is the blessed repair escape hatch — the daemon park loop converges on whatever this says. Unset ⇒ derived from the dev wrapper\'s presence.'
+  },
   {
     key: "rt.integrations",
     type: "object",
@@ -1549,18 +1637,27 @@ export {
   expandVariables,
   eventsHead,
   deriveRepoIdentity,
+  daemonHealth,
+  createRelay,
   clearIdentityMemo,
   chatWho,
   chatUnreadWaking,
   chatTouch,
+  chatSignOut,
+  chatSignIn,
   chatRooms,
   chatRead,
+  chatPulse,
   chatPost,
   chatMessages,
   chatMark,
   chatLeave,
   chatJoin,
+  chatDm,
   chatDisarm,
+  chatBuddies,
+  chatBack,
+  chatAway,
   chatArm,
   allDefs,
   abandonRun,

package/dist/relay.d.ts

@@ -13,3 +13,18 @@ export declare const DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
  * the daemon being down just means silence, never a crash.
  */
 export declare function subscribe(onEvent: (type: RelayEventType, data: unknown) => void, opts?: RtClientOptions): () => void;
+/**
+ * One daemon subscription for the whole process, republished onto a
+ * caller-chosen pub/sub topic. Every subscriber to that topic then shares
+ * one relay connection instead of each opening its own — filtering here
+ * (rather than at each subscriber) is what keeps an unrelated event from
+ * making every subscriber re-render.
+ *
+ * Ported from console's `startRelay` (src/server/ws.ts) with the match
+ * predicate and target topic lifted to arguments.
+ */
+export declare function createRelay(cfg: {
+    match: (topic: string) => boolean;
+    topic: string;
+    publish: (topic: string, data: string) => void;
+}, opts?: RtClientOptions): () => void;

package/dist/transport.d.ts

@@ -6,6 +6,15 @@ export interface RtResponse<T = unknown> {
 export interface RtClientOptions {
     sockPath?: string;
     wsUrl?: string;
+    /** Per-call override of rtCommand's own default (15s); chat's pulse wrapper needs an 800ms hook budget. */
+    timeoutMs?: number;
+    /**
+     * Test seam for createRelay (relay.ts): swaps the daemon subscription for
+     * a fake without a live WebSocket server. Typed structurally against
+     * relay.ts's `subscribe` rather than importing its RelayEventType, which
+     * would make this module depend on the one that already depends on it.
+     */
+    subscribeImpl?: (onEvent: (type: string, data: unknown) => void, opts?: RtClientOptions) => () => void;
 }
 /**
  * Display-only: a module-load snapshot for callers that just want to show

package/package.json

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

package/src/client.ts

@@ -19,6 +19,8 @@ import type {
   ChatMember,
   ChatMessage,
   RoomSummary,
+  BuddyStatus,
+  PresenceRow,
 } from "./commands.ts";
 
 /**
@@ -151,21 +153,23 @@ export function chatJoin(
   if (a.wakeOn !== undefined) payload.wakeOn = a.wakeOn;
   if (a.cwd !== undefined) payload.cwd = a.cwd;
   if (a.pane !== undefined) payload.pane = a.pane;
-  return rtCommand<{ handle: string; memberCount: number; unread: number }>("chat:join", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ handle: string; memberCount: number; unread: number }>("chat:join", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatLeave(
   a: { room: string; handle: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<Record<string, never>>> {
-  return rtCommand<Record<string, never>>("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<Record<string, never>>("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatPost(
-  a: { room: string; handle: string; body: string },
+  a: { room: string; handle: string; body: string; mentions?: string[] },
   o: RtClientOptions = {},
 ): Promise<RtResponse<{ id: number; recipients: string[] }>> {
-  return rtCommand<{ id: number; recipients: string[] }>("chat:post", { room: a.room, handle: a.handle, body: a.body }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  const payload: Record<string, unknown> = { room: a.room, handle: a.handle, body: a.body };
+  if (a.mentions !== undefined) payload.mentions = a.mentions;
+  return rtCommand<{ id: number; recipients: string[] }>("chat:post", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatRead(
@@ -176,21 +180,21 @@ export function chatRead(
   if (a.room !== undefined) payload.room = a.room;
   if (a.limit !== undefined) payload.limit = a.limit;
   if (a.sinceMs !== undefined) payload.sinceMs = a.sinceMs;
-  return rtCommand<{ rooms: { room: string; messages: ChatMessage[] }[] }>("chat:read", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ rooms: { room: string; messages: ChatMessage[] }[] }>("chat:read", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatRooms(
   a: { handle: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<{ rooms: RoomSummary[] }>> {
-  return rtCommand<{ rooms: RoomSummary[] }>("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ rooms: RoomSummary[] }>("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatWho(
   a: { room: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<{ members: ChatMember[] }>> {
-  return rtCommand<{ members: ChatMember[] }>("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ members: ChatMember[] }>("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatMark(
@@ -199,7 +203,7 @@ export function chatMark(
 ): Promise<RtResponse<Record<string, never>>> {
   const payload: Record<string, unknown> = { handle: a.handle };
   if (a.room !== undefined) payload.room = a.room;
-  return rtCommand<Record<string, never>>("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<Record<string, never>>("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatMessages(
@@ -209,30 +213,35 @@ export function chatMessages(
   const payload: Record<string, unknown> = { room: a.room };
   if (a.before !== undefined) payload.before = a.before;
   if (a.limit !== undefined) payload.limit = a.limit;
-  return rtCommand<{ messages: ChatMessage[] }>("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ messages: ChatMessage[] }>("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatArm(
-  a: { handle: string; room?: string },
+  a: { handle: string; room?: string; sessionId?: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<Record<string, never>>> {
   const payload: Record<string, unknown> = { handle: a.handle };
   if (a.room !== undefined) payload.room = a.room;
-  return rtCommand<Record<string, never>>("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
+  return rtCommand<Record<string, never>>("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatTouch(
-  a: { handle: string },
+  a: { handle: string; sessionId?: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<Record<string, never>>> {
-  return rtCommand<Record<string, never>>("chat:touch", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
+  return rtCommand<Record<string, never>>("chat:touch", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatDisarm(
-  a: { handle: string },
+  a: { handle: string; sessionId?: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<Record<string, never>>> {
-  return rtCommand<Record<string, never>>("chat:disarm", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
+  return rtCommand<Record<string, never>>("chat:disarm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatUnreadWaking(
@@ -241,9 +250,76 @@ export function chatUnreadWaking(
 ): Promise<RtResponse<{ rooms: { room: string; count: number; mentions: number; maxId: number }[] }>> {
   const payload: Record<string, unknown> = { handle: a.handle };
   if (a.room !== undefined) payload.room = a.room;
-  return rtCommand<{ rooms: { room: string; count: number; mentions: number; maxId: number }[] }>("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ rooms: { room: string; count: number; mentions: number; maxId: number }[] }>("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+// ─── Presence ──────────────────────────────────────────────────────────
+
+export function chatSignIn(
+  a: { sessionId: string; baseHandle: string; cwd?: string; repo?: string; branch?: string; pane?: string; statusText?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ handle: string; reclaimed: boolean }>> {
+  const payload: Record<string, unknown> = { sessionId: a.sessionId, baseHandle: a.baseHandle };
+  if (a.cwd !== undefined) payload.cwd = a.cwd;
+  if (a.repo !== undefined) payload.repo = a.repo;
+  if (a.branch !== undefined) payload.branch = a.branch;
+  if (a.pane !== undefined) payload.pane = a.pane;
+  if (a.statusText !== undefined) payload.statusText = a.statusText;
+  return rtCommand<{ handle: string; reclaimed: boolean }>("chat:sign-in", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatSignOut(
+  a: { sessionId: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:sign-out", { sessionId: a.sessionId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatAway(
+  a: { sessionId: string; text: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:away", { sessionId: a.sessionId, text: a.text }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatBack(
+  a: { sessionId: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:back", { sessionId: a.sessionId }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatBuddies(
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ buddies: Array<PresenceRow & { status: BuddyStatus }> }>> {
+  return rtCommand<{ buddies: Array<PresenceRow & { status: BuddyStatus }> }>("chat:buddies", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatPulse(
+  a: { sessionId: string; cwd?: string; repo?: string; branch?: string; pane?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ unread: { dms: number; mentions: number; rooms: number }; status: BuddyStatus }>> {
+  const payload: Record<string, unknown> = { sessionId: a.sessionId };
+  if (a.cwd !== undefined) payload.cwd = a.cwd;
+  if (a.repo !== undefined) payload.repo = a.repo;
+  if (a.branch !== undefined) payload.branch = a.branch;
+  if (a.pane !== undefined) payload.pane = a.pane;
+  return rtCommand<{ unread: { dms: number; mentions: number; rooms: number }; status: BuddyStatus }>(
+    "chat:pulse",
+    payload,
+    { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 },
+  );
+}
+
+export function chatDm(
+  a: { from: string; to: string; body: string; sessionId?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ room: string; id: number; recipients: string[] }>> {
+  const payload: Record<string, unknown> = { from: a.from, to: a.to, body: a.body };
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
+  return rtCommand<{ room: string; id: number; recipients: string[] }>("chat:dm", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function eventsHead(o: RtClientOptions = {}): Promise<RtResponse<{ cursor: number }>> {
-  return rtCommand<{ cursor: number }>("events:head", {}, { sockPath: o.sockPath, timeoutMs: 10_000 });
+  return rtCommand<{ cursor: number }>("events:head", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }

package/src/commands.ts

@@ -96,6 +96,8 @@ export interface ChatMember {
   armedAt?: number;
   cwd?: string;
   pane?: string;
+  /** Presence-joined by chat:who's handler — the only place this type is ever returned, and it always attaches one. */
+  status: BuddyStatus;
 }
 
 export interface ChatMessage {
@@ -114,6 +116,34 @@ export interface RoomSummary {
   unread: number;
   mentions: number;
   lastPostedAt?: number;
+  /** Set only by chat:rooms's left join against chat_dms. */
+  kind?: "dm";
+  participants?: { a: string; b: string };
+  /** Set only by chat:rooms's left join against chat_room_defaults; undefined for a room never stamped a default (every DM room included). */
+  defaultWake?: WakeMode;
+}
+
+/**
+ * Duplicated shape on purpose, same reasoning as ChatMember/ChatMessage
+ * above: mirrors lib/state/presence-store.ts's types, which rt-client
+ * cannot import.
+ */
+export type BuddyStatus = "live" | "idle" | "deaf" | "offline";
+
+export interface PresenceRow {
+  sessionId: string;
+  handle: string;
+  baseHandle: string;
+  cwd?: string;
+  repo?: string;
+  branch?: string;
+  pane?: string;
+  statusText?: string;
+  signedInAt: number;
+  lastSeenAt: number;
+  tailSeenAt?: number;
+  armedAt?: number;
+  signedOutAt?: number;
 }
 
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
@@ -147,7 +177,7 @@ export interface RunSummary {
       pre-mirror daemons. */
   agent?: RunAgent | null;
   /** Executed stages only, in run order — the pipeline may define more that have not started. */
-  stages?: { name: string; status: string }[];
+  stages?: { name: string; status: string; started_at: number | null }[];
 }
 export interface RunAgent {
   status: "working" | "idle" | "blocked" | "done" | "unknown";
@@ -220,16 +250,33 @@ export interface Commands {
   "runs:abandon": { payload: { runId: string; repo?: string; reason?: string }; data: { ok: boolean } };
   "chat:join": { payload: { room: string; handle: string; wakeOn?: WakeMode; cwd?: string; pane?: string }; data: { handle: string; memberCount: number; unread: number } };
   "chat:leave": { payload: { room: string; handle: string }; data: Record<string, never> };
-  "chat:post": { payload: { room: string; handle: string; body: string }; data: { id: number; recipients: string[] } };
+  "chat:post": { payload: { room: string; handle: string; body: string; mentions?: string[] }; data: { id: number; recipients: string[] } };
   "chat:read": { payload: { handle: string; room?: string; limit?: number; sinceMs?: number }; data: { rooms: { room: string; messages: ChatMessage[] }[] } };
   "chat:rooms": { payload: { handle: string }; data: { rooms: RoomSummary[] } };
   "chat:who": { payload: { room: string }; data: { members: ChatMember[] } };
   "chat:mark": { payload: { handle: string; room?: string }; data: Record<string, never> };
   "chat:messages": { payload: { room: string; before?: number; limit?: number }; data: { messages: ChatMessage[] } };
-  "chat:arm": { payload: { handle: string; room?: string }; data: Record<string, never> };
-  "chat:touch": { payload: { handle: string }; data: Record<string, never> };
-  "chat:disarm": { payload: { handle: string }; data: Record<string, never> };
+  "chat:arm": { payload: { handle: string; room?: string; sessionId?: string }; data: Record<string, never> };
+  "chat:touch": { payload: { handle: string; sessionId?: string }; data: Record<string, never> };
+  "chat:disarm": { payload: { handle: string; sessionId?: string }; data: Record<string, never> };
   "chat:unread-waking": { payload: { handle: string; room?: string }; data: { rooms: { room: string; count: number; mentions: number; maxId: number }[] } };
+
+  // A session id keys these to one signed-in handle, not a room-membership
+  // handle string.
+  "chat:sign-in": {
+    payload: { sessionId: string; baseHandle: string; cwd?: string; repo?: string; branch?: string; pane?: string; statusText?: string };
+    data: { handle: string; reclaimed: boolean };
+  };
+  "chat:sign-out": { payload: { sessionId: string }; data: Record<string, never> };
+  "chat:away": { payload: { sessionId: string; text: string }; data: Record<string, never> };
+  "chat:back": { payload: { sessionId: string }; data: Record<string, never> };
+  "chat:buddies": { payload: Record<string, never>; data: { buddies: Array<PresenceRow & { status: BuddyStatus }> } };
+  /** `unread`'s three fields are disjoint and sum to the true total: `dms` is DM-room waking count; `mentions` is non-DM waking mentions; `rooms` is non-DM waking count minus those mentions (never negative). */
+  "chat:pulse": {
+    payload: { sessionId: string; cwd?: string; repo?: string; branch?: string; pane?: string };
+    data: { unread: { dms: number; mentions: number; rooms: number }; status: BuddyStatus };
+  };
+  "chat:dm": { payload: { from: string; to: string; body: string; sessionId?: string }; data: { room: string; id: number; recipients: string[] } };
 }
 
 export type CommandName = keyof Commands;
@@ -259,4 +306,11 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "chat:touch",
   "chat:disarm",
   "chat:unread-waking",
+  "chat:sign-in",
+  "chat:sign-out",
+  "chat:away",
+  "chat:back",
+  "chat:buddies",
+  "chat:pulse",
+  "chat:dm",
 ];

package/src/health.ts

@@ -0,0 +1,15 @@
+import { eventsHead } from "./client.ts";
+import type { RtClientOptions } from "./transport.ts";
+
+/**
+ * A daemon-down result is a successful probe, not a failure of this call —
+ * eventsHead already never throws (transport.ts degrades every fetch to
+ * `{ ok: false, error }`), so this only reshapes that envelope for callers
+ * who want a boolean, not `{ ok, data, error }`.
+ */
+export async function daemonHealth(
+  opts: RtClientOptions = {},
+): Promise<{ reachable: boolean; error?: string }> {
+  const res = await eventsHead(opts);
+  return { reachable: res.ok, error: res.ok ? undefined : res.error };
+}

package/src/index.ts

@@ -22,6 +22,13 @@ export {
   chatTouch,
   chatDisarm,
   chatUnreadWaking,
+  chatSignIn,
+  chatSignOut,
+  chatAway,
+  chatBack,
+  chatBuddies,
+  chatPulse,
+  chatDm,
   eventsHead,
 } from "./client.ts";
 
@@ -49,11 +56,15 @@ export type {
   ChatMember,
   ChatMessage,
   RoomSummary,
+  BuddyStatus,
+  PresenceRow,
 } from "./commands.ts";
 
-export { subscribe, DEFAULT_WS_URL } from "./relay.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";
 
 // ─── Settings (RT-50) ────────────────────────────────────────────────────────

package/src/relay.ts

@@ -59,3 +59,34 @@ export function subscribe(
     try { ws?.close(); } catch { /* already closed */ }
   };
 }
+
+/**
+ * One daemon subscription for the whole process, republished onto a
+ * caller-chosen pub/sub topic. Every subscriber to that topic then shares
+ * one relay connection instead of each opening its own — filtering here
+ * (rather than at each subscriber) is what keeps an unrelated event from
+ * making every subscriber re-render.
+ *
+ * Ported from console's `startRelay` (src/server/ws.ts) with the match
+ * predicate and target topic lifted to arguments.
+ */
+export function createRelay(
+  cfg: { match: (topic: string) => boolean; topic: string; publish: (topic: string, data: string) => void },
+  opts: RtClientOptions = {},
+): () => void {
+  const doSubscribe = opts.subscribeImpl ?? subscribe;
+  return doSubscribe((type, data) => {
+    if (type !== "event") return;
+    const frame = data as { topic?: unknown };
+    if (typeof frame?.topic !== "string" || !cfg.match(frame.topic)) return;
+    // Serializing outside the catch keeps the suppression narrow: only a
+    // publish that rejects its own frame is expected here, and one
+    // subscriber's broken publish must not tear down the shared relay.
+    const payload = JSON.stringify(data);
+    try {
+      cfg.publish(cfg.topic, payload);
+    } catch {
+      /* the subscriber went away */
+    }
+  }, opts);
+}

package/src/settings/registry-defs.ts

@@ -228,6 +228,13 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "replace",
     description: "Absolute path to the installed mattstack.app bundle, written by the app at launch so rt stops hardcoding ~/Applications.",
   },
+  {
+    key: "mattstack.mode",
+    type: "string",
+    scopes: ["machine"],
+    merge: "replace",
+    description: "The machine's intended flavor, \"dev\" or \"prod\". Normally written by `rt settings dev-mode` after a successful handoff; a manual `rt settings set` is the blessed repair escape hatch — the daemon park loop converges on whatever this says. Unset ⇒ derived from the dev wrapper's presence.",
+  },
   {
     key: "rt.integrations",
     type: "object",

package/src/transport.ts

@@ -19,6 +19,15 @@ export interface RtResponse<T = unknown> {
 export interface RtClientOptions {
   sockPath?: string;
   wsUrl?: string;
+  /** Per-call override of rtCommand's own default (15s); chat's pulse wrapper needs an 800ms hook budget. */
+  timeoutMs?: number;
+  /**
+   * Test seam for createRelay (relay.ts): swaps the daemon subscription for
+   * a fake without a live WebSocket server. Typed structurally against
+   * relay.ts's `subscribe` rather than importing its RelayEventType, which
+   * would make this module depend on the one that already depends on it.
+   */
+  subscribeImpl?: (onEvent: (type: string, data: unknown) => void, opts?: RtClientOptions) => () => void;
 }
 
 // Duplicates the ~/.mattstack/rt layout: rt-client has no dependency on rt's