@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/types/tools/info.d.ts

@@ -0,0 +1,102 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Config } from '../index.ts';
+import type { CardCacheEntry, InFlightRoute, RouteActivityEntry } from '../runtime.ts';
+import type { A2aPeerCard } from '../types.ts';
+import type { ZoneCardFetch } from '../zone.ts';
+import type { A2aClient, CardFetchOutcome } from '../a2a-client.ts';
+import type { CanvasStore } from '../canvas-store.ts';
+import type { ExposureStore } from '../exposure-store.ts';
+import type { IdempotencyStore } from '../idempotency-store.ts';
+import type { JoinedSessions } from '../joined-store.ts';
+import type { PeerStore } from '../peer-store.ts';
+import type { TaskLedger } from '../task-ledger.ts';
+import type { TeamMembershipStore } from '../team-store.ts';
+/** One directory row shared with listDirectoryTeams (which stays in index.ts). */
+export type DirectoryTeamRow = {
+    team: string;
+    session: string;
+    name: string;
+    description: string;
+    local?: boolean;
+    origin?: string;
+    workspace?: string;
+    via?: string;
+    legacy?: boolean; /** gh#106: the peer's last card fetch missed — this row is its kept card, not a live answer. */
+    unreachable?: boolean;
+    teams?: string[]; /** Internal S5 scope hint, stripped before the tool's public output. */
+    canvasMembers?: readonly string[];
+};
+/** Everything the information-plane tools capture from apply(). */
+export interface InfoToolsDeps {
+    readonly ctx: Context;
+    readonly config: Config;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly session: string;
+    readonly lanIp: string;
+    readonly ownCardUrl: string;
+    readonly peerStore: PeerStore;
+    readonly taskLedger: TaskLedger;
+    readonly joinedSessions: JoinedSessions;
+    readonly teamMemberships: TeamMembershipStore;
+    readonly canvasStore: CanvasStore;
+    readonly exposureStore: ExposureStore;
+    readonly idempotencyStore: IdempotencyStore;
+    readonly cardCache: Map<string, CardCacheEntry>;
+    readonly inFlightRoutes: Map<number, InFlightRoute>;
+    readonly recentActivity: RouteActivityEntry[];
+    readonly teamAuditRing: {
+        at: number;
+        action: 'join' | 'leave' | 'archive-prune' | 'agent-less';
+        team: string;
+        id: string;
+        ok: boolean;
+        reason?: string;
+    }[];
+    readonly reportRing: {
+        at: number;
+        level: 'info' | 'warning' | 'error';
+        message: string;
+        session: string;
+        task?: string;
+    }[];
+    readonly sessionNodes: Map<string, Agent>;
+    readonly ownerAllowlist: readonly string[];
+    readonly ownerTeamScopeInfo: boolean;
+    readonly id8: (id: string) => string;
+    readonly sessionTeamOf: (agent: Agent) => string;
+    readonly nodeMetadataOf: (agent: Agent) => {
+        name: string;
+        description: string;
+        workspace?: string;
+    };
+    readonly canvasTeamOf: (name: string) => string;
+    /** gh#152: the session's canvas teams read through the local lens — a handle-stored membership of this session counts. */
+    readonly canvasTeamsOfSession: (id: string) => string[];
+    /** Resolve a handle against the current local/seeded-peer collision snapshot. */
+    readonly localHandleResolver: () => (ref: string) => string | undefined;
+    readonly memoizedCardFetch: () => ZoneCardFetch;
+    readonly mapBounded: <T, R>(items: readonly T[], limit: number, task: (item: T) => Promise<R>) => Promise<R[]>;
+    readonly SWEEP_CONCURRENCY: number;
+    readonly a2aJoinGateRefusal: (exec: {
+        agent?: {
+            id: unknown;
+        };
+    } | undefined) => void;
+    readonly observeAuthorization: (cause: string) => void;
+    readonly settlePeerCard: (peer: string, outcome: CardFetchOutcome) => A2aPeerCard | undefined;
+    readonly client: A2aClient;
+    readonly listDirectoryTeams: (expand: boolean, includeCanvas?: boolean) => Promise<DirectoryTeamRow[]>;
+}
+/**
+ * Build the five registrars. Call createInfoTools after its deps exist, then
+ * invoke each registrar at the tool's original registration position — the
+ * registry order the model sees must not change.
+ */
+export declare function createInfoTools(deps: InfoToolsDeps): {
+    registerWhoami: () => void;
+    registerTeams: () => void;
+    registerStatus: () => void;
+    registerTasks: () => void;
+    registerProbe: () => void;
+};

package/lib/types/types.d.ts

@@ -129,6 +129,12 @@ export interface A2aRouteOk {
      * receipt-owed (`trackOwedTask` skips it).
      */
     readonly bridge?: 'native-teams';
+    /**
+     * gh#141: the peer refused the settlement the delivered message carried
+     * (its enforce verdict, `settlement: {status: 'refused'}` on the wire,
+     * #139) — the delivery landed, the debt it named stays owed there.
+     */
+    readonly settlementRefused?: true;
 }
 /** Canonical `a2a_route` failure value. */
 export interface A2aRouteError {

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

@@ -13,16 +13,17 @@
  */
 
 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 }
+  | { type: 'remove-team'; name: string; /** set when the frame is a REMOTE peer's team: the owner dissolves it, through the relay. */ fleetPeer?: string }
   /** `ops` comes from reorderOps() at emit time; the wire stays model-free. */
   | { type: 'reorder'; team: string; ops: ReadonlyArray<RosterOp> }
   /** Network-level join/leave (the session joins the A2A mesh) — distinct from canvas-team membership. */
@@ -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/federation.ts

@@ -70,6 +70,7 @@ export function peerHostOf(url: string): string {
 /** One remote team row as the directory reports it (state.remote). */
 export interface RemoteTeamRow {
   team: string
+  unreachable?: boolean
   name?: string
   via?: string
   workspace?: string

package/nexus-stage/src/main.ts

@@ -154,28 +154,34 @@ const canvasWire = createCanvasWire({
   onNotice: (kind, text) => planning.notice(kind, text),
 })
 
+/** One relayed op on a REMOTE peer's team. THIS host signs the envelope
+ *  and forwards; the peer's link gate authorizes the write. */
+async function fleetOp(peer: string, op: 'add-member' | 'remove-member' | 'remove', name: string, id?: string): Promise<boolean> {
+  const r = await controlFetch('/__dsh_a2a/fleet-canvas-op', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ peer, op, name, ...(id !== undefined ? { id } : {}) }),
+    cache: 'no-store',
+  }).catch(() => undefined)
+  const body = r !== undefined ? await r.json().catch(() => undefined) : undefined
+  if (body?.ok === true && op === 'remove' && body.removed === false) planning.notice('info', `属主那边已没有「${name}」，无需解散`)
+  if (body?.ok === true) return 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
+}
+
 function runCanvasAction(a: CanvasAction): Promise<boolean> {
-  // gh#41: a remote-frame drop forks to the fleet relay — THIS host signs
-  // the envelope and forwards; the peer's link gate authorizes the write.
+  // gh#41: a remote-frame drop forks to the fleet relay; so does dissolving
+  // a mirror frame (single owner + mirror: the owner's store is the truth).
   if ((a.type === 'add-member' || a.type === 'remove-member') && a.fleetPeer !== undefined) {
+    const peer = a.fleetPeer
     return (async () => {
-      for (const id of a.ids) {
-        const r = await controlFetch('/__dsh_a2a/fleet-canvas-op', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ peer: a.fleetPeer, op: a.type === 'add-member' ? 'add-member' : 'remove-member', name: a.team, id }),
-          cache: 'no-store',
-        }).catch(() => undefined)
-        const body = r !== undefined ? await r.json().catch(() => undefined) : undefined
-        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
-        }
-      }
+      for (const id of a.ids) if (!(await fleetOp(peer, a.type, a.team, id))) return false
       return true
     })()
   }
+  if (a.type === 'remove-team' && a.fleetPeer !== undefined) return fleetOp(a.fleetPeer, 'remove', a.name)
   switch (a.type) {
     case 'create-team': return canvasWire.createTeam(a.name, a.ids, a.created)
     case 'add-member': return canvasWire.addMembers(a.team, a.ids)
@@ -200,6 +206,9 @@ async function postNetworkJoin(action: 'join' | 'leave', id: string): Promise<bo
 }
 
 let lampState: LampState = 'idle'
+// The nodes face reports effective scoped assemblies; a mounted registration alone does not prove visibility.
+let nodePromptMissing = new Set<string>()
+let nodePromptCheckedAt = 0
 let canvasFace = false
 let lastLayoutJson: string | undefined
 /** True once any layout answer (saved doc or an explicit null) has been
@@ -375,13 +384,25 @@ async function poll(): Promise<void> {
     const res = await controlFetch('/__dsh_a2a/state', { cache: 'no-store' })
     if (!res.ok) throw new Error(`/__dsh_a2a/state ${res.status}`)
     const body = (await res.json()) as StateBody
+    if (Date.now() - nodePromptCheckedAt >= 15_000) {
+      nodePromptCheckedAt = Date.now()
+      try {
+        const nodes = await controlFetch('/__dsh_a2a/nodes', { cache: 'no-store' })
+        if (!nodes.ok) throw new Error(`nodes ${nodes.status}`)
+        const view = await nodes.json() as { bindings?: Array<{ session: string; mounted: unknown; effective: { core: boolean; mutable: boolean } | null }> }
+        nodePromptMissing = new Set((view.bindings ?? [])
+          .filter(b => b.mounted !== null && b.effective !== null && (b.effective.core === false || b.effective.mutable === false))
+          .map(b => b.session))
+      } catch { nodePromptMissing.clear() } // unavailable is unknown, not confirmed missing
+    }
+    const shown = { ...body, sessions: (body.sessions ?? []).map(s => ({ ...s, ...(nodePromptMissing.has(s.id) ? { nodePromptMissing: true } : {}) })) }
     clearFault()
     // canvasFace first: bench.update reads board.available() to pick the
     // mode, so assigning it afterwards held the very first paint in data
     // mode (board display:none, 0px wide) until the next 3s poll — and the
     // board's first reconcile measured a zero-width view.
     canvasFace = body.canvas !== undefined
-    bench.update(body)
+    bench.update(shown)
 
     // ── The layout answer precedes the first reconcile on purpose ──
     // The board's first build reads `layoutDoc` for saved positions and
@@ -429,15 +450,17 @@ async function poll(): Promise<void> {
         name: r.name,
         via: r.via,
         workspace: r.workspace,
+        ...(r.unreachable === true ? { unreachable: true } : {}),
         ...(typeof r.origin === 'string' && r.origin !== '' ? { origin: r.origin } : {}),
         ...(Array.isArray(r.teams) && r.teams.length > 0 ? { teams: r.teams.filter((t): t is string => typeof t === 'string' && t !== '') } : {}),
       }))
     // gh#41: the peers' published canvas org rides the board (remote frames).
     const peerOrg = (body.peerOrg as unknown[] ?? [])
-      .filter((r): r is { url?: unknown; org?: unknown } => r !== null && typeof r === 'object')
+      .filter((r): r is { url?: unknown; org?: unknown; unreachable?: unknown } => r !== null && typeof r === 'object')
       .filter(r => typeof r.url === 'string' && Array.isArray(r.org))
       .map(r => ({
         url: r.url as string,
+        ...(r.unreachable === true ? { unreachable: true } : {}),
         org: (r.org as unknown[])
           .filter((e): e is { name?: unknown; team?: unknown; members?: unknown } => e !== null && typeof e === 'object')
           .filter(e => typeof e.team === 'string' && e.team !== '')

package/nexus-stage/src/planning-member-handles.ts

@@ -0,0 +1,34 @@
+/** Pure joined-local-handle projection for remote organization members. */
+import type { RemoteTeamRow } from './federation'
+import type { SessionLite } from './world'
+
+type HandleSession = Pick<SessionLite, 'id' | 'team' | 'joined'>
+
+/** Map only unique joined id8 handles that no remote directory row already owns. */
+export function joinedLocalIdsByHandle(sessions: ReadonlyArray<HandleSession>, publishedHandles: ReadonlySet<string>): Map<string, string> {
+  const localIds = new Map<string, string>()
+  const ambiguous = new Set<string>()
+  for (const session of sessions) {
+    if (session.joined !== true) continue
+    const slash = session.team.lastIndexOf('/')
+    if (slash <= 0 || session.team.slice(slash + 1) !== session.id.replace(/^session-/, '').slice(0, 8)) continue
+    const handle = session.team
+    if (publishedHandles.has(handle) || ambiguous.has(handle)) continue
+    if (localIds.has(handle)) {
+      localIds.delete(handle)
+      ambiguous.add(handle)
+    } else {
+      localIds.set(handle, session.id)
+    }
+  }
+  return localIds
+}
+
+/** Project a remote canvas member to its local card or stable synthetic card id. */
+export function remoteMemberBoardId(member: string, localIdsByHandle: ReadonlyMap<string, string>, remoteTeams: ReadonlyArray<RemoteTeamRow> | undefined, peerUrl: string): string {
+  const localId = localIdsByHandle.get(member)
+  if (localId !== undefined) return localId
+  if (member.includes('/')) return `member-${member.replace(/[^a-z0-9-]/gi, '-')}`
+  const peerZone = remoteTeams?.find(row => row.via === peerUrl)?.team.split('/')[0] ?? 'dsh'
+  return `member-${peerZone}-${member.replace(/^session-/, '').slice(0, 8)}`
+}

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

@@ -4,9 +4,9 @@
  * 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.
+ * answers (the relay then re-reads the owner's card in the background, and
+ * the owner's own change ping backs it up). Local frames carry no marker —
+ * this host is their owner.
  * @module nexus-stage/planning-mirror
  */
 import { peerHostOf } from './federation'
@@ -29,3 +29,47 @@ export function mirrorRoute(ownerUrl: string | undefined, syncing: boolean): Mir
     syncing,
   }
 }
+
+type MirrorOrg = ReadonlyArray<{ readonly url: string; readonly org: ReadonlyArray<{ readonly name: string }> }>
+
+/** After the owner accepted a dissolve, hide its team at most this long: a
+ *  peer's late add-member re-creates the team on the owner, and then it is
+ *  real again even though the owner's org never stopped listing it. */
+export const DISSOLVE_HIDE_MS = 10_000
+
+/**
+ * 解散 on a mirror frame: the frame stays gone from the moment the dissolve
+ * is sent until the owner's published org stops listing the team (or
+ * DISSOLVE_HIDE_MS after the owner accepted). Without this, a poll that lands
+ * while the relay is in flight — or before the owner's card is re-read —
+ * draws the frame again (and keeps its saved rect for a later team of the
+ * same name). Keyed by owner AND name: two owners may both have a team X.
+ */
+export function createDissolveGuard(now: () => number = Date.now) {
+  const key = (ownerUrl: string, name: string): string => `${ownerUrl}\u0000${name}`
+  const dissolving = new Map<string, { url: string; name: string; acceptedAt?: number }>()
+  return {
+    /** Mark the dissolve and return the action carrying its owner (the relay fork). */
+    fork<A extends { type: 'remove-team'; name: string }>(act: A, ownerUrl: string): A & { fleetPeer: string } {
+      dissolving.set(key(ownerUrl, act.name), { url: ownerUrl, name: act.name })
+      return { ...act, fleetPeer: ownerUrl }
+    },
+    /** The owner answered: a refusal (or a failed channel) lets the frame back now, an acceptance starts the clock. */
+    settled(act: { type: string; name?: string; fleetPeer?: string }, ok: boolean): void {
+      if (act.type !== 'remove-team' || act.name === undefined || act.fleetPeer === undefined) return
+      const entry = dissolving.get(key(act.fleetPeer, act.name))
+      if (entry === undefined) return
+      if (ok) entry.acceptedAt = now()
+      else dissolving.delete(key(act.fleetPeer, act.name))
+    },
+    /** True while this owner's team is being (or has just been) dissolved here. */
+    hides(name: string, ownerUrl: string): boolean { return dissolving.has(key(ownerUrl, name)) },
+    /** Forget a dissolve once its owner's org no longer lists the team, or once its time is up. */
+    sweep(peerOrg: MirrorOrg): void {
+      for (const [k, e] of dissolving) {
+        const listed = peerOrg.find(row => row.url === e.url)?.org.some(t => t.name === e.name) === true
+        if (!listed || (e.acceptedAt !== undefined && now() - e.acceptedAt > DISSOLVE_HIDE_MS)) dissolving.delete(k)
+      }
+    },
+  }
+}

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

@@ -0,0 +1,28 @@
+/** Project the peer's last missed card read onto existing remote cards and frames. */
+import { peerHostOf, type RemoteTeamRow } from './federation'
+
+export const UNREACHABLE_HINT = '对端未应答（显示的是最后已知状态）'
+
+export function unreachableRefs(input: {
+  remoteTeams?: ReadonlyArray<RemoteTeamRow>
+  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean }>
+}): { hosts: ReadonlySet<string>; members: ReadonlySet<string> } {
+  const hosts = new Set<string>()
+  for (const row of input.remoteTeams ?? []) if (row.unreachable === true && row.via) hosts.add(peerHostOf(row.via))
+  for (const row of input.peerOrg ?? []) if (row.unreachable === true) hosts.add(peerHostOf(row.url))
+  const members = new Set<string>()
+  for (const row of input.remoteTeams ?? []) if (row.via && hosts.has(peerHostOf(row.via))) members.add(`member-${row.team.replace(/[^a-z0-9-]/gi, '-')}`)
+  return { hosts, members }
+}
+
+/** A mirror keeps its last known contents visible but warns until its owner responds again. */
+export function showFrameReachability(frame: HTMLElement, lost: boolean): void {
+  frame.classList.toggle('is-unreachable', lost)
+  const existing = frame.querySelector('.p-frame-unreachable')
+  if (lost && existing === null) {
+    const hint = document.createElement('span')
+    hint.className = 'p-frame-unreachable'
+    hint.textContent = UNREACHABLE_HINT
+    frame.appendChild(hint)
+  } else if (!lost) existing?.remove()
+}

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

@@ -26,7 +26,7 @@ export interface PlanningInput {
   remoteTeams?: ReadonlyArray<RemoteTeamRow>
   /** gh#41 fleet planning: each tracked peer's published canvas org —
    *  rendered as REMOTE team frames (read + cross-host regulation). */
-  peerOrg?: ReadonlyArray<{ url: string; org: ReadonlyArray<{ name: string; team: string; members: readonly string[] }> }>
+  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean; org: ReadonlyArray<{ name: string; team: string; members: readonly string[] }> }>
 }
 
 /** Screen-width class a viewport is remembered under (window width, not board width — collapsing the rail must not switch buckets). */