@openscout/protocol 0.2.97 → 0.2.102

package/dist/broker-routes.d.ts

@@ -8,9 +8,13 @@ export declare const scoutBrokerPaths: {
         readonly capabilities: "/v1/capabilities";
         readonly runtimeCatalog: "/v1/runtime-catalog";
         readonly topologySnapshot: "/v1/topology/snapshot";
+        readonly meshNodes: "/v1/mesh/nodes";
+        readonly meshNodeState: "/v1/mesh/node-state";
         readonly tailDiscover: "/v1/tail/discover";
         readonly tailRecent: "/v1/tail/recent";
         readonly repoWatchSnapshot: "/v1/repo-watch/snapshot";
+        readonly machines: "/v1/machines";
+        readonly machinesScan: "/v1/machines/scan";
         readonly messages: "/v1/messages";
         readonly brokerMessages: "/v1/broker/messages";
         readonly eventsStream: "/v1/events/stream";
@@ -35,7 +39,10 @@ export declare const scoutBrokerPaths: {
 };
 export declare function scoutBrokerMessagesListPath(search: URLSearchParams): string;
 export declare function scoutBrokerMessagesPath(search: URLSearchParams): string;
+/** Name a conversation. An empty title hands it back to automatic naming. */
+export declare function scoutBrokerConversationTitlePath(conversationId: string): string;
 export declare function scoutBrokerInvocationPath(invocationId: string): string;
 export declare function scoutBrokerInvocationStreamPath(invocationId: string): string;
 export declare function scoutBrokerInvocationLifecyclePath(invocationId: string): string;
+export declare function scoutBrokerMachinePath(machineRef: string): string;
 //# sourceMappingURL=broker-routes.d.ts.map

package/dist/broker-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E"}
+{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../src/broker-routes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCnB,CAAC;AAEX,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKvE;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/broker-routes.js

@@ -11,9 +11,16 @@ export const scoutBrokerPaths = {
         capabilities: "/v1/capabilities",
         runtimeCatalog: "/v1/runtime-catalog",
         topologySnapshot: "/v1/topology/snapshot",
+        meshNodes: "/v1/mesh/nodes",
+        // Observe-tier compact node state. Read against a PEER broker's base URL
+        // through the signed/pinned mesh client; the local home feed is never
+        // widened for remote callers (mesh trust cone §4).
+        meshNodeState: "/v1/mesh/node-state",
         tailDiscover: "/v1/tail/discover",
         tailRecent: "/v1/tail/recent",
         repoWatchSnapshot: "/v1/repo-watch/snapshot",
+        machines: "/v1/machines",
+        machinesScan: "/v1/machines/scan",
         messages: "/v1/messages",
         brokerMessages: "/v1/broker/messages",
         eventsStream: "/v1/events/stream",
@@ -46,6 +53,10 @@ export function scoutBrokerMessagesPath(search) {
         ? `${scoutBrokerPaths.v1.brokerMessages}?${q}`
         : scoutBrokerPaths.v1.brokerMessages;
 }
+/** Name a conversation. An empty title hands it back to automatic naming. */
+export function scoutBrokerConversationTitlePath(conversationId) {
+    return `${scoutBrokerPaths.v1.conversations}/${encodeURIComponent(conversationId)}/title`;
+}
 export function scoutBrokerInvocationPath(invocationId) {
     return `${scoutBrokerPaths.v1.invocations}/${encodeURIComponent(invocationId)}`;
 }
@@ -55,3 +66,6 @@ export function scoutBrokerInvocationStreamPath(invocationId) {
 export function scoutBrokerInvocationLifecyclePath(invocationId) {
     return `${scoutBrokerInvocationPath(invocationId)}/lifecycle`;
 }
+export function scoutBrokerMachinePath(machineRef) {
+    return `${scoutBrokerPaths.v1.machines}/${encodeURIComponent(machineRef)}`;
+}

package/dist/conversation-projection.d.ts

@@ -1,6 +1,6 @@
 import type { ConversationKind } from "./conversations.js";
 import type { ObservedActivity } from "./observed-status.js";
-export declare const CONVERSATION_PROJECTION_VERSION = 1;
+export declare const CONVERSATION_PROJECTION_VERSION = 2;
 export type ConversationProjectionEntityKind = "scout_conversation" | "observed_session";
 export type ConversationProjectionVisibility = "visible" | "hidden";
 export type ConversationProjectionItem = {

package/dist/conversation-projection.js

@@ -1,4 +1,4 @@
-export const CONVERSATION_PROJECTION_VERSION = 1;
+export const CONVERSATION_PROJECTION_VERSION = 2;
 export function scoutConversationFeedId(conversationId) {
     return `conv:${conversationId}`;
 }

package/dist/herdr-workspace-digest.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Herdr workspace digest — the presentation layer over {@link HerdrSessionTopology}.
+ *
+ * The raw projection is faithful but shapeless: a complex session is several
+ * workspaces × tabs × panes, and handing that whole tree to an operator (or to
+ * an assistant that has to answer for it) buries the one thing they came for.
+ * A digest ranks, groups, bounds, and describes it.
+ *
+ * Four commitments, in order of how much they matter:
+ *
+ * 1. **Attention leads.** A `blocked` pane is the only thing in a herdr session
+ *    that is actually waiting on a person. It comes first, always, before any
+ *    inventory. Everything else is context for it.
+ * 2. **Directory is the grouping axis, not the tab.** Operators think "which
+ *    repo", herdr thinks "which tab". Grouping is by the pane's literal working
+ *    directory — no repo-root inference, because a guessed grouping presented as
+ *    a fact is worse than an honest fragmented one.
+ * 3. **Shape is described, not dumped.** A tab's layout becomes one readable
+ *    phrase ("2×2 grid", "3 columns (2 · 1 · 1)") derived from the pane rects.
+ * 4. **Bounded and honest.** Panes are capped and truncation is declared;
+ *    `unknown` never collapses into `done`; a persisted projection is labeled
+ *    last-known rather than passed off as live.
+ *
+ * There are no mutation verbs here, for the same reason there are none in the
+ * topology projection: herdr owns workspaces, tabs and panes, and Scout's layer
+ * is coordination over whatever host is present. A digest pane carries the
+ * herdr `target` string so a caller can construct a handoff; performing it is
+ * the herdr client's job.
+ */
+import type { HerdrAgentStatus, HerdrSessionTopology, HerdrTabLayout, HerdrTopologyUnavailableReason } from "./terminal-host-topology.js";
+/** Total emitted panes across every group before the digest declares truncation. */
+export declare const HERDR_DIGEST_PANE_CAP = 40;
+/** Ceiling on each of the two lead lists; attention is a shortlist, not an inventory. */
+export declare const HERDR_DIGEST_LEAD_CAP = 12;
+export type HerdrStatusCounts = Record<HerdrAgentStatus, number>;
+export type HerdrDigestPane = {
+    /**
+     * What `herdr agent <verb>` accepts as a target for this pane: the stable
+     * terminal id when herdr reported one, else the pane id. Null on a persisted
+     * projection, where neither is live — a pane you cannot address yet.
+     */
+    target: string | null;
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    label: string | null;
+    /** Detected agent label ("claude", "codex"), or null for a plain shell. */
+    agent: string | null;
+    status: HerdrAgentStatus;
+    /** Working directory: the foreground process's when known, else the pane's. */
+    directory: string | null;
+    focused: boolean;
+    /**
+     * Scrollback backlog depth in lines. The cheapest activity signal a
+     * projection carries — a deep backlog on an idle pane is work that already
+     * happened, not work happening. Null when herdr did not report scroll state.
+     */
+    backlog: number | null;
+};
+export type HerdrDigestGroup = {
+    /** The panes' literal shared working directory; null when they report none. */
+    directory: string | null;
+    /** Last path segment — how an operator names the place. */
+    name: string;
+    counts: HerdrStatusCounts;
+    panes: HerdrDigestPane[];
+    /** Panes in this group dropped by the pane cap. */
+    omitted: number;
+    /**
+     * What was dropped, by status. A collapsed label has to carry its own scent:
+     * a reader decides whether the hidden rows matter from the label alone, so
+     * "2 idle not shown" is a usable label and "2 not shown" is not.
+     */
+    omittedCounts: HerdrStatusCounts;
+};
+export type HerdrDigestShape = {
+    workspaceId: string;
+    workspaceLabel: string;
+    tabId: string;
+    tabLabel: string;
+    paneCount: number;
+    /** One readable phrase for the arrangement, e.g. "2×2 grid". */
+    arrangement: string;
+    zoomed: boolean;
+    focused: boolean;
+};
+export type HerdrWorkspaceDigest = {
+    session: string;
+    /** True only for a projection read from a running herdr server. */
+    live: boolean;
+    observedAt: number;
+    /** Set when the projection is the persisted last-known state, not a live read. */
+    savedAt: number | null;
+    /**
+     * Why a non-live projection is not live. `unreadable` means a server for the
+     * session IS running and did not answer — the digest must not present that as
+     * a stopped session. Null on a live read.
+     */
+    unavailable: HerdrTopologyUnavailableReason | null;
+    totals: {
+        workspaces: number;
+        tabs: number;
+        panes: number;
+        /** Panes herdr recognized an agent in. The rest are plain shells. */
+        agents: number;
+    };
+    counts: HerdrStatusCounts;
+    /** Blocked panes — the only entries that represent something waiting on a person. */
+    needsYou: HerdrDigestPane[];
+    /** Panes herdr observed as working, bounded. */
+    working: HerdrDigestPane[];
+    groups: HerdrDigestGroup[];
+    shapes: HerdrDigestShape[];
+    truncated: boolean;
+    /** Caveats the reader must carry with the numbers. Never decorative. */
+    notes: string[];
+};
+export declare function herdrStatusRank(status: HerdrAgentStatus): number;
+/**
+ * Describe a tab's arrangement from its pane rects.
+ *
+ * Panes sharing an x start a column; panes sharing a y start a row. A layout
+ * whose columns all hold the same number of panes is a grid and is named as
+ * one; anything else is named by its columns and their depths, which is both
+ * shorter and more truthful than inventing a name for an irregular split.
+ */
+export declare function describeHerdrArrangement(layout: HerdrTabLayout | null, paneCount: number): string;
+/**
+ * Build the digest for one herdr session topology.
+ *
+ * Pure: the same topology always digests to the same value, so the whole
+ * presentation is testable without a herdr server.
+ */
+export declare function digestHerdrTopology(topology: HerdrSessionTopology, options?: {
+    paneCap?: number;
+    leadCap?: number;
+}): HerdrWorkspaceDigest;
+/**
+ * Render a digest as the text an operator should actually read.
+ *
+ * Ordering is the whole design: what is waiting, then what is moving, then
+ * where things live, then how the screen is arranged. A reader who stops after
+ * the first section has still got the answer that mattered.
+ *
+ * Section heads are verb phrases rather than bare nouns, and there is no
+ * trailing caveat block: a qualifier that changes how a count should be read
+ * sits directly under that count, because a scanning reader reaches the top of
+ * the output and not the bottom of it.
+ */
+export declare function renderHerdrWorkspaceDigest(digest: HerdrWorkspaceDigest): string;
+//# sourceMappingURL=herdr-workspace-digest.d.ts.map

package/dist/herdr-workspace-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-workspace-digest.d.ts","sourceRoot":"","sources":["../src/herdr-workspace-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACpB,cAAc,EACd,8BAA8B,EAC/B,MAAM,6BAA6B,CAAC;AAErC,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,gBAAgB,CAAC;IACzB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,EAAE,iBAAiB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,8BAA8B,GAAG,IAAI,CAAC;IACnD,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,qEAAqE;QACrE,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gDAAgD;IAChD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAaF,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAEhE;AAiDD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,GAAG,IAAI,EAC7B,SAAS,EAAE,MAAM,GAChB,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,oBAAoB,CAuHtB;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA+C/E"}

package/dist/herdr-workspace-digest.js

@@ -0,0 +1,343 @@
+/**
+ * Herdr workspace digest — the presentation layer over {@link HerdrSessionTopology}.
+ *
+ * The raw projection is faithful but shapeless: a complex session is several
+ * workspaces × tabs × panes, and handing that whole tree to an operator (or to
+ * an assistant that has to answer for it) buries the one thing they came for.
+ * A digest ranks, groups, bounds, and describes it.
+ *
+ * Four commitments, in order of how much they matter:
+ *
+ * 1. **Attention leads.** A `blocked` pane is the only thing in a herdr session
+ *    that is actually waiting on a person. It comes first, always, before any
+ *    inventory. Everything else is context for it.
+ * 2. **Directory is the grouping axis, not the tab.** Operators think "which
+ *    repo", herdr thinks "which tab". Grouping is by the pane's literal working
+ *    directory — no repo-root inference, because a guessed grouping presented as
+ *    a fact is worse than an honest fragmented one.
+ * 3. **Shape is described, not dumped.** A tab's layout becomes one readable
+ *    phrase ("2×2 grid", "3 columns (2 · 1 · 1)") derived from the pane rects.
+ * 4. **Bounded and honest.** Panes are capped and truncation is declared;
+ *    `unknown` never collapses into `done`; a persisted projection is labeled
+ *    last-known rather than passed off as live.
+ *
+ * There are no mutation verbs here, for the same reason there are none in the
+ * topology projection: herdr owns workspaces, tabs and panes, and Scout's layer
+ * is coordination over whatever host is present. A digest pane carries the
+ * herdr `target` string so a caller can construct a handoff; performing it is
+ * the herdr client's job.
+ */
+/** Total emitted panes across every group before the digest declares truncation. */
+export const HERDR_DIGEST_PANE_CAP = 40;
+/** Ceiling on each of the two lead lists; attention is a shortlist, not an inventory. */
+export const HERDR_DIGEST_LEAD_CAP = 12;
+const EMPTY_COUNTS = { blocked: 0, working: 0, idle: 0, done: 0, unknown: 0 };
+/** Attention order. Blocked outranks working because it is the only state that waits on a person. */
+const STATUS_RANK = {
+    blocked: 5,
+    working: 4,
+    idle: 3,
+    done: 2,
+    unknown: 1,
+};
+export function herdrStatusRank(status) {
+    return STATUS_RANK[status];
+}
+function emptyCounts() {
+    return { ...EMPTY_COUNTS };
+}
+function totalCount(counts) {
+    return counts.blocked + counts.working + counts.idle + counts.done + counts.unknown;
+}
+function paneDirectory(pane) {
+    return pane.foregroundCwd ?? pane.cwd ?? null;
+}
+function directoryName(directory) {
+    if (!directory)
+        return "no directory";
+    const segments = directory.replace(/\/+$/, "").split("/").filter(Boolean);
+    return segments[segments.length - 1] ?? directory;
+}
+function toDigestPane(pane) {
+    return {
+        target: pane.terminalId ?? pane.paneId ?? null,
+        paneId: pane.paneId,
+        workspaceId: pane.workspaceId,
+        tabId: pane.tabId,
+        label: pane.label,
+        agent: pane.agent,
+        status: pane.agentStatus,
+        directory: paneDirectory(pane),
+        focused: pane.focused,
+        backlog: pane.scroll?.maxOffsetFromBottom ?? null,
+    };
+}
+/**
+ * Rank panes for a lead list: attention state, then the focused pane (where the
+ * operator's eyes already are), then the deepest backlog, then pane id so the
+ * order never wobbles between polls.
+ */
+function compareLeadPanes(left, right) {
+    const byStatus = STATUS_RANK[right.status] - STATUS_RANK[left.status];
+    if (byStatus !== 0)
+        return byStatus;
+    if (left.focused !== right.focused)
+        return left.focused ? -1 : 1;
+    const byBacklog = (right.backlog ?? -1) - (left.backlog ?? -1);
+    if (byBacklog !== 0)
+        return byBacklog;
+    return left.paneId.localeCompare(right.paneId, undefined, { numeric: true });
+}
+/**
+ * Describe a tab's arrangement from its pane rects.
+ *
+ * Panes sharing an x start a column; panes sharing a y start a row. A layout
+ * whose columns all hold the same number of panes is a grid and is named as
+ * one; anything else is named by its columns and their depths, which is both
+ * shorter and more truthful than inventing a name for an irregular split.
+ */
+export function describeHerdrArrangement(layout, paneCount) {
+    if (paneCount <= 0)
+        return "no panes";
+    if (paneCount === 1)
+        return "single pane";
+    const panes = layout?.panes ?? [];
+    if (panes.length !== paneCount)
+        return `${paneCount} panes (layout unavailable)`;
+    const columns = new Map();
+    const rows = new Map();
+    for (const pane of panes) {
+        columns.set(pane.rect.x, (columns.get(pane.rect.x) ?? 0) + 1);
+        rows.set(pane.rect.y, (rows.get(pane.rect.y) ?? 0) + 1);
+    }
+    if (columns.size === 1)
+        return `${paneCount} stacked rows`;
+    if (rows.size === 1)
+        return `${paneCount} side-by-side columns`;
+    const depths = [...columns.entries()]
+        .sort((left, right) => left[0] - right[0])
+        .map(([, count]) => count);
+    const first = depths[0] ?? 0;
+    if (depths.every((depth) => depth === first) && first * columns.size === paneCount) {
+        return `${first}×${columns.size} grid`;
+    }
+    return `${columns.size} columns (${depths.join(" · ")})`;
+}
+/**
+ * Build the digest for one herdr session topology.
+ *
+ * Pure: the same topology always digests to the same value, so the whole
+ * presentation is testable without a herdr server.
+ */
+export function digestHerdrTopology(topology, options = {}) {
+    const paneCap = options.paneCap ?? HERDR_DIGEST_PANE_CAP;
+    const leadCap = options.leadCap ?? HERDR_DIGEST_LEAD_CAP;
+    const counts = emptyCounts();
+    const shapes = [];
+    const all = [];
+    let tabTotal = 0;
+    let agentTotal = 0;
+    for (const workspace of topology.workspaces) {
+        const workspaceLabel = workspace.label ?? (workspace.number != null ? `workspace ${workspace.number}` : workspace.workspaceId);
+        for (const tab of workspace.tabs) {
+            tabTotal += 1;
+            shapes.push({
+                workspaceId: workspace.workspaceId,
+                workspaceLabel,
+                tabId: tab.tabId,
+                tabLabel: tab.label ?? (tab.number != null ? `tab ${tab.number}` : tab.tabId),
+                paneCount: tab.panes.length,
+                arrangement: describeHerdrArrangement(tab.layout, tab.panes.length),
+                zoomed: tab.layout?.zoomed ?? false,
+                focused: workspace.focused && tab.focused,
+            });
+            for (const pane of tab.panes) {
+                const digestPane = toDigestPane(pane);
+                counts[digestPane.status] += 1;
+                if (digestPane.agent)
+                    agentTotal += 1;
+                all.push(digestPane);
+            }
+        }
+    }
+    // Groups are filled in rank order so the pane cap spends its budget on the
+    // panes that matter, not on whichever directory herdr happened to list first.
+    const ranked = [...all].sort(compareLeadPanes);
+    const kept = ranked.slice(0, paneCap);
+    const droppedByDirectory = new Map();
+    for (const pane of ranked.slice(paneCap)) {
+        const key = pane.directory ?? "";
+        let dropped = droppedByDirectory.get(key);
+        if (!dropped) {
+            dropped = emptyCounts();
+            droppedByDirectory.set(key, dropped);
+        }
+        dropped[pane.status] += 1;
+    }
+    const groupsByDirectory = new Map();
+    for (const pane of all) {
+        const key = pane.directory ?? "";
+        let group = groupsByDirectory.get(key);
+        if (!group) {
+            group = {
+                directory: pane.directory,
+                name: directoryName(pane.directory),
+                counts: emptyCounts(),
+                panes: [],
+                omitted: totalCount(droppedByDirectory.get(key) ?? EMPTY_COUNTS),
+                omittedCounts: { ...(droppedByDirectory.get(key) ?? EMPTY_COUNTS) },
+            };
+            groupsByDirectory.set(key, group);
+        }
+        group.counts[pane.status] += 1;
+    }
+    const keptIds = new Set(kept.map((pane) => `${pane.workspaceId}/${pane.paneId}`));
+    for (const pane of all) {
+        if (!keptIds.has(`${pane.workspaceId}/${pane.paneId}`))
+            continue;
+        groupsByDirectory.get(pane.directory ?? "")?.panes.push(pane);
+    }
+    const groups = [...groupsByDirectory.values()];
+    for (const group of groups)
+        group.panes.sort(compareLeadPanes);
+    // Groups sort by what is waiting, then what is moving, then size — the same
+    // precedence the lead lists use, applied one level up.
+    groups.sort((left, right) => right.counts.blocked - left.counts.blocked
+        || right.counts.working - left.counts.working
+        || (right.panes.length + right.omitted) - (left.panes.length + left.omitted)
+        || left.name.localeCompare(right.name, undefined, { numeric: true }));
+    const notes = [];
+    if (!topology.running) {
+        // "Last known" is only useful with a when: a layout saved an hour ago and
+        // one saved in March are the same claim with very different weight.
+        const saved = topology.savedAt ? ` Last saved ${new Date(topology.savedAt).toISOString()}.` : "";
+        notes.push(topology.unavailable === "unreadable"
+            // The session IS running; herdr just would not answer. Saying "stopped"
+            // here would be the one thing a digest must never do — state, of live
+            // work, that it is not live.
+            ? `A herdr server for this session is running but did not answer, so this is the persisted last-known layout, not what is on screen. The usual cause is a protocol skew between the installed herdr client and a long-lived server; restarting that session's server (which exits its pane processes) is what clears it.${saved}`
+            : `Not live: this is the persisted last-known layout. Agent status, terminal ids and geometry are absent from it — no pane here is claimed to be running.${saved}`);
+    }
+    if (counts.unknown > 0) {
+        notes.push(`${counts.unknown} ${counts.unknown === 1 ? "pane reports" : "panes report"} unknown: herdr sees an agent it cannot classify. Unknown is the absence of a signal, not completion.`);
+    }
+    return {
+        session: topology.session,
+        live: topology.running,
+        observedAt: topology.observedAt,
+        savedAt: topology.savedAt ?? null,
+        unavailable: topology.running ? null : topology.unavailable ?? "not_running",
+        totals: {
+            workspaces: topology.workspaces.length,
+            tabs: tabTotal,
+            panes: all.length,
+            agents: agentTotal,
+        },
+        counts,
+        needsYou: ranked.filter((pane) => pane.status === "blocked").slice(0, leadCap),
+        working: ranked.filter((pane) => pane.status === "working").slice(0, leadCap),
+        groups,
+        shapes,
+        truncated: all.length > paneCap,
+        notes,
+    };
+}
+/**
+ * One row, led by whatever is most specific to this pane.
+ *
+ * Rows that all begin `term-w1:p1`, `term-w1:p2` share a long prefix, and a
+ * scanning reader learns to skip the opening of every line — so the identity
+ * column becomes the one column nobody reads. The lead is therefore the pane's
+ * label when it has one, and its pane id when it does not, since a short id
+ * differs within the first couple of characters where a terminal id does not.
+ *
+ * The pane id is enough to act on: `herdr agent <verb>` accepts the pane
+ * currently hosting an agent as a target. The directory is the basename only —
+ * the full path is carried once, in the grouped section, and repeating it on
+ * every row buys nothing.
+ */
+function paneLine(pane) {
+    const parts = pane.label
+        ? [pane.label, pane.agent ?? "shell", pane.paneId]
+        : [pane.paneId, pane.agent ?? "shell"];
+    if (pane.directory)
+        parts.push(directoryName(pane.directory));
+    if (pane.focused)
+        parts.push("focused");
+    return `  ${parts.join("  ")}`;
+}
+/** "2 idle not shown" — a collapsed label a reader can decide from. */
+function omittedLabel(counts) {
+    const total = totalCount(counts);
+    if (total === 0)
+        return null;
+    const order = ["blocked", "working", "idle", "done", "unknown"];
+    const present = order.filter((status) => counts[status] > 0);
+    if (present.length === 1)
+        return `+${total} ${present[0]} not shown`;
+    return `+${total} not shown (${present.map((status) => `${counts[status]} ${status}`).join(" · ")})`;
+}
+function countsLine(counts) {
+    const order = ["blocked", "working", "idle", "done", "unknown"];
+    const parts = order.filter((status) => counts[status] > 0).map((status) => `${counts[status]} ${status}`);
+    return parts.length ? parts.join(" · ") : "no panes";
+}
+/**
+ * Render a digest as the text an operator should actually read.
+ *
+ * Ordering is the whole design: what is waiting, then what is moving, then
+ * where things live, then how the screen is arranged. A reader who stops after
+ * the first section has still got the answer that mattered.
+ *
+ * Section heads are verb phrases rather than bare nouns, and there is no
+ * trailing caveat block: a qualifier that changes how a count should be read
+ * sits directly under that count, because a scanning reader reaches the top of
+ * the output and not the bottom of it.
+ */
+export function renderHerdrWorkspaceDigest(digest) {
+    const lines = [];
+    const state = digest.live
+        ? "live"
+        : digest.unavailable === "unreadable" ? "running, not readable" : "not running";
+    const { workspaces, tabs, panes } = digest.totals;
+    lines.push(`herdr · ${digest.session} — ${state} · ${workspaces} workspace${workspaces === 1 ? "" : "s"}, ${tabs} tab${tabs === 1 ? "" : "s"}, ${panes} pane${panes === 1 ? "" : "s"} (${countsLine(digest.counts)})`);
+    // Caveats sit under the counts they qualify, not in a block at the bottom.
+    // A qualifier that changes how a number should be read is body text; a
+    // scanning reader never reaches a footnote, and these are the lines that stop
+    // someone believing `unknown` meant done or that a stale layout was current.
+    for (const note of digest.notes)
+        lines.push(`  ${note}`);
+    if (digest.needsYou.length) {
+        lines.push("", "Waiting on you");
+        for (const pane of digest.needsYou)
+            lines.push(paneLine(pane));
+    }
+    if (digest.working.length) {
+        lines.push("", "Working now");
+        for (const pane of digest.working)
+            lines.push(paneLine(pane));
+    }
+    if (digest.groups.length) {
+        lines.push("", "Grouped by directory");
+        for (const group of digest.groups) {
+            const total = totalCount(group.counts);
+            const where = group.directory ? ` (${group.directory})` : "";
+            const hidden = omittedLabel(group.omittedCounts);
+            lines.push(`  ${group.name}${where} — ${total} pane${total === 1 ? "" : "s"} · ${countsLine(group.counts)}${hidden ? ` · ${hidden}` : ""}`);
+        }
+    }
+    if (digest.shapes.length) {
+        lines.push("", "Arranged like this");
+        for (const shape of digest.shapes) {
+            const marks = [shape.arrangement];
+            if (shape.zoomed)
+                marks.push("zoomed");
+            if (shape.focused)
+                marks.push("focused");
+            // The tab id leads because two workspaces can carry the same label, and
+            // a label can itself contain the separator — the id cannot do either.
+            lines.push(`  ${shape.tabId}  ${shape.workspaceLabel} / ${shape.tabLabel} — ${marks.join(" · ")}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./a2a.js";
 export * from "./scout-agent-card.js";
 export * from "./relay-agent-card.js";
 export * from "./mesh.js";
+export * from "./machines.js";
 export * from "./conversations.js";
 export * from "./conversation-projection.js";
 export * from "./channel-identity.js";
@@ -53,6 +54,7 @@ export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
+export * from "./herdr-workspace-digest.js";
 export * from "./broker-routes.js";
 export * from "./rendezvous.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./a2a.js";
 export * from "./scout-agent-card.js";
 export * from "./relay-agent-card.js";
 export * from "./mesh.js";
+export * from "./machines.js";
 export * from "./conversations.js";
 export * from "./conversation-projection.js";
 export * from "./channel-identity.js";
@@ -53,5 +54,6 @@ export * from "./terminal-surface-id.js";
 export * from "./terminal-sessions.js";
 export * from "./terminal-workspaces.js";
 export * from "./terminal-host-topology.js";
+export * from "./herdr-workspace-digest.js";
 export * from "./broker-routes.js";
 export * from "./rendezvous.js";