@kangentic/protocol 0.8.0 → 0.10.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,8 +13,8 @@
  * 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", "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 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", "list_board_profiles", "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_board_profile", "update_board_profile", "delete_board_profile", "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];
 export type BoardToolName = BoardToolReadName | BoardToolWriteName;

package/dist/events/payloads.d.ts

@@ -167,6 +167,44 @@ export interface SessionUsageWire {
         effort?: string;
     };
 }
+/**
+ * Phone-needed subset of the desktop's SessionSummary: what a task COST over
+ * its whole life, as opposed to SessionUsageWire's live snapshot of one
+ * running agent.
+ *
+ * Every figure is a lifetime aggregate across every session record of the
+ * task, which is what makes it meaningful for a completed one: a task worked
+ * across five `--resume` legs has five session rows, and reporting only the
+ * final leg would under-report everything. The desktop's getSummaryForTask
+ * owns those aggregation rules (SUM cost/duration/tool calls/lines, MAX files
+ * changed, and tokens taken as the latest row per session lineage so a
+ * resumed session is not double-counted) - they are not re-derived here.
+ *
+ * `sessionId` is the transcript ANCHOR, not a live session: it resolves
+ * through the desktop's session records, which outlive the agent, so it reads
+ * a finished task's conversation with nothing running. An archived task's
+ * `session_id` on the board is null by then, so this is the only handle to it.
+ */
+export interface SessionSummaryWire {
+    sessionId: string;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    modelDisplayName: string;
+    durationMs: number;
+    toolCallCount: number;
+    compactionCount: number;
+    linesAdded: number;
+    linesRemoved: number;
+    filesChanged: number;
+    /** ISO 8601. The task's creation, which is where its timeline starts. */
+    taskCreatedAt: string;
+    /** ISO 8601. Earliest session start across every leg. */
+    startedAt: string;
+    /** ISO 8601, or null while a leg is still open. Latest exit or suspend. */
+    exitedAt: string | null;
+    exitCode: number | null;
+}
 /**
  * Loose mirror of the desktop's SessionEvent telemetry entry. `type` is
  * deliberately a plain string, not the desktop's EventType enum, so a new
@@ -267,6 +305,16 @@ export declare function isActivityStateWire(value: unknown): value is ActivitySt
 export declare function isActivityReasonWire(value: unknown): value is ActivityReasonWire;
 /** Narrows a usage payload to the SessionUsageWire subset. Throws on a malformed required field. */
 export declare function parseSessionUsageWire(payload: JsonValue): SessionUsageWire;
+/**
+ * Narrows a session-summary payload to SessionSummaryWire. Throws on a
+ * malformed required field.
+ *
+ * The numeric metrics are required rather than optional because the desktop
+ * COALESCEs each to 0 before it sends them, so "no data" arrives as a real
+ * zero. Making them optional here would invite a phone to render an em-dash
+ * where the honest answer is 0.
+ */
+export declare function parseSessionSummaryWire(payload: JsonValue): SessionSummaryWire;
 /** Narrows a session-event payload to SessionEventWire. Throws on a malformed required field. */
 export declare function parseSessionEventWire(payload: JsonValue): SessionEventWire;
 /** Narrows one board-column row. Throws on a malformed required field. */

package/dist/index.cjs

@@ -58,6 +58,7 @@ __export(index_exports, {
   encodeProtocolVersion: () => encodeProtocolVersion,
   encodeRosterEntryForSigning: () => encodeRosterEntryForSigning,
   findRosterDevice: () => findRosterDevice,
+  formatKeyFingerprint: () => formatKeyFingerprint,
   generateEd25519KeyPair: () => generateEd25519KeyPair,
   generateX25519KeyPair: () => generateX25519KeyPair,
   hexToBytes: () => hexToBytes,
@@ -72,6 +73,7 @@ __export(index_exports, {
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
   isSecureRelayAddress: () => isSecureRelayAddress,
+  openPairingConfirm: () => openPairingConfirm,
   openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
   parseBacklogItemWire: () => parseBacklogItemWire,
@@ -86,6 +88,7 @@ __export(index_exports, {
   parseReadStreamResponsePayload: () => parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload: () => parseRegisterPushRequestPayload,
   parseSessionEventWire: () => parseSessionEventWire,
+  parseSessionSummaryWire: () => parseSessionSummaryWire,
   parseSessionUsageWire: () => parseSessionUsageWire,
   parseTerminalDimensionsWire: () => parseTerminalDimensionsWire,
   parseTranscriptEntriesWire: () => parseTranscriptEntriesWire,
@@ -93,6 +96,7 @@ __export(index_exports, {
   parseTranscriptWindowResponsePayload: () => parseTranscriptWindowResponsePayload,
   randomBytes: () => randomBytes4,
   rosterDeviceCapabilitySet: () => rosterDeviceCapabilitySet,
+  sealPairingConfirm: () => sealPairingConfirm,
   sealPushEnvelope: () => sealPushEnvelope,
   signRosterEntry: () => signRosterEntry,
   unwrapSessionFrame: () => unwrapSessionFrame,
@@ -5361,6 +5365,26 @@ function parseSessionUsageWire(payload) {
     }
   };
 }
+function parseSessionSummaryWire(payload) {
+  if (!isRecord(payload)) throw new Error("session summary payload must be an object");
+  return {
+    sessionId: requireString(payload, "sessionId", "session summary"),
+    totalCostUsd: requireNumber(payload, "totalCostUsd", "session summary"),
+    totalInputTokens: requireNumber(payload, "totalInputTokens", "session summary"),
+    totalOutputTokens: requireNumber(payload, "totalOutputTokens", "session summary"),
+    modelDisplayName: requireString(payload, "modelDisplayName", "session summary"),
+    durationMs: requireNumber(payload, "durationMs", "session summary"),
+    toolCallCount: requireNumber(payload, "toolCallCount", "session summary"),
+    compactionCount: requireNumber(payload, "compactionCount", "session summary"),
+    linesAdded: requireNumber(payload, "linesAdded", "session summary"),
+    linesRemoved: requireNumber(payload, "linesRemoved", "session summary"),
+    filesChanged: requireNumber(payload, "filesChanged", "session summary"),
+    taskCreatedAt: requireString(payload, "taskCreatedAt", "session summary"),
+    startedAt: requireString(payload, "startedAt", "session summary"),
+    exitedAt: typeof payload.exitedAt === "string" ? payload.exitedAt : null,
+    exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null
+  };
+}
 function parseSessionEventWire(payload) {
   if (!isRecord(payload)) throw new Error("session event payload must be an object");
   return {
@@ -5563,6 +5587,18 @@ function parseAccentColor(value, context) {
 }
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
+  if (Array.isArray(payload.archivedTasks)) {
+    if (typeof payload.projectId !== "string") throw new Error('read-board archived response is missing "projectId"');
+    if (typeof payload.archivedTotalCount !== "number") {
+      throw new Error('read-board archived response is missing "archivedTotalCount"');
+    }
+    return {
+      projectId: payload.projectId,
+      archivedTasks: payload.archivedTasks.map((task) => parseBoardTaskWire(task)),
+      archivedTotalCount: payload.archivedTotalCount,
+      summariesByTaskId: parseSummariesByTaskId(payload.summariesByTaskId)
+    };
+  }
   if (Array.isArray(payload.projects)) {
     const projects = payload.projects.map((project, index) => {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
@@ -5579,28 +5615,70 @@ 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 parseSummariesByTaskId(value) {
+  if (value === void 0) return {};
+  if (!isRecord(value)) throw new Error('read-board archived response has a non-object "summariesByTaskId"');
+  const summaries = {};
+  for (const [taskId, summary] of Object.entries(value)) {
+    try {
+      summaries[taskId] = parseSessionSummaryWire(summary);
+    } catch {
+    }
+  }
+  return summaries;
+}
 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") {
     throw new Error('read-board payload has a non-string "projectId"');
   }
-  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
+  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe" && payload.action !== "archived") {
     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"');
+  }
+  if (payload.limit !== void 0 && (typeof payload.limit !== "number" || !Number.isInteger(payload.limit) || payload.limit < 1)) {
+    throw new Error('read-board payload has an invalid "limit"');
+  }
+  if (payload.offset !== void 0 && (typeof payload.offset !== "number" || !Number.isInteger(payload.offset) || payload.offset < 0)) {
+    throw new Error('read-board payload has an invalid "offset"');
+  }
+  return {
+    projectId: payload.projectId,
+    action: payload.action,
+    view: payload.view,
+    limit: payload.limit,
+    offset: payload.offset
+  };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5841,6 +5919,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);
@@ -5880,6 +5979,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",
@@ -5891,6 +5999,7 @@ var BOARD_TOOL_READ_NAMES = [
   "list_sessions",
   "get_session_history",
   "get_column_detail",
+  "list_board_profiles",
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
@@ -5904,6 +6013,9 @@ var BOARD_TOOL_WRITE_NAMES = [
   "link_pr",
   "remove_attachment",
   "update_column",
+  "create_board_profile",
+  "update_board_profile",
+  "delete_board_profile",
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
@@ -6041,6 +6153,7 @@ function isBridgeEvent(value) {
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
   findRosterDevice,
+  formatKeyFingerprint,
   generateEd25519KeyPair,
   generateX25519KeyPair,
   hexToBytes,
@@ -6055,6 +6168,7 @@ function isBridgeEvent(value) {
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
@@ -6069,6 +6183,7 @@ function isBridgeEvent(value) {
   parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload,
   parseSessionEventWire,
+  parseSessionSummaryWire,
   parseSessionUsageWire,
   parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,
@@ -6076,6 +6191,7 @@ function isBridgeEvent(value) {
   parseTranscriptWindowResponsePayload,
   randomBytes,
   rosterDeviceCapabilitySet,
+  sealPairingConfirm,
   sealPushEnvelope,
   signRosterEntry,
   unwrapSessionFrame,

package/dist/index.d.ts

@@ -12,13 +12,15 @@ 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 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, } 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';
-export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, 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, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionSummaryWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardTaskWire, 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

@@ -5248,6 +5248,26 @@ function parseSessionUsageWire(payload) {
     }
   };
 }
+function parseSessionSummaryWire(payload) {
+  if (!isRecord(payload)) throw new Error("session summary payload must be an object");
+  return {
+    sessionId: requireString(payload, "sessionId", "session summary"),
+    totalCostUsd: requireNumber(payload, "totalCostUsd", "session summary"),
+    totalInputTokens: requireNumber(payload, "totalInputTokens", "session summary"),
+    totalOutputTokens: requireNumber(payload, "totalOutputTokens", "session summary"),
+    modelDisplayName: requireString(payload, "modelDisplayName", "session summary"),
+    durationMs: requireNumber(payload, "durationMs", "session summary"),
+    toolCallCount: requireNumber(payload, "toolCallCount", "session summary"),
+    compactionCount: requireNumber(payload, "compactionCount", "session summary"),
+    linesAdded: requireNumber(payload, "linesAdded", "session summary"),
+    linesRemoved: requireNumber(payload, "linesRemoved", "session summary"),
+    filesChanged: requireNumber(payload, "filesChanged", "session summary"),
+    taskCreatedAt: requireString(payload, "taskCreatedAt", "session summary"),
+    startedAt: requireString(payload, "startedAt", "session summary"),
+    exitedAt: typeof payload.exitedAt === "string" ? payload.exitedAt : null,
+    exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null
+  };
+}
 function parseSessionEventWire(payload) {
   if (!isRecord(payload)) throw new Error("session event payload must be an object");
   return {
@@ -5450,6 +5470,18 @@ function parseAccentColor(value, context) {
 }
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
+  if (Array.isArray(payload.archivedTasks)) {
+    if (typeof payload.projectId !== "string") throw new Error('read-board archived response is missing "projectId"');
+    if (typeof payload.archivedTotalCount !== "number") {
+      throw new Error('read-board archived response is missing "archivedTotalCount"');
+    }
+    return {
+      projectId: payload.projectId,
+      archivedTasks: payload.archivedTasks.map((task) => parseBoardTaskWire(task)),
+      archivedTotalCount: payload.archivedTotalCount,
+      summariesByTaskId: parseSummariesByTaskId(payload.summariesByTaskId)
+    };
+  }
   if (Array.isArray(payload.projects)) {
     const projects = payload.projects.map((project, index) => {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
@@ -5466,28 +5498,70 @@ 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 parseSummariesByTaskId(value) {
+  if (value === void 0) return {};
+  if (!isRecord(value)) throw new Error('read-board archived response has a non-object "summariesByTaskId"');
+  const summaries = {};
+  for (const [taskId, summary] of Object.entries(value)) {
+    try {
+      summaries[taskId] = parseSessionSummaryWire(summary);
+    } catch {
+    }
+  }
+  return summaries;
+}
 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") {
     throw new Error('read-board payload has a non-string "projectId"');
   }
-  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
+  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe" && payload.action !== "archived") {
     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"');
+  }
+  if (payload.limit !== void 0 && (typeof payload.limit !== "number" || !Number.isInteger(payload.limit) || payload.limit < 1)) {
+    throw new Error('read-board payload has an invalid "limit"');
+  }
+  if (payload.offset !== void 0 && (typeof payload.offset !== "number" || !Number.isInteger(payload.offset) || payload.offset < 0)) {
+    throw new Error('read-board payload has an invalid "offset"');
+  }
+  return {
+    projectId: payload.projectId,
+    action: payload.action,
+    view: payload.view,
+    limit: payload.limit,
+    offset: payload.offset
+  };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5728,6 +5802,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);
@@ -5767,6 +5862,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",
@@ -5778,6 +5882,7 @@ var BOARD_TOOL_READ_NAMES = [
   "list_sessions",
   "get_session_history",
   "get_column_detail",
+  "list_board_profiles",
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
@@ -5791,6 +5896,9 @@ var BOARD_TOOL_WRITE_NAMES = [
   "link_pr",
   "remove_attachment",
   "update_column",
+  "create_board_profile",
+  "update_board_profile",
+  "delete_board_profile",
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
@@ -5927,6 +6035,7 @@ export {
   encodeProtocolVersion,
   encodeRosterEntryForSigning,
   findRosterDevice,
+  formatKeyFingerprint,
   generateEd25519KeyPair,
   generateX25519KeyPair,
   hexToBytes,
@@ -5941,6 +6050,7 @@ export {
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
@@ -5955,6 +6065,7 @@ export {
   parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload,
   parseSessionEventWire,
+  parseSessionSummaryWire,
   parseSessionUsageWire,
   parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,
@@ -5962,6 +6073,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/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

@@ -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 SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
+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';
 export interface ReadStreamRequestPayload {
     sessionId: string;
     /**
@@ -99,10 +99,57 @@ 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';
+    /**
+     * 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.
+     *
+     * 'archived' (protocol 0.10.0) is a one-shot page of the project's COMPLETED
+     * tasks, which no other projection carries: both 'full' and 'sessions' are
+     * built from the desktop's non-archived task list. It is deliberately not a
+     * field on the snapshot, because a board subscription re-snapshots on every
+     * board change - archived tasks would then repeat down the wire forever,
+     * which is the exact bloat the 0.9.0 projections removed. Completed work
+     * changes rarely and is read on demand.
+     */
+    action?: 'subscribe' | 'unsubscribe' | 'archived';
+    /** 'archived' only: page size, newest-archived first. The desktop clamps it. */
+    limit?: number;
+    /** 'archived' only: how many newest to skip, for paging. Defaults to 0. */
+    offset?: number;
+    /**
+     * 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;
@@ -123,8 +170,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;
     /**
@@ -133,9 +182,46 @@ 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>;
+}
+/**
+ * Returned for `action: 'archived'` - one page of a project's completed tasks
+ * (protocol 0.10.0).
+ *
+ * These never appear in a board snapshot: the desktop builds those from its
+ * non-archived task list, so a phone that only ever subscribed has no way to
+ * know a completed task exists at all.
+ */
+export interface ReadBoardArchivedResponsePayload {
+    projectId: string;
+    /** Newest-archived first. At most the requested `limit`. */
+    archivedTasks: BoardTaskWire[];
+    /**
+     * Total archived tasks in the project, NOT the length of the page above.
+     * Drives the column count and tells the phone whether another page exists.
+     */
+    archivedTotalCount: number;
+    /**
+     * Lifetime cost/duration/churn per task id, for the tasks on THIS page that
+     * have recorded metrics. Sparse on purpose: a task archived without ever
+     * running an agent has nothing to summarize and is simply absent, which is
+     * not an error.
+     */
+    summariesByTaskId: Record<string, SessionSummaryWire>;
 }
-export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
-/** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */
+export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload | ReadBoardArchivedResponsePayload;
+/** Phone-side narrowing of a read-board response (project list, board snapshot, or archived page). Throws on a malformed required field. */
 export declare function parseReadBoardResponsePayload(payload: JsonValue): ReadBoardResponsePayload;
 /** 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.8.0",
+  "version": "0.10.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",
@@ -25,6 +25,7 @@
   ],
   "author": {
     "name": "Kangentic",
+    "email": "hello@kangentic.com",
     "url": "https://github.com/Kangentic"
   },
   "license": "AGPL-3.0-only",