@kangentic/protocol 0.18.0 → 0.20.0

package/README.md

@@ -25,7 +25,9 @@ model, and the honest relay-metadata statement.
   phone: it is a liveness/intent signal, not the security boundary. It opens only if both peers
   completed the same handshake transcript, which is exactly the property the SAS comparison
   already vouches for - the human's comparison remains the actual defense.
-- No shell, file, or arbitrary-command verb exists in the protocol.
+- No shell, file, or arbitrary-command verb exists in the protocol. `command-terminal` starts the
+  project's agent CLI at the project root with no command, branch, or model named by the phone, and
+  the desktop ends the session when that agent exits.
 
 This package has not undergone a third-party security audit. Report suspected vulnerabilities
 per the repository's security policy rather than filing a public issue.

package/dist/capabilities/verbs.d.ts

@@ -23,8 +23,16 @@
  * session exactly as the desktop's Pause button does, without moving the task,
  * and keeps the conversation for a later `start-session` Resume. Gate it on
  * `BoardTaskWire.pausable`.
+ *
+ * `command-terminal` starts or stops a Command Terminal: an AGENT CLI the
+ * desktop launches at a project's root, the same session the desktop's
+ * Ctrl+Shift+P terminal runs. It is not a shell verb. The phone names no
+ * command, branch, model or effort, and the desktop ends the session when its
+ * agent exits, so no bare shell is left behind for `interactive-terminal` to
+ * reach. Stop accepts only a Command Terminal's session. Gate the phone's
+ * Terminals button on `ReadBoardSnapshotResponsePayload.commandTerminalsOffered`.
  */
-export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write", "register-push", "start-session", "pause-session"];
+export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write", "register-push", "start-session", "pause-session", "command-terminal"];
 export type CapabilityVerb = (typeof CAPABILITY_VERBS)[number];
 export declare function isCapabilityVerb(value: string): value is CapabilityVerb;
 /** Deny-by-default: a verb absent from the set is not authorized. */

package/dist/crypto/push-envelope.d.ts

@@ -5,6 +5,15 @@ export declare function isPushCategory(value: unknown): value is PushCategory;
 export declare const PUSH_ENVELOPE_MAX_AGE_MS: number;
 /** Tolerated forward clock skew; anything claiming to be further in the future is rejected. */
 export declare const PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS: number;
+/**
+ * What kind of session a notification is about, when it is not a task's
+ * agent (protocol 0.20.0). `command-terminal`: a Command Terminal, so the tap
+ * opens that terminal's screen by `sessionId` (its `taskId` names no board
+ * task) and `taskTitle` carries the terminal's name.
+ */
+export declare const PUSH_SESSION_KINDS: readonly ["command-terminal"];
+export type PushSessionKind = (typeof PUSH_SESSION_KINDS)[number];
+export declare function isPushSessionKind(value: unknown): value is PushSessionKind;
 /**
  * The real notification content, visible only on the sealing desktop and
  * the opening device. Everything the OS-visible push payload carries
@@ -15,10 +24,13 @@ export interface PushEnvelopePlaintext {
     projectId: string;
     taskId: string;
     sessionId: string;
+    /** The task's title, or for a `command-terminal` session the terminal's name. */
     taskTitle: string;
     detail: string;
     /** Wall-clock ms at seal time; openPushEnvelope enforces the freshness window from it. */
     sentAt: number;
+    /** Absent for a task's agent. See PUSH_SESSION_KINDS. */
+    sessionKind?: PushSessionKind;
 }
 /** Narrows a decrypted envelope's JSON to PushEnvelopePlaintext. Throws on any malformed field. */
 export declare function parsePushEnvelopePlaintext(value: unknown): PushEnvelopePlaintext;

package/dist/events/event.d.ts

@@ -198,8 +198,20 @@ export interface TerminalResizeEvent {
     /** The PTY's new grid; every terminal byte sent after this event is laid out for it. */
     payload: TerminalDimensionsWire;
 }
+/**
+ * `command-terminals-changed` (protocol 0.20.0): one of the project's Command
+ * Terminals started, ended, or was named. `ids` holds the terminal's session id
+ * and the envelope carries no `taskId`, since a Command Terminal belongs to no
+ * task. The phone re-reads `commandTerminals` from the next snapshot. A change
+ * of activity does not fire it: the terminal's state and reason ride its own
+ * `read-stream` activity events, as a task agent's do, and the snapshot's
+ * `CommandTerminalWire.activity` covers the first paint.
+ *
+ * The union is closed, so a phone built before a kind existed drops that event
+ * (`isBridgeEvent` returns false) and keeps the rest of its feed.
+ */
 export interface BoardEventPayload {
-    change: 'task-created' | 'task-updated' | 'task-deleted' | 'swimlane-updated' | 'backlog-changed';
+    change: 'task-created' | 'task-updated' | 'task-deleted' | 'swimlane-updated' | 'backlog-changed' | 'command-terminals-changed';
     ids: string[];
 }
 export interface BoardEvent {
@@ -208,9 +220,15 @@ export interface BoardEvent {
     taskId?: string;
     payload: BoardEventPayload;
 }
+/**
+ * "Re-read the diff." A task's diff names its `taskId`. A project-folder diff
+ * (a `read-diff` request with no `taskId`, protocol 0.20.0, for a Command
+ * Terminal's Changes tab) names its `projectId` instead. Exactly one is set.
+ */
 export interface DiffEvent {
     kind: 'diff';
-    taskId: string;
+    taskId?: string;
+    projectId?: string;
     payload: null;
 }
 export type BridgeEvent = TranscriptEvent | ActivityEvent | TerminalEvent | TerminalResizeEvent | BoardEvent | DiffEvent;

package/dist/events/payloads.d.ts

@@ -466,6 +466,35 @@ export interface BoardTaskWire {
      */
     pausable?: boolean | null;
 }
+/**
+ * One live Command Terminal of a project (protocol 0.20.0): an agent the
+ * desktop runs at the project root with no task, started from the desktop's
+ * Ctrl+Shift+P layer or by a phone's `command-terminal` start. It is listed
+ * beside a project's tasks in a read-board snapshot (`commandTerminals`), and
+ * the Agents feed draws it with a "Command Terminal" pill.
+ *
+ * - `slot` is the terminal's durable number in its project, 1 to 4. It never
+ *   renumbers while siblings start and stop.
+ * - `name` is what to show: the terminal's own name once it has one, else
+ *   "Command Terminal N". `named` is true once it has its own name (the
+ *   desktop derives one from the first prompt), which is when the phone's
+ *   session header adds its pill.
+ * - `activity` is the raw state and reason, the same shape `read-stream`
+ *   reports, so the phone formats the line ("Running Bash", "Awaiting
+ *   permission") with the formatter it already uses for a task's agent. Both
+ *   are null until the desktop's activity engine has classified the session.
+ */
+export interface CommandTerminalWire {
+    sessionId: string;
+    projectId: string;
+    slot: number;
+    name: string;
+    named: boolean;
+    activity: {
+        state: ActivityStateWire | null;
+        reason: ActivityReasonWire | null;
+    };
+}
 /** Phone-needed subset of the desktop's BacklogTask row. */
 export interface BacklogItemWire {
     id: string;
@@ -535,6 +564,12 @@ export declare function parseSessionEventWire(payload: JsonValue): SessionEventW
 export declare function parseBoardColumnWire(value: JsonValue): BoardColumnWire;
 /** Narrows one board-task row. Throws on a malformed required field. */
 export declare function parseBoardTaskWire(value: JsonValue): BoardTaskWire;
+/**
+ * Narrows one Command Terminal row. Throws on a malformed required field. An
+ * unrecognized activity state or reason reads as null rather than throwing, so
+ * a reason kind a newer desktop adds costs the line, not the whole snapshot.
+ */
+export declare function parseCommandTerminalWire(value: JsonValue): CommandTerminalWire;
 /** Narrows one backlog-item row. Throws on a malformed required field. */
 export declare function parseBacklogItemWire(value: JsonValue): BacklogItemWire;
 /** Narrows a read-diff file-list payload. Throws on a malformed required field. */

package/dist/index.cjs

@@ -20,10 +20,13 @@ var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: tr
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENT_UNAVAILABLE_ERROR_CODE: () => AGENT_UNAVAILABLE_ERROR_CODE,
   BOARD_COLUMN_ROLES: () => BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES: () => BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES: () => BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS: () => CAPABILITY_VERBS,
+  COMMAND_TERMINAL_LIMIT_ERROR_CODE: () => COMMAND_TERMINAL_LIMIT_ERROR_CODE,
+  COMMAND_TERMINAL_START_FAILED_ERROR_CODE: () => COMMAND_TERMINAL_START_FAILED_ERROR_CODE,
   COMPRESSION_THRESHOLD: () => COMPRESSION_THRESHOLD,
   CipherState: () => CipherState,
   ED25519_KEY_LENGTH: () => ED25519_KEY_LENGTH,
@@ -34,13 +37,18 @@ __export(index_exports, {
   MAX_DECODED_LENGTH: () => MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH: () => MAX_FRAME_LENGTH,
   MAX_RELAY_ADDRESS_LENGTH: () => MAX_RELAY_ADDRESS_LENGTH,
+  NOT_COMMAND_TERMINAL_ERROR_CODE: () => NOT_COMMAND_TERMINAL_ERROR_CODE,
   PAIRING_URI_SCHEME: () => PAIRING_URI_SCHEME,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
   PUSH_CATEGORIES: () => PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS: () => PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS: () => PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  PUSH_SESSION_KINDS: () => PUSH_SESSION_KINDS,
+  RESPONSE_TOO_LARGE_ERROR_CODE: () => RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState: () => SecretstreamState,
   SessionFrameKind: () => SessionFrameKind,
+  UNKNOWN_PROJECT_ERROR_CODE: () => UNKNOWN_PROJECT_ERROR_CODE,
+  UNKNOWN_SESSION_ERROR_CODE: () => UNKNOWN_SESSION_ERROR_CODE,
   UNSUPPORTED_VERB_ERROR_CODE: () => UNSUPPORTED_VERB_ERROR_CODE,
   UnsupportedVerbError: () => UnsupportedVerbError,
   X25519_KEY_LENGTH: () => X25519_KEY_LENGTH,
@@ -58,6 +66,7 @@ __export(index_exports, {
   deriveSessionSlotId: () => deriveSessionSlotId,
   deriveShortAuthenticationString: () => deriveShortAuthenticationString,
   encodeMessage: () => encodeMessage,
+  encodeMessageFailure: () => encodeMessageFailure,
   encodePairingQrPayload: () => encodePairingQrPayload,
   encodeProtocolVersion: () => encodeProtocolVersion,
   encodeRosterEntryForSigning: () => encodeRosterEntryForSigning,
@@ -75,6 +84,7 @@ __export(index_exports, {
   isDoneRole: () => isDoneRole,
   isJsonValue: () => isJsonValue,
   isPushCategory: () => isPushCategory,
+  isPushSessionKind: () => isPushSessionKind,
   isReadStreamSessionStatusWire: () => isReadStreamSessionStatusWire,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
@@ -88,6 +98,8 @@ __export(index_exports, {
   parseBoardColumnWire: () => parseBoardColumnWire,
   parseBoardTaskWire: () => parseBoardTaskWire,
   parseCapabilityRequestPayload: () => parseCapabilityRequestPayload,
+  parseCommandTerminalStartResponsePayload: () => parseCommandTerminalStartResponsePayload,
+  parseCommandTerminalWire: () => parseCommandTerminalWire,
   parseDiffFileContentWire: () => parseDiffFileContentWire,
   parseDiffFileListWire: () => parseDiffFileListWire,
   parsePauseSessionResponsePayload: () => parsePauseSessionResponsePayload,
@@ -4973,7 +4985,8 @@ var CAPABILITY_VERBS = [
   "board-tool-write",
   "register-push",
   "start-session",
-  "pause-session"
+  "pause-session",
+  "command-terminal"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -5010,6 +5023,13 @@ var FRAME_FORMAT_DEFLATE = 1;
 var JSON_OPEN_BRACE = 123;
 var DEFLATE_HEADER_LENGTH = 5;
 var UNSUPPORTED_VERB_ERROR_CODE = "unsupported-verb";
+var RESPONSE_TOO_LARGE_ERROR_CODE = "response-too-large";
+var UNKNOWN_PROJECT_ERROR_CODE = "unknown-project";
+var UNKNOWN_SESSION_ERROR_CODE = "unknown-session";
+var COMMAND_TERMINAL_LIMIT_ERROR_CODE = "command-terminal-limit";
+var NOT_COMMAND_TERMINAL_ERROR_CODE = "not-command-terminal";
+var AGENT_UNAVAILABLE_ERROR_CODE = "agent-unavailable";
+var COMMAND_TERMINAL_START_FAILED_ERROR_CODE = "command-terminal-start-failed";
 var UNSUPPORTED_VERB_ERROR_NAME = "UnsupportedVerbError";
 var UnsupportedVerbError = class extends Error {
   requestId;
@@ -5046,6 +5066,15 @@ function encodeMessage(message) {
   }
   return frame;
 }
+function encodeMessageFailure(message) {
+  try {
+    if (new TextEncoder().encode(JSON.stringify(message)).length <= MAX_FRAME_LENGTH) return null;
+    encodeMessage(message);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
 function decodeMessage(bytes) {
   if (bytes.length > MAX_FRAME_LENGTH) {
     throw new Error(`Bridge message frame exceeds ${MAX_FRAME_LENGTH} bytes`);
@@ -5088,7 +5117,11 @@ function validateEvent(event) {
       return event;
     }
     case "diff": {
-      if (typeof event.taskId !== "string") throw new Error('"diff" event is missing "taskId"');
+      if (event.taskId !== void 0 && typeof event.taskId !== "string") throw new Error('"diff" event has a non-string "taskId"');
+      if (event.projectId !== void 0 && typeof event.projectId !== "string") throw new Error('"diff" event has a non-string "projectId"');
+      if (event.taskId === void 0 === (event.projectId === void 0)) {
+        throw new Error('"diff" event must carry exactly one of "taskId" and "projectId"');
+      }
       return event;
     }
     default:
@@ -5201,6 +5234,10 @@ function isPushCategory(value) {
 }
 var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
 var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+var PUSH_SESSION_KINDS = ["command-terminal"];
+function isPushSessionKind(value) {
+  return typeof value === "string" && PUSH_SESSION_KINDS.includes(value);
+}
 function requireEnvelopeString(record, field) {
   const value = record[field];
   if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
@@ -5219,7 +5256,10 @@ function parsePushEnvelopePlaintext(value) {
     sessionId: requireEnvelopeString(value, "sessionId"),
     taskTitle: requireEnvelopeString(value, "taskTitle"),
     detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
+    sentAt: value.sentAt,
+    // An unknown kind (from a newer desktop) is dropped, not rejected, so the
+    // notification still opens; the tap then routes as a task's would.
+    ...isPushSessionKind(value.sessionKind) ? { sessionKind: value.sessionKind } : {}
   };
 }
 function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
@@ -5472,6 +5512,21 @@ function parseBoardTaskWire(value) {
     pausable: nullableBoolean(value, "pausable")
   };
 }
+function parseCommandTerminalWire(value) {
+  if (!isRecord(value)) throw new Error("command terminal must be an object");
+  const activity = isRecord(value.activity) ? value.activity : {};
+  return {
+    sessionId: requireString(value, "sessionId", "command terminal"),
+    projectId: requireString(value, "projectId", "command terminal"),
+    slot: requireNumber(value, "slot", "command terminal"),
+    name: requireString(value, "name", "command terminal"),
+    named: requireBoolean(value, "named", "command terminal"),
+    activity: {
+      state: isActivityStateWire(activity.state) ? activity.state : null,
+      reason: isActivityReasonWire(activity.reason) ? activity.reason : null
+    }
+  };
+}
 function parseBacklogItemWire(value) {
   if (!isRecord(value)) throw new Error("backlog item must be an object");
   return {
@@ -5664,6 +5719,12 @@ function parseReadBoardResponsePayload(payload) {
   if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
     throw new Error('read-board response has an invalid "view"');
   }
+  if (payload.commandTerminals !== void 0 && !Array.isArray(payload.commandTerminals)) {
+    throw new Error('read-board response has a non-array "commandTerminals"');
+  }
+  if (payload.commandTerminalsOffered !== void 0 && typeof payload.commandTerminalsOffered !== "boolean") {
+    throw new Error('read-board response has a non-boolean "commandTerminalsOffered"');
+  }
   return {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
@@ -5672,7 +5733,9 @@ function parseReadBoardResponsePayload(payload) {
     ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {},
     ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {},
     ...payload.view !== void 0 ? { view: payload.view } : {},
-    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {}
+    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {},
+    ...payload.commandTerminals !== void 0 ? { commandTerminals: payload.commandTerminals.map((terminal) => parseCommandTerminalWire(terminal)) } : {},
+    ...payload.commandTerminalsOffered !== void 0 ? { commandTerminalsOffered: payload.commandTerminalsOffered } : {}
   };
 }
 function parseTaskCountsByColumnId(value) {
@@ -5726,7 +5789,7 @@ function parseReadDiffResponsePayload(payload) {
 }
 function parseReadDiffRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff payload must be an object");
-  if (typeof payload.taskId !== "string") throw new Error('read-diff payload missing "taskId"');
+  if (payload.taskId !== void 0 && typeof payload.taskId !== "string") throw new Error('read-diff payload has a non-string "taskId"');
   if (typeof payload.projectId !== "string") throw new Error('read-diff payload missing "projectId"');
   if (payload.filePath !== void 0 && typeof payload.filePath !== "string") {
     throw new Error('read-diff payload has a non-string "filePath"');
@@ -5738,7 +5801,7 @@ function parseReadDiffRequestPayload(payload) {
     throw new Error('read-diff payload has an invalid "action"');
   }
   return {
-    taskId: payload.taskId,
+    ...payload.taskId !== void 0 ? { taskId: payload.taskId } : {},
     projectId: payload.projectId,
     filePath: payload.filePath,
     scope: payload.scope,
@@ -5790,6 +5853,28 @@ function parsePauseSessionRequestPayload(payload) {
     projectId: payload.projectId
   };
 }
+function parseCommandTerminalRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("command-terminal payload must be an object");
+  if (payload.action === "start") {
+    if (typeof payload.projectId !== "string") throw new Error('command-terminal start payload missing "projectId"');
+    return { action: "start", projectId: payload.projectId };
+  }
+  if (payload.action === "stop") {
+    if (typeof payload.sessionId !== "string") throw new Error('command-terminal stop payload missing "sessionId"');
+    return { action: "stop", sessionId: payload.sessionId };
+  }
+  throw new Error('command-terminal payload has an invalid "action"');
+}
+function parseCommandTerminalStartResponsePayload(payload) {
+  if (!isRecord(payload)) throw new Error("command-terminal start response must be an object");
+  if (payload.ok !== true) throw new Error('command-terminal start response missing "ok"');
+  if (typeof payload.sessionId !== "string") throw new Error('command-terminal start response missing "sessionId"');
+  if (typeof payload.slot !== "number" || !Number.isInteger(payload.slot) || payload.slot < 1) {
+    throw new Error('command-terminal start response has an invalid "slot"');
+  }
+  if (typeof payload.name !== "string") throw new Error('command-terminal start response missing "name"');
+  return { ok: true, sessionId: payload.sessionId, slot: payload.slot, name: payload.name };
+}
 function parsePauseSessionResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("pause-session response must be an object");
   if (typeof payload.ok !== "boolean") throw new Error('pause-session response missing "ok"');
@@ -5894,6 +5979,8 @@ function parseCapabilityRequestPayload(verb, payload) {
       return parseStartSessionRequestPayload(payload);
     case "pause-session":
       return parsePauseSessionRequestPayload(payload);
+    case "command-terminal":
+      return parseCommandTerminalRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -6124,7 +6211,14 @@ function isBoardToolWriteName(value) {
 }
 
 // src/events/event.ts
-var BOARD_CHANGES = ["task-created", "task-updated", "task-deleted", "swimlane-updated", "backlog-changed"];
+var BOARD_CHANGES = [
+  "task-created",
+  "task-updated",
+  "task-deleted",
+  "swimlane-updated",
+  "backlog-changed",
+  "command-terminals-changed"
+];
 function parseActivityEventPayload(payload) {
   if (!isRecord(payload)) throw new Error("activity payload must be an object");
   switch (payload.type) {
@@ -6219,18 +6313,27 @@ function isBridgeEvent(value) {
       if (typeof change !== "string" || !BOARD_CHANGES.includes(change)) return false;
       return Array.isArray(value.payload.ids) && value.payload.ids.every((id) => typeof id === "string");
     }
-    case "diff":
-      return typeof value.taskId === "string" && value.payload === null;
+    case "diff": {
+      if (value.payload !== null) return false;
+      const hasTaskId = typeof value.taskId === "string";
+      const hasProjectId = typeof value.projectId === "string";
+      if (value.taskId !== void 0 && !hasTaskId) return false;
+      if (value.projectId !== void 0 && !hasProjectId) return false;
+      return hasTaskId !== hasProjectId;
+    }
     default:
       return false;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_UNAVAILABLE_ERROR_CODE,
   BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
+  COMMAND_TERMINAL_LIMIT_ERROR_CODE,
+  COMMAND_TERMINAL_START_FAILED_ERROR_CODE,
   COMPRESSION_THRESHOLD,
   CipherState,
   ED25519_KEY_LENGTH,
@@ -6241,13 +6344,18 @@ function isBridgeEvent(value) {
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
   MAX_RELAY_ADDRESS_LENGTH,
+  NOT_COMMAND_TERMINAL_ERROR_CODE,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  PUSH_SESSION_KINDS,
+  RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState,
   SessionFrameKind,
+  UNKNOWN_PROJECT_ERROR_CODE,
+  UNKNOWN_SESSION_ERROR_CODE,
   UNSUPPORTED_VERB_ERROR_CODE,
   UnsupportedVerbError,
   X25519_KEY_LENGTH,
@@ -6265,6 +6373,7 @@ function isBridgeEvent(value) {
   deriveSessionSlotId,
   deriveShortAuthenticationString,
   encodeMessage,
+  encodeMessageFailure,
   encodePairingQrPayload,
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
@@ -6282,6 +6391,7 @@ function isBridgeEvent(value) {
   isDoneRole,
   isJsonValue,
   isPushCategory,
+  isPushSessionKind,
   isReadStreamSessionStatusWire,
   isRecord,
   isRosterEntryExpired,
@@ -6295,6 +6405,8 @@ function isBridgeEvent(value) {
   parseBoardColumnWire,
   parseBoardTaskWire,
   parseCapabilityRequestPayload,
+  parseCommandTerminalStartResponsePayload,
+  parseCommandTerminalWire,
   parseDiffFileContentWire,
   parseDiffFileListWire,
   parsePauseSessionResponsePayload,

package/dist/index.d.ts

@@ -9,11 +9,11 @@ export { SecretstreamState, deriveSecretstreamPair, FrameTag, type SecretstreamD
 export { deriveShortAuthenticationString, type ShortAuthenticationString } from './crypto/sas';
 export { deriveSessionSlotId, derivePairingSlotId } from './crypto/slot';
 export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessage, CapabilityResponseMessage, CapabilityErrorCode, EventMessage } from './wire/messages';
-export { encodeMessage, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD, } from './wire/framing';
+export { encodeMessage, encodeMessageFailure, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, RESPONSE_TOO_LARGE_ERROR_CODE, UNKNOWN_PROJECT_ERROR_CODE, UNKNOWN_SESSION_ERROR_CODE, COMMAND_TERMINAL_LIMIT_ERROR_CODE, NOT_COMMAND_TERMINAL_ERROR_CODE, AGENT_UNAVAILABLE_ERROR_CODE, COMMAND_TERMINAL_START_FAILED_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, parsePauseSessionResponsePayload, 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, type PauseSessionRequestPayload, type PauseSessionResponsePayload, } 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 { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, parseStartSessionResponsePayload, parsePauseSessionResponsePayload, parseCommandTerminalStartResponsePayload, 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, type PauseSessionRequestPayload, type PauseSessionResponsePayload, type CommandTerminalRequestPayload, type CommandTerminalStartResponsePayload, type CommandTerminalStopResponsePayload, type CommandTerminalResponsePayload, } from './wire/payloads';
+export { PUSH_CATEGORIES, isPushCategory, PUSH_SESSION_KINDS, isPushSessionKind, parsePushEnvelopePlaintext, sealPushEnvelope, openPushEnvelope, PUSH_ENVELOPE_MAX_AGE_MS, PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS, type PushCategory, type PushSessionKind, type PushEnvelopePlaintext, } from './crypto/push-envelope';
 export { PAIRING_URI_SCHEME, encodePairingQrPayload, decodePairingQrPayload, type PairingQrPayload, } from './pairing/qr';
 export { sealPairingConfirm, openPairingConfirm } from './pairing/confirm';
 export { MAX_RELAY_ADDRESS_LENGTH, isSecureRelayAddress } from './pairing/relay-address';
@@ -22,5 +22,5 @@ export { formatKeyFingerprint } from './roster/fingerprint';
 export { CAPABILITY_VERBS, isCapabilityVerb, capabilitySetFromArray, capabilitySetToArray, type CapabilityVerb, type CapabilitySet, } from './capabilities/verbs';
 export { BOARD_TOOL_READ_NAMES, BOARD_TOOL_WRITE_NAMES, isBoardToolReadName, isBoardToolWriteName, type BoardToolReadName, type BoardToolWriteName, type BoardToolName, } from './capabilities/board-tools';
 export { isBridgeEvent, parseActivityEventPayload, type BridgeEvent, type TranscriptEvent, type ActivityEvent, type ActivityEventPayload, type TerminalEvent, type TerminalResizeEvent, type BoardEvent, type BoardEventPayload, type DiffEvent, } from './events/event';
-export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionSummaryWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, isTodoRole, isDoneRole, BOARD_COLUMN_ROLES, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionSummaryWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardColumnRoleWire, type BoardTaskWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
+export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionSummaryWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseCommandTerminalWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, isTodoRole, isDoneRole, BOARD_COLUMN_ROLES, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionSummaryWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardColumnRoleWire, type BoardTaskWire, type CommandTerminalWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
 export type { Transport, TransportState, Unsubscribe } from './transport/transport';

package/dist/index.mjs

@@ -4846,7 +4846,8 @@ var CAPABILITY_VERBS = [
   "board-tool-write",
   "register-push",
   "start-session",
-  "pause-session"
+  "pause-session",
+  "command-terminal"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -4883,6 +4884,13 @@ var FRAME_FORMAT_DEFLATE = 1;
 var JSON_OPEN_BRACE = 123;
 var DEFLATE_HEADER_LENGTH = 5;
 var UNSUPPORTED_VERB_ERROR_CODE = "unsupported-verb";
+var RESPONSE_TOO_LARGE_ERROR_CODE = "response-too-large";
+var UNKNOWN_PROJECT_ERROR_CODE = "unknown-project";
+var UNKNOWN_SESSION_ERROR_CODE = "unknown-session";
+var COMMAND_TERMINAL_LIMIT_ERROR_CODE = "command-terminal-limit";
+var NOT_COMMAND_TERMINAL_ERROR_CODE = "not-command-terminal";
+var AGENT_UNAVAILABLE_ERROR_CODE = "agent-unavailable";
+var COMMAND_TERMINAL_START_FAILED_ERROR_CODE = "command-terminal-start-failed";
 var UNSUPPORTED_VERB_ERROR_NAME = "UnsupportedVerbError";
 var UnsupportedVerbError = class extends Error {
   requestId;
@@ -4919,6 +4927,15 @@ function encodeMessage(message) {
   }
   return frame;
 }
+function encodeMessageFailure(message) {
+  try {
+    if (new TextEncoder().encode(JSON.stringify(message)).length <= MAX_FRAME_LENGTH) return null;
+    encodeMessage(message);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
 function decodeMessage(bytes) {
   if (bytes.length > MAX_FRAME_LENGTH) {
     throw new Error(`Bridge message frame exceeds ${MAX_FRAME_LENGTH} bytes`);
@@ -4961,7 +4978,11 @@ function validateEvent(event) {
       return event;
     }
     case "diff": {
-      if (typeof event.taskId !== "string") throw new Error('"diff" event is missing "taskId"');
+      if (event.taskId !== void 0 && typeof event.taskId !== "string") throw new Error('"diff" event has a non-string "taskId"');
+      if (event.projectId !== void 0 && typeof event.projectId !== "string") throw new Error('"diff" event has a non-string "projectId"');
+      if (event.taskId === void 0 === (event.projectId === void 0)) {
+        throw new Error('"diff" event must carry exactly one of "taskId" and "projectId"');
+      }
       return event;
     }
     default:
@@ -5074,6 +5095,10 @@ function isPushCategory(value) {
 }
 var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
 var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+var PUSH_SESSION_KINDS = ["command-terminal"];
+function isPushSessionKind(value) {
+  return typeof value === "string" && PUSH_SESSION_KINDS.includes(value);
+}
 function requireEnvelopeString(record, field) {
   const value = record[field];
   if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
@@ -5092,7 +5117,10 @@ function parsePushEnvelopePlaintext(value) {
     sessionId: requireEnvelopeString(value, "sessionId"),
     taskTitle: requireEnvelopeString(value, "taskTitle"),
     detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
+    sentAt: value.sentAt,
+    // An unknown kind (from a newer desktop) is dropped, not rejected, so the
+    // notification still opens; the tap then routes as a task's would.
+    ...isPushSessionKind(value.sessionKind) ? { sessionKind: value.sessionKind } : {}
   };
 }
 function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
@@ -5345,6 +5373,21 @@ function parseBoardTaskWire(value) {
     pausable: nullableBoolean(value, "pausable")
   };
 }
+function parseCommandTerminalWire(value) {
+  if (!isRecord(value)) throw new Error("command terminal must be an object");
+  const activity = isRecord(value.activity) ? value.activity : {};
+  return {
+    sessionId: requireString(value, "sessionId", "command terminal"),
+    projectId: requireString(value, "projectId", "command terminal"),
+    slot: requireNumber(value, "slot", "command terminal"),
+    name: requireString(value, "name", "command terminal"),
+    named: requireBoolean(value, "named", "command terminal"),
+    activity: {
+      state: isActivityStateWire(activity.state) ? activity.state : null,
+      reason: isActivityReasonWire(activity.reason) ? activity.reason : null
+    }
+  };
+}
 function parseBacklogItemWire(value) {
   if (!isRecord(value)) throw new Error("backlog item must be an object");
   return {
@@ -5537,6 +5580,12 @@ function parseReadBoardResponsePayload(payload) {
   if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
     throw new Error('read-board response has an invalid "view"');
   }
+  if (payload.commandTerminals !== void 0 && !Array.isArray(payload.commandTerminals)) {
+    throw new Error('read-board response has a non-array "commandTerminals"');
+  }
+  if (payload.commandTerminalsOffered !== void 0 && typeof payload.commandTerminalsOffered !== "boolean") {
+    throw new Error('read-board response has a non-boolean "commandTerminalsOffered"');
+  }
   return {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
@@ -5545,7 +5594,9 @@ function parseReadBoardResponsePayload(payload) {
     ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {},
     ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {},
     ...payload.view !== void 0 ? { view: payload.view } : {},
-    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {}
+    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {},
+    ...payload.commandTerminals !== void 0 ? { commandTerminals: payload.commandTerminals.map((terminal) => parseCommandTerminalWire(terminal)) } : {},
+    ...payload.commandTerminalsOffered !== void 0 ? { commandTerminalsOffered: payload.commandTerminalsOffered } : {}
   };
 }
 function parseTaskCountsByColumnId(value) {
@@ -5599,7 +5650,7 @@ function parseReadDiffResponsePayload(payload) {
 }
 function parseReadDiffRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff payload must be an object");
-  if (typeof payload.taskId !== "string") throw new Error('read-diff payload missing "taskId"');
+  if (payload.taskId !== void 0 && typeof payload.taskId !== "string") throw new Error('read-diff payload has a non-string "taskId"');
   if (typeof payload.projectId !== "string") throw new Error('read-diff payload missing "projectId"');
   if (payload.filePath !== void 0 && typeof payload.filePath !== "string") {
     throw new Error('read-diff payload has a non-string "filePath"');
@@ -5611,7 +5662,7 @@ function parseReadDiffRequestPayload(payload) {
     throw new Error('read-diff payload has an invalid "action"');
   }
   return {
-    taskId: payload.taskId,
+    ...payload.taskId !== void 0 ? { taskId: payload.taskId } : {},
     projectId: payload.projectId,
     filePath: payload.filePath,
     scope: payload.scope,
@@ -5663,6 +5714,28 @@ function parsePauseSessionRequestPayload(payload) {
     projectId: payload.projectId
   };
 }
+function parseCommandTerminalRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("command-terminal payload must be an object");
+  if (payload.action === "start") {
+    if (typeof payload.projectId !== "string") throw new Error('command-terminal start payload missing "projectId"');
+    return { action: "start", projectId: payload.projectId };
+  }
+  if (payload.action === "stop") {
+    if (typeof payload.sessionId !== "string") throw new Error('command-terminal stop payload missing "sessionId"');
+    return { action: "stop", sessionId: payload.sessionId };
+  }
+  throw new Error('command-terminal payload has an invalid "action"');
+}
+function parseCommandTerminalStartResponsePayload(payload) {
+  if (!isRecord(payload)) throw new Error("command-terminal start response must be an object");
+  if (payload.ok !== true) throw new Error('command-terminal start response missing "ok"');
+  if (typeof payload.sessionId !== "string") throw new Error('command-terminal start response missing "sessionId"');
+  if (typeof payload.slot !== "number" || !Number.isInteger(payload.slot) || payload.slot < 1) {
+    throw new Error('command-terminal start response has an invalid "slot"');
+  }
+  if (typeof payload.name !== "string") throw new Error('command-terminal start response missing "name"');
+  return { ok: true, sessionId: payload.sessionId, slot: payload.slot, name: payload.name };
+}
 function parsePauseSessionResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("pause-session response must be an object");
   if (typeof payload.ok !== "boolean") throw new Error('pause-session response missing "ok"');
@@ -5767,6 +5840,8 @@ function parseCapabilityRequestPayload(verb, payload) {
       return parseStartSessionRequestPayload(payload);
     case "pause-session":
       return parsePauseSessionRequestPayload(payload);
+    case "command-terminal":
+      return parseCommandTerminalRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -5997,7 +6072,14 @@ function isBoardToolWriteName(value) {
 }
 
 // src/events/event.ts
-var BOARD_CHANGES = ["task-created", "task-updated", "task-deleted", "swimlane-updated", "backlog-changed"];
+var BOARD_CHANGES = [
+  "task-created",
+  "task-updated",
+  "task-deleted",
+  "swimlane-updated",
+  "backlog-changed",
+  "command-terminals-changed"
+];
 function parseActivityEventPayload(payload) {
   if (!isRecord(payload)) throw new Error("activity payload must be an object");
   switch (payload.type) {
@@ -6092,17 +6174,26 @@ function isBridgeEvent(value) {
       if (typeof change !== "string" || !BOARD_CHANGES.includes(change)) return false;
       return Array.isArray(value.payload.ids) && value.payload.ids.every((id) => typeof id === "string");
     }
-    case "diff":
-      return typeof value.taskId === "string" && value.payload === null;
+    case "diff": {
+      if (value.payload !== null) return false;
+      const hasTaskId = typeof value.taskId === "string";
+      const hasProjectId = typeof value.projectId === "string";
+      if (value.taskId !== void 0 && !hasTaskId) return false;
+      if (value.projectId !== void 0 && !hasProjectId) return false;
+      return hasTaskId !== hasProjectId;
+    }
     default:
       return false;
   }
 }
 export {
+  AGENT_UNAVAILABLE_ERROR_CODE,
   BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
+  COMMAND_TERMINAL_LIMIT_ERROR_CODE,
+  COMMAND_TERMINAL_START_FAILED_ERROR_CODE,
   COMPRESSION_THRESHOLD,
   CipherState,
   ED25519_KEY_LENGTH,
@@ -6113,13 +6204,18 @@ export {
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
   MAX_RELAY_ADDRESS_LENGTH,
+  NOT_COMMAND_TERMINAL_ERROR_CODE,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  PUSH_SESSION_KINDS,
+  RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState,
   SessionFrameKind,
+  UNKNOWN_PROJECT_ERROR_CODE,
+  UNKNOWN_SESSION_ERROR_CODE,
   UNSUPPORTED_VERB_ERROR_CODE,
   UnsupportedVerbError,
   X25519_KEY_LENGTH,
@@ -6137,6 +6233,7 @@ export {
   deriveSessionSlotId,
   deriveShortAuthenticationString,
   encodeMessage,
+  encodeMessageFailure,
   encodePairingQrPayload,
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
@@ -6154,6 +6251,7 @@ export {
   isDoneRole,
   isJsonValue,
   isPushCategory,
+  isPushSessionKind,
   isReadStreamSessionStatusWire,
   isRecord,
   isRosterEntryExpired,
@@ -6167,6 +6265,8 @@ export {
   parseBoardColumnWire,
   parseBoardTaskWire,
   parseCapabilityRequestPayload,
+  parseCommandTerminalStartResponsePayload,
+  parseCommandTerminalWire,
   parseDiffFileContentWire,
   parseDiffFileListWire,
   parsePauseSessionResponsePayload,

package/dist/wire/framing.d.ts

@@ -6,6 +6,20 @@ export declare const MAX_DECODED_LENGTH: number;
 export declare const COMPRESSION_THRESHOLD: number;
 /** The `code` a desktop puts on its refusal of a verb its build does not know. */
 export declare const UNSUPPORTED_VERB_ERROR_CODE: CapabilityErrorCode;
+/** The `code` a desktop puts on its refusal of a response that would not fit the frame caps above. */
+export declare const RESPONSE_TOO_LARGE_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a refusal that named a project this desktop does not have. */
+export declare const UNKNOWN_PROJECT_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a refusal that named a session id that is not live. */
+export declare const UNKNOWN_SESSION_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a `command-terminal` start refused at the per-project cap. */
+export declare const COMMAND_TERMINAL_LIMIT_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a `command-terminal` stop that named a session which is not a Command Terminal. */
+export declare const NOT_COMMAND_TERMINAL_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a start refused because the project's agent CLI is not installed. */
+export declare const AGENT_UNAVAILABLE_ERROR_CODE: CapabilityErrorCode;
+/** The `code` on a `command-terminal` start that failed for any other reason. */
+export declare const COMMAND_TERMINAL_START_FAILED_ERROR_CODE: CapabilityErrorCode;
 /**
  * Thrown by `decodeMessage` for a capability-request whose envelope is
  * well-formed (a string `requestId`, a string `verb`, a JSON `payload`) but
@@ -34,4 +48,17 @@ export declare class UnsupportedVerbError extends Error {
  */
 export declare function isUnsupportedVerbError(error: unknown): error is UnsupportedVerbError;
 export declare function encodeMessage(message: BridgeMessage): Uint8Array;
+/**
+ * Why `encodeMessage` would throw for `message`, or null when it would not,
+ * without keeping the frame. A sender with side effects asks this BEFORE
+ * committing them, so it can send something smaller instead of committing to
+ * a message it cannot send (the desktop re-takes a shorter terminal seed).
+ *
+ * Exact, not an estimate. Raw UTF-8 JSON at or under MAX_FRAME_LENGTH always
+ * fits, because `encodeMessage` only switches to deflate when deflate is
+ * smaller, so that common case costs one stringify. A larger message runs the
+ * real encode, deflate included, and a sender that then sends it pays that
+ * encode a second time. Measured terminal seeds are far under the threshold.
+ */
+export declare function encodeMessageFailure(message: BridgeMessage): string | null;
 export declare function decodeMessage(bytes: Uint8Array): BridgeMessage;

package/dist/wire/messages.d.ts

@@ -32,13 +32,37 @@ export interface CapabilityRequestMessage {
 }
 /**
  * A stable key a client can branch on, beside the human-readable `error`.
- * Today the one member is the refusal a desktop sends for a verb its build
- * does not know (see `UnsupportedVerbError` in framing.ts), so a newer phone
- * can tell "desktop is old" from "desktop is unreachable" and show the right
- * copy. A union rather than a bare string so a second code is a deliberate
- * addition here, not a typo at a call site.
+ * A union rather than a bare string so a new code is a deliberate addition
+ * here, not a typo at a call site.
+ *
+ * - `unsupported-verb`: the desktop's build does not know the verb (see
+ *   `UnsupportedVerbError` in framing.ts), so a newer phone can tell "desktop
+ *   is old" from "desktop is unreachable" and show the right copy.
+ * - `response-too-large`: the answer would not fit the frame caps
+ *   (MAX_DECODED_LENGTH before compression, MAX_FRAME_LENGTH after), so the
+ *   desktop refused instead of sending it. The request was valid and its
+ *   target still exists, so a client must not read it as the target being
+ *   gone (a session ending, a project removed). It is a backstop. A desktop
+ *   shrinks a `read-stream` terminal seed to fit rather than refuse it, so a
+ *   phone's terminal subscribe is never answered with this code.
+ * - `unknown-project`: the request named a project id this desktop does not
+ *   have (removed, or never registered).
+ * - `unknown-session`: the request named a session id that is not live. For a
+ *   `command-terminal` stop it means the terminal already ended, so a phone
+ *   treats it as stopped.
+ * - `command-terminal-limit`: the project already runs the most Command
+ *   Terminals a project may have at once (four).
+ * - `not-command-terminal`: a `command-terminal` stop named a session that is
+ *   not a Command Terminal (a task's agent). Nothing was stopped.
+ * - `agent-unavailable`: the project's agent CLI could not be found on the
+ *   desktop, so nothing could be started.
+ * - `command-terminal-start-failed`: a `command-terminal` start failed for any
+ *   other reason. `error` carries the desktop's text for logs.
+ *
+ * A peer must treat a code it does not know as a generic failure and show
+ * `error` or a plain line of its own: a newer desktop may add codes.
  */
-export type CapabilityErrorCode = 'unsupported-verb';
+export type CapabilityErrorCode = 'unsupported-verb' | 'response-too-large' | 'unknown-project' | 'unknown-session' | 'command-terminal-limit' | 'not-command-terminal' | 'agent-unavailable' | 'command-terminal-start-failed';
 export interface CapabilityResponseMessage {
     type: 'capability-response';
     requestId: string;

package/dist/wire/payloads.d.ts

@@ -16,7 +16,7 @@
 import type { CapabilityVerb } from '../capabilities/verbs';
 import type { JsonValue } from './messages';
 import { type PushCategory } from '../crypto/push-envelope';
-import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionSummaryWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
+import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type CommandTerminalWire, type DiffFileContentWire, type DiffFileListWire, type SessionSummaryWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
 export interface ReadStreamRequestPayload {
     sessionId: string;
     /**
@@ -251,6 +251,20 @@ export interface ReadBoardSnapshotResponsePayload {
      * card to a column needs the real length.
      */
     taskCountsByColumnId?: Record<string, number>;
+    /**
+     * The project's live Command Terminals, ordered by slot (protocol 0.20.0).
+     * Carried by every snapshot view, because the Agents feed lists them beside
+     * every project's task agents. Absent from an older desktop, which has no way
+     * to report them. A `command-terminals-changed` board event says to re-read it.
+     */
+    commandTerminals?: CommandTerminalWire[];
+    /**
+     * True when this desktop serves the `command-terminal` verb AND the device
+     * holds it (protocol 0.20.0). The phone keeps no grant list, so it shows its
+     * Terminals button on this flag, the way `BoardTaskWire.pausable` gates Pause.
+     * Absent from an older desktop: treat that as false.
+     */
+    commandTerminalsOffered?: boolean;
 }
 /**
  * Returned for `action: 'archived'` - one page of a project's completed tasks
@@ -283,7 +297,14 @@ export declare function parseReadBoardResponsePayload(payload: JsonValue): ReadB
 /** Mirrors DiffService's GitDiffScope in the desktop app; kept as a literal union here rather than an import, since the protocol package does not depend on the app. */
 export type ReadDiffScope = 'working' | 'staged' | 'branch';
 export interface ReadDiffRequestPayload {
-    taskId: string;
+    /**
+     * The task whose worktree (or, for a task with none, whose base) to diff.
+     * Optional from protocol 0.20.0: with no `taskId` the desktop diffs the
+     * PROJECT FOLDER against the project's default base branch, exactly as a
+     * Command Terminal window's Changes panel does, and its live pings arrive
+     * as a `DiffEvent` carrying `projectId` instead of `taskId`.
+     */
+    taskId?: string;
     projectId: string;
     filePath?: string;
     scope?: ReadDiffScope;
@@ -363,6 +384,50 @@ export interface PauseSessionRequestPayload {
 export interface PauseSessionResponsePayload {
     ok: boolean;
 }
+/**
+ * Start or stop a Command Terminal (protocol 0.20.0). See `command-terminal` in
+ * capabilities/verbs.ts for what one is.
+ *
+ * `start` names only the project. The desktop picks the slot, runs the
+ * project's default agent with its default model and effort, and starts on the
+ * project's default branch the same way its own New terminal does; there is no
+ * branch, model or effort parameter, and the parser below drops any such key.
+ * `stop` names the terminal's session and is refused for any other session.
+ */
+export type CommandTerminalRequestPayload = {
+    action: 'start';
+    projectId: string;
+} | {
+    action: 'stop';
+    sessionId: string;
+};
+/**
+ * A `start` is answered once the desktop has the session, before the agent has
+ * drawn anything, so the phone opens the terminal's screen at once and its
+ * stream shows the agent arriving. `slot` is the terminal's number in its
+ * project (1 to 4) and `name` its label, "Command Terminal N" until the
+ * desktop names it from its first prompt.
+ *
+ * Refusals carry a `code` on the capability response: `command-terminal-limit`,
+ * `unknown-project`, `agent-unavailable` or `command-terminal-start-failed`.
+ */
+export interface CommandTerminalStartResponsePayload {
+    ok: true;
+    sessionId: string;
+    slot: number;
+    name: string;
+}
+/**
+ * A `stop` is answered once the desktop has ended the terminal. Refusals carry
+ * `unknown-session` (it already ended, so treat it as stopped) or
+ * `not-command-terminal`.
+ */
+export interface CommandTerminalStopResponsePayload {
+    ok: true;
+}
+export type CommandTerminalResponsePayload = CommandTerminalStartResponsePayload | CommandTerminalStopResponsePayload;
+/** Phone-side guard: narrows a decoded `command-terminal` start response before the phone opens the terminal. */
+export declare function parseCommandTerminalStartResponsePayload(payload: JsonValue): CommandTerminalStartResponsePayload;
 /** Phone-side guard: narrows a decoded pause-session response before the phone acts on it. */
 export declare function parsePauseSessionResponsePayload(payload: JsonValue): PauseSessionResponsePayload;
 export interface AnswerPermissionPromptRequestPayload {
@@ -452,6 +517,7 @@ export interface CapabilityRequestPayloadMap {
     'register-push': RegisterPushRequestPayload;
     'start-session': StartSessionRequestPayload;
     'pause-session': PauseSessionRequestPayload;
+    'command-terminal': CommandTerminalRequestPayload;
 }
 export interface CapabilityResponsePayloadMap {
     'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
@@ -466,6 +532,7 @@ export interface CapabilityResponsePayloadMap {
     'register-push': RegisterPushResponsePayload;
     'start-session': StartSessionResponsePayload;
     'pause-session': PauseSessionResponsePayload;
+    'command-terminal': CommandTerminalResponsePayload;
 }
 /**
  * Validates and narrows a decoded capability-request's generic JsonValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.18.0",
+  "version": "0.20.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",