@kangentic/protocol 0.15.0 → 0.17.0

package/dist/events/event.d.ts

@@ -27,6 +27,7 @@
  * event before its router dispatches on `kind`.
  */
 import type { JsonValue } from '../wire/messages';
+import { type ReadStreamSessionStatusWire } from '../wire/payloads';
 import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEventPayload } from './payloads';
 export interface TranscriptEvent {
     kind: 'transcript';
@@ -60,11 +61,25 @@ export type ActivityEventPayload = {
     options?: string[];
 }
 /**
- * The streamed session's PTY exited. Pushed once by the desktop's
- * read-stream subscription right before it tears itself down, so the
- * phone learns "this session is over" from the feed itself instead of
- * inferring it from silence. `intentional` distinguishes a deliberate
- * stop (desktop Stop button, suspend, shutdown) from a crash.
+ * The feed's last word: the desktop's read-stream subscription pushes this
+ * once, right before it tears itself down, so the phone learns "this
+ * session is over" from the feed itself instead of inferring it from
+ * silence. Sent when the streamed session's PTY exits. From 0.16.0 it is
+ * also sent when a paused row, which the feed holds without a PTY, is
+ * replaced or removed. `intentional` distinguishes a deliberate stop
+ * (desktop Stop button, suspend, shutdown, a resume replacing a paused row)
+ * from a crash.
+ *
+ * `successorSessionId`, when present, names the session that replaced this
+ * one for the same task. A desktop resume never reuses the paused session's
+ * id: it spawns a new session and drops the paused row, so a feed held on
+ * the paused session can only end, never turn back into `running`. The task
+ * continues as the successor; subscribe to it. Its snapshot carries
+ * `sessionStatus` (`queued` when the desktop's concurrency limit holds it)
+ * and `resuming: true`. Absent when no successor exists (a removed paused
+ * row, or a successor whose own spawn failed), and from pre-0.16.0
+ * desktops, which never end a feed this way and leave it silent instead. An
+ * older phone ignores the field and still sees an ended session.
  *
  * `spawnProgressLabel`, when present, means the desktop had a respawn in
  * flight for this task when the session ended - a same-column respawn
@@ -81,7 +96,8 @@ export type ActivityEventPayload = {
  * the desktop's own display text for what it is doing ("Switching
  * model...", "Starting agent...", a live git-queue wait count) - treat it
  * as untrusted display text, not a key to switch on, cap its length, and
- * fall back to generic copy rather than parsing it.
+ * fall back to generic copy rather than parsing it. From 0.16.0 the desktop
+ * sends it sanitized as `BoardTaskWire.spawn_progress` describes.
  *
  * INTENT, not a guarantee, on the same terms `BoardColumnWire.spawns_session`
  * documents: the desktop can suspend without a successor ever landing (a
@@ -107,6 +123,41 @@ export type ActivityEventPayload = {
     type: 'session-ended';
     intentional: boolean;
     spawnProgressLabel?: string;
+    successorSessionId?: string;
+}
+/**
+ * The streamed session's lifecycle status changed after the subscribe
+ * snapshot: `queued` -> `running` when the desktop's concurrency limit
+ * frees a slot, -> `suspended` on a pause or a respawn, -> `exited` when the
+ * desktop retires a session whose agent already ended. Sent only on an
+ * actual change, for the same session id only. A resume is a NEW session
+ * id, so suspended -> running never arrives here: see `session-ended`'s
+ * `successorSessionId`.
+ *
+ * A `suspended` push precedes the PTY's `session-ended` when a running
+ * session is suspended, so for an instant both say the session is parked.
+ *
+ * Precedence, matching the desktop card: a non-null `spawn_progress` on the
+ * task's board row overrides `suspended` (the desktop suspends a session
+ * before every model, agent or effort respawn), and never `running` or
+ * `queued`. Read `suspended` alone as "Paused"; read it next to a label as
+ * that label.
+ *
+ * `resuming` and `resumable` repeat the snapshot fields so the payload is
+ * complete on its own. The desktop re-reads all three on each lifecycle
+ * edge of this session and sends the payload when any of them differs. A
+ * move to Done or an archive of a paused task is no edge of its row, so
+ * `resumable` here can stay true until the feed ends; gate Resume on
+ * `BoardTaskWire.resumable`, which the board event for that move refreshes.
+ * Absent from pre-0.16.0 desktops, whose phones drop the unknown
+ * type through `isBridgeEvent` and keep inferring status from activity
+ * events.
+ */
+ | {
+    type: 'status';
+    status: ReadStreamSessionStatusWire;
+    resuming: boolean;
+    resumable: boolean;
 }
 /**
  * The agent's most recent assistant message, already collapsed to a short

package/dist/events/payloads.d.ts

@@ -160,6 +160,12 @@ export interface SessionUsageWire {
         totalCostUsd: number;
         totalDurationMs: number;
     };
+    /**
+     * Completed tool calls across every run of the session. A resume (an app
+     * restart, a pause and resume) is a new run, and the desktop adds the
+     * session's earlier runs to the live count. Optional: an older desktop
+     * omits it.
+     */
     toolCallCount?: number;
     model: {
         id: string;
@@ -325,6 +331,104 @@ export interface BoardTaskWire {
     archived_at: string | null;
     created_at: string;
     updated_at: string;
+    /**
+     * The task's in-flight spawn-progress label, the text of the desktop card's
+     * preparing footer: "Creating worktree...", "Fetching latest...",
+     * "Waiting (2 ahead)", "Switching model...", "Starting agent...", a git-queue
+     * wait with its elapsed time, and any staleness note the desktop appends
+     * ("Starting agent... (base 3 behind)"). The desktop announces every change
+     * with a `task-updated` board event, coalesced to at most about one a
+     * second per task.
+     *
+     * Untrusted display text, the same terms as `session-ended`'s
+     * `spawnProgressLabel`: never parse it or switch on it, and fall back to
+     * generic copy. It can carry text the desktop did not write: a column
+     * automation's name, in `Running "<name>"...`, from a config a team may
+     * share. From 0.16.0 the desktop strips escape sequences, control characters,
+     * invisible format characters (bidi controls, the zero-width space, the soft
+     * hyphen, the byte order mark) and tag characters outside the England,
+     * Scotland and Wales flag emoji, turns line breaks and tabs into spaces, and
+     * caps it at
+     * 120 characters ending in "...", but a client still caps it for its own
+     * layout.
+     *
+     * Precedence, matching the desktop card: a label overrides a `suspended`
+     * session status (a respawn is in flight behind a session that was just
+     * suspended for it), and never a `running` or `queued` one. A client that
+     * reads the read-stream feed's `status: 'suspended'` during a model or
+     * effort switch shows this label, not "Paused".
+     *
+     * A spawn path that dies without clearing its label leaves it in place for
+     * up to the desktop's 120s spawn-progress TTL, and the TTL expiry sends no
+     * board event, so a stale label can outlive its spawn until the next
+     * snapshot. Null or absent means no spawn is in flight, or a desktop that
+     * predates the field (pre-0.16.0). Under `view: 'sessions'` a task with a
+     * label is kept even while its `session_id` is null, so a first start and
+     * a respawn's gap stay visible.
+     *
+     * Declared OPTIONAL (`?`) like `pr_merge_readiness`; `parseBoardTaskWire`
+     * populates the key from every real wire response.
+     */
+    spawn_progress?: string | null;
+    /**
+     * True when the task's session is paused and the desktop's own task view
+     * would offer Resume for it: the task is not in To Do or Done and not
+     * archived. It is the desktop's promise that `start-session` for this task
+     * resumes the paused session exactly as its Resume button does: the same
+     * conversation, the column's model, effort and permission, a "Resuming
+     * session..." label, and NO enter automations or column message. Gate a
+     * phone's Resume control on THIS field.
+     *
+     * On the board row because the phone always holds the board: a desktop
+     * pause clears the task's `session_id`, so a phone keeps no read-stream on
+     * a paused session (the stream's `resumable` covers only an open session
+     * screen through the suspend itself). A pause, a resume, a column move and
+     * an archive each reach the phone as a `task-updated` board event, after
+     * which the next snapshot carries the new value. Under `view: 'sessions'` a
+     * resumable task is kept even though its `session_id` is null, so an agent
+     * feed can draw it as Paused with a Resume control.
+     *
+     * Explicit on purpose, never inferred from another field: a pre-0.16.0
+     * desktop answers `start-session` by STARTING the column, which re-runs its
+     * enter automations and resends its message (a paused task in Code Review
+     * would get `/code-review` again). Null or absent means such a desktop; a
+     * client offers no Resume then. While `spawn_progress` is non-null a spawn
+     * is already in flight and the desktop card shows that label instead of a
+     * Resume control; a client applies the same precedence. `start-session`
+     * re-checks the column and refuses a To Do, Done or archived task with the
+     * desktop's Resume copy, so a value overtaken by a move is safe to act on.
+     * A paused task that offers no Resume reads false here. From 0.17.0 `paused`
+     * tells it apart from a task with no paused session.
+     *
+     * Declared OPTIONAL (`?`) like `spawns_session`; `parseBoardTaskWire`
+     * populates the key from every real wire response.
+     */
+    resumable?: boolean | null;
+    /**
+     * True when the task has a paused session (a `suspended` session that is not
+     * a Command Terminal) and no live one. No column or archive gate applies. It
+     * is the fact the desktop card's "Paused" footer reads, so a paused task in
+     * Done or on the archived page reads true here while `resumable` reads
+     * false. A move into To Do removes the task's session rows, so a task there
+     * normally reads false. Gate Resume on `resumable` only; `resumable: true`
+     * always comes with `paused: true`.
+     *
+     * A desktop pause clears the task's `session_id`, so find a paused session
+     * from this field, not from `session_id`. A respawn queued behind the
+     * desktop's concurrency limit leaves the task holding a paused session and a
+     * queued one; that task reads false, as the desktop card shows the queued
+     * session. While `spawn_progress` is non-null the desktop card shows that
+     * label instead of "Paused"; a client applies the same precedence.
+     *
+     * Under `view: 'sessions'` a paused task that offers no Resume stays out of
+     * the snapshot, because an agent feed has nothing to act on for it. Null or
+     * absent means a desktop that predates the field (pre-0.17.0); a client
+     * then reads a paused task from `resumable` alone, as before.
+     *
+     * Declared OPTIONAL (`?`) like `resumable`; `parseBoardTaskWire` populates
+     * the key from every real wire response.
+     */
+    paused?: boolean | null;
 }
 /** Phone-needed subset of the desktop's BacklogTask row. */
 export interface BacklogItemWire {

package/dist/index.cjs

@@ -75,6 +75,7 @@ __export(index_exports, {
   isDoneRole: () => isDoneRole,
   isJsonValue: () => isJsonValue,
   isPushCategory: () => isPushCategory,
+  isReadStreamSessionStatusWire: () => isReadStreamSessionStatusWire,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
   isSecureRelayAddress: () => isSecureRelayAddress,
@@ -5462,7 +5463,10 @@ function parseBoardTaskWire(value) {
     attachment_count: typeof value.attachment_count === "number" ? value.attachment_count : 0,
     archived_at: nullableString(value, "archived_at"),
     created_at: requireString(value, "created_at", "board task"),
-    updated_at: requireString(value, "updated_at", "board task")
+    updated_at: requireString(value, "updated_at", "board task"),
+    spawn_progress: nullableString(value, "spawn_progress"),
+    resumable: nullableBoolean(value, "resumable"),
+    paused: nullableBoolean(value, "paused")
   };
 }
 function parseBacklogItemWire(value) {
@@ -5514,6 +5518,9 @@ function parseDiffFileContentWire(payload) {
 
 // src/wire/payloads.ts
 var READ_STREAM_SESSION_STATUSES = ["running", "queued", "suspended", "exited"];
+function isReadStreamSessionStatusWire(value) {
+  return typeof value === "string" && READ_STREAM_SESSION_STATUSES.includes(value);
+}
 function parseReadStreamResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-stream response must be an object");
   if (typeof payload.scrollback !== "string") throw new Error('read-stream response is missing "scrollback"');
@@ -5544,11 +5551,19 @@ function parseReadStreamResponsePayload(payload) {
     response.ptyDimensions = parseTerminalDimensionsWire(payload.ptyDimensions);
   }
   if (payload.sessionStatus !== void 0) {
-    if (typeof payload.sessionStatus !== "string" || !READ_STREAM_SESSION_STATUSES.includes(payload.sessionStatus)) {
+    if (!isReadStreamSessionStatusWire(payload.sessionStatus)) {
       throw new Error('read-stream response has an invalid "sessionStatus"');
     }
     response.sessionStatus = payload.sessionStatus;
   }
+  if (payload.resuming !== void 0) {
+    if (typeof payload.resuming !== "boolean") throw new Error('read-stream response has an invalid "resuming"');
+    response.resuming = payload.resuming;
+  }
+  if (payload.resumable !== void 0) {
+    if (typeof payload.resumable !== "boolean") throw new Error('read-stream response has an invalid "resumable"');
+    response.resumable = payload.resumable;
+  }
   return response;
 }
 function parseTranscriptWindowResponsePayload(payload) {
@@ -6116,11 +6131,24 @@ function parseActivityEventPayload(payload) {
     }
     case "session-ended": {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
-      if (payload.spawnProgressLabel === void 0) {
-        return { type: "session-ended", intentional: payload.intentional };
+      if (payload.spawnProgressLabel !== void 0 && typeof payload.spawnProgressLabel !== "string") {
+        throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
+      }
+      if (payload.successorSessionId !== void 0 && typeof payload.successorSessionId !== "string") {
+        throw new Error('session-ended payload has an invalid "successorSessionId"');
       }
-      if (typeof payload.spawnProgressLabel !== "string") throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
-      return { type: "session-ended", intentional: payload.intentional, spawnProgressLabel: payload.spawnProgressLabel };
+      return {
+        type: "session-ended",
+        intentional: payload.intentional,
+        ...payload.spawnProgressLabel !== void 0 ? { spawnProgressLabel: payload.spawnProgressLabel } : {},
+        ...payload.successorSessionId !== void 0 ? { successorSessionId: payload.successorSessionId } : {}
+      };
+    }
+    case "status": {
+      if (!isReadStreamSessionStatusWire(payload.status)) throw new Error('status payload has an invalid "status"');
+      if (typeof payload.resuming !== "boolean") throw new Error('status payload is missing "resuming"');
+      if (typeof payload.resumable !== "boolean") throw new Error('status payload is missing "resumable"');
+      return { type: "status", status: payload.status, resuming: payload.resuming, resumable: payload.resumable };
     }
     case "message-preview": {
       if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
@@ -6235,6 +6263,7 @@ function isBridgeEvent(value) {
   isDoneRole,
   isJsonValue,
   isPushCategory,
+  isReadStreamSessionStatusWire,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessa
 export { encodeMessage, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD, } from './wire/framing';
 export { isJsonValue, isRecord } from './wire/json-value';
 export { SessionFrameKind, wrapSessionFrame, unwrapSessionFrame } from './wire/session-frame';
-export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, parseStartSessionResponsePayload, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectGroup, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, type ReadBoardArchivedResponsePayload, type ReadBoardResponsePayload, type ReadDiffScope, type ReadDiffRequestPayload, type ReadDiffResponsePayload, type SendUserMessageRequestPayload, type SendUserMessageResponsePayload, type MoveTaskRequestPayload, type MoveTaskResponsePayload, type AnswerPermissionPromptRequestPayload, type AnswerPermissionPromptResponsePayload, type InteractiveTerminalRequestPayload, type InteractiveTerminalResponsePayload, type BoardToolRequestPayload, type BoardToolResponsePayload, type RegisterPushRequestPayload, type RegisterPushResponsePayload, type StartSessionRequestPayload, type StartSessionResponsePayload, type StartSessionOutcome, } from './wire/payloads';
+export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, parseStartSessionResponsePayload, isReadStreamSessionStatusWire, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectGroup, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, type ReadBoardArchivedResponsePayload, type ReadBoardResponsePayload, type ReadDiffScope, type ReadDiffRequestPayload, type ReadDiffResponsePayload, type SendUserMessageRequestPayload, type SendUserMessageResponsePayload, type MoveTaskRequestPayload, type MoveTaskResponsePayload, type AnswerPermissionPromptRequestPayload, type AnswerPermissionPromptResponsePayload, type InteractiveTerminalRequestPayload, type InteractiveTerminalResponsePayload, type BoardToolRequestPayload, type BoardToolResponsePayload, type RegisterPushRequestPayload, type RegisterPushResponsePayload, type StartSessionRequestPayload, type StartSessionResponsePayload, type StartSessionOutcome, } from './wire/payloads';
 export { PUSH_CATEGORIES, isPushCategory, parsePushEnvelopePlaintext, sealPushEnvelope, openPushEnvelope, PUSH_ENVELOPE_MAX_AGE_MS, PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS, type PushCategory, type PushEnvelopePlaintext, } from './crypto/push-envelope';
 export { PAIRING_URI_SCHEME, encodePairingQrPayload, decodePairingQrPayload, type PairingQrPayload, } from './pairing/qr';
 export { sealPairingConfirm, openPairingConfirm } from './pairing/confirm';

package/dist/index.mjs

@@ -5337,7 +5337,10 @@ function parseBoardTaskWire(value) {
     attachment_count: typeof value.attachment_count === "number" ? value.attachment_count : 0,
     archived_at: nullableString(value, "archived_at"),
     created_at: requireString(value, "created_at", "board task"),
-    updated_at: requireString(value, "updated_at", "board task")
+    updated_at: requireString(value, "updated_at", "board task"),
+    spawn_progress: nullableString(value, "spawn_progress"),
+    resumable: nullableBoolean(value, "resumable"),
+    paused: nullableBoolean(value, "paused")
   };
 }
 function parseBacklogItemWire(value) {
@@ -5389,6 +5392,9 @@ function parseDiffFileContentWire(payload) {
 
 // src/wire/payloads.ts
 var READ_STREAM_SESSION_STATUSES = ["running", "queued", "suspended", "exited"];
+function isReadStreamSessionStatusWire(value) {
+  return typeof value === "string" && READ_STREAM_SESSION_STATUSES.includes(value);
+}
 function parseReadStreamResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-stream response must be an object");
   if (typeof payload.scrollback !== "string") throw new Error('read-stream response is missing "scrollback"');
@@ -5419,11 +5425,19 @@ function parseReadStreamResponsePayload(payload) {
     response.ptyDimensions = parseTerminalDimensionsWire(payload.ptyDimensions);
   }
   if (payload.sessionStatus !== void 0) {
-    if (typeof payload.sessionStatus !== "string" || !READ_STREAM_SESSION_STATUSES.includes(payload.sessionStatus)) {
+    if (!isReadStreamSessionStatusWire(payload.sessionStatus)) {
       throw new Error('read-stream response has an invalid "sessionStatus"');
     }
     response.sessionStatus = payload.sessionStatus;
   }
+  if (payload.resuming !== void 0) {
+    if (typeof payload.resuming !== "boolean") throw new Error('read-stream response has an invalid "resuming"');
+    response.resuming = payload.resuming;
+  }
+  if (payload.resumable !== void 0) {
+    if (typeof payload.resumable !== "boolean") throw new Error('read-stream response has an invalid "resumable"');
+    response.resumable = payload.resumable;
+  }
   return response;
 }
 function parseTranscriptWindowResponsePayload(payload) {
@@ -5991,11 +6005,24 @@ function parseActivityEventPayload(payload) {
     }
     case "session-ended": {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
-      if (payload.spawnProgressLabel === void 0) {
-        return { type: "session-ended", intentional: payload.intentional };
+      if (payload.spawnProgressLabel !== void 0 && typeof payload.spawnProgressLabel !== "string") {
+        throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
+      }
+      if (payload.successorSessionId !== void 0 && typeof payload.successorSessionId !== "string") {
+        throw new Error('session-ended payload has an invalid "successorSessionId"');
       }
-      if (typeof payload.spawnProgressLabel !== "string") throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
-      return { type: "session-ended", intentional: payload.intentional, spawnProgressLabel: payload.spawnProgressLabel };
+      return {
+        type: "session-ended",
+        intentional: payload.intentional,
+        ...payload.spawnProgressLabel !== void 0 ? { spawnProgressLabel: payload.spawnProgressLabel } : {},
+        ...payload.successorSessionId !== void 0 ? { successorSessionId: payload.successorSessionId } : {}
+      };
+    }
+    case "status": {
+      if (!isReadStreamSessionStatusWire(payload.status)) throw new Error('status payload has an invalid "status"');
+      if (typeof payload.resuming !== "boolean") throw new Error('status payload is missing "resuming"');
+      if (typeof payload.resumable !== "boolean") throw new Error('status payload is missing "resumable"');
+      return { type: "status", status: payload.status, resuming: payload.resuming, resumable: payload.resumable };
     }
     case "message-preview": {
       if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
@@ -6109,6 +6136,7 @@ export {
   isDoneRole,
   isJsonValue,
   isPushCategory,
+  isReadStreamSessionStatusWire,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,

package/dist/wire/payloads.d.ts

@@ -53,6 +53,8 @@ export interface ReadStreamRequestPayload {
  * snapshot races the session's teardown.
  */
 export type ReadStreamSessionStatusWire = 'running' | 'queued' | 'suspended' | 'exited';
+/** True for a value that is one of the four session lifecycle statuses. */
+export declare function isReadStreamSessionStatusWire(value: unknown): value is ReadStreamSessionStatusWire;
 /** Initial snapshot returned on subscribe; live updates arrive as TerminalEvent/ActivityEvent/TranscriptEvent. */
 export interface ReadStreamResponsePayload {
     scrollback: string;
@@ -80,9 +82,34 @@ export interface ReadStreamResponsePayload {
     ptyDimensions?: TerminalDimensionsWire;
     /**
      * The session's lifecycle status at snapshot time. Absent from
-     * pre-0.5.0 desktops; the phone then assumes 'running'.
+     * pre-0.5.0 desktops; the phone then assumes 'running'. Later changes for
+     * the same session id arrive as the `status` activity payload.
      */
     sessionStatus?: ReadStreamSessionStatusWire;
+    /**
+     * True when the desktop spawned this session as a resume of an earlier
+     * conversation. The desktop card then reads "Resuming agent..." where it
+     * would read "Starting agent...", for as long as a running session has no
+     * model name yet. Fixed for the life of a session id. Absent from pre-0.16.0
+     * desktops; read absent as false.
+     */
+    resuming?: boolean;
+    /**
+     * The streamed session's copy of `BoardTaskWire.resumable`: true when this
+     * session is paused (`suspended`) and the desktop's own task view would
+     * offer Resume for it. Gate a Resume control on the BOARD ROW's field, not
+     * this one: a desktop pause clears the task's `session_id`, so a phone holds
+     * no stream on a paused session once its board refreshes. This copy keeps a
+     * session screen that is open during the suspend current until then, and it
+     * carries the same promise: `start-session` resumes rather than starts.
+     *
+     * Recomputed on each lifecycle edge of this session, and a `status` push
+     * carries it even when it is the only value that changed. A move to Done or
+     * an archive of a paused task is no edge of its row, so this copy can stay
+     * true after the board row's turns false. Absent from pre-0.16.0 desktops,
+     * which a client reads as "offer no Resume".
+     */
+    resumable?: boolean;
 }
 /** Phone-side narrowing of a read-stream subscribe response. Throws on a malformed required field. */
 export declare function parseReadStreamResponsePayload(payload: JsonValue): ReadStreamResponsePayload;
@@ -105,7 +132,12 @@ export declare function parseTranscriptWindowResponsePayload(payload: JsonValue)
  * - 'sessions': columns, per-column task counts, and only the non-archived
  *   tasks that carry a `session_id`. This is what an agent feed renders: it
  *   watches every project at once but only ever draws the handful of tasks
- *   with a live agent on them.
+ *   with a live agent on them. From 0.16.0 it also keeps a task with a
+ *   `spawn_progress` label in flight (a first start, or a respawn that has
+ *   nulled `session_id`) and a `resumable` paused task (a desktop pause
+ *   nulls `session_id` too), so the feed can draw "Paused" with a Resume.
+ *   A paused task that offers no Resume (in Done, say) stays out even though
+ *   its row reads `paused: true` from 0.17.0 (see `BoardTaskWire.paused`).
  * - 'full': every non-archived task, for the one project whose board the user
  *   actually has open.
  *
@@ -195,7 +227,7 @@ export interface ReadBoardProjectListResponsePayload {
 export interface ReadBoardSnapshotResponsePayload {
     projectId: string;
     columns: BoardColumnWire[];
-    /** Non-archived tasks; filtered to the ones carrying a `session_id` when `view` is 'sessions'. */
+    /** Non-archived tasks; filtered when `view` is 'sessions' (see ReadBoardView for which tasks it keeps). */
     tasks: BoardTaskWire[];
     /** Absent whenever the request carried a `view` (protocol 0.9.0) - no phone has ever rendered it. */
     backlog?: BacklogItemWire[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Kangentic mobile bridge wire protocol: framing, Noise-based pairing and session handshakes, signed device roster, and capability verbs shared between desktop and mobile.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",