@kangentic/protocol 0.11.1 → 0.13.0

package/dist/crypto/slot.d.ts

@@ -1 +1,17 @@
 export declare function deriveSessionSlotId(desktopStaticPublicKey: Uint8Array, phoneStaticPublicKey: Uint8Array): string;
+/**
+ * Derives the relay rendezvous slot id for the PAIRING ceremony from the
+ * pairing token, for both peers to dial.
+ *
+ * The slot must be derived rather than being the token itself, because it
+ * travels in cleartext in the relay URL's query string while the same token is
+ * the Noise IKpsk0 pre-shared key. Dialing it verbatim published the PSK to
+ * every hop that can read a request URI - on a hosted relay that includes
+ * whatever terminates TLS - which reduced IKpsk0 to plain IK for such an
+ * observer. A one-way labeled hash keeps the routing label public and the PSK
+ * secret: the token itself now never leaves the QR code.
+ *
+ * The result is a routing label, NOT key material. Its 128 bits are sized to
+ * defeat blind enumeration, which is all a rendezvous label has to do.
+ */
+export declare function derivePairingSlotId(pairingToken: Uint8Array): string;

package/dist/events/payloads.d.ts

@@ -217,17 +217,80 @@ export interface SessionEventWire {
     toolId?: string;
     detail?: string;
 }
+/**
+ * The system column roles, mirroring the desktop's `SWIMLANE_ROLES` /
+ * `SwimlaneRole` (`src/shared/types.ts`). This package cannot import that
+ * file (see the module doc), so the two lists are a deliberate mirror, kept
+ * in sync by `tests/unit/protocol/board-column-role-parity.test.ts` on the
+ * desktop side rather than by a shared import.
+ */
+export declare const BOARD_COLUMN_ROLES: readonly ["todo", "done"];
+export type BoardColumnRoleWire = (typeof BOARD_COLUMN_ROLES)[number];
+/** True for a column whose role is the system 'todo' role. Prefer this at a call site over a literal `=== 'todo'`, which the `(string & {})` widening leaves unchecked. */
+export declare function isTodoRole(role: string | null | undefined): boolean;
+/** True for a column whose role is the system 'done' role. Prefer this at a call site over a literal `=== 'done'`, which the `(string & {})` widening leaves unchecked. */
+export declare function isDoneRole(role: string | null | undefined): boolean;
 /** Phone-needed subset of the desktop's Swimlane row (snake_case preserved so the desktop mapper is a mechanical pick). */
 export interface BoardColumnWire {
     id: string;
     name: string;
     description: string | null;
-    role: string | null;
+    /**
+     * `'todo'` / `'done'` are the system roles; anything else (including a
+     * future role this package predates) is a custom or not-yet-known column,
+     * which is exactly what the `(string & {})` escape hatch preserves - the
+     * literal union alone would reject a value a newer desktop legitimately
+     * sends. That widening does NOT make a typo'd comparison a compile error
+     * (a string literal is assignable to `string & {}`), so call sites should
+     * use `isTodoRole` / `isDoneRole` rather than `=== 'todo'` / `=== 'done'`.
+     */
+    role: BoardColumnRoleWire | (string & {}) | null;
     position: number;
     color: string;
     icon: string | null;
     is_archived: boolean;
     is_ghost: boolean;
+    /**
+     * Whether moving a task into this column spawns a successor agent
+     * session, derived desktop-side from the column's `auto_spawn` flag and
+     * role. This is INTENT, not a guarantee:
+     *
+     * - `false` - this column does not intend to spawn. Reliable enough to act
+     *   on ONLY when the column's own `role` is 'todo' or 'done': those two
+     *   produce a full reset or an archive, and a Board Profile cannot change a
+     *   column's role, so a client MAY skip a session-swap transition entirely
+     *   for them. `role` rides this same object, so
+     *   `isTodoRole(column.role) || isDoneRole(column.role)` is how a client
+     *   recognizes that case. A `false` that came from `auto_spawn: false` on
+     *   any other column is intent only, exactly like `true`: a Board Profile
+     *   can set `autoSpawn: true` for one task on that column, and the move
+     *   then does spawn.
+     * - `true` - this column intends to spawn, but a handful of desktop-side
+     *   conditions can suspend the old session without a successor actually
+     *   landing (a board profile disabling auto_spawn for this task, a failed
+     *   worktree checkout that reverts the move, a shutdown or a newer move
+     *   racing this one). A client MUST NOT treat `true` as a promise; keep
+     *   whatever timeout already bounds a session-swap wait and let `true`
+     *   only skip a redundant one.
+     * - `null` / absent - a desktop that predates this field. A client falls
+     *   back to its pre-existing behavior, the same way an absent
+     *   `pr_merge_readiness` reads as "never judged".
+     *
+     * Declared OPTIONAL (`?`) so a hand-built `BoardColumnWire` literal does
+     * not have to list it. `parseBoardColumnWire` populates the key from every
+     * real wire response regardless, so the optionality costs nothing at
+     * runtime. `docs/mobile-bridge.md` records why this differs from
+     * `pr_merge_readiness`, which shipped required.
+     *
+     * Ordering precondition this field depends on: the phone must learn a
+     * MOVE's destination column before the old session's `session-ended`
+     * arrives, or it cannot resolve `spawns_session` against the right column.
+     * That holds today because `handleTaskMove` emits its board-changed event
+     * at the commit point rather than at settle time. See the comment above
+     * `emitBoardChanged()` in `src/main/ipc/handlers/task-move.ts`, and
+     * `docs/mobile-bridge.md`.
+     */
+    spawns_session?: boolean | null;
 }
 /** Phone-needed subset of the desktop's Task row. A non-null `session_id` is the live-session signal the phone's triage view keys on. */
 export interface BoardTaskWire {
@@ -244,6 +307,14 @@ export interface BoardTaskWire {
     pr_number: number | null;
     pr_url: string | null;
     pr_state: string | null;
+    /**
+     * Normalized merge readiness of the linked PR: `ready` / `blocked` /
+     * `conflicting` / `queued` / `running` / `unknown`, or null when never
+     * judged. `queued` and `running` mean a blocking check is still in flight.
+     * Absent from desktops that predate it, which the parser reads as null; a
+     * value a client does not know should render as plain open.
+     */
+    pr_merge_readiness: string | null;
     base_branch: string | null;
     labels: string[];
     priority: number;

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: tr
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  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,
@@ -50,6 +51,7 @@ __export(index_exports, {
   createPairingResponderHandshake: () => createPairingResponderHandshake,
   decodeMessage: () => decodeMessage,
   decodePairingQrPayload: () => decodePairingQrPayload,
+  derivePairingSlotId: () => derivePairingSlotId,
   deriveSecretstreamPair: () => deriveSecretstreamPair,
   deriveSessionSlotId: () => deriveSessionSlotId,
   deriveShortAuthenticationString: () => deriveShortAuthenticationString,
@@ -68,11 +70,13 @@ __export(index_exports, {
   isBoardToolWriteName: () => isBoardToolWriteName,
   isBridgeEvent: () => isBridgeEvent,
   isCapabilityVerb: () => isCapabilityVerb,
+  isDoneRole: () => isDoneRole,
   isJsonValue: () => isJsonValue,
   isPushCategory: () => isPushCategory,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
   isSecureRelayAddress: () => isSecureRelayAddress,
+  isTodoRole: () => isTodoRole,
   openPairingConfirm: () => openPairingConfirm,
   openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
@@ -107,7 +111,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var PROTOCOL_VERSION = "2";
+var PROTOCOL_VERSION = "3";
 function encodeProtocolVersion(version = PROTOCOL_VERSION) {
   return new TextEncoder().encode(`kangentic-bridge-v${version}`);
 }
@@ -4285,6 +4289,11 @@ function deriveSessionSlotId(desktopStaticPublicKey, phoneStaticPublicKey) {
   const material = concatBytes4(desktopStaticPublicKey, phoneStaticPublicKey);
   return bytesToHex(deriveLabeledKey(material, SESSION_SLOT_LABEL, SESSION_SLOT_LENGTH));
 }
+var PAIRING_SLOT_LABEL = "kangentic-pairing-slot-v1";
+var PAIRING_SLOT_LENGTH = 16;
+function derivePairingSlotId(pairingToken) {
+  return bytesToHex(deriveLabeledKey(pairingToken, PAIRING_SLOT_LABEL, PAIRING_SLOT_LENGTH));
+}
 
 // ../../node_modules/fflate/esm/index.mjs
 var import_module = require("module");
@@ -5243,6 +5252,15 @@ function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
 }
 
 // src/events/payloads.ts
+var BOARD_COLUMN_ROLES = ["todo", "done"];
+var TODO_ROLE = "todo";
+var DONE_ROLE = "done";
+function isTodoRole(role) {
+  return role === TODO_ROLE;
+}
+function isDoneRole(role) {
+  return role === DONE_ROLE;
+}
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
 function requireString(record, field, context) {
@@ -5409,18 +5427,26 @@ function nullableNumber(record, field) {
   const value = record[field];
   return typeof value === "number" ? value : null;
 }
+function nullableBoolean(record, field) {
+  const value = record[field];
+  return typeof value === "boolean" ? value : null;
+}
 function parseBoardColumnWire(value) {
   if (!isRecord(value)) throw new Error("board column must be an object");
   return {
     id: requireString(value, "id", "board column"),
     name: requireString(value, "name", "board column"),
     description: nullableString(value, "description"),
+    // An unrecognized role passes through rather than throwing: it is a
+    // custom column (or a future system role this package predates), not a
+    // malformed payload. See the BoardColumnRoleWire doc comment.
     role: nullableString(value, "role"),
     position: requireNumber(value, "position", "board column"),
     color: requireString(value, "color", "board column"),
     icon: nullableString(value, "icon"),
     is_archived: requireBoolean(value, "is_archived", "board column"),
-    is_ghost: requireBoolean(value, "is_ghost", "board column")
+    is_ghost: requireBoolean(value, "is_ghost", "board column"),
+    spawns_session: nullableBoolean(value, "spawns_session")
   };
 }
 function parseBoardTaskWire(value) {
@@ -5439,6 +5465,7 @@ function parseBoardTaskWire(value) {
     pr_number: nullableNumber(value, "pr_number"),
     pr_url: nullableString(value, "pr_url"),
     pr_state: nullableString(value, "pr_state"),
+    pr_merge_readiness: nullableString(value, "pr_merge_readiness"),
     base_branch: nullableString(value, "base_branch"),
     labels: Array.isArray(value.labels) ? parseStringArray(value.labels, "board task labels") : [],
     priority: typeof value.priority === "number" ? value.priority : 0,
@@ -6140,6 +6167,7 @@ function isBridgeEvent(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
@@ -6170,6 +6198,7 @@ function isBridgeEvent(value) {
   createPairingResponderHandshake,
   decodeMessage,
   decodePairingQrPayload,
+  derivePairingSlotId,
   deriveSecretstreamPair,
   deriveSessionSlotId,
   deriveShortAuthenticationString,
@@ -6188,11 +6217,13 @@ function isBridgeEvent(value) {
   isBoardToolWriteName,
   isBridgeEvent,
   isCapabilityVerb,
+  isDoneRole,
   isJsonValue,
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  isTodoRole,
   openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { createKKHandshake, type KKHandshakeOptions } from './crypto/noise/kk';
 export { createPairingInitiatorHandshake, createPairingResponderHandshake, type PairingInitiatorOptions, type PairingResponderOptions, } from './crypto/pairing-handshake';
 export { SecretstreamState, deriveSecretstreamPair, FrameTag, type SecretstreamDirectionPair, } from './crypto/secretstream';
 export { deriveShortAuthenticationString, type ShortAuthenticationString } from './crypto/sas';
-export { deriveSessionSlotId } from './crypto/slot';
+export { deriveSessionSlotId, derivePairingSlotId } from './crypto/slot';
 export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessage, CapabilityResponseMessage, EventMessage } from './wire/messages';
 export { encodeMessage, decodeMessage, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD } from './wire/framing';
 export { isJsonValue, isRecord } from './wire/json-value';
@@ -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, 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 { 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 type { Transport, TransportState, Unsubscribe } from './transport/transport';

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/version.ts
-var PROTOCOL_VERSION = "2";
+var PROTOCOL_VERSION = "3";
 function encodeProtocolVersion(version = PROTOCOL_VERSION) {
   return new TextEncoder().encode(`kangentic-bridge-v${version}`);
 }
@@ -4177,6 +4177,11 @@ function deriveSessionSlotId(desktopStaticPublicKey, phoneStaticPublicKey) {
   const material = concatBytes4(desktopStaticPublicKey, phoneStaticPublicKey);
   return bytesToHex(deriveLabeledKey(material, SESSION_SLOT_LABEL, SESSION_SLOT_LENGTH));
 }
+var PAIRING_SLOT_LABEL = "kangentic-pairing-slot-v1";
+var PAIRING_SLOT_LENGTH = 16;
+function derivePairingSlotId(pairingToken) {
+  return bytesToHex(deriveLabeledKey(pairingToken, PAIRING_SLOT_LABEL, PAIRING_SLOT_LENGTH));
+}
 
 // ../../node_modules/fflate/esm/browser.js
 var u8 = Uint8Array;
@@ -5126,6 +5131,15 @@ function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
 }
 
 // src/events/payloads.ts
+var BOARD_COLUMN_ROLES = ["todo", "done"];
+var TODO_ROLE = "todo";
+var DONE_ROLE = "done";
+function isTodoRole(role) {
+  return role === TODO_ROLE;
+}
+function isDoneRole(role) {
+  return role === DONE_ROLE;
+}
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
 function requireString(record, field, context) {
@@ -5292,18 +5306,26 @@ function nullableNumber(record, field) {
   const value = record[field];
   return typeof value === "number" ? value : null;
 }
+function nullableBoolean(record, field) {
+  const value = record[field];
+  return typeof value === "boolean" ? value : null;
+}
 function parseBoardColumnWire(value) {
   if (!isRecord(value)) throw new Error("board column must be an object");
   return {
     id: requireString(value, "id", "board column"),
     name: requireString(value, "name", "board column"),
     description: nullableString(value, "description"),
+    // An unrecognized role passes through rather than throwing: it is a
+    // custom column (or a future system role this package predates), not a
+    // malformed payload. See the BoardColumnRoleWire doc comment.
     role: nullableString(value, "role"),
     position: requireNumber(value, "position", "board column"),
     color: requireString(value, "color", "board column"),
     icon: nullableString(value, "icon"),
     is_archived: requireBoolean(value, "is_archived", "board column"),
-    is_ghost: requireBoolean(value, "is_ghost", "board column")
+    is_ghost: requireBoolean(value, "is_ghost", "board column"),
+    spawns_session: nullableBoolean(value, "spawns_session")
   };
 }
 function parseBoardTaskWire(value) {
@@ -5322,6 +5344,7 @@ function parseBoardTaskWire(value) {
     pr_number: nullableNumber(value, "pr_number"),
     pr_url: nullableString(value, "pr_url"),
     pr_state: nullableString(value, "pr_state"),
+    pr_merge_readiness: nullableString(value, "pr_merge_readiness"),
     base_branch: nullableString(value, "base_branch"),
     labels: Array.isArray(value.labels) ? parseStringArray(value.labels, "board task labels") : [],
     priority: typeof value.priority === "number" ? value.priority : 0,
@@ -6022,6 +6045,7 @@ function isBridgeEvent(value) {
   }
 }
 export {
+  BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
@@ -6052,6 +6076,7 @@ export {
   createPairingResponderHandshake,
   decodeMessage,
   decodePairingQrPayload,
+  derivePairingSlotId,
   deriveSecretstreamPair,
   deriveSessionSlotId,
   deriveShortAuthenticationString,
@@ -6070,11 +6095,13 @@ export {
   isBoardToolWriteName,
   isBridgeEvent,
   isCapabilityVerb,
+  isDoneRole,
   isJsonValue,
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  isTodoRole,
   openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,

package/dist/pairing/confirm.d.ts

@@ -14,8 +14,14 @@
  * 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.
+ * its own.
+ *
+ * A failed open is IGNORED rather than treated as a ceremony-ending failure.
+ * The frame is unauthenticated and the relay slot is reachable by anyone who
+ * can read the request URI, so treating one bad frame as a mismatch let an
+ * observer end a pairing at will. The caller stays in its sas-pending phase
+ * and lets its own timeout decide - see pairing-service.ts's
+ * handleConfirmFrame().
  *
  * 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
@@ -35,5 +41,14 @@ export declare function sealPairingConfirm(initiatorToResponder: CipherState): U
  * tampered/wrong-key ciphertext or an unexpected plaintext, so the caller
  * can treat "could not verify" uniformly whether the failure was
  * cryptographic or structural.
+ *
+ * A false return from a FAILED DECRYPT leaves `initiatorToResponder` untouched:
+ * CipherState advances its nonce only on a successful decrypt, so a caller may
+ * keep waiting for the real frame after rejecting any number of bad ones. Scoped
+ * to that path deliberately - the structural checks below return false only
+ * after a decrypt already succeeded and already advanced the nonce. They are
+ * unreachable in practice (an authenticating tag means the plaintext is the one
+ * sealPairingConfirm wrote) and kept as belt-and-braces, but a caller that ever
+ * made them reachable would not inherit the keep-waiting guarantee.
  */
 export declare function openPairingConfirm(initiatorToResponder: CipherState, frame: Uint8Array): boolean;

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

@@ -10,15 +10,24 @@
 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=`.
+ * wss:// is always secure; ws:// is accepted only for loopback.
+ *
+ * The relay address arrives inside a scanned QR payload, so it is attacker
+ * controllable: a crafted QR naming a plaintext host would route the whole
+ * ceremony through that host, and the pairing then persists it to the trust
+ * anchor for every later session. That is what the restriction prevents, and
+ * it holds regardless of how strong the frames themselves are.
+ *
+ * Note this rule predates derivePairingSlotId() and used to be justified by
+ * the pairing token being dialed verbatim as `?slot=`, which put the Noise PSK
+ * in cleartext on the wire. The slot is a derived routing label now, so that
+ * particular exposure is gone - the address-pinning reason above is not, which
+ * is why the restriction stays.
  *
  * Parses the AUTHORITY rather than prefix-matching. Prefix matching accepted
  * `ws://127.0.0.1:8080@evil.test`: everything before an '@' is userinfo, so
- * that address dials evil.test while looking like loopback, putting the PSK
- * on the wire in cleartext to an attacker-chosen host - and the pairing then
- * persists that host to the trust anchor for every later session. Authority
- * parsing also subsumes the old boundary check, since `localhost.evil.com`
- * is simply a different host.
+ * that address dials evil.test while looking like loopback. Authority parsing
+ * also subsumes the old boundary check, since `localhost.evil.com` is simply a
+ * different host.
  */
 export declare function isSecureRelayAddress(relayAddress: string): boolean;

package/dist/version.d.ts

@@ -1,6 +1,14 @@
 /**
  * The protocol version string. Bumped on any wire-incompatible change to
- * framing, message shapes, or the handshake patterns in this package.
+ * framing, message shapes, the handshake patterns, or the relay slot
+ * derivations in this package.
+ *
+ * A slot derivation counts because the slot is a zero-negotiation rendezvous
+ * value: peers computing it differently never meet, and would otherwise just
+ * hang until the relay's park timeout. Binding the version here instead turns
+ * that into an explicit "update the app" at QR-scan time, before anything
+ * dials. v3 derives the pairing slot from the token rather than using the
+ * token verbatim (see crypto/slot.ts's derivePairingSlotId).
  *
  * Bound into every Noise handshake's prologue (see crypto/noise/kk.ts and
  * crypto/pairing-handshake.ts), so two peers running different protocol
@@ -8,5 +16,5 @@
  * differing prologue produces a differing transcript hash `h` from the
  * first MixHash call, which cascades into every derived key.
  */
-export declare const PROTOCOL_VERSION = "2";
+export declare const PROTOCOL_VERSION = "3";
 export declare function encodeProtocolVersion(version?: string): Uint8Array;

package/package.json

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