@kangentic/protocol 0.7.0 → 0.9.0

package/README.md

@@ -20,7 +20,11 @@ model, and the honest relay-metadata statement.
 - `Noise_KK_25519_ChaChaPoly_BLAKE2s` for ongoing sessions (mutual authentication by construction,
   no trust-on-first-use).
 - A token-bound Noise PSK handshake for the one-time pairing ceremony, confirmed by a Matrix-style
-  short authentication string (SAS) on both screens.
+  short authentication string (SAS) compared on both screens - digits only, no emoji.
+- A sealed pairing-confirm frame (`pairing/confirm.ts`), sent once the human taps Confirm on the
+  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.
 
 This package has not undergone a third-party security audit. Report suspected vulnerabilities

package/dist/capabilities/board-tools.d.ts

@@ -13,7 +13,7 @@
  * this protocol surface honest: a tool renamed or removed desktop-side
  * fails that test instead of silently breaking phones.
  */
-export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events"];
+export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events", "get_activity_intervals"];
 export declare const BOARD_TOOL_WRITE_NAMES: readonly ["create_task", "update_task", "delete_task", "link_pr", "remove_attachment", "update_column", "create_backlog_task", "promote_backlog", "update_backlog_item", "delete_backlog_item"];
 export type BoardToolReadName = (typeof BOARD_TOOL_READ_NAMES)[number];
 export type BoardToolWriteName = (typeof BOARD_TOOL_WRITE_NAMES)[number];

package/dist/events/event.d.ts

@@ -69,6 +69,24 @@ export type ActivityEventPayload = {
  | {
     type: 'session-ended';
     intentional: boolean;
+}
+/**
+ * The agent's most recent assistant message, already collapsed to a short
+ * plain-text preview, pushed whenever it changes.
+ *
+ * A phone's session list renders exactly one line per session. Deriving it
+ * client-side cost a transcript-window request per session (measured 2.3 to
+ * 34.6 KB each, to keep a string under 200 characters) plus 0.7 to 3.8
+ * seconds of desktop work per request. The desktop already resolves the
+ * transcript to compute its delta pushes, so it can carry the line for
+ * free on a feed the phone is receiving anyway.
+ *
+ * Absent from pre-0.8.0 desktops; a phone that sees none should fall back
+ * to whatever it can derive locally rather than showing nothing.
+ */
+ | {
+    type: 'message-preview';
+    text: string;
 };
 export interface ActivityEvent {
     kind: 'activity';

package/dist/events/payloads.d.ts

@@ -115,11 +115,19 @@ export interface TerminalDimensionsWire {
 }
 /** Mirrors the desktop's ActivityState. 'permission' means the agent paused for user approval (incl. AskUserQuestion / ExitPlanMode pauses). */
 export type ActivityStateWire = 'thinking' | 'idle' | 'permission';
-/** Mirrors the desktop's ActivityReason discriminated union. */
+/**
+ * Mirrors the desktop's ActivityReason discriminated union. `since` (epoch ms
+ * the session first needed the user) is optional, additive-field style like
+ * `toolCallCount`/`effort` above: an older phone parsing a payload with the
+ * field missing still validates, and a desktop that has not yet learned a
+ * `since` for a phantom-state edge case can omit it.
+ */
 export type ActivityReasonWire = {
     kind: 'idle';
+    since?: number;
 } | {
     kind: 'permission';
+    since?: number;
 } | {
     kind: 'tool';
     pendingCount: number;

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   KK_PATTERN: () => KK_PATTERN,
   MAX_DECODED_LENGTH: () => MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH: () => MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH: () => MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME: () => PAIRING_URI_SCHEME,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
   PUSH_CATEGORIES: () => PUSH_CATEGORIES,
@@ -57,6 +58,7 @@ __export(index_exports, {
   encodeProtocolVersion: () => encodeProtocolVersion,
   encodeRosterEntryForSigning: () => encodeRosterEntryForSigning,
   findRosterDevice: () => findRosterDevice,
+  formatKeyFingerprint: () => formatKeyFingerprint,
   generateEd25519KeyPair: () => generateEd25519KeyPair,
   generateX25519KeyPair: () => generateX25519KeyPair,
   hexToBytes: () => hexToBytes,
@@ -70,6 +72,8 @@ __export(index_exports, {
   isPushCategory: () => isPushCategory,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
+  isSecureRelayAddress: () => isSecureRelayAddress,
+  openPairingConfirm: () => openPairingConfirm,
   openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
   parseBacklogItemWire: () => parseBacklogItemWire,
@@ -91,6 +95,7 @@ __export(index_exports, {
   parseTranscriptWindowResponsePayload: () => parseTranscriptWindowResponsePayload,
   randomBytes: () => randomBytes4,
   rosterDeviceCapabilitySet: () => rosterDeviceCapabilitySet,
+  sealPairingConfirm: () => sealPairingConfirm,
   sealPushEnvelope: () => sealPushEnvelope,
   signRosterEntry: () => signRosterEntry,
   unwrapSessionFrame: () => unwrapSessionFrame,
@@ -5317,6 +5322,7 @@ function isActivityReasonWire(value) {
   switch (value.kind) {
     case "idle":
     case "permission":
+      return value.since === void 0 || typeof value.since === "number";
     case "turn-active":
       return true;
     case "tool":
@@ -5545,6 +5551,10 @@ function parseReadStreamRequestPayload(payload) {
     }
     request.limit = payload.limit;
   }
+  if (payload.terminal !== void 0) {
+    if (typeof payload.terminal !== "boolean") throw new Error('read-stream payload has an invalid "terminal"');
+    request.terminal = payload.terminal;
+  }
   return request;
 }
 var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
@@ -5572,19 +5582,34 @@ function parseReadBoardResponsePayload(payload) {
   if (typeof payload.projectId !== "string") throw new Error('read-board response is missing "projectId"');
   if (!Array.isArray(payload.columns)) throw new Error('read-board response is missing "columns"');
   if (!Array.isArray(payload.tasks)) throw new Error('read-board response is missing "tasks"');
-  if (!Array.isArray(payload.backlog)) throw new Error('read-board response is missing "backlog"');
+  if (payload.backlog !== void 0 && !Array.isArray(payload.backlog)) {
+    throw new Error('read-board response has a non-array "backlog"');
+  }
   if (payload.showTicketNumbers !== void 0 && typeof payload.showTicketNumbers !== "boolean") {
     throw new Error('read-board response has a non-boolean "showTicketNumbers"');
   }
+  if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
+    throw new Error('read-board response has an invalid "view"');
+  }
   return {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
     tasks: payload.tasks.map((task) => parseBoardTaskWire(task)),
-    backlog: payload.backlog.map((item) => parseBacklogItemWire(item)),
+    ...payload.backlog !== void 0 ? { backlog: payload.backlog.map((item) => parseBacklogItemWire(item)) } : {},
     ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {},
-    ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {}
+    ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {},
+    ...payload.view !== void 0 ? { view: payload.view } : {},
+    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {}
   };
 }
+function parseTaskCountsByColumnId(value) {
+  if (!isRecord(value)) throw new Error('read-board response has a non-object "taskCountsByColumnId"');
+  const counts = {};
+  for (const [columnId, count] of Object.entries(value)) {
+    if (typeof count === "number" && Number.isInteger(count) && count >= 0) counts[columnId] = count;
+  }
+  return counts;
+}
 function parseReadBoardRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board payload must be an object");
   if (payload.projectId !== void 0 && typeof payload.projectId !== "string") {
@@ -5593,7 +5618,10 @@ function parseReadBoardRequestPayload(payload) {
   if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
     throw new Error('read-board payload has an invalid "action"');
   }
-  return { projectId: payload.projectId, action: payload.action };
+  if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
+    throw new Error('read-board payload has an invalid "view"');
+  }
+  return { projectId: payload.projectId, action: payload.action, view: payload.view };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5741,11 +5769,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
+// src/pairing/relay-address.ts
+var MAX_RELAY_ADDRESS_LENGTH = 512;
+var LOOPBACK_WS_PREFIXES = ["ws://localhost", "ws://127.0.0.1", "ws://[::1]"];
+function isSecureRelayAddress(relayAddress) {
+  if (relayAddress.startsWith("wss://")) return true;
+  return LOOPBACK_WS_PREFIXES.some((prefix) => {
+    if (!relayAddress.startsWith(prefix)) return false;
+    const boundaryChar = relayAddress.charAt(prefix.length);
+    return boundaryChar === "" || boundaryChar === ":" || boundaryChar === "/" || boundaryChar === "?" || boundaryChar === "#";
+  });
+}
+
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;
 var PAIRING_TOKEN_LENGTH = 32;
-var MAX_RELAY_ADDRESS_LENGTH = 512;
 var MAX_PAYLOAD_LENGTH = 4096;
 function writeUint32(value) {
   const bytes = new Uint8Array(4);
@@ -5823,6 +5862,27 @@ function decodePairingQrPayload(uri) {
   return { desktopStaticPublicKey, pairingToken, relayAddress, expiresAt, protocolVersion };
 }
 
+// src/pairing/confirm.ts
+var PAIRING_CONFIRM_PLAINTEXT = new TextEncoder().encode("kangentic-pairing-confirm-v1");
+var EMPTY_ASSOCIATED_DATA = new Uint8Array(0);
+function sealPairingConfirm(initiatorToResponder) {
+  return initiatorToResponder.encryptWithAd(EMPTY_ASSOCIATED_DATA, PAIRING_CONFIRM_PLAINTEXT);
+}
+function openPairingConfirm(initiatorToResponder, frame) {
+  let plaintext;
+  try {
+    plaintext = initiatorToResponder.decryptWithAd(EMPTY_ASSOCIATED_DATA, frame);
+  } catch {
+    return false;
+  }
+  if (plaintext.length !== PAIRING_CONFIRM_PLAINTEXT.length) return false;
+  let mismatch = 0;
+  for (let index = 0; index < plaintext.length; index += 1) {
+    mismatch |= plaintext[index] ^ PAIRING_CONFIRM_PLAINTEXT[index];
+  }
+  return mismatch === 0;
+}
+
 // src/roster/roster.ts
 function uint32LengthPrefixed(bytes) {
   const prefix = new Uint8Array(4);
@@ -5862,6 +5922,15 @@ function capabilitySetToRosterCapabilities(capabilities) {
   return capabilitySetToArray(capabilities);
 }
 
+// src/roster/fingerprint.ts
+function formatKeyFingerprint(publicKeyHex, groups = 4) {
+  const clusters = [];
+  for (let index = 0; index < groups; index += 1) {
+    clusters.push(publicKeyHex.slice(index * 4, index * 4 + 4));
+  }
+  return clusters.join(" ");
+}
+
 // src/capabilities/board-tools.ts
 var BOARD_TOOL_READ_NAMES = [
   "search_tasks",
@@ -5876,7 +5945,8 @@ var BOARD_TOOL_READ_NAMES = [
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
-  "get_session_events"
+  "get_session_events",
+  "get_activity_intervals"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -5926,6 +5996,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
       return { type: "session-ended", intentional: payload.intentional };
     }
+    case "message-preview": {
+      if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
+      return { type: "message-preview", text: payload.text };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5992,6 +6066,7 @@ function isBridgeEvent(value) {
   KK_PATTERN,
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
@@ -6017,6 +6092,7 @@ function isBridgeEvent(value) {
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
   findRosterDevice,
+  formatKeyFingerprint,
   generateEd25519KeyPair,
   generateX25519KeyPair,
   hexToBytes,
@@ -6030,6 +6106,8 @@ function isBridgeEvent(value) {
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  isSecureRelayAddress,
+  openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
@@ -6051,6 +6129,7 @@ function isBridgeEvent(value) {
   parseTranscriptWindowResponsePayload,
   randomBytes,
   rosterDeviceCapabilitySet,
+  sealPairingConfirm,
   sealPushEnvelope,
   signRosterEntry,
   unwrapSessionFrame,

package/dist/index.d.ts

@@ -12,10 +12,13 @@ export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessa
 export { encodeMessage, decodeMessage, 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, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardProjectSummary, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, 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, } from './wire/payloads';
+export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, 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, } 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';
+export { MAX_RELAY_ADDRESS_LENGTH, isSecureRelayAddress } from './pairing/relay-address';
 export { signRosterEntry, verifyRosterEntry, encodeRosterEntryForSigning, isRosterEntryExpired, findRosterDevice, rosterDeviceCapabilitySet, capabilitySetToRosterCapabilities, type RosterDeviceEntry, type DeviceRoster, } from './roster/roster';
+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';

package/dist/index.mjs

@@ -5206,6 +5206,7 @@ function isActivityReasonWire(value) {
   switch (value.kind) {
     case "idle":
     case "permission":
+      return value.since === void 0 || typeof value.since === "number";
     case "turn-active":
       return true;
     case "tool":
@@ -5434,6 +5435,10 @@ function parseReadStreamRequestPayload(payload) {
     }
     request.limit = payload.limit;
   }
+  if (payload.terminal !== void 0) {
+    if (typeof payload.terminal !== "boolean") throw new Error('read-stream payload has an invalid "terminal"');
+    request.terminal = payload.terminal;
+  }
   return request;
 }
 var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
@@ -5461,19 +5466,34 @@ function parseReadBoardResponsePayload(payload) {
   if (typeof payload.projectId !== "string") throw new Error('read-board response is missing "projectId"');
   if (!Array.isArray(payload.columns)) throw new Error('read-board response is missing "columns"');
   if (!Array.isArray(payload.tasks)) throw new Error('read-board response is missing "tasks"');
-  if (!Array.isArray(payload.backlog)) throw new Error('read-board response is missing "backlog"');
+  if (payload.backlog !== void 0 && !Array.isArray(payload.backlog)) {
+    throw new Error('read-board response has a non-array "backlog"');
+  }
   if (payload.showTicketNumbers !== void 0 && typeof payload.showTicketNumbers !== "boolean") {
     throw new Error('read-board response has a non-boolean "showTicketNumbers"');
   }
+  if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
+    throw new Error('read-board response has an invalid "view"');
+  }
   return {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
     tasks: payload.tasks.map((task) => parseBoardTaskWire(task)),
-    backlog: payload.backlog.map((item) => parseBacklogItemWire(item)),
+    ...payload.backlog !== void 0 ? { backlog: payload.backlog.map((item) => parseBacklogItemWire(item)) } : {},
     ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {},
-    ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {}
+    ...payload.showTicketNumbers !== void 0 ? { showTicketNumbers: payload.showTicketNumbers } : {},
+    ...payload.view !== void 0 ? { view: payload.view } : {},
+    ...payload.taskCountsByColumnId !== void 0 ? { taskCountsByColumnId: parseTaskCountsByColumnId(payload.taskCountsByColumnId) } : {}
   };
 }
+function parseTaskCountsByColumnId(value) {
+  if (!isRecord(value)) throw new Error('read-board response has a non-object "taskCountsByColumnId"');
+  const counts = {};
+  for (const [columnId, count] of Object.entries(value)) {
+    if (typeof count === "number" && Number.isInteger(count) && count >= 0) counts[columnId] = count;
+  }
+  return counts;
+}
 function parseReadBoardRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board payload must be an object");
   if (payload.projectId !== void 0 && typeof payload.projectId !== "string") {
@@ -5482,7 +5502,10 @@ function parseReadBoardRequestPayload(payload) {
   if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
     throw new Error('read-board payload has an invalid "action"');
   }
-  return { projectId: payload.projectId, action: payload.action };
+  if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
+    throw new Error('read-board payload has an invalid "view"');
+  }
+  return { projectId: payload.projectId, action: payload.action, view: payload.view };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5630,11 +5653,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
+// src/pairing/relay-address.ts
+var MAX_RELAY_ADDRESS_LENGTH = 512;
+var LOOPBACK_WS_PREFIXES = ["ws://localhost", "ws://127.0.0.1", "ws://[::1]"];
+function isSecureRelayAddress(relayAddress) {
+  if (relayAddress.startsWith("wss://")) return true;
+  return LOOPBACK_WS_PREFIXES.some((prefix) => {
+    if (!relayAddress.startsWith(prefix)) return false;
+    const boundaryChar = relayAddress.charAt(prefix.length);
+    return boundaryChar === "" || boundaryChar === ":" || boundaryChar === "/" || boundaryChar === "?" || boundaryChar === "#";
+  });
+}
+
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;
 var PAIRING_TOKEN_LENGTH = 32;
-var MAX_RELAY_ADDRESS_LENGTH = 512;
 var MAX_PAYLOAD_LENGTH = 4096;
 function writeUint32(value) {
   const bytes = new Uint8Array(4);
@@ -5712,6 +5746,27 @@ function decodePairingQrPayload(uri) {
   return { desktopStaticPublicKey, pairingToken, relayAddress, expiresAt, protocolVersion };
 }
 
+// src/pairing/confirm.ts
+var PAIRING_CONFIRM_PLAINTEXT = new TextEncoder().encode("kangentic-pairing-confirm-v1");
+var EMPTY_ASSOCIATED_DATA = new Uint8Array(0);
+function sealPairingConfirm(initiatorToResponder) {
+  return initiatorToResponder.encryptWithAd(EMPTY_ASSOCIATED_DATA, PAIRING_CONFIRM_PLAINTEXT);
+}
+function openPairingConfirm(initiatorToResponder, frame) {
+  let plaintext;
+  try {
+    plaintext = initiatorToResponder.decryptWithAd(EMPTY_ASSOCIATED_DATA, frame);
+  } catch {
+    return false;
+  }
+  if (plaintext.length !== PAIRING_CONFIRM_PLAINTEXT.length) return false;
+  let mismatch = 0;
+  for (let index = 0; index < plaintext.length; index += 1) {
+    mismatch |= plaintext[index] ^ PAIRING_CONFIRM_PLAINTEXT[index];
+  }
+  return mismatch === 0;
+}
+
 // src/roster/roster.ts
 function uint32LengthPrefixed(bytes) {
   const prefix = new Uint8Array(4);
@@ -5751,6 +5806,15 @@ function capabilitySetToRosterCapabilities(capabilities) {
   return capabilitySetToArray(capabilities);
 }
 
+// src/roster/fingerprint.ts
+function formatKeyFingerprint(publicKeyHex, groups = 4) {
+  const clusters = [];
+  for (let index = 0; index < groups; index += 1) {
+    clusters.push(publicKeyHex.slice(index * 4, index * 4 + 4));
+  }
+  return clusters.join(" ");
+}
+
 // src/capabilities/board-tools.ts
 var BOARD_TOOL_READ_NAMES = [
   "search_tasks",
@@ -5765,7 +5829,8 @@ var BOARD_TOOL_READ_NAMES = [
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
-  "get_session_events"
+  "get_session_events",
+  "get_activity_intervals"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -5815,6 +5880,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
       return { type: "session-ended", intentional: payload.intentional };
     }
+    case "message-preview": {
+      if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
+      return { type: "message-preview", text: payload.text };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5880,6 +5949,7 @@ export {
   KK_PATTERN,
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
@@ -5905,6 +5975,7 @@ export {
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
   findRosterDevice,
+  formatKeyFingerprint,
   generateEd25519KeyPair,
   generateX25519KeyPair,
   hexToBytes,
@@ -5918,6 +5989,8 @@ export {
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  isSecureRelayAddress,
+  openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
@@ -5939,6 +6012,7 @@ export {
   parseTranscriptWindowResponsePayload,
   randomBytes4 as randomBytes,
   rosterDeviceCapabilitySet,
+  sealPairingConfirm,
   sealPushEnvelope,
   signRosterEntry,
   unwrapSessionFrame,

package/dist/pairing/confirm.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The pairing-confirm frame: one AEAD-sealed message the phone sends after
+ * the human taps Confirm, over the transport key the completed IKpsk0
+ * handshake just produced (HandshakeState.writeMessage's `split` result -
+ * see pairing-handshake.ts). This is a LIVENESS AND INTENT signal, not the
+ * pairing's security boundary: a relay-in-the-middle already holds a valid
+ * session with the desktop and could forge any frame it wants. The actual
+ * defense is unchanged - the human compares the desktop's SAS digits
+ * against the phone's, and only taps Confirm on a match.
+ *
+ * What this frame buys instead: both peers derive their transport keys
+ * from the SAME completed handshake transcript (getHandshakeHash/split are
+ * both functions of the transcript), so if the sealed frame opens under the
+ * desktop's key, the two transcripts necessarily agree - which means the
+ * SAS the human compared necessarily agreed too. The AEAD open IS the
+ * desktop's SAS verification; that is why the frame carries no digits of
+ * its own, and why a failed open is treated as a mismatch/failure, not a
+ * silent no-op.
+ *
+ * There is no reject frame. Backing out of the ceremony on the phone closes
+ * the transport without sending this frame; close-without-confirm is the
+ * rejection, observed by the desktop as its pairing timeout (see
+ * pairing-service.ts's phase timers).
+ */
+import { CipherState } from '../crypto/noise/cipher-state';
+/**
+ * Seals the confirm frame under the initiator-to-responder cipher state
+ * (index 0 of HandshakeState's `split` pair, by Noise Protocol Framework
+ * convention). Called once per ceremony, so nonce reuse under this key is
+ * not a concern - the key itself is fresh per handshake transcript.
+ */
+export declare function sealPairingConfirm(initiatorToResponder: CipherState): Uint8Array;
+/**
+ * Opens a received confirm frame. Returns false (never throws) on a
+ * tampered/wrong-key ciphertext or an unexpected plaintext, so the caller
+ * can treat "could not verify" uniformly whether the failure was
+ * cryptographic or structural.
+ */
+export declare function openPairingConfirm(initiatorToResponder: CipherState, frame: Uint8Array): boolean;

package/dist/pairing/qr.d.ts

@@ -1,3 +1,4 @@
+export { MAX_RELAY_ADDRESS_LENGTH, isSecureRelayAddress } from './relay-address';
 export declare const PAIRING_URI_SCHEME = "kangentic-pair";
 export interface PairingQrPayload {
     desktopStaticPublicKey: Uint8Array;

package/dist/pairing/relay-address.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Relay address rules shared, byte-for-byte, with the mobile app's
+ * src/pairing/qr.ts. This module imports nothing on purpose: it is
+ * deep-imported by the desktop's src/shared/relay.ts, which the RENDERER
+ * bundles, and pulling in the rest of this package (crypto/primitives ->
+ * @noble/*) would drag Noise crypto into that bundle for no reason. Keep it
+ * dependency-free.
+ */
+export declare const MAX_RELAY_ADDRESS_LENGTH = 512;
+/**
+ * True if the phone's pairing QR scanner will accept this relay address.
+ * wss:// is always secure; ws:// is accepted only for loopback, since the
+ * pairing token doubles as the Noise PSK and is dialed verbatim as
+ * `?slot=`. Prefix-based (not hostname-based) with an explicit boundary
+ * check, so `ws://localhost.evil.com` - a hostname that merely starts with
+ * the string "localhost" - is rejected rather than treated as loopback.
+ */
+export declare function isSecureRelayAddress(relayAddress: string): boolean;

package/dist/roster/fingerprint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formats a device's static public key as a short, human-comparable
+ * fingerprint - the identity the pairing ceremony actually bound and the
+ * SAS actually confirmed, unlike a name (not unique) or a hardware id
+ * (unavailable on modern Android, permanent PII). Matches
+ * kangentic-mobile's src/screens/usePairedDesktopInfo.ts formatKeyFingerprint
+ * exactly, so a user can hold the phone next to the desktop and compare
+ * directly: front-only slice, no ellipsis, no case change.
+ */
+export declare function formatKeyFingerprint(publicKeyHex: string, groups?: number): string;

package/dist/wire/payloads.d.ts

@@ -32,6 +32,20 @@ export interface ReadStreamRequestPayload {
     beforeIndex?: number;
     /** transcript-window only: maximum entries wanted (the desktop may cap this and may return fewer). */
     limit?: number;
+    /**
+     * subscribe only: whether this subscription wants live PTY bytes.
+     *
+     * A phone watching its session list needs activity, permission and
+     * transcript pushes, but NOT the terminal - it discards those bytes on
+     * arrival. Measured on a live board, that discard cost roughly 13MB an hour
+     * of relay traffic and mobile data for a feed showing no terminal at all.
+     *
+     * Omitted means true, so an older phone keeps the previous behaviour and an
+     * older desktop that ignores the field simply keeps sending (wasteful, not
+     * broken). Set false for a list-only subscription and re-subscribe with it
+     * true when a terminal actually opens.
+     */
+    terminal?: boolean;
 }
 /**
  * Mirrors the desktop's SessionStatus. 'suspended' is a registered-but-
@@ -85,10 +99,41 @@ export interface TranscriptWindowResponsePayload {
 }
 /** Phone-side narrowing of a transcript-window response. Throws on a malformed required field. */
 export declare function parseTranscriptWindowResponsePayload(payload: JsonValue): TranscriptWindowResponsePayload;
+/**
+ * Which projection of a board the phone wants.
+ *
+ * - '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.
+ * - 'full': every non-archived task, for the one project whose board the user
+ *   actually has open.
+ *
+ * Neither carries the backlog. Sending the field at all is the signal that
+ * this phone tolerates a response without one; a phone that omits it gets the
+ * pre-0.9.0 payload unchanged.
+ */
+export type ReadBoardView = 'full' | 'sessions';
 export interface ReadBoardRequestPayload {
     projectId?: string;
     /** Defaults to 'subscribe' when omitted. 'unsubscribe' only has an effect when projectId is set - the no-projectId project list is a one-shot read with no live feed to tear down. */
     action?: 'subscribe' | 'unsubscribe';
+    /**
+     * subscribe only: the projection wanted (protocol 0.9.0). Omitted means the
+     * legacy full board WITH the backlog.
+     *
+     * Measured on a 15-project desktop, the full boards were 63 kB compressed
+     * of a ~96 kB cold start, of which 23 kB was a backlog no phone has ever
+     * rendered and another 30 kB was tasks with no session on them. Worse, a
+     * board subscription re-snapshots on every board change, so that payload
+     * repeats for as long as the phone is connected. The 'sessions' projection
+     * is 12 kB for the same 15 projects.
+     *
+     * A pre-0.9.0 desktop ignores the field and returns a full board with no
+     * `view` echo, which is exactly how a 0.9.0 phone detects that it must not
+     * treat the snapshot as filtered.
+     */
+    view?: ReadBoardView;
 }
 export interface ReadBoardProjectSummary {
     id: string;
@@ -109,8 +154,10 @@ 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'. */
     tasks: BoardTaskWire[];
-    backlog: BacklogItemWire[];
+    /** Absent whenever the request carried a `view` (protocol 0.9.0) - no phone has ever rendered it. */
+    backlog?: BacklogItemWire[];
     /** The project's accent color ("#rrggbb"); same semantics as ReadBoardProjectSummary.color. Absent from pre-0.5.0 desktops. */
     projectColor?: string;
     /**
@@ -119,6 +166,18 @@ export interface ReadBoardSnapshotResponsePayload {
      * true, the desktop default).
      */
     showTicketNumbers?: boolean;
+    /**
+     * The projection actually applied, echoed back. Absent from a pre-0.9.0
+     * desktop, which always sends a full board - so treat an absent `view` as
+     * 'full', never as "filtered, unknown how".
+     */
+    view?: ReadBoardView;
+    /**
+     * Non-archived task count per column id, sent with a 'sessions' view because
+     * `tasks` is filtered and a count taken from it would be wrong. Appending a
+     * card to a column needs the real length.
+     */
+    taskCountsByColumnId?: Record<string, number>;
 }
 export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
 /** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */

package/package.json

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