mixdog 1.2.2 → 1.2.4

package/src/standalone/session-service/agent-tree/agent-child.mjs

@@ -3,11 +3,12 @@
 // caller's spec, creation of the runtime behind it, and the descriptor linked
 // into the agent registry. Running a turn on that child is ./agent-turns.mjs.
 
-export function createAgentChildFactory({ registry, rehydrateAgentSessions, createSession }) {
+export function createAgentChildFactory({ registry, rehydrateAgentSessions, createSession, entryForSession }) {
   return async function createAgentChild({ spec = {}, tag = null } = {}) {
     await rehydrateAgentSessions();
     const parentSessionId = String(spec.parentSessionId || '').trim();
     if (!parentSessionId) throw new TypeError('agent child parentSessionId is required');
+    const parentEpoch = registry.assertAdmission(parentSessionId);
     const ownerSessionId = String(
       spec.ownerSessionId || registry.get(parentSessionId)?.ownerSessionId || parentSessionId
     );
@@ -29,6 +30,7 @@ export function createAgentChildFactory({ registry, rehydrateAgentSessions, crea
       sourceType: spec.sourceType || 'agent',
       sourceName: spec.sourceName || spec.agent || 'agent',
       clientHostPid: spec.clientHostPid || null,
+      ...(preset.fallbacks !== undefined ? { routeFallbacks: preset.fallbacks } : {}),
     };
     const created = await createSession({
       cwd: spec.cwd || process.cwd(),
@@ -45,6 +47,22 @@ export function createAgentChildFactory({ registry, rehydrateAgentSessions, crea
       toolMode: 'full',
       sessionProfile,
     });
+    try {
+      registry.assertAdmission(parentSessionId, parentEpoch);
+    } catch (error) {
+      // The parent was cancelled while the runtime was being created: close it
+      // like any cancelled child instead of leaving it unlinked and open.
+      try {
+        const entry = await entryForSession?.(created.sessionId, {
+          cwd: spec.cwd || process.cwd(),
+          provider,
+          model,
+          toolMode: 'full',
+        });
+        await entry?.runtime?.closeCanonicalSession?.('parent cancelled during agent creation', { tombstone: false });
+      } catch {}
+      throw error;
+    }
     const descriptor = registry.linkAgentDescriptor({
       id: created.sessionId,
       ...sessionProfile,

package/src/standalone/session-service/agent-tree/agent-registry.mjs

@@ -6,6 +6,8 @@ export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
 export function createAgentRegistry() {
   const agentSessions = new Map();
   const agentChildren = new Map();
+  const cancellationCounts = new Map();
+  const cancellationEpochs = new Map();
 
   function linkAgentDescriptor(descriptor) {
     const sessionId = String(descriptor?.id || '').trim();
@@ -54,6 +56,27 @@ export function createAgentRegistry() {
   }
 
   return {
+    assertAdmission(id, epoch = cancellationEpochs.get(id) || 0) {
+      if (cancellationCounts.has(id) || (cancellationEpochs.get(id) || 0) !== epoch) {
+        throw new Error(`agent session ${id} was cancelled during admission`);
+      }
+      return epoch;
+    },
+    beginCancellation(ids) {
+      for (const id of ids) {
+        cancellationCounts.set(id, (cancellationCounts.get(id) || 0) + 1);
+        cancellationEpochs.set(id, (cancellationEpochs.get(id) || 0) + 1);
+      }
+      return () => {
+        for (const id of ids) {
+          const remaining = (cancellationCounts.get(id) || 0) - 1;
+          if (remaining > 0) cancellationCounts.set(id, remaining);
+          else cancellationCounts.delete(id);
+        }
+      };
+    },
+    isCancelling: (id) => cancellationCounts.has(id),
+    cancellationEpoch: (id) => cancellationEpochs.get(id) || 0,
     linkAgentDescriptor,
     agentDescendantSessionIds,
     get: (sessionId) => agentSessions.get(String(sessionId || '').trim()),
@@ -68,6 +91,8 @@ export function createAgentRegistry() {
     clear() {
       agentSessions.clear();
       agentChildren.clear();
+      cancellationCounts.clear();
+      cancellationEpochs.clear();
     },
   };
 }

package/src/standalone/session-service/agent-tree/agent-turns.mjs

@@ -14,7 +14,12 @@ export function createAgentTurns({
   takeWatchdogStop,
   takeCancelTranscript,
 }) {
-  const createAgentChild = createAgentChildFactory({ registry, rehydrateAgentSessions, createSession });
+  const createAgentChild = createAgentChildFactory({
+    registry,
+    rehydrateAgentSessions,
+    createSession,
+    entryForSession,
+  });
 
   // The turn was stopped (progress watchdog or cancellation): rethrow its error
   // carrying the assistant text the turn produced, so the owner still gets a
@@ -35,6 +40,7 @@ export function createAgentTurns({
   async function runAgentTurn({ session, prompt, context = null, onToolResult, onTerminalResult } = {}) {
     await rehydrateAgentSessions();
     const sessionId = String(session?.id || session || '').trim();
+    const cancelEpoch = registry.assertAdmission(sessionId);
     const descriptor = registry.get(sessionId);
     if (!descriptor || descriptor.closed) {
       throw new Error(`agent session ${sessionId || '(empty)'} is closed`);
@@ -46,6 +52,7 @@ export function createAgentTurns({
       toolMode: 'full',
     });
     const target = entry.runtime.submitAndWait;
+    registry.assertAdmission(sessionId, cancelEpoch);
     if (typeof target !== 'function') {
       throw new TypeError('session runtime must implement submitAndWait');
     }
@@ -55,6 +62,7 @@ export function createAgentTurns({
     // Transcript length before this turn: where a watchdog stop's partial
     // output starts.
     const { messageCount: messageStart } = await entry.runtime.readModelMessages(Number.MAX_SAFE_INTEGER);
+    registry.assertAdmission(sessionId, cancelEpoch);
     descriptor.status = 'running';
     descriptor.stage = 'running';
     descriptor.updatedAt = Date.now();

package/src/standalone/session-service/agent-tree.mjs

@@ -109,9 +109,34 @@ export function createAgentTree({
     canRun: (session) => Boolean(registry.get(session?.id)),
     createChild: createAgentChild,
     runTurn: runAgentTurn,
+    /** A model or tuning change for a reused child goes through the session's
+     *  own route API: saved at once, applied from the next turn (never refused
+     *  because a turn is running). `route` may be partial; the route write
+     *  completes it against the latest selected route. The descriptor follows
+     *  the selected route. */
+    async setRoute({ session, route }) {
+      const descriptor = registry.get(session?.id);
+      if (!descriptor || descriptor.closed) throw new Error('agent session is closed');
+      const entry = await entryForSession(descriptor.id, {
+        cwd: descriptor.cwd,
+        provider: descriptor.provider,
+        model: descriptor.model,
+        toolMode: 'full',
+      });
+      try {
+        const applied = await entry.runtime.setRoute({ ...route, sessionOnly: true });
+        descriptor.provider = applied?.provider || route.provider || descriptor.provider;
+        descriptor.model = applied?.model || route.model || descriptor.model;
+        descriptor.updatedAt = Date.now();
+        return applied;
+      } finally {
+        retainUnwatched(entry, 'agent route change');
+      }
+    },
     async enqueueTurn({ session, prompt, context = null }) {
       const descriptor = registry.get(session?.id);
       if (!descriptor || descriptor.closed) throw new Error('agent session is closed');
+      const cancelEpoch = registry.assertAdmission(descriptor.id);
       const runtime = sessionOwner(descriptor.id)?.runtime;
       if (!runtime || !stateBusy(runtime.getState())) return null;
       const accepted = await runtime.submitAsync(String(prompt || ''), {
@@ -122,6 +147,7 @@ export function createAgentTree({
         transcriptMeta: { sender: 'lead' },
       });
       if (accepted === false) throw new Error('agent follow-up was not accepted');
+      registry.assertAdmission(descriptor.id, cancelEpoch);
       return { queueDepth: runtime.getState()?.queued?.length ?? null };
     },
   });
@@ -167,9 +193,9 @@ export function createAgentTree({
       if (handoff) descriptor.lastHandoff = handoff;
       return handoff;
     },
-    async closeSession(sessionId, reason = 'agent session closed') {
+    async closeSession(sessionId, reason = 'agent session closed', options = {}) {
       await rehydrateAgentSessions();
-      return cancelAgentTree(sessionId, reason);
+      return cancelAgentTree(sessionId, reason, options);
     },
     unloadSessionRuntime: (sessionId) => {
       progress.delete(sessionId);

package/src/standalone/session-service/entries/session-loads.mjs

@@ -6,6 +6,7 @@
 // converge on one runtime.
 
 export function createSessionLoads({
+  pendingViewers,
   sessionExists,
   log,
   assertAvailable,
@@ -20,12 +21,21 @@ export function createSessionLoads({
   const sessionLoads = new Map(); // sessionId -> Promise<entry>
 
   function getOrCreateSessionEntry(sessionId, create) {
-    const owner = sessionOwner(sessionId);
-    if (owner) return Promise.resolve(owner);
     const inFlight = sessionLoads.get(sessionId);
     if (inFlight) return inFlight;
     const loading = Promise.resolve()
-      .then(create)
+      .then(async () => {
+        const owner = sessionOwner(sessionId);
+        if (owner) {
+          if ((await owner.runtime.isSessionTerminal?.()) !== true) return owner;
+          if (owner.subscribers?.size) {
+            if (!pendingViewers.has(sessionId)) pendingViewers.set(sessionId, new Set());
+            for (const subscriber of owner.subscribers) pendingViewers.get(sessionId).add(subscriber);
+          }
+          await destroy(owner, 'replace terminal runtime', { keepBackgroundWork: true, announce: false });
+        }
+        return create();
+      })
       .finally(() => {
         if (sessionLoads.get(sessionId) === loading) sessionLoads.delete(sessionId);
       });
@@ -84,11 +94,12 @@ export function createSessionLoads({
    *  flight), or null where answering would take a fresh load. */
   async function hostedEntryForSession(sessionId) {
     assertAvailable();
+    if (sessionLoads.has(sessionId)) return sessionLoads.get(sessionId);
     const owner = sessionOwner(sessionId);
-    if (owner) return owner;
+    if (owner) return (await owner.runtime.isSessionTerminal?.()) === true ? null : owner;
     const external = await bindExternalSessionView(sessionId);
     const acquiredOwner = sessionOwner(sessionId);
-    if (acquiredOwner) return acquiredOwner;
+    if (acquiredOwner) return (await acquiredOwner.runtime.isSessionTerminal?.()) === true ? null : acquiredOwner;
     if (external?.runtime?.externalAction === true) return external;
     return sessionLoads.get(sessionId) || null;
   }

package/src/standalone/session-service/entries.mjs

@@ -70,6 +70,7 @@ export function createSessionEntries({
     publishExternalSessionState,
   });
   const loads = createSessionLoads({
+    pendingViewers,
     sessionExists,
     log,
     assertAvailable: lifecycle.assertAvailable,

package/src/standalone/session-service/projection/transcript-window.mjs

@@ -386,3 +386,42 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
   view.headOlder = from > 0 || stored.transcriptHasOlder === true;
   return true;
 }
+
+/** A one-shot range must not grow or rebudget an attached desktop's window. */
+export async function readTranscriptRange(entry, sessionId, readStoredSession, { offset, limit }) {
+  if (
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > 100 ||
+    !Number.isSafeInteger(offset + limit)
+  )
+    throw new TypeError('invalid transcript range');
+  const requested = offset + limit;
+  let snapshot;
+  if (entry) {
+    const state = entry.runtime.getState();
+    const isolated = { runtime: { getState: () => state } };
+    requestLiveTranscriptWindow(isolated, { limit: requested, byteBudget: null, pageBase: 0 });
+    windowTranscriptSnapshot(isolated, state);
+    isolated.transcriptView.paged = true;
+    await loadLiveTranscriptHead(isolated, sessionId, readStoredSession);
+    snapshot = windowTranscriptSnapshot(isolated, state);
+  } else {
+    snapshot = await readStoredSession(sessionId, { transcriptItemLimit: requested });
+  }
+  if (!snapshot) throw new Error(`session ${sessionId} is not available`);
+  const source = snapshot.items || [];
+  if (offset >= source.length && snapshot.transcriptHasOlder) {
+    throw new Error('session: requested history is not available in the retained projection');
+  }
+  const end = Math.max(0, source.length - offset);
+  const start = Math.max(0, end - limit);
+  return {
+    sessionId,
+    offset,
+    items: sanitizeForWire(source.slice(start, end)),
+    hasOlder: start > 0 || snapshot.transcriptHasOlder === true,
+  };
+}

package/src/standalone/session-service/quota-resume.mjs

@@ -8,8 +8,6 @@
 // again, and the session's own lane runs the retry under the entry's
 // generation. Overdue entries run as soon as the scheduler starts.
 
-import { isAgentOnlySession } from '../../runtime/shared/quota-resume-store.mjs';
-
 /** A still-exhausted reading is re-taken once, this much later. */
 export const QUOTA_RESUME_RETRY_MS = 5 * 60_000;
 /** A busy session is re-checked this much later, without spending an attempt. */
@@ -32,19 +30,33 @@ async function resumeDueEntry(entry, { store, materializeSession, readQuotaUsabl
     return 'unavailable';
   }
   if (!isCurrent(store, entry)) return 'cancelled';
-  // A delegated agent child never owns a resume (the Lead decides retries), so
-  // an entry persisted for one never fires, whatever wrote it.
-  if (isAgentOnlySession({ id: sessionId, ...runtime?.session })) {
-    store.cancelQuotaResumeEntry(sessionId, { generation });
-    return 'agent-session';
-  }
   let usable = false;
+  const currentRoute = () => {
+    const snapshot = runtime.getState?.() ?? {};
+    return {
+      // The selected route is what the next turn runs on; sessionProvider /
+      // sessionModel still hold the previous turn's after a deferred selection.
+      provider: snapshot.provider || snapshot.sessionProvider || runtime.session?.provider || entry.provider,
+      model: snapshot.model || snapshot.sessionModel || runtime.session?.model || entry.model,
+    };
+  };
+  const { provider, model } = currentRoute();
   try {
-    usable = await readQuotaUsable(entry.provider, entry.model);
+    usable = await readQuotaUsable(provider, model);
   } catch (error) {
-    log(`quota resume usage reading failed provider=${entry.provider}: ${error?.message || error}`);
+    log(`quota resume usage reading failed provider=${provider}: ${error?.message || error}`);
   }
   if (!isCurrent(store, entry)) return 'cancelled';
+  const selected = currentRoute();
+  if (selected.provider !== provider || selected.model !== model) {
+    // The reading belongs to the old route. Preserve the reservation and
+    // check the selected route on the normal busy-recheck cadence.
+    store.deferQuotaResumeEntry(sessionId, generation, {
+      resetAt: now() + QUOTA_RESUME_BUSY_RECHECK_MS,
+      attempts: entry.attempts,
+    });
+    return 'route-changed';
+  }
   if (!usable) {
     // One more reading five minutes on; after that the session falls back
     // to the user's own choice.
@@ -59,8 +71,8 @@ async function resumeDueEntry(entry, { store, materializeSession, readQuotaUsabl
     return 'exhausted';
   }
   const outcome =
-    typeof runtime?.fireQuotaResume === 'function' ? runtime.fireQuotaResume({ generation }) : 'unsupported';
-  if (outcome === 'busy') {
+    typeof runtime?.fireQuotaResume === 'function' ? await runtime.fireQuotaResume({ generation }) : 'unsupported';
+  if (outcome === 'busy' || outcome === 'rejected') {
     store.deferQuotaResumeEntry(sessionId, generation, {
       resetAt: now() + QUOTA_RESUME_BUSY_RECHECK_MS,
       attempts: entry.attempts,
@@ -117,7 +129,10 @@ export function createQuotaResumeScheduler({
           log(`quota resume session=${entry.sessionId} outcome=${outcome}`);
         } catch (error) {
           log(`quota resume failed session=${entry.sessionId}: ${error?.message || error}`);
-          store.cancelQuotaResumeEntry(entry.sessionId, { generation: entry.generation });
+          store.deferQuotaResumeEntry(entry.sessionId, entry.generation, {
+            resetAt: now() + QUOTA_RESUME_RETRY_MS,
+            attempts: entry.attempts,
+          });
         }
       }
     })().finally(() => {

package/src/standalone/session-service/session-calls/session-action.mjs

@@ -2,10 +2,17 @@
 // The generic runtime-action lane (read / configure allowlists) and the
 // session catalog listing.
 import { SESSION_CONFIGURE_ACTION_SET, SESSION_READ_ACTION_SET } from '../../session-protocol.mjs';
+import { annotateSpan, markPhase } from '../../../runtime/shared/slow-span.mjs';
 import { sanitizeForWire } from '../../session-wire-values.mjs';
 
 /** Reads a session without a live runtime answers from disk (readStoredReview). */
-const STORED_REVIEW_ACTIONS = new Set(['getTurnReviewDiff', 'getSessionReviewDiff', 'getTurnChanges']);
+const STORED_REVIEW_ACTIONS = new Set([
+  'getTurnReviewDiff',
+  'getSessionReviewDiff',
+  'getTurnChanges',
+  'getSessionReviewFilePatch',
+  'getTurnReviewFilePatch',
+]);
 
 /** One compact description of an action result for the daemon log, never the payload itself. */
 function resultSummary(value) {
@@ -44,7 +51,8 @@ export function createSessionActionCalls(ctx) {
     assertAvailable();
     if (value === null) throw new Error(`session ${id} is not available`);
     log(`session action ${name} session=${id} result=${resultSummary(value)} (stored)`);
-    return {
+    markPhase('load');
+    const result = {
       value: sanitizeForWire(value) ?? null,
       sessionId: id,
       reservedOnly: false,
@@ -52,6 +60,8 @@ export function createSessionActionCalls(ctx) {
       unchanged: true,
       ...(Number.isInteger(baseRevision) ? { revision: baseRevision } : {}),
     };
+    markPhase('project');
+    return result;
   }
 
   async function runSessionAction(
@@ -62,6 +72,7 @@ export function createSessionActionCalls(ctx) {
     const id = String(sessionId || '');
     if (!id) throw new TypeError('sessionId is required');
     const name = requireSessionAction(action, allowedActions);
+    annotateSpan(name);
     // Opening an earlier session asks for its review right away; loading the
     // whole runtime for that held the review bar (and the pane's reveal) for
     // seconds.
@@ -72,7 +83,9 @@ export function createSessionActionCalls(ctx) {
     assertAvailable(entry);
     const target = entry.runtime[name];
     if (typeof target !== 'function') throw new TypeError(`session action ${name} is unavailable`);
+    markPhase('load');
     const value = await target.apply(entry.runtime, Array.isArray(args) ? args : []);
+    markPhase('action');
     if (name === 'setCwd' && value) {
       try {
         const projects = await loadProjectStore();
@@ -89,11 +102,13 @@ export function createSessionActionCalls(ctx) {
     // Still unwatched: keep it on the retention clock exactly like a runtime
     // released by its view, so an untouched load cannot leak past the idle window.
     retainUnwatched(entry);
-    return {
+    const result = {
       value: sanitizeForWire(value) ?? null,
       sessionId: responseSessionId(entry, id),
       ...bodyForClient(step, Number.isInteger(baseRevision) ? baseRevision : null),
     };
+    markPhase('project');
+    return result;
   }
 
   async function listSessionCatalog(options = {}) {

package/src/standalone/session-service/session-calls/session-turns.mjs

@@ -5,6 +5,7 @@
 // ./goal-recovery.mjs.
 import { createGoalRecovery } from './goal-recovery.mjs';
 import {
+  attachmentsForIntake,
   materializePromptSubmission,
   preparePromptSubmissionForProvider,
 } from '../../../runtime/attachments/store.mjs';
@@ -52,18 +53,28 @@ export function createSessionTurnCalls(ctx) {
     const entry = await entryForSession(id, openHints || {});
     const target = entry.runtime.submitAsync;
     if (typeof target !== 'function') throw new TypeError('session runtime must implement submitAsync');
-    const intake = await preparePromptSubmissionForProvider(
-      materializePromptSubmission(prompt, options || {}),
-      { nativePdf: providerNativePdf(entry.runtime.provider || entry.runtime.session?.provider || '') }
-    );
+    const intake = await preparePromptSubmissionForProvider(materializePromptSubmission(prompt, options || {}), {
+      nativePdf: providerNativePdf(entry.runtime.provider || entry.runtime.session?.provider || ''),
+    });
     // Await intake only: submitAsync resolves once the prompt is represented by
     // the queue/user row, while provider execution remains daemon-owned and
     // detached.
     let submissionOptions = intake.options;
-    if (entry.runtime.externalAction === true) {
+    // Every send (desktop or paired device) reaches the engine here: the
+    // message records its attachments by content hash, so any device can open
+    // or download them by id later (and the store's census keeps the blobs).
+    const attachments = attachmentsForIntake(intake.prompt, intake.options);
+    if (attachments.length || entry.runtime.externalAction === true) {
       const transcriptMeta = intake.options?.transcriptMeta;
       const baseMeta = transcriptMeta && typeof transcriptMeta === 'object' ? transcriptMeta : {};
-      submissionOptions = { ...intake.options, transcriptMeta: { ...baseMeta, sender: 'user' } };
+      submissionOptions = {
+        ...intake.options,
+        transcriptMeta: {
+          ...baseMeta,
+          ...(attachments.length ? { attachments } : {}),
+          ...(entry.runtime.externalAction === true ? { sender: 'user' } : {}),
+        },
+      };
     }
     const accepted = await Promise.resolve(target.call(entry.runtime, intake.prompt, submissionOptions));
     if (accepted === true) {

package/src/standalone/session-service/session-calls/session-views.mjs

@@ -6,6 +6,7 @@ import { SESSION_READ_ACTION_SET } from '../../session-protocol.mjs';
 import { SESSION_ID_PATTERN } from '../agent-tree.mjs';
 import {
   loadLiveTranscriptHead,
+  readTranscriptRange,
   rebudgetTranscriptWindow,
   requestedHeldTranscript,
   requestedTranscriptWindow,
@@ -132,6 +133,11 @@ export function createSessionViewCalls(ctx) {
     if (!id) throw new TypeError('sessionId is required');
     const live = await liveEntryFor(id);
     assertAvailable(live);
+    if (params.transcriptRange) {
+      const range = await readTranscriptRange(live, id, readStoredSession, params.transcriptRange);
+      assertAvailable(live);
+      return { range };
+    }
     if (live) {
       return liveSessionReadResult(live, params, id, baseRevision);
     }

package/src/standalone/session-service-api.mjs

@@ -1,3 +1,5 @@
+import { shortId, slowSpans } from '../runtime/shared/slow-span.mjs';
+
 const sessionServiceRoutes = ({ desktop, project, session }) => ({
   'desktop.init': (params, ctx) => desktop.init(params, ctx),
   'desktop.invoke': (params, ctx) => desktop.invoke(params, ctx),
@@ -32,13 +34,16 @@ export function createSessionServiceApi({
   getTurnBusyCount,
   getStatus,
   getExternalClientCount,
+  spans = slowSpans,
 }) {
   const routes = sessionServiceRoutes({ desktop, project, session });
   return {
     async handleCall(name, args = {}, ctx = null) {
       const route = routes[String(name || '')];
       if (!route) throw new Error(`unknown session service call ${name}`);
-      return route(args || {}, ctx);
+      const params = args || {};
+      const sid = shortId(params.sessionId);
+      return spans.trace(sid ? `${name}#${sid}` : String(name), () => route(params, ctx));
     },
     ...methods,
     get size() {

package/src/standalone/session-state-patch.d.mts

@@ -3,5 +3,6 @@ export function diffSessionState(
   next: unknown,
   options?: { prepend?: boolean }
 ): Record<string, unknown> | null;
-export function applySessionStatePatch(previous: unknown, patch: unknown): Record<string, unknown>;
+export function streamingPartialSuffix(before: unknown, after: unknown): string | null;
+export function applySessionStatePatch(previous: unknown, patch: unknown): Record<string, unknown> | null;
 export function transcriptItemsDigest(items: readonly unknown[]): string;

package/src/standalone/session-state-patch.mjs

@@ -7,16 +7,51 @@
 // `transcriptPrepend`) carries rows revealed ABOVE the previous list, an
 // older-history page: the previous rows then start `values.length` rows in,
 // and `itemsAppend.from` indexes the PREVIOUS list.
+//
+// `partialAppend` carries growth of the desktop-only `streamingPartial` (the
+// unfinished streamed line) as just its new text: re-sending the whole line on
+// every tick made a long unfinished line cost O(length²) on the wire. A
+// decoder that predates it keeps its last partial, which the desktop join
+// then ignores or shows behind — never wrong text.
 import { createHash } from 'node:crypto';
 
+/** The text `after` appends to `before` when both are the same unfinished
+ *  line (same row, same offset, same row identity), else null: a retraction,
+ *  another row or a new line travels as a full replacement. */
+export function streamingPartialSuffix(before, after) {
+  if (!before || !after || typeof before !== 'object' || typeof after !== 'object') return null;
+  const { text: beforeText, ...beforeRest } = before;
+  const { text: afterText, ...afterRest } = after;
+  if (typeof beforeText !== 'string' || typeof afterText !== 'string') return null;
+  if (afterText.length <= beforeText.length || !afterText.startsWith(beforeText)) return null;
+  // id, from and the row identity: everything but the text stays put.
+  if (JSON.stringify(beforeRest) !== JSON.stringify(afterRest)) return null;
+  return afterText.slice(beforeText.length);
+}
+
+function appendStreamingPartial(state, suffix) {
+  const held = state.streamingPartial;
+  if (!held || typeof held !== 'object' || typeof held.text !== 'string' || typeof suffix !== 'string') return false;
+  state.streamingPartial = { ...held, text: held.text + suffix };
+  return true;
+}
+
 export function diffSessionState(previous, next, { prepend = false } = {}) {
   if (!previous || !next || typeof previous !== 'object' || typeof next !== 'object') return null;
   const set = {};
   const remove = [];
   let itemsAppend = null;
   let itemsPrepend = null;
+  let partialAppend = null;
   for (const [key, value] of Object.entries(next)) {
     if (previous[key] === value) continue;
+    if (key === 'streamingPartial') {
+      const suffix = streamingPartialSuffix(previous[key], value);
+      if (suffix !== null) {
+        partialAppend = { text: suffix };
+        continue;
+      }
+    }
     if (key === 'items' && Array.isArray(value) && Array.isArray(previous.items)) {
       let head = 0;
       if (prepend && previous.items.length > 0 && value[0] !== previous.items[0]) {
@@ -36,13 +71,18 @@ export function diffSessionState(previous, next, { prepend = false } = {}) {
   for (const key of Object.keys(previous)) {
     if (!(key in next)) remove.push(key);
   }
-  return itemsPrepend ? { set, remove, itemsAppend, itemsPrepend } : { set, remove, itemsAppend };
+  const patch = itemsPrepend ? { set, remove, itemsAppend, itemsPrepend } : { set, remove, itemsAppend };
+  if (partialAppend) patch.partialAppend = partialAppend;
+  return patch;
 }
 
+/** The patched state, or null when a `partialAppend` has no held line to grow
+ *  (a broken chain the caller answers with a full resync, never lost text). */
 export function applySessionStatePatch(previous, patch) {
   const base = previous && typeof previous === 'object' ? previous : {};
   if (!patch || typeof patch !== 'object') return base;
   const next = { ...base, ...(patch.set || {}) };
+  if (Object.hasOwn(patch, 'partialAppend') && !appendStreamingPartial(next, patch.partialAppend?.text)) return null;
   if (patch.itemsAppend || patch.itemsPrepend) {
     const items = Array.isArray(base.items) ? base.items : [];
     const head = Array.isArray(patch.itemsPrepend?.values) ? patch.itemsPrepend.values : [];