@nelsonlongxiang/dsh-open-a2a-net 0.6.29 → 0.6.31

package/lib/types/faces/wire.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The /a2a/* wire faces (gh#77 batch B2; slice 2 adds log + query).
+ *
+ * Moved verbatim out of apply() in src/index.ts: the routes register when
+ * the web server settles, exactly as before. What used to be closure
+ * captures arrives through WireDeps and is destructured once below, so the
+ * route bodies read as they did in index.ts (the B1 admin.ts pattern). The
+ * one accessor deviation: the log face's `legacyInboundCount += 1` (a let in
+ * index.ts) goes through `d.bumpLegacyInbound()`, the same mutable-binding
+ * treatment admin.ts gives its six lets. direct stays inline for slice 3.
+ * @module src/faces/wire
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+import type { A2aPeerCard } from '../types.ts';
+import { CanvasStore } from '../canvas-store.ts';
+import type { CliDepositStore } from '../cli-deposit.ts';
+import type { IdempotencyStore } from '../idempotency-store.ts';
+import type { JoinedSessions } from '../joined-store.ts';
+import { type TaskLedger } from '../task-ledger.ts';
+import type { Config } from '../index.ts';
+/** The cold-wake answer (mirrors index.ts's local ColdWake). */
+export type ColdWake = {
+    readonly kind: 'flight';
+    readonly flight: Promise<Agent>;
+} | {
+    readonly kind: 'no-face';
+} | {
+    readonly kind: 'archived';
+} | {
+    readonly kind: 'no-match';
+};
+/** routeIntoAgent's settled answer (mirrors index.ts's local union). */
+export type RouteOutcome = {
+    ok: true;
+    reply: string;
+    status?: string;
+    bridge?: 'native-teams';
+    placeholder?: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+interface BridgeTeamsRegistryMirror {
+    listTeams(): Array<{
+        name: string;
+        description: string;
+    }>;
+    describeTarget(handle: string): Promise<{
+        plane: 'local' | 'a2a';
+        ambiguous?: boolean;
+        localLabel?: string;
+    }>;
+    startRound(args: {
+        team?: string;
+        message: string;
+    }, parent: {
+        id: string;
+        session: {
+            events?: readonly unknown[];
+        };
+    }, signal: AbortSignal): Promise<string>;
+}
+/** nativeTeamsPrepare's answer (mirrors index.ts's local union). */
+export type NativePrepared = {
+    readonly ok: true;
+    readonly teams: BridgeTeamsRegistryMirror;
+    readonly parent: {
+        id: string;
+        session: {
+            events?: readonly unknown[];
+        };
+    };
+} | {
+    readonly ok: false;
+    readonly reason: 'not-claimed';
+} | {
+    readonly ok: false;
+    readonly reason: 'error';
+    readonly error: string;
+};
+/** nativeTeamsRound's settled answer (mirrors index.ts's local union). */
+export type NativeRoundOutcome = {
+    readonly ok: true;
+    readonly reply: string;
+    readonly settled: boolean;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly phase?: 'pre-dispatch';
+    readonly aborted?: boolean;
+};
+/** What verifyOriginClaim answers (see index.ts; reason widens to string here — the faces only interpolate it). */
+export type OriginClaimResult = {
+    ok: true;
+    caller: string;
+    callerUrl: string;
+    card: A2aPeerCard;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The closure captures the wire faces read (grows with each extracted face). */
+export interface WireDeps {
+    readonly ctx: Context;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly config: Config;
+    readonly cliDeposits: CliDepositStore;
+    readonly canvasStore: CanvasStore;
+    readonly sessionNodes: Map<string, Agent>;
+    readonly joinedSessions: JoinedSessions;
+    readonly idempotencyStore: IdempotencyStore;
+    readonly verifyOriginClaim: (req: IncomingMessage) => Promise<OriginClaimResult>;
+    readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
+    readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
+    readonly bumpLegacyInbound: () => void;
+    readonly secretEqual: (a: string, b: string) => boolean;
+    readonly a2aCallerRefusal: (caller: string, targetTeam?: string) => string | undefined;
+    readonly scanSessionLogList: () => Array<{
+        id: string;
+        mtimeMs: number;
+        sizeBytes: number;
+    }>;
+    readonly readSessionLogTail: (id: string, limit: number) => {
+        ok: true;
+        id: string;
+        messages: Array<{
+            role: string;
+            text: string;
+            time?: number;
+        }>;
+    } | {
+        ok: false;
+        error: string;
+    };
+    readonly taskLedger: TaskLedger;
+    readonly refuseIfFlooded: (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
+    readonly settleAndAnnounce: (message: string) => void;
+    readonly touchWakeDemand: () => void;
+    readonly session: string;
+    readonly resolveAgentForTeam: (team: string) => Agent | undefined;
+    readonly parseCanvasTeamName: (team: string) => string | undefined;
+    readonly canvasLiveAgent: (name: string | undefined, skipId?: string) => Agent | undefined;
+    readonly wakeColdTeam: (team: string, skipId?: string) => ColdWake;
+    readonly probeConsumption: (agent: Agent, taskId: string) => boolean;
+    readonly steerRelay: (agent: Agent, text: string, sender?: string) => void;
+    readonly fromClause: (from: string) => string;
+    readonly armReceiptAutosend: (target: Agent, taskId: string, callerTeam: string | undefined, deliveredText: string) => void;
+    readonly receiptExpectationOf: (receiptTarget: string) => 'receivable' | 'process-label';
+    readonly armAsyncNudge: (agent: Agent, team: string, taskId: string, delayMs: number) => void;
+    readonly liveAgent: () => Agent | undefined;
+    readonly callerIsAgent: (agent: Agent, caller: string) => boolean;
+    readonly selfRouteText: (team: string) => string;
+    readonly noWakeFaceText: (team: string) => string;
+    readonly archivedColdMatchText: (team: string) => string;
+    readonly noColdMatchText: (team: string) => string;
+    readonly nativeTeamsPrepare: (team: string) => Promise<NativePrepared>;
+    readonly nativeTeamsRound: (prepared: Extract<NativePrepared, {
+        ok: true;
+    }>, team: string, caller: string, message: string, taskId: string | undefined) => Promise<NativeRoundOutcome>;
+    readonly routeIntoAgent: (team: string, message: string, caller: string, taskId?: string) => Promise<RouteOutcome>;
+}
+/**
+ * Register the small wire faces on a settled web server.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link WireDeps}.
+ */
+export declare function registerWireFaces(webServer: WebServer, d: WireDeps): void;
+export {};

package/lib/types/flood-guard.d.ts

@@ -0,0 +1,29 @@
+/** gh#91 transitional ingress brakes. One guard per apply(), never process-global.
+ * Run AFTER admission, OriginClaim and the fresh idempotency claim, BEFORE
+ * settlement/mailbox/steer. Replays keep 409 and spend no delivery quota.
+ * All refusals carry a stable reason, task id, failed query outcome and an
+ * activity event. This is not the independent file channel or deployment.
+ */
+import type { ServerResponse } from 'node:http';
+import type { IdempotencyStore } from './idempotency-store.ts';
+export declare const WIRE_ERROR_RATE_LIMITED = -32008;
+export declare const MAX_PARTS_PER_TRANSFER = 16;
+export declare const DEFAULT_RATE_PER_MINUTE = 16;
+type Reason = 'sender-rate-limited' | 'file-parts-exceeded' | 'file-part-invalid' | 'file-part-duplicate' | 'flood-state-full';
+export declare class FloodGuard {
+    private readonly now;
+    private readonly senders;
+    private readonly transfers;
+    constructor(now?: () => number);
+    /** Check/admit one fresh task. No timer; maps and per-key sets are bounded.
+     * Active transfer entries NEVER evict to make space (which would reset a
+     * transfer's allowance); capacity exhaustion refuses visibly instead.
+     * Counts are boot-local: restart resets them, disclosed in the guide.
+     */
+    check(caller: string, message: string): Reason | undefined;
+}
+/** Host-scoped adapter; rejected fresh keys are FAILED, not stranded pending.
+ * HTTP 200 retains the existing client's structured peer-error path.
+ */
+export declare function createFloodGuard(outcomes: Pick<IdempotencyStore, 'recordOutcome'>, recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void): (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
+export {};

package/lib/types/runtime.d.ts

@@ -31,4 +31,5 @@ export interface InFlightRoute {
 export interface CardCacheEntry {
     at: number;
     card: A2aPeerCard | undefined;
+    missAt?: number;
 }

package/lib/types/task-ledger.d.ts

@@ -53,7 +53,7 @@ export type TaskStatus = 'pending' | 'dead';
 /** F5 layer-3: why a dead row aged out (stamped by the sweep at flip time). */
 export type DeadReason = 'fire-forget' | 'unconsumed';
 /** gh#31: which archive path ended a row — a receipt, a content echo, or the caller. */
-export type ArchiveEnd = 'receipt' | 'echo' | 'abandoned' | 'cancelled';
+export type ArchiveEnd = 'receipt' | 'echo' | 'abandoned' | 'cancelled' | 'evicted';
 /** One tracked outbound task still in the owed book (unsettled). */
 export interface TaskRecord {
     readonly taskId: string;
@@ -323,6 +323,14 @@ export declare class TaskLedger {
     resolveEcho(message: string): string[];
     /** Move one settled record to the archive head, trimming at the cap. */
     private archiveSettled;
+    /**
+     * gh#86 (chief order direct-4f596524): when the owed book exceeds
+     * TASK_CAP, the overflow rows go to the ARCHIVE as evicted - visible
+     * for audit, never silently dropped. The review seat's recommendation,
+     * chief-endorsed: the silent cap slice lost the oldest pending rows
+     * with no trace. L8 criterion: zero silently-dropped.
+     */
+    private trimOwed;
     /** Lazy dead-letter sweep: overdue pending rows flip status, at most once. */
     private sweep;
     /** Load a persisted snapshot on construction, if present. */

package/nexus-stage/src/canvas-ops.ts

@@ -13,13 +13,14 @@
  */
 
 import { nodeRect, deriveInitialFrame, type WorldModel } from './world'
+import type { LayoutDoc } from './layout-doc'
 
 /** One pre-computed host op (remove = remove-member, add = add-member). */
 export type RosterOp = { op: 'remove' | 'add'; id: string }
 
 /** The five user-facing write actions (one per design.md §3.3 row), plus the two network join/leave actions the panel-slim migration moved into the planning view. */
 export type CanvasAction =
-  | { type: 'create-team'; name: string; ids: readonly string[]; /** true when the model had no such team before this action (a serial failure then leaves a ghost EMPTY team on the host — the wire compensates with a remove). */ created?: boolean }
+  | { type: 'create-team'; name: string; ids: readonly string[]; /** true when the model had no such team before this action; NOT server creation provenance and never authority to delete on failure. */ created?: boolean }
   | { type: 'add-member'; team: string; ids: readonly string[]; /** gh#41: set when the target frame is a REMOTE peer's team — the wire routes the op through the host fleet relay. */ fleetPeer?: string }
   | { type: 'remove-member'; team: string; ids: readonly string[]; /** gh#41: see add-member. */ fleetPeer?: string }
   | { type: 'remove-team'; name: string }
@@ -123,6 +124,20 @@ export function applyAction(model: WorldModel, a: CanvasAction): Undo {
   }
 }
 
+/** Settle the optimistic delta and forget geometry only for a removed frame.
+ * Never prune all saved frames: remote/offline teams may be absent this poll.
+ * The caller schedules a correcting save even on rollback, so an earlier
+ * in-flight layout POST cannot leave optimistic geometry persisted forever.
+ */
+export function settleAction(model: WorldModel, a: CanvasAction, ok: boolean, undo: Undo, layout: LayoutDoc | undefined): LayoutDoc | undefined {
+  if (!ok) undo()
+  const removed = (a.type === 'remove-team' && ok) || (a.type === 'create-team' && !ok && a.created === true)
+  if (!removed || layout === undefined || model.getFrame(actionTeam(a)) !== undefined) return layout
+  const frames = { ...layout.frames }
+  delete frames[actionTeam(a)]
+  return { ...layout, frames }
+}
+
 /**
  * The minimal remove+add walk that turns `current` into `desired` on a
  * host whose add-member always APPENDS: walk desired positions in order;

package/nexus-stage/src/canvas-wire.ts

@@ -7,14 +7,12 @@
  * Classification per request:
  * - `ok:true`                                    → success (silent)
  * - `ok:false` WITH an `error` string            → error notice, verbatim
- * - `ok:false` without `error` (absent target,   → idempotent no-op,
- *   member cap hit)                                silent success
+ * - `ok:false` without `error` → success only when returned members/teams
+ *   prove the requested idempotent effect; cap/unknown results are failures
  * - HTTP >= 400                                  → body error verbatim, else `HTTP <status>`
  * - send() throws                                → `画布不可达：<message>`
- * - 200 + ok:false WITHOUT an error string       → idempotent no-op
- *   (absent target, member/team cap hit) — silent success
- * - 200 + non-JSON body (proxy artifact)         → classified as success
- *   (known limitation: nothing parseable to classify)
+ * - missing success acknowledgement (including non-JSON transport errors)
+ *   → visible failure, never a confirmed join
  *
  * Ops on the same team run through a serial queue (a later gesture waits
  * instead of racing; cross-team ops run in parallel) - mirrors the
@@ -38,10 +36,9 @@ export interface CanvasWireDeps {
 }
 
 export interface CanvasWire {
-  /** create → add-member per id, serial, first failure stops. `created`:
-   *  the team did not exist model-side before this action — a first-add
-   *  failure would then leave a ghost EMPTY team on the host, compensated
-   *  with a best-effort remove. */
+  /** create → add-member per id, serial, first failure stops. `created` is
+   * a model-side hint ONLY, never server creation provenance. A failed add
+   * cannot authorize deleting a same-name team; preserve it for retry. */
   createTeam(name: string, ids: readonly string[], created?: boolean): Promise<boolean>
   addMembers(team: string, ids: readonly string[]): Promise<boolean>
   removeMembers(team: string, ids: readonly string[]): Promise<boolean>
@@ -54,7 +51,7 @@ export interface CanvasWire {
 type RosterOp = { op: 'remove' | 'add'; id: string }
 
 function errorText(body: CanvasWireResult['body']): string | undefined {
-  return typeof body.error === 'string' ? body.error : undefined
+  return body != null && typeof body.error === 'string' ? body.error : undefined
 }
 
 export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
@@ -97,13 +94,25 @@ export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
       deps.onNotice('error', errorText(res.body) ?? `HTTP ${res.status}`)
       return false
     }
-    if (res.body.ok === true) return true
-    const text = errorText(res.body)
+    if (res.body?.ok === true) return true
+    const text = res.body != null && typeof res.body === 'object' ? errorText(res.body) : undefined
     if (text !== undefined) {
       deps.onNotice('error', text)
       return false
     }
-    return true // ok:false without error: idempotent no-op (absent target / cap)
+    // A bare false can mean a capacity refusal, not just an idempotent no-op.
+    // Accept a no-op only when the host's returned state proves the effect.
+    const name = String(body.name ?? ''), id = String(body.id ?? '')
+    const members = res.body?.members, teams = res.body?.teams
+    const memberProof = Array.isArray(members) && members.every(v => typeof v === 'string')
+    const teamProof = Array.isArray(teams) && teams.every(v => typeof v === 'string')
+    if (res.body?.ok === false && (
+      (body.action === 'add-member' && memberProof && members.includes(id)) ||
+      (body.action === 'remove-member' && memberProof && !members.includes(id)) ||
+      (body.action === 'remove' && teamProof && !teams.includes(name))
+    )) return true
+    deps.onNotice('error', '画布操作未确认：' + String(body.action) + '（可能队伍/成员已达上限，请重试）')
+    return false
   }
 
   async function serial(body: Record<string, unknown>, ids: readonly string[]): Promise<boolean> {
@@ -114,15 +123,14 @@ export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
   }
 
   return {
-    createTeam(name, ids, created = false) {
+    createTeam(name, ids) {
       return enqueue(name, async () => {
         if (!(await raw({ action: 'create', name }))) return false
         for (let i = 0; i < ids.length; i++) {
           if (!(await raw({ action: 'add-member', name, id: ids[i]! }))) {
-            // A failure on the FIRST add of a team this action created leaves
-            // a ghost EMPTY team on the host — compensate with a remove.
-            // Later failures keep whatever members genuinely joined.
-            if (created && i === 0) await raw({ action: 'remove', name })
+            // Local absence does not prove server-side creation. Never issue
+            // an unconditional compensating remove: an idempotent create may
+            // have reused an existing team (including one already at capacity).
             return false
           }
         }

package/nexus-stage/src/main.ts

@@ -167,7 +167,11 @@ function runCanvasAction(a: CanvasAction): Promise<boolean> {
           cache: 'no-store',
         }).catch(() => undefined)
         const body = r !== undefined ? await r.json().catch(() => undefined) : undefined
-        if (body?.ok !== true) return false
+        if (body?.ok !== true) {
+          // Say WHY the peer refused (not linked, untrusted origin, unknown member…), not just that it did.
+          planning.notice('error', `跨主机团队操作失败：${String(body?.error ?? '对端无响应')}`)
+          return false
+        }
       }
       return true
     })()

package/nexus-stage/src/planning-edges.ts

@@ -0,0 +1,26 @@
+/**
+ * The membership spokes' SVG layer (edges.ts stays pure geometry). Moved
+ * out of planning-view (module-size cap) when pointercancel landed.
+ * @module nexus-stage/planning-edges
+ */
+import { starEdges } from './edges'
+import type { WorldModel } from './world'
+
+/**
+ * Stateless, rebuilt wholesale. Derived from the MODEL (not the host's
+ * teams): optimistic membership changes must repaint their edges
+ * immediately, before the host confirms.
+ */
+export function drawMemberEdges(svg: SVGSVGElement, model: WorldModel): void {
+  while (svg.firstChild !== null) svg.firstChild.remove()
+  const teams = model.allFrames().map(([name]) => ({ name, members: model.teamMemberIds(name).map(id => ({ id })) }))
+  for (const e of starEdges(teams, new Map(model.allFrames()), model.positions())) {
+    const line = document.createElementNS('http://www.w3.org/2000/svg', 'line')
+    line.setAttribute('class', 'e-member' + (e.dashed ? ' dashed' : ''))
+    line.setAttribute('x1', String(e.x1))
+    line.setAttribute('y1', String(e.y1))
+    line.setAttribute('x2', String(e.x2))
+    line.setAttribute('y2', String(e.y2))
+    svg.appendChild(line)
+  }
+}

package/nexus-stage/src/planning-mirror.ts

@@ -0,0 +1,31 @@
+/**
+ * Owner vs mirror on the board (owner ruling 2026-10-29, PR#96: canvas sync
+ * is single owner + mirror). A team belongs to the host that made it; every
+ * other host renders it as a MIRROR of that host's published card and edits
+ * it through the fleet relay. The frame head says so: 「镜像 · <owner host>」,
+ * and 「同步中…」 from the moment a relayed edit is sent until the owner
+ * answers (the relay refreshes the owner's card before replying, so the next
+ * poll already shows the result). Local frames carry no marker — this host
+ * is their owner.
+ * @module nexus-stage/planning-mirror
+ */
+import { peerHostOf } from './federation'
+
+export interface MirrorRoute {
+  readonly text: string
+  readonly title: string
+  readonly syncing: boolean
+}
+
+/** The route line of a remote (mirrored) frame; undefined for a local frame. */
+export function mirrorRoute(ownerUrl: string | undefined, syncing: boolean): MirrorRoute | undefined {
+  if (ownerUrl === undefined) return undefined
+  const host = peerHostOf(ownerUrl)
+  return {
+    text: syncing ? `同步中… · ${host}` : `镜像 · ${host}`,
+    title: syncing
+      ? `已把改动交给属主 ${host}，等待它确认`
+      : `这个团队属于 ${host}，这里显示的是它的镜像；拖入或移出成员会经中继交给 ${host} 执行`,
+    syncing,
+  }
+}

package/nexus-stage/src/planning-overlap.ts

@@ -9,9 +9,14 @@
  *   frame the user just touched stays where it was put; a remote org frame
  *   never moves on its own (gh#44: its rect is the user's), so a local frame
  *   yields to it; two remote frames are left alone.
- * - Card vs frame: a card lying on a frame it does not belong to moves just
- *   outside that frame (right of it, else below it, else right of every
- *   frame). Members are never moved off their own frame.
+ * - Card vs frame: a card lying on a frame it does not belong to goes home
+ *   first — the first free grid seat inside its own frame (memberships in
+ *   state order) — and only a card with no frame (or no free seat) goes
+ *   outside: right of that frame, else below it, else down a column right of
+ *   every frame. No landing spot covers another card or a foreign frame, and
+ *   frames are never moved or resized by this step. Members are never moved
+ *   off their own frame; a member merely outside its frame (PR#85: a frame
+ *   moves only itself) is left where it is.
  * Callers run it after a frame drag or resize, after 整理成员 / 一键重排,
  * and once when the board first has content — never on every poll (a poll
  * does not reposition what the user arranged).
@@ -74,22 +79,45 @@ export function separateFrames(model: WorldModel, remote: ReadonlySet<string>, t
   return changed
 }
 
+/** Grid of the 整理成员 layout, shared by eviction seats. */
+const PAD = 28
+const GAP_X = 16
+const GAP_Y = 14
+
+/** Card-centred seats inside a frame, row by row (the 整理成员 grid). */
+function seatsIn(f: Rect): Array<{ x: number; y: number }> {
+  const out: Array<{ x: number; y: number }> = []
+  for (let y = f.y + PAD; y + NODE_H <= f.y + f.h - PAD; y += NODE_H + GAP_Y) {
+    for (let x = f.x + PAD; x + NODE_W <= f.x + f.w - PAD; x += NODE_W + GAP_X) out.push({ x: x + NODE_W / 2, y: y + NODE_H / 2 })
+  }
+  return out
+}
+
 /** Move cards off frames they do not belong to; true when anything moved. */
 export function evictStrangers(model: WorldModel): boolean {
   let changed = false
   const frames = model.allFrames()
-  const clear = (r: Rect, own: ReadonlySet<string>): boolean => frames.every(([name, f]) => own.has(name) || !hit(r, f))
+  const rectOf = new Map(frames)
   for (const n of model.allNodes()) {
     const own = new Set(n.memberships.map(m => m.team))
-    const r = nodeRect(n)
-    const host = frames.find(([name, f]) => !own.has(name) && hit(r, f))
+    const host = frames.find(([name, f]) => !own.has(name) && hit(nodeRect(n), f))
     if (host === undefined) continue
     const f = host[1]
-    const at = (x: number, y: number): Rect => ({ x: x - NODE_W / 2, y: y - NODE_H / 2, w: NODE_W, h: NODE_H })
+    // Free = no foreign frame and no other card under it (cards read live: earlier evictions count).
+    const free = (p: { x: number; y: number }): boolean => {
+      const r = nodeRect(p)
+      return frames.every(([name, g]) => own.has(name) || !hit(r, g)) &&
+        model.allNodes().every(o => o.id === n.id || !hit(r, nodeRect(o)))
+    }
+    const home = n.memberships.map(m => rectOf.get(m.team)).filter((g): g is FrameGeom => g !== undefined)
+    const seat = home.flatMap(seatsIn).find(free)
     const right = { x: f.x + f.w + OVERLAP_GAP + NODE_W / 2, y: n.y }
     const below = { x: n.x, y: f.y + f.h + OVERLAP_GAP + NODE_H / 2 }
+    // Last resort: a column right of every frame, top-down from this frame. A card blocks
+    // at most two seats of this pitch, so 2·cards+1 seats always hold a free one.
     const farX = Math.max(...frames.map(([, g]) => g.x + g.w)) + OVERLAP_GAP + NODE_W / 2
-    const to = clear(at(right.x, right.y), own) ? right : clear(at(below.x, below.y), own) ? below : { x: farX, y: n.y }
+    const column = Array.from({ length: 2 * model.allNodes().length + 1 }, (_, i) => ({ x: farX, y: f.y + NODE_H / 2 + i * (NODE_H + GAP_Y) }))
+    const to = seat ?? [right, below, ...column].find(free) ?? column[column.length - 1]!
     model.dragNodes([n.id], to.x - n.x, to.y - n.y)
     changed = true
   }
@@ -109,9 +137,6 @@ export function settleBoard(model: WorldModel, remote: ReadonlySet<string>, touc
  * fit them. Members of 2+ teams keep their positions.
  */
 export function tidyMembers(model: WorldModel): void {
-  const PAD = 28
-  const GAP_X = 16
-  const GAP_Y = 14
   for (const [name, rect] of model.allFrames()) {
     const sole = model.teamMemberIds(name)
       .map(id => model.getNode(id))

package/nexus-stage/src/planning-types.ts

@@ -105,6 +105,7 @@ export interface PlanningView {
     pointerDown(ev: SeamPointer): void
     pointerMove(ev: SeamPointer): void
     pointerUp(ev: SeamPointer): void
+    pointerCancel(ev: SeamPointer): void
     wheel(ev: SeamPointer): void
     key(ev: SeamKey): void
     keyUp(ev: SeamKey): void

package/nexus-stage/src/planning-undo.ts

@@ -0,0 +1,68 @@
+/**
+ * 撤销 for the board layout (frontend seat, 2026-10-29): with no status-bar
+ * hint for automatic moves (owner: 载入时避让挪了卡片，不需要在状态条提示),
+ * a wrong move must be one keystroke away from undone. Covers card drags,
+ * frame drags and resizes, keyboard nudges, 整理成员, 一键重排 and the
+ * load-time settle — positions and frame rects only. Team membership
+ * (入队 / 离队, host writes) is not undone here.
+ *
+ * capture() before an edit, commit(before) after it: only an edit that
+ * actually moved something already on the board is recorded, so a click,
+ * a pan or a marquee leaves the stack alone, and a card that arrived by
+ * poll mid-gesture is not counted as a move. revert(before) is for a
+ * gesture the OS cancelled (pointercancel): layout back, nothing recorded.
+ * @module nexus-stage/planning-undo
+ */
+import type { FrameGeom, WorldModel } from './world'
+
+export interface LayoutSnap {
+  readonly nodes: ReadonlyMap<string, { readonly x: number; readonly y: number }>
+  readonly frames: ReadonlyMap<string, FrameGeom>
+}
+
+/** Undo depth (older steps fall off). */
+export const UNDO_LIMIT = 30
+
+export function createLayoutUndo(model: WorldModel) {
+  const stack: LayoutSnap[] = []
+  const capture = (): LayoutSnap => ({
+    nodes: new Map(model.allNodes().map(n => [n.id, { x: n.x, y: n.y }])),
+    frames: new Map(model.allFrames().map(([name, f]) => [name, { ...f }])),
+  })
+  /** True when something present both before and now has moved or changed size. */
+  const moved = (before: LayoutSnap): boolean =>
+    model.allNodes().some(n => { const b = before.nodes.get(n.id); return b !== undefined && (b.x !== n.x || b.y !== n.y) }) ||
+    model.allFrames().some(([name, f]) => { const b = before.frames.get(name); return b !== undefined && (b.x !== f.x || b.y !== f.y || b.w !== f.w || b.h !== f.h) })
+  const restore = (snap: LayoutSnap): void => {
+    for (const n of model.allNodes()) {
+      const b = snap.nodes.get(n.id)
+      if (b !== undefined && (b.x !== n.x || b.y !== n.y)) model.dragNodes([n.id], b.x - n.x, b.y - n.y)
+    }
+    for (const [name, f] of model.allFrames()) {
+      const b = snap.frames.get(name)
+      if (b !== undefined && (b.x !== f.x || b.y !== f.y || b.w !== f.w || b.h !== f.h)) model.setFrame(name, { ...b })
+    }
+  }
+  return {
+    capture,
+    commit(before: LayoutSnap): void {
+      if (!moved(before)) return
+      stack.push(before)
+      if (stack.length > UNDO_LIMIT) stack.shift()
+    },
+    /** Restore the last recorded layout; false when there is nothing to undo. */
+    undo(): boolean {
+      const snap = stack.pop()
+      if (snap === undefined) return false
+      restore(snap)
+      return true
+    },
+    /** Put back `before` without recording a step (an abandoned gesture); true when something moved. */
+    revert(before: LayoutSnap): boolean {
+      if (!moved(before)) return false
+      restore(before)
+      return true
+    },
+    get depth(): number { return stack.length },
+  }
+}