dsh-ferry 0.1.0 → 0.1.2

package/README.md

@@ -86,7 +86,7 @@ A 推送会话到 B、在 A 上继续之后再次推送，对话框会显示对
 | 对方内容一致 | ✅ | 0 条事件，只同步工作区文件 |
 | 对方也续写过（分叉） | ❌ 只能新建 | 对方副本原样保留 |
 | 对方副本更长 | ❌ 只能新建 | 或反过来从对方拉取 |
-| 对方正在运行该会话 | ❌ 只能新建 | 先停止才能追加 |
+| 对方已打开该会话 | ❌ 只能新建 | 对方的 DSH 进程持有该会话的写句柄，即使没在运行也一样；在那里关闭该会话或重启实例后才能追加 |
 
 判定依据是事件数 + 尾部 8 条事件指纹；真正导入前还会逐条校验前缀，不一致直接拒绝。追加只追加事件，不改会话头部：对方的 cwd、标题、模型预设保持原样。
 
@@ -228,3 +228,5 @@ npm view dsh-ferry version --registry=https://registry.npmjs.org/
 
 发布前用 `npm pack --dry-run` 检查包内容（`files` 已限定为入口、`lib/`、`client.js`、`locale/`、`cordis.patch.yml`、`icon.svg`、README 和 `docs/`）。
 版本号遵循语义化版本：改了协议/行为就走 minor，纯修复走 patch。
+
+首次发布若走了 npm 的 staged publish，包里会先出现一个 `0.0.0-stage` 占位版本（manifest 没有 `dsh` 字段），镜像可能缓存它几分钟。此时安装会报 `dsh-ferry declares no dsh.bundle`，等真实版本同步后再装即可；也可以 `npm deprecate dsh-ferry@0.0.0-stage "staged-publish placeholder"` 标记作废。

package/client.js

@@ -71,16 +71,20 @@ window.__ModuleLoader__.load({
 .ferry-choice.offline:hover{background:transparent}
 .ferry-status{display:inline-flex;align-items:center;gap:6px;flex:none;font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary)}
 .ferry-choice-body{flex:1 1 auto;min-width:0}
-.ferry-choice-row{display:flex;align-items:center;gap:8px;min-width:0}
 .ferry-state{font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary);margin-top:2px;white-space:normal}
-.ferry-mode{display:flex;flex-direction:column;gap:6px;border-top:.5px solid var(--dsw-alias-border-l1);padding-top:10px}
-.ferry-mode-label{display:flex;align-items:flex-start;gap:8px;font-size:12px;line-height:18px;cursor:pointer}
-.ferry-mode-label.disabled{opacity:.45;cursor:default}
-.ferry-mode-text{display:flex;flex-direction:column;min-width:0}
+.ferry-mode{display:flex;flex-direction:column;gap:2px;padding-top:6px}
+.ferry-mode-title{font-size:12px;line-height:18px;font-weight:500;color:var(--dsw-alias-label-primary);padding:0 10px;margin-bottom:2px}
+.ferry-mode-label{display:flex;align-items:flex-start;gap:10px;padding:5px 10px;border-radius:7px;font-size:12px;line-height:18px;cursor:pointer}
+.ferry-mode-label:hover:not(.disabled){background:var(--dsw-alias-bg-layer-2)}
+.ferry-mode-label input[type=radio]{flex:none;margin:2px 0 0;width:14px;height:14px;cursor:inherit}
+.ferry-mode-label.disabled{cursor:default;color:var(--dsw-alias-label-secondary)}
+.ferry-mode-text{display:flex;flex-direction:column;min-width:0;gap:1px}
+.ferry-mode-hint{font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary)}
+.ferry-stack{display:flex;flex-direction:column;gap:4px}
 .ferry-choice-name{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .ferry-modal-error{font-size:11px;line-height:16px;color:var(--dsw-alias-state-error-primary)}
 .ferry-modal-foot{display:flex;align-items:center;gap:8px;border-top:.5px solid var(--dsw-alias-border-l1);padding-top:12px;margin-top:2px}
-.ferry-check{display:flex;align-items:center;gap:6px;font-size:11px;color:var(--dsw-alias-label-secondary);cursor:pointer}
+.ferry-check{display:flex;align-items:center;gap:6px;font-size:12px;color:var(--dsw-alias-label-secondary);cursor:pointer}
 .ferry-toasts{position:fixed;right:20px;bottom:20px;z-index:90;display:flex;flex-direction:column;gap:8px;max-width:380px;pointer-events:none}
 .ferry-toast{pointer-events:auto;border:.5px solid var(--dsw-alias-border-l2);border-left-width:3px;border-radius:8px;background:var(--dsw-alias-bg-overlay);padding:10px 12px;font-size:12px;line-height:18px;box-shadow:0 8px 24px rgba(0,0,0,.24)}
 .ferry-toast.success{border-left-color:var(--dsw-alias-state-success-primary)}
@@ -161,23 +165,31 @@ window.__ModuleLoader__.load({
       mergeInMenu: 'Merge into an existing directory (backs up)',
       modeTitle: 'How to send it',
       modeNew: 'New session',
-      modeNewHint: 'Create a separate copy there; the peer keeps whatever it already has.',
+      modeNewHint: 'Create a separate copy; the peer keeps what it already has.',
       modeUpdate: 'Append update',
-      modeUpdateHint: 'Keep one session: add the events the peer is missing and merge the workspace.',
-      modeUpdateUnavailable: 'Not possible for this peer',
+      modeUpdateHint: 'Append only the missing events and merge the workspace.',
+      modeUpdateUnavailable: 'Not available for this peer',
+      blocked_state_open: 'The peer has it open',
+      blocked_state_ahead: "The peer's copy is longer",
+      blocked_state_diverged: 'The two copies differ',
+      blocked_state_absent: 'The peer has no copy yet',
+      blocked_local_open: 'It is open here',
+      blocked_local_ahead: 'The local copy is longer',
+      blocked_local_diverged: 'The two copies differ',
+      blocked_local_absent: 'No local copy here yet',
       state_absent: 'No copy there yet; it will be created',
       state_behind: 'The peer has {have} events; {add} will be appended',
       state_same: 'The peer has {have} events and matches; only workspace files are synced',
       state_ahead: 'The peer has {have} events, more than here; only a new copy is possible',
       state_diverged: 'The peer copy has diverged; only a new copy is possible',
-      state_active: 'The peer has this session open; only a new copy is possible',
+      state_active: 'The peer has this session open; close it or restart that instance to append',
       state_unknown: 'Cannot tell what the peer has (offline, or its plugin is older; append updates need the same version on both sides)',
       local_absent: 'No local copy yet; it will be created',
       local_behind: 'This instance has {have} events; {add} will be appended',
       local_same: 'This instance has {have} events and matches; only workspace files are synced',
       local_ahead: 'This instance has {have} events, more than the peer; only a new copy is possible',
       local_diverged: 'The local copy has diverged; only a new copy is possible',
-      local_active: 'This session is open here; only a new copy is possible',
+      local_active: 'This session is open here; close it or restart this instance to append',
       local_unknown: 'Cannot tell what this instance has',
       pullDialogTitle: 'Pull from another instance',
       pullDialogChecking: 'Checking the local copy…',
@@ -186,7 +198,7 @@ window.__ModuleLoader__.load({
       appended: 'events appended',
       code_session_ahead: 'The peer has a longer copy of this session; send it as a new session.',
       code_session_diverged: 'The peer has a different copy of this session; send it as a new session.',
-      code_session_active: 'The session is open there; close it or stop its turn before updating it.',
+      code_session_active: 'The session is open there; close it or restart that instance before updating it.',
       code_session_unreadable: 'The stored session log could not be read, so the peer copy cannot be compared.',
       code_sessionForked: 'The two copies had diverged, so the push created a separate session on the peer.',
       files: 'files',
@@ -291,23 +303,31 @@ window.__ModuleLoader__.load({
       mergeInMenu: '合并已有目录（自动备份）',
       modeTitle: '推送方式',
       modeNew: '新建会话',
-      modeNewHint: '在对方创建一份独立副本，对方已有的内容不动。',
+      modeNewHint: '在对方创建独立副本，不动已有内容。',
       modeUpdate: '追加更新',
-      modeUpdateHint: '沿用同一个会话：补上对方缺少的事件，并合并工作区。',
-      modeUpdateUnavailable: '当前对端不可用',
+      modeUpdateHint: '只补上对方缺少的事件，并合并工作区。',
+      modeUpdateUnavailable: '当前对端不可追加',
+      blocked_state_open: '对方已打开该会话',
+      blocked_state_ahead: '对方副本更长',
+      blocked_state_diverged: '两边内容已不同',
+      blocked_state_absent: '对方没有此会话',
+      blocked_local_open: '本地已打开该会话',
+      blocked_local_ahead: '本地副本更长',
+      blocked_local_diverged: '两边内容已不同',
+      blocked_local_absent: '本地还没有此会话',
       state_absent: '对方没有此会话，将新建',
       state_behind: '对方已有 {have} 条，本次追加 {add} 条',
       state_same: '对方已有 {have} 条且内容一致，只同步工作区文件',
       state_ahead: '对方已有 {have} 条，比本地多，只能新建副本',
       state_diverged: '对方内容与本地不同，只能新建副本',
-      state_active: '对方已打开该会话，只能新建副本',
+      state_active: '对方已打开该会话；在那边关闭或重启实例后即可追加',
       state_unknown: '无法判断对方状态（离线，或对方插件较旧；追加更新需要两端同版本）',
       local_absent: '本地没有此会话，将新建',
       local_behind: '本地已有 {have} 条，本次追加 {add} 条',
       local_same: '本地已有 {have} 条且内容一致，只同步工作区文件',
       local_ahead: '本地已有 {have} 条，比远端多，只能新建副本',
       local_diverged: '本地内容与远端不同，只能新建副本',
-      local_active: '本地已打开该会话，只能新建副本',
+      local_active: '本地已打开该会话；关闭或重启本实例后即可追加',
       local_unknown: '无法判断本地状态',
       pullDialogTitle: '从其他实例拉取',
       pullDialogChecking: '正在检查本地副本…',
@@ -316,7 +336,7 @@ window.__ModuleLoader__.load({
       appended: '条事件已追加',
       code_session_ahead: '对方有比本地更长的副本，请改为新建会话推送。',
       code_session_diverged: '对方已有内容不同的同名会话，请改为新建会话推送。',
-      code_session_active: '该会话在对端/本地处于打开状态，请先关闭或停止后再更新。',
+      code_session_active: '该会话在对端/本地处于打开状态，请先关闭或重启实例后再更新。',
       code_session_unreadable: '会话日志无法读取，无法比较对方副本。',
       code_sessionForked: '两边内容已分叉，已在对方新建独立会话。',
       files: '文件',
@@ -960,6 +980,20 @@ window.__ModuleLoader__.load({
       return row.state === 'behind' || row.state === 'same';
     }
 
+    /**
+     * Why an in-place append is unavailable, phrased for the row it belongs to.
+     * @param {'state'|'local'} side - whose copy the row describes.
+     * @param {object | undefined} row - plan row.
+     * @param {(key: string) => string} t - translator.
+     * @returns {string} short reason.
+     */
+    function blockedReason(side, row, t) {
+      const reason = row?.active === true ? 'open' : (row?.state ?? 'unknown');
+      const key = `blocked_${side}_${reason}`;
+      const text = t(key);
+      return text === key ? t('modeUpdateUnavailable') : text;
+    }
+
     /**
      * Render one state line for a peer row (`state_*`) or a local plan row
      * (`local_*`).
@@ -1092,7 +1126,7 @@ window.__ModuleLoader__.load({
         }
       };
 
-      const modeOption = (value, label, hint, enabled) =>
+      const modeOption = (value, label, hint, enabled, reason) =>
         h(
           'label',
           { key: value, className: `ferry-mode-label ${enabled ? '' : 'disabled'}` },
@@ -1108,7 +1142,7 @@ window.__ModuleLoader__.load({
             'span',
             { className: 'ferry-mode-text' },
             h('span', null, label),
-            h('span', { className: 'ferry-modal-hint' }, hint),
+            h('span', { className: 'ferry-mode-hint' }, enabled ? hint : reason ?? t('modeUpdateUnavailable')),
           ),
         );
 
@@ -1149,30 +1183,25 @@ window.__ModuleLoader__.load({
                   { className: 'ferry-choice-body' },
                   h(
                     'div',
-                    { className: 'ferry-choice-row' },
-                    h(
-                      'span',
-                      { className: 'ferry-choice-name', title: candidate.name || candidate.id },
-                      candidate.name || candidate.id,
-                    ),
-                    h('span', { className: 'ferry-spacer' }),
-                    h(
-                      'span',
-                      { className: 'ferry-status' },
-                      h('span', { className: `ferry-dot ${candidate.online === true ? 'on' : 'off'}` }),
-                      h(
-                        'span',
-                        null,
-                        candidate.online === true && typeof candidate.latencyMs === 'number'
-                          ? `${candidate.latencyMs}${t('latency')}`
-                          : t('offline'),
-                      ),
-                    ),
+                    { className: 'ferry-choice-name', title: candidate.name || candidate.id },
+                    candidate.name || candidate.id,
                   ),
                   candidate.online === true
                     ? h('div', { className: 'ferry-state' }, stateLine('state', candidate, total, t))
                     : null,
                 ),
+                h(
+                  'span',
+                  { className: 'ferry-status' },
+                  h('span', { className: `ferry-dot ${candidate.online === true ? 'on' : 'off'}` }),
+                  h(
+                    'span',
+                    null,
+                    candidate.online === true && typeof candidate.latencyMs === 'number'
+                      ? `${candidate.latencyMs}${t('latency')}`
+                      : t('offline'),
+                  ),
+                ),
               ),
             ),
           ),
@@ -1229,13 +1258,14 @@ window.__ModuleLoader__.load({
             : h(
                 'div',
                 { className: 'ferry-mode' },
-                h('div', { className: 'ferry-modal-hint' }, t('modeTitle')),
+                h('div', { className: 'ferry-mode-title' }, t('modeTitle')),
                 modeOption('new', t('modeNew'), t('modeNewHint'), true),
                 modeOption(
                   'update',
                   t('modeUpdate'),
-                  canAppend ? t('modeUpdateHint') : `${t('modeUpdateHint')} · ${t('modeUpdateUnavailable')}`,
+                  t('modeUpdateHint'),
                   canAppend,
+                  blockedReason('state', selectedPeer, t),
                 ),
               ),
           mode === 'new'
@@ -1407,7 +1437,7 @@ window.__ModuleLoader__.load({
         }
       };
 
-      const modeOption = (value, label, hint, enabled) =>
+      const modeOption = (value, label, hint, enabled, reason) =>
         h(
           'label',
           { key: value, className: `ferry-mode-label ${enabled ? '' : 'disabled'}` },
@@ -1423,7 +1453,7 @@ window.__ModuleLoader__.load({
             'span',
             { className: 'ferry-mode-text' },
             h('span', null, label),
-            h('span', { className: 'ferry-modal-hint' }, hint),
+            h('span', { className: 'ferry-mode-hint' }, enabled ? hint : reason ?? t('modeUpdateUnavailable')),
           ),
         );
 
@@ -1448,18 +1478,19 @@ window.__ModuleLoader__.load({
           h(
             'div',
             { className: 'ferry-mode' },
-            h('div', { className: 'ferry-modal-hint' }, t('modeTitle')),
+            h('div', { className: 'ferry-mode-title' }, t('modeTitle')),
             modeOption('new', t('modeNew'), t('modeNewHint'), true),
             modeOption(
               'update',
               t('modeUpdate'),
-              canAppend ? t('modeUpdateHint') : `${t('modeUpdateHint')} · ${t('modeUpdateUnavailable')}`,
+              t('modeUpdateHint'),
               canAppend,
+              blockedReason('local', plan, t),
             ),
           ),
           h(
             'label',
-            { className: 'ferry-mode-text', style: { gap: '4px' } },
+            { className: 'ferry-stack' },
             h('span', { className: 'ferry-modal-hint' }, t('targetDir')),
             h('input', {
               className: 'ferry-input wide',

package/lib/ferry.js

@@ -285,6 +285,7 @@ export function createFerry({ ctx, config, transfer, log = () => {} }) {
             {
               sessionId,
               eventCount: description.session.eventCount,
+              conversationCount: description.session.conversationCount,
               createdAt: description.session.createdAt,
               formatVersion: description.session.formatVersion,
               sourceRoot: description.session.cwd,
@@ -362,6 +363,7 @@ export function createFerry({ ctx, config, transfer, log = () => {} }) {
         // With a fresh id, an id collision on the peer is not a conflict.
         sessionId: forkId ? undefined : sessionId,
         eventCount: description.session.eventCount,
+        conversationCount: description.session.conversationCount,
         createdAt: description.session.createdAt,
         formatVersion: description.session.formatVersion,
         // No target means the receiver applies its own mapping: reuse the
@@ -463,6 +465,7 @@ export function createFerry({ ctx, config, transfer, log = () => {} }) {
     const local = await transfer.preflight({
       sessionId,
       eventCount: description.session.eventCount,
+      conversationCount: description.session.conversationCount,
       createdAt: description.session.createdAt,
       formatVersion: description.session.formatVersion,
       sourceRoot: description.session.cwd,
@@ -513,6 +516,7 @@ export function createFerry({ ctx, config, transfer, log = () => {} }) {
     const local = await transfer.preflight({
       sessionId: forkId ? undefined : sessionId,
       eventCount: description.session.eventCount,
+      conversationCount: description.session.conversationCount,
       createdAt: description.session.createdAt,
       formatVersion: description.session.formatVersion,
       targetDir,

package/lib/routes.js

@@ -106,6 +106,7 @@ export function createPeerHandler({ config, ferry, transfer, log = () => {} }) {
           const decision = await transfer.preflight({
             sessionId: typeof body.sessionId === 'string' ? body.sessionId : undefined,
             eventCount: typeof body.eventCount === 'number' ? body.eventCount : undefined,
+            conversationCount: typeof body.conversationCount === 'number' ? body.conversationCount : undefined,
             createdAt: typeof body.createdAt === 'number' ? body.createdAt : undefined,
             formatVersion: typeof body.formatVersion === 'number' ? body.formatVersion : undefined,
             sourceRoot: typeof body.sourceRoot === 'string' ? body.sourceRoot : undefined,

package/lib/state.js

@@ -10,6 +10,13 @@
  */
 import { createHash } from 'node:crypto';
 
+/**
+ * Payload fields that hold a sequence number pointing at another event. They
+ * move when a log is renumbered, so they are compared as "a reference exists"
+ * rather than by value.
+ */
+const SEQ_REFERENCE_KEYS = new Set(['headerSeq', 'sourceEventSeq', 'shadowedSeqs', 'shadowedRange']);
+
 /** Number of trailing events that make up a tail fingerprint. */
 export const TAIL_EVENTS = 8;
 
@@ -63,12 +70,78 @@ function updateHash(hash, value) {
   for (const key of Object.keys(record).sort()) {
     hash.update(JSON.stringify(key));
     hash.update(':');
-    updateHash(hash, record[key]);
+    // Sequence references are derived positions, not content: an append that
+    // renumbers its tail must not read as a different conversation.
+    if (SEQ_REFERENCE_KEYS.has(key)) hash.update('"#seq"');
+    else updateHash(hash, record[key]);
     hash.update(',');
   }
   hash.update('}');
 }
 
+/**
+ * Event types each instance writes for its own runtime, not as conversation.
+ *
+ * DSH records the locally chosen model, sandbox mode, permission preset, and a
+ * seed marker on open. Two instances that ever opened the same session hold
+ * their own copies of these events, stamped with their own clocks and values;
+ * requiring them to match would report divergence on every healthy pair.
+ */
+export const LOCAL_EVENT_TYPES = new Set([
+  'session/end-seed',
+  'model/selection',
+  'sandbox/mode',
+  'permission/preset',
+  'agent-preset/selected',
+  'plan/mode',
+  'working-directory/change',
+  'goal/change',
+  'session/title',
+  'feedback/record',
+  'feedback/message-put',
+  'feedback/message-delete',
+]);
+
+/**
+ * Whether one event belongs to the shared conversation rather than local state.
+ * @param {object} event - session event.
+ * @returns {boolean} true when both copies must agree on it.
+ */
+export function isConversationEvent(event) {
+  return event === null || typeof event !== 'object' || !LOCAL_EVENT_TYPES.has(event.type);
+}
+
+/**
+ * Keep only the events both instances must agree on.
+ * @param {readonly object[]} events - session events, in seq order.
+ * @returns {object[]} conversation events.
+ */
+export function conversationEvents(events) {
+  return events.filter(isConversationEvent);
+}
+
+/**
+ * Drop the one field that is written locally rather than carried in the log.
+ *
+ * DSH appends a `session/end-seed` marker when a session is opened, stamped
+ * with the local clock. Two instances that open the same session therefore
+ * hold the same event at the same seq with different times; that difference is
+ * not a divergence, and treating it as one blocks every legitimate append.
+ * @param {object} event - session event.
+ * @returns {object} event as compared.
+ */
+function comparableEvent(event) {
+  if (event === null || typeof event !== 'object') return event;
+  // Position is the array index; the stored number moves when a tail is
+  // renumbered onto a peer's log, so it must not decide equality.
+  const { seq: _seq, ...rest } = event;
+  if (rest.type === 'session/end-seed' && 'time' in rest) {
+    const { time: _time, ...withoutTime } = rest;
+    return withoutTime;
+  }
+  return rest;
+}
+
 /**
  * Digest one contiguous slice of a session log.
  * @param {readonly object[]} events - session events, in seq order.
@@ -79,7 +152,7 @@ function updateHash(hash, value) {
 export function hashEvents(events, from = 0, to = events.length) {
   const hash = createHash('sha256');
   for (let index = from; index < to; index += 1) {
-    updateHash(hash, events[index]);
+    updateHash(hash, comparableEvent(events[index]));
     hash.update('\n');
   }
   return hash.digest('hex');

package/lib/transfer.js

@@ -15,7 +15,7 @@ import path from 'node:path';
 import { BundleReader, PROTOCOL, encodeBundle, validateManifest } from './bundle.js';
 import { HttpError } from './http.js';
 import { canonicalRoots, chooseImportTarget } from './paths.js';
-import { classifySession, hashEvents, readTail, tailOf } from './state.js';
+import { classifySession, conversationEvents, hashEvents, isConversationEvent, readTail, tailOf } from './state.js';
 import { hashFile, hashPlan, planWorkspace, resolveBelow } from './workspace.js';
 
 /** Event types whose payload may embed an attachment reference. */
@@ -276,6 +276,7 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
     }
     const records = await ctx.sessionPersistence.list({ signal });
     const children = records.filter((record) => record.header.parentSession === sessionId).length;
+    const conversation = conversationEvents(snapshot.events);
     return {
       session: {
         sessionId,
@@ -283,7 +284,8 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
         cwd: header.cwd,
         createdAt: header.createdAt,
         eventCount: snapshot.events.length,
-        tail: tailOf(snapshot.events),
+        conversationCount: conversation.length,
+        tail: tailOf(conversation),
         inheritedEventCount: snapshot.inheritedEventCount,
         origin: header.origin,
         agentPreset: header.agentPreset,
@@ -442,7 +444,8 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
         header,
         inheritedEventCount: snapshot.inheritedEventCount,
         eventCount: snapshot.events.length,
-        tail: tailOf(snapshot.events),
+        conversationCount: conversationEvents(snapshot.events).length,
+        tail: tailOf(conversationEvents(snapshot.events)),
         lastSeq: snapshot.events.at(-1)?.seq ?? -1,
         agentPreset: header.agentPreset,
         origin: header.origin,
@@ -504,9 +507,15 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
       );
     }
     const local = await readSnapshot(sessionId, signal);
-    const remoteCount = typeof sourceSession.eventCount === 'number' ? sourceSession.eventCount : undefined;
+    const mine = conversationEvents(local.events);
+    const remoteCount =
+      typeof sourceSession.conversationCount === 'number'
+        ? sourceSession.conversationCount
+        : typeof sourceSession.eventCount === 'number'
+          ? sourceSession.eventCount
+          : undefined;
     const state = classifySession(
-      { count: local.events.length, tail: tailOf(local.events) },
+      { count: mine.length, tail: tailOf(mine) },
       { count: remoteCount, tail: readTail(sourceSession.tail) },
     );
     if (state === 'same') return { mode: update ? 'update' : 'exists', snapshot: local };
@@ -705,21 +714,32 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
           events: rewriteAttachmentRefs(sessionPayload.events, attachmentReplacements),
         };
       }
-      // An update may only append: prove the receiver's log is an exact prefix
-      // of what arrived before touching either the log or the workspace.
+      // An update may only append: prove the receiver's conversation is a prefix
+      // of what arrived before touching either the log or the workspace. Each
+      // instance writes its own runtime events (model choice, seed marker), so
+      // those are compared away rather than read as divergence.
+      let appendFrom = 0;
       if (plan.mode === 'update') {
         const local = /** @type {{ events: object[] }} */ (plan.snapshot);
-        const shared = local.events.length;
+        const mine = conversationEvents(local.events);
+        const incoming = conversationEvents(sessionPayload.events);
         if (
-          sessionPayload.events.length < shared ||
-          hashEvents(sessionPayload.events, 0, shared) !== hashEvents(local.events, 0, shared)
+          incoming.length < mine.length ||
+          hashEvents(incoming, 0, mine.length) !== hashEvents(mine)
         ) {
+          const mismatch = firstDivergence(mine, incoming);
           throw new HttpError(
             409,
             'session-diverged',
-            `Session "${sessionId}" has diverged from this instance's copy; import it under a new id instead`,
+            `Session "${sessionId}" has diverged from this instance's copy${
+              mismatch === undefined ? '' : ` at event ${mismatch.seq} (${mismatch.type})`
+            }; import it under a new id instead`,
           );
         }
+        // Runtime events may sit at different positions on either side, so the
+        // new tail starts at the sender's next conversation event, not at the
+        // receiver's raw length.
+        appendFrom = appendOffset(sessionPayload.events, mine.length);
       }
       const header = {
         ...sessionPayload.header,
@@ -739,13 +759,37 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
       const workspace = await ctx.workspaceRegistry.create(target);
       workspaceId = workspace.id;
       if (plan.mode === 'update') {
-        const shared = /** @type {{ events: object[] }} */ (plan.snapshot).events.length;
-        const handle = await ctx.sessionPersistence.open(sessionId, 'write', { signal });
+        const shared = appendFrom;
+        // The receiver may hold more events than the sender at the same
+        // conversation position (it wrote its own runtime markers), so the
+        // appended batch is renumbered to continue the receiver's log.
+        const local = /** @type {{ events: object[] }} */ (plan.snapshot);
+        const sourceEvents = sessionPayload.events;
+        const nextSeq = local.events.length;
+        const delta = nextSeq - (sourceEvents[shared]?.seq ?? shared);
+        const tail = sourceEvents.slice(shared).map((event, index) => {
+          const seq = nextSeq + index;
+          return seq === event.seq ? event : renumberEvent(event, seq, delta, shared);
+        });
+        let handle;
         try {
-          const events = sessionPayload.events;
-          for (let offset = shared; offset < events.length; offset += 200) {
+          handle = await ctx.sessionPersistence.open(sessionId, 'write', { signal });
+        } catch (error) {
+          // The owner can appear between preflight and the upload; report it as
+          // the state it is instead of an internal error.
+          if (error instanceof Error && error.name === 'SessionAlreadyOwnedError') {
+            throw new HttpError(
+              409,
+              'session-active',
+              `Session "${sessionId}" is open on this instance; close it or restart the instance before updating it`,
+            );
+          }
+          throw error;
+        }
+        try {
+          for (let offset = 0; offset < tail.length; offset += 200) {
             signal?.throwIfAborted();
-            await handle.append(events.slice(offset, offset + 200), { signal });
+            await handle.append(tail.slice(offset, offset + 200), { signal });
           }
           await handle.flush({ signal });
         } finally {
@@ -767,7 +811,7 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
           sessionId,
           targetDir: target,
           workspaceId,
-          appended: sessionPayload.events.length - shared,
+          appended: tail.length,
           events: sessionPayload.events.length,
           attachments: { rewritten: attachmentReplacements.size },
           workspace: {
@@ -861,6 +905,7 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
     targetDir,
     merge = false,
     tail,
+    conversationCount,
   }) => {
     const target = await resolveImportTarget({ requested: targetDir, sourceRoot, sessionId });
     const currentVersion = await currentFormatVersion();
@@ -898,10 +943,14 @@ export function createTransfer({ ctx, config, rules, log = () => {} }) {
             }`,
           };
         }
-        localCount = snapshot.events.length;
+        const conversation = conversationEvents(snapshot.events);
+        localCount = conversation.length;
         state = classifySession(
-          { count: localCount, tail: tailOf(snapshot.events) },
-          { count: eventCount, tail: readTail(tail) },
+          { count: localCount, tail: tailOf(conversation) },
+          {
+            count: typeof conversationCount === 'number' ? conversationCount : eventCount,
+            tail: readTail(tail),
+          },
         );
         if (state === 'unknown') {
           // A sender predating tail fingerprints only reports its creation time.
@@ -965,6 +1014,87 @@ async function* once(buffer) {
   if (buffer !== undefined && buffer.length > 0) yield buffer;
 }
 
+/**
+ * Rewrite one event for a log that numbers the same content differently.
+ * @param {object} event - source event.
+ * @param {number} seq - sequence number it takes in the receiver's log.
+ * @param {number} delta - shift applied to the receiver-relative numbering.
+ * @param {number} from - first sender seq that belongs to the shifted tail.
+ * @returns {object} renumbered event.
+ */
+function renumberEvent(event, seq, delta, from) {
+  const next = { ...event, seq };
+  if (event.data !== null && typeof event.data === 'object') {
+    next.data = shiftSeqRefs(event.data, delta, from);
+  }
+  return next;
+}
+
+/**
+ * Shift the sequence references a payload may hold into the receiver's numbering.
+ * @param {unknown} value - payload value.
+ * @param {number} delta - shift for references inside the moved tail.
+ * @param {number} from - first sender seq that belongs to the moved tail.
+ * @returns {unknown} rewritten value.
+ */
+function shiftSeqRefs(value, delta, from) {
+  if (Array.isArray(value)) return value.map((item) => shiftSeqRefs(item, delta, from));
+  if (value === null || typeof value !== 'object') return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if ((key === 'headerSeq' || key === 'sourceEventSeq') && Number.isSafeInteger(item) && item >= from) {
+      out[key] = item + delta;
+      continue;
+    }
+    if (key === 'shadowedSeqs' && Array.isArray(item)) {
+      out[key] = item.map((entry) => (Number.isSafeInteger(entry) && entry >= from ? entry + delta : entry));
+      continue;
+    }
+    if (key === 'shadowedRange' && item !== null && typeof item === 'object') {
+      out[key] = {
+        ...item,
+        ...(Number.isSafeInteger(item.start) && item.start >= from ? { start: item.start + delta } : {}),
+        ...(Number.isSafeInteger(item.end) && item.end >= from ? { end: item.end + delta } : {}),
+      };
+      continue;
+    }
+    out[key] = shiftSeqRefs(item, delta, from);
+  }
+  return out;
+}
+
+/**
+ * Raw index in the incoming log where the receiver's new events begin.
+ * @param {readonly object[]} incoming - incoming session events.
+ * @param {number} matched - conversation events the receiver already holds.
+ * @returns {number} index into `incoming`; past the end when nothing is new.
+ */
+function appendOffset(incoming, matched) {
+  let seen = 0;
+  for (let index = 0; index < incoming.length; index += 1) {
+    if (!isConversationEvent(incoming[index])) continue;
+    if (seen === matched) return index;
+    seen += 1;
+  }
+  return incoming.length;
+}
+
+/**
+ * Find the first event two conversation logs disagree on, for diagnostics.
+ * @param {readonly object[]} mine - receiver events.
+ * @param {readonly object[]} incoming - incoming events.
+ * @returns {{ seq: number, type: string } | undefined} first mismatch.
+ */
+function firstDivergence(mine, incoming) {
+  const shared = Math.min(mine.length, incoming.length);
+  for (let index = 0; index < shared; index += 1) {
+    if (hashEvents([mine[index]]) !== hashEvents([incoming[index]])) {
+      return { seq: mine[index].seq, type: String(mine[index].type) };
+    }
+  }
+  return shared === incoming.length ? { seq: mine[shared]?.seq ?? shared, type: 'missing event' } : undefined;
+}
+
 /**
  * Reject a merge that would follow a symlinked parent directory out of the
  * workspace. The manifest paths are already lexical-safe; this closes the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ferry",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Move Sessions and their Workspace between DSH instances over any reachable network.",
   "license": "MIT",