@kangentic/protocol 0.13.0 → 0.14.0

package/dist/events/event.d.ts

@@ -65,10 +65,45 @@ export type ActivityEventPayload = {
  * phone learns "this session is over" from the feed itself instead of
  * inferring it from silence. `intentional` distinguishes a deliberate
  * stop (desktop Stop button, suspend, shutdown) from a crash.
+ *
+ * `spawnProgressLabel`, when present, means the desktop had a respawn in
+ * flight for this task when the session ended - a same-column respawn
+ * (model switch, agent switch, effort change, isolated-session-track
+ * switch) rather than a genuine park. Read it as what the desktop
+ * believed, not as a fact about what happens next; the caveats below
+ * bound it. `intentional` cannot carry this distinction on its own:
+ * the desktop's SessionManager.suspend() sets `status = 'suspended'`
+ * before the force-kill for every caller, a respawn and a real park
+ * alike, so both reach the phone as `intentional: true`. The string is
+ * the desktop's own display text for what it is doing ("Switching
+ * model...", "Starting agent...", a live git-queue wait count) - treat it
+ * as untrusted display text, not a key to switch on, cap its length, and
+ * fall back to generic copy rather than parsing it.
+ *
+ * INTENT, not a guarantee, on the same terms `BoardColumnWire.spawns_session`
+ * documents: the desktop can suspend without a successor ever landing (a
+ * board profile change, a failed worktree checkout, a shutdown, a racing
+ * move), so a client MUST keep whatever timeout already bounds its
+ * session-swap wait and use the label only to skip a redundant one.
+ *
+ * Absent from pre-0.14.0 desktops, and never sent as `null`. A park that
+ * goes through `task-move.ts` (move to To Do, to Done, or into an
+ * `auto_spawn=false` column) clears the label first, so it carries none.
+ * Five other genuine parks do not clear it - a manual pause, the
+ * idle-timeout suspend, the `kill_session` action, project-relocate, and
+ * auto-spawn-reconcile - so one of those firing while a label is still in
+ * flight sends the label on a real park. The label then survives at most
+ * the desktop's 120s spawn-progress TTL. That gap is why the timeout above
+ * is mandatory, not advisory.
+ *
+ * A label can also ride an `intentional: false` exit, since a respawn whose
+ * spawn fails still has its label in flight when the PTY dies. The two
+ * fields are independent; do not read them as mutually exclusive.
  */
  | {
     type: 'session-ended';
     intentional: boolean;
+    spawnProgressLabel?: string;
 }
 /**
  * The agent's most recent assistant message, already collapsed to a short

package/dist/events/payloads.d.ts

@@ -279,8 +279,7 @@ export interface BoardColumnWire {
      * 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.
+     * runtime.
      *
      * Ordering precondition this field depends on: the phone must learn a
      * MOVE's destination column before the old session's `session-ended`
@@ -313,8 +312,12 @@ export interface BoardTaskWire {
      * 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.
+     *
+     * Declared OPTIONAL (`?`) so a hand-built `BoardTaskWire` literal does not
+     * have to list it. `parseBoardTaskWire` populates the key from every real
+     * wire response regardless, so the optionality costs nothing at runtime.
      */
-    pr_merge_readiness: string | null;
+    pr_merge_readiness?: string | null;
     base_branch: string | null;
     labels: string[];
     priority: number;

package/dist/index.cjs

@@ -6107,7 +6107,11 @@ function parseActivityEventPayload(payload) {
     }
     case "session-ended": {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
-      return { type: "session-ended", intentional: payload.intentional };
+      if (payload.spawnProgressLabel === void 0) {
+        return { type: "session-ended", intentional: payload.intentional };
+      }
+      if (typeof payload.spawnProgressLabel !== "string") throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
+      return { type: "session-ended", intentional: payload.intentional, spawnProgressLabel: payload.spawnProgressLabel };
     }
     case "message-preview": {
       if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');

package/dist/index.mjs

@@ -5986,7 +5986,11 @@ function parseActivityEventPayload(payload) {
     }
     case "session-ended": {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
-      return { type: "session-ended", intentional: payload.intentional };
+      if (payload.spawnProgressLabel === void 0) {
+        return { type: "session-ended", intentional: payload.intentional };
+      }
+      if (typeof payload.spawnProgressLabel !== "string") throw new Error('session-ended payload has an invalid "spawnProgressLabel"');
+      return { type: "session-ended", intentional: payload.intentional, spawnProgressLabel: payload.spawnProgressLabel };
     }
     case "message-preview": {
       if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');

package/package.json

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