@yancyyu/openhermit 1.6.42 → 1.6.43

package/src/main/services/teams-mvp/TeamWorkspaceService.test.ts

@@ -0,0 +1,207 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TeamWorkspaceService } from './TeamWorkspaceService';
+import type { GroupMessage } from './TeamWorkspaceService';
+
+// CLAUDE.md 把 "server-side appendMessage ID propagation" 列为零覆盖的关键回归路径：
+// 去重管线按 id 去重，若 appendMessage 重新生成 id，同一条逻辑消息会得到不同 id →
+// 重复消息回归。这里直测真实文件 IO 实现（TaskDispatchService.test.ts 用的是 FakeWorkspace，
+// 完全绕过真实落盘）。
+const PREV_HERMIT_HOME = process.env.HERMIT_HOME;
+let tmpHome = '';
+
+function svc() {
+  return new TeamWorkspaceService();
+}
+
+afterAll(() => {
+  if (PREV_HERMIT_HOME === undefined) delete process.env.HERMIT_HOME;
+  else process.env.HERMIT_HOME = PREV_HERMIT_HOME;
+});
+
+beforeEach(() => {
+  tmpHome = path.join(
+    os.tmpdir(),
+    `hermit-tws-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  process.env.HERMIT_HOME = tmpHome;
+});
+
+afterEach(async () => {
+  await fs.promises.rm(tmpHome, { recursive: true, force: true });
+});
+
+describe('TeamWorkspaceService.appendMessage — message pipeline', () => {
+  it('preserves a caller-supplied id (dedup guarantee: never regenerates)', async () => {
+    const out = await svc().appendMessage('alpha', { id: 'fixed-1', from: 'user', content: 'hi' });
+    expect(out.id).toBe('fixed-1');
+    // 第二条用相同显式 id 仍各自落盘（去重发生在渲染层，service 不负责丢弃）。
+    await svc().appendMessage('alpha', { id: 'fixed-1', from: 'user', content: 'dup' });
+    const msgs = await svc().readMessages('alpha');
+    expect(msgs.map((m) => m.id)).toEqual(['fixed-1', 'fixed-1']);
+    expect(msgs.map((m) => m.content)).toEqual(['hi', 'dup']);
+  });
+
+  it('generates an m_-prefixed id when none is supplied', async () => {
+    const out = await svc().appendMessage('alpha', { from: 'agent-7', content: 'x' });
+    expect(out.id).toMatch(/^m_/);
+    expect(out.id.length).toBeGreaterThan(4);
+  });
+
+  it('stamps a server-side ISO ts and defaults `to` to "team"', async () => {
+    const out = await svc().appendMessage('alpha', { from: 'user', content: 'x' });
+    expect(out.ts).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    expect(out.to).toBe('team');
+  });
+
+  it('derives role from `from` and honors an explicit role override', async () => {
+    const s = svc();
+    const user = await s.appendMessage('alpha', { from: 'user', content: 'u' });
+    const agent = await s.appendMessage('alpha', { from: 'agent-7', content: 'a' });
+    const system = await s.appendMessage('alpha', {
+      from: 'agent-7',
+      role: 'system',
+      content: 's',
+    });
+    expect(user.role).toBe('user');
+    expect(agent.role).toBe('agent');
+    expect(system.role).toBe('system');
+  });
+
+  it('passes meta through (null default + object preserved)', async () => {
+    const s = svc();
+    const noMeta = await s.appendMessage('alpha', { from: 'user', content: 'a' });
+    const withMeta = await s.appendMessage('alpha', {
+      from: 'user',
+      content: 'b',
+      meta: { taskId: 't_1', mentions: ['@d'] },
+    });
+    expect(noMeta.meta).toBeNull();
+    expect(withMeta.meta).toEqual({ taskId: 't_1', mentions: ['@d'] });
+  });
+
+  it('persists each message as its own newline-delimited JSONL line', async () => {
+    const s = svc();
+    await s.appendMessage('alpha', { id: 'a', from: 'user', content: 'first' });
+    await s.appendMessage('alpha', { id: 'b', from: 'user', content: 'second' });
+    const file = path.join(tmpHome, 'teams', 'alpha', 'messages', 'group.jsonl');
+    const raw = await fs.promises.readFile(file, 'utf8');
+    const lines = raw.split('\n').filter(Boolean);
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).id).toBe('a');
+    expect(JSON.parse(lines[1]).id).toBe('b');
+  });
+
+  it('readMessages round-trips appended messages sorted by ts', async () => {
+    const s = svc();
+    await s.appendMessage('alpha', { id: 'm1', from: 'user', content: 'one' });
+    await s.appendMessage('alpha', { id: 'm2', from: 'user', content: 'two' });
+    await s.appendMessage('alpha', { id: 'm3', from: 'user', content: 'three' });
+    const msgs = await s.readMessages('alpha');
+    expect(msgs.map((m) => m.id)).toEqual(['m1', 'm2', 'm3']);
+    for (let i = 1; i < msgs.length; i++) {
+      expect(msgs[i].ts.localeCompare(msgs[i - 1].ts)).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('readMessages returns [] for an external platform session slug', async () => {
+    await expect(svc().readMessages('feishu:some-session')).resolves.toEqual([]);
+  });
+
+  it('appendMessage rejects an external platform session slug', async () => {
+    await expect(
+      svc().appendMessage('feishu:some-session', { from: 'user', content: 'x' })
+    ).rejects.toThrow(/外部平台/);
+  });
+
+  it('survives a corrupted JSONL line on read (skips unparseable lines)', async () => {
+    const s = svc();
+    await s.appendMessage('alpha', { id: 'good', from: 'user', content: 'ok' });
+    const file = path.join(tmpHome, 'teams', 'alpha', 'messages', 'group.jsonl');
+    await fs.promises.appendFile(file, '{ not valid json\n');
+    const msgs = await s.readMessages('alpha');
+    expect(msgs.map((m: GroupMessage) => m.id)).toEqual(['good']);
+  });
+});
+
+describe('TeamWorkspaceService task board', () => {
+  it('createTask requires a title', async () => {
+    await expect(svc().createTask('alpha', { title: '' } as never)).rejects.toThrow('title');
+  });
+
+  it('createTask assigns incrementing order within a column and round-trips', async () => {
+    const s = svc();
+    const t1 = await s.createTask('alpha', { title: 'A' });
+    const t2 = await s.createTask('alpha', { title: 'B' });
+    const t3 = await s.createTask('alpha', { title: 'C', status: 'done' });
+    expect(t1.id).toMatch(/^t_/);
+    expect(t1.order).toBe(0);
+    expect(t2.order).toBe(1); // same 'todo' column increments
+    expect(t3.order).toBe(0); // different column ('done') starts fresh
+    expect(t3.status).toBe('done');
+    const tasks = await s.readTasks('alpha');
+    expect(tasks.map((t) => t.title).sort()).toEqual(['A', 'B', 'C']);
+  });
+
+  it('patchTask updates fields, bumps updatedAt, and pins id/teamSlug', async () => {
+    const s = svc();
+    const t = await s.createTask('alpha', { title: 'A' });
+    const patched = await s.patchTask('alpha', t.id, { status: 'doing', assignee: 'w1' });
+    expect(patched.status).toBe('doing');
+    expect(patched.assignee).toBe('w1');
+    expect(patched.id).toBe(t.id);
+    expect(patched.teamSlug).toBe('alpha');
+    expect(patched.updatedAt).not.toBe(t.updatedAt);
+  });
+
+  it('patchTask throws for an unknown id', async () => {
+    await expect(svc().patchTask('alpha', 'nope', { status: 'done' })).rejects.toThrow('not found');
+  });
+
+  it('deleteTask returns true when removed, false when absent, and persists', async () => {
+    const s = svc();
+    const t = await s.createTask('alpha', { title: 'A' });
+    expect(await s.deleteTask('alpha', 'nope')).toBe(false);
+    expect(await s.deleteTask('alpha', t.id)).toBe(true);
+    expect(await s.readTasks('alpha')).toEqual([]);
+  });
+
+  // F-4 (gstack-QA TEAM-010-007): a cross-team dispatch writes a received task
+  // onto the TARGET team's board via createOrReuseReceivedTask → createTask. The
+  // target team's kanban (GET /api/teams/:name/tasks → readTasks) must reflect it
+  // — read and write share resolveStorageSlug + teamRoot, so this is the
+  // read-after-write guarantee that the reported "API returns []" contradicted.
+  // (The cited route /api/teams/:name/board does not exist; the real route is
+  // /tasks. This test pins target-side visibility with the dispatchMeta intact.)
+  it('a dispatched received task is visible on the target team board (dispatchMeta round-trip)', async () => {
+    const s = svc();
+    const dispatchMeta = {
+      dispatchId: 'loop-cross-team-test-1',
+      originTeam: 'team-jcve',
+      targetTeam: 'team-4',
+      status: 'received' as const,
+      dispatchedAt: '2026-06-14T08:26:32.118Z',
+      receivedAt: '2026-06-14T08:26:32.118Z',
+    };
+    const created = await s.createTask('team-4', {
+      title: '[TEAM-010-005] cross-team dispatch arrival',
+      description: '@team-4 ...',
+      status: 'todo',
+      dispatchMeta,
+    });
+
+    // Re-read from disk the same way the board endpoint does.
+    const tasks = await s.readTasks('team-4');
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0].id).toBe(created.id);
+    expect(tasks[0].status).toBe('todo');
+    expect(tasks[0].dispatchMeta).toEqual(dispatchMeta);
+
+    // A second, unrelated read of a different team must NOT bleed the task over
+    // (guards against a slug-misroute false visible/invisible).
+    expect(await s.readTasks('team-jcve')).toEqual([]);
+  });
+});

package/src/main/services/teams-mvp/TeamWorkspaceService.ts

@@ -12,11 +12,11 @@
  *   └─ tasks/board.json       # 任务看板
  */
 
+import { resolveExternalPlatformSessionTeamSlug } from '@main/utils/externalPlatformSessionRouting';
+import { createLogger } from '@shared/utils/logger';
 import * as fs from 'fs';
-import * as path from 'path';
 import * as os from 'os';
-
-import { createLogger } from '@shared/utils/logger';
+import * as path from 'path';
 
 const logger = createLogger('TeamWorkspace');
 
@@ -33,7 +33,7 @@ export interface TeamManifest {
   bindProject: string;
   /** agent 类型，用于 MCP 配置注入等 harness 特定逻辑 */
   harness: string;
-  /** agent 工作目录（cc-connect project work_dir） */
+  /** agent runtime 工作目录（cc-connect project work_dir） */
   workDir: string;
   color?: string;
   description?: string;
@@ -91,6 +91,7 @@ export interface GroupMessage {
 }
 
 export interface AppendGroupMessageInput {
+  id?: string;
   from: string;
   to?: string;
   role?: GroupMessage['role'];
@@ -136,6 +137,18 @@ export function toSlug(input: string, fallback = 'team'): string {
   return ascii || fallback;
 }
 
+export function isValidBindProject(value: string): boolean {
+  return /^[a-z0-9][a-z0-9_-]*$/.test(value);
+}
+
+function assertValidBindProject(value: string): void {
+  if (!isValidBindProject(value)) {
+    throw new Error(
+      'bindProject must contain only lowercase ASCII letters, digits, hyphens, and underscores, and start with a letter or digit'
+    );
+  }
+}
+
 export function teamsRoot(): string {
   return path.join(hermitHome(), 'teams');
 }
@@ -144,6 +157,10 @@ export function teamRoot(teamSlug: string): string {
   return path.join(teamsRoot(), teamSlug);
 }
 
+function isExternalPlatformSlug(teamSlug: string): boolean {
+  return /^(feishu|lark|weixin|telegram|discord|slack):/.test(teamSlug);
+}
+
 export function groupSessionKey(teamSlug: string): string {
   return `hermit:${teamSlug}:session`;
 }
@@ -179,16 +196,46 @@ async function writeJson(p: string, data: unknown): Promise<void> {
 // ---------------------------------------------------------------------------
 
 export class TeamWorkspaceService {
+  private async readTeamManifestByStorageSlug(storageSlug: string): Promise<TeamManifest> {
+    const root = teamRoot(storageSlug);
+    const manifest = await readJson<TeamManifest | null>(path.join(root, 'team.json'), null);
+    if (!manifest) {
+      if (!(await pathExists(root))) {
+        throw new Error(`团队 "${storageSlug}" 不存在 (${root})`);
+      }
+      const stat = await fs.promises.stat(root).catch(() => null);
+      return {
+        schemaVersion: 2,
+        slug: storageSlug,
+        displayName: storageSlug,
+        bindProject: storageSlug,
+        harness: 'claudecode',
+        workDir: '',
+        collaboration: true,
+        rootPath: root,
+        createdAt: (stat?.birthtime ?? stat?.mtime ?? new Date()).toISOString(),
+      };
+    }
+    return manifest;
+  }
+
   private async resolveStorageSlug(teamSlug: string): Promise<string> {
     if (await pathExists(path.join(teamRoot(teamSlug), 'team.json'))) {
       return teamSlug;
     }
-    const match = (await this.listTeams()).find((manifest) => manifest.bindProject === teamSlug);
-    return match?.slug ?? teamSlug;
+    const teams = await this.listTeams();
+    const directMatch = teams.find((manifest) => manifest.bindProject === teamSlug);
+    if (directMatch) return directMatch.slug;
+    if (isExternalPlatformSlug(teamSlug)) {
+      const platformMatch = resolveExternalPlatformSessionTeamSlug(teamSlug, teams);
+      if (platformMatch) return platformMatch;
+    }
+    return teamSlug;
   }
 
-  private async createUniqueStorageSlug(displayName: string): Promise<string> {
-    const baseSlug = toSlug(displayName);
+  private async createUniqueStorageSlug(bindProject: string): Promise<string> {
+    assertValidBindProject(bindProject);
+    const baseSlug = bindProject;
     let slug = baseSlug;
     let suffix = 2;
     while (await pathExists(path.join(teamRoot(slug), 'team.json'))) {
@@ -201,11 +248,14 @@ export class TeamWorkspaceService {
   async createTeam(
     input: CreateTeamInput
   ): Promise<{ slug: string; root: string; manifest: TeamManifest }> {
-    if (!input.displayName) throw new Error('displayName is required');
-    if (!input.bindProject) throw new Error('bindProject is required');
+    const displayName = input.displayName.trim();
+    const bindProject = input.bindProject.trim();
+    if (!displayName) throw new Error('displayName is required');
+    if (!bindProject) throw new Error('bindProject is required');
     if (!input.workDir) throw new Error('workDir is required');
+    assertValidBindProject(bindProject);
 
-    const slug = await this.createUniqueStorageSlug(input.bindProject);
+    const slug = await this.createUniqueStorageSlug(bindProject);
     const root = teamRoot(slug);
 
     await fs.promises.mkdir(root, { recursive: true });
@@ -215,8 +265,8 @@ export class TeamWorkspaceService {
     const manifest: TeamManifest = {
       schemaVersion: 2,
       slug,
-      displayName: input.displayName,
-      bindProject: input.bindProject,
+      displayName,
+      bindProject,
       harness: input.harness,
       workDir: input.workDir,
       color: input.color,
@@ -230,43 +280,17 @@ export class TeamWorkspaceService {
     };
 
     await writeJson(path.join(root, 'team.json'), manifest);
-    logger.info(`created team ${slug} → cc-project:${input.bindProject}`);
+    logger.info(`created team ${slug} → cc-project:${bindProject}`);
     return { slug, root, manifest };
   }
 
   async readTeamManifest(teamSlug: string): Promise<TeamManifest> {
-    const root = teamRoot(teamSlug);
-    const manifest = await readJson<TeamManifest | null>(path.join(root, 'team.json'), null);
-    if (!manifest) {
-      if (!(await pathExists(root))) {
-        throw new Error(`团队 "${teamSlug}" 不存在 (${root})`);
-      }
-      const stat = await fs.promises.stat(root).catch(() => null);
-      return {
-        schemaVersion: 2,
-        slug: teamSlug,
-        displayName: teamSlug,
-        bindProject: teamSlug,
-        harness: 'claudecode',
-        workDir: '',
-        collaboration: true,
-        rootPath: root,
-        createdAt: (stat?.birthtime ?? stat?.mtime ?? new Date()).toISOString(),
-      };
-    }
-    return manifest;
+    const storageSlug = await this.resolveStorageSlug(teamSlug);
+    return this.readTeamManifestByStorageSlug(storageSlug);
   }
 
   async readTeamManifestByProject(projectName: string): Promise<TeamManifest> {
-    try {
-      return await this.readTeamManifest(projectName);
-    } catch {
-      const match = (await this.listTeams()).find(
-        (manifest) => manifest.bindProject === projectName
-      );
-      if (match) return match;
-      throw new Error(`团队 "${projectName}" 不存在 (${teamsRoot()})`);
-    }
+    return this.readTeamManifest(projectName);
   }
 
   async listTeams(): Promise<TeamManifest[]> {
@@ -278,7 +302,7 @@ export class TeamWorkspaceService {
       if (!e.isDirectory()) continue;
       if (e.name.startsWith('.')) continue;
       try {
-        out.push(await this.readTeamManifest(e.name));
+        out.push(await this.readTeamManifestByStorageSlug(e.name));
       } catch {
         // skip broken dirs
       }
@@ -326,19 +350,23 @@ export class TeamWorkspaceService {
     if (opts.deleteFiles) {
       await fs.promises.rm(root, { recursive: true, force: true });
     } else {
-      const archive = path.join(teamsRoot(), `.archived-${teamSlug}-${Date.now()}`);
+      const archive = path.join(teamsRoot(), `.archived-${manifest.slug}-${Date.now()}`);
       await fs.promises.rename(root, archive);
     }
-    logger.info(`deleted team ${teamSlug} (deleteFiles=${opts.deleteFiles ?? false})`);
+    logger.info(`deleted team ${manifest.slug} (deleteFiles=${opts.deleteFiles ?? false})`);
   }
 
   // ---- 消息记录 ----
 
   async appendMessage(teamSlug: string, msg: AppendGroupMessageInput): Promise<GroupMessage> {
-    const file = path.join(teamRoot(teamSlug), 'messages', 'group.jsonl');
+    const storageSlug = await this.resolveStorageSlug(teamSlug);
+    if (storageSlug === teamSlug && isExternalPlatformSlug(teamSlug)) {
+      throw new Error(`外部平台 session_key 不能作为 Hermit team slug 写入消息: ${teamSlug}`);
+    }
+    const file = path.join(teamRoot(storageSlug), 'messages', 'group.jsonl');
     await fs.promises.mkdir(path.dirname(file), { recursive: true });
     const entry: GroupMessage = {
-      id: `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+      id: msg.id || `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
       ts: new Date().toISOString(),
       from: msg.from,
       to: msg.to || 'team',
@@ -350,9 +378,7 @@ export class TeamWorkspaceService {
     return entry;
   }
 
-  async readMessages(teamSlug: string, opts: { limit?: number } = {}): Promise<GroupMessage[]> {
-    const limit = opts.limit ?? 200;
-    const file = path.join(teamRoot(teamSlug), 'messages', 'group.jsonl');
+  private async readGroupMessageFile(file: string): Promise<GroupMessage[]> {
     let raw: string;
     try {
       raw = await fs.promises.readFile(file, 'utf8');
@@ -369,6 +395,33 @@ export class TeamWorkspaceService {
         /* skip */
       }
     }
+    return all;
+  }
+
+  private async findLegacyExternalMessageFiles(storageSlug: string): Promise<string[]> {
+    const dir = teamsRoot();
+    if (!(await pathExists(dir))) return [];
+    const manifests = await this.listTeams();
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory() && isExternalPlatformSlug(entry.name))
+      .filter(
+        (entry) => resolveExternalPlatformSessionTeamSlug(entry.name, manifests) === storageSlug
+      )
+      .map((entry) => path.join(dir, entry.name, 'messages', 'group.jsonl'));
+  }
+
+  async readMessages(teamSlug: string, opts: { limit?: number } = {}): Promise<GroupMessage[]> {
+    const limit = opts.limit ?? 200;
+    const storageSlug = await this.resolveStorageSlug(teamSlug);
+    if (storageSlug === teamSlug && isExternalPlatformSlug(teamSlug)) return [];
+
+    const files = [
+      path.join(teamRoot(storageSlug), 'messages', 'group.jsonl'),
+      ...(await this.findLegacyExternalMessageFiles(storageSlug)),
+    ];
+    const all = (await Promise.all(files.map((file) => this.readGroupMessageFile(file)))).flat();
+    all.sort((a, b) => a.ts.localeCompare(b.ts));
     return all.length <= limit ? all : all.slice(all.length - limit);
   }
 

package/src/main/services/teams-mvp/index.ts

@@ -25,5 +25,11 @@ export type {
 } from './TeamWorkspaceService';
 
 export { TeamProvisioningService } from './TeamProvisioningService';
+export {
+  HERMIT_OPS_GUIDE_URL,
+  buildHermitOpsRunbookContext,
+  buildMemberWorkflowWithOpsContext,
+  removeHermitOpsRunbookContext,
+} from './OpsRunbookContext';
 
 export { CollaborationBoardService } from './CollaborationBoardService';

package/src/main/utils/externalPlatformSessionRouting.ts

@@ -0,0 +1,92 @@
+import type { TeamManifest } from '@main/services/teams-mvp/TeamWorkspaceService';
+
+const EXTERNAL_PLATFORM_SESSION_RE = /^(feishu|lark|weixin|telegram|discord|slack):/;
+const FEISHU_LARK_KEYS = new Set(['feishu', 'lark']);
+
+export interface ExternalPlatformSessionKey {
+  platform: string;
+  chatId?: string;
+  userId?: string;
+}
+
+export function isExternalPlatformSessionKey(sessionKey: string): boolean {
+  return EXTERNAL_PLATFORM_SESSION_RE.test(sessionKey);
+}
+
+export function parseExternalPlatformSessionKey(
+  sessionKey: string
+): ExternalPlatformSessionKey | null {
+  if (!isExternalPlatformSessionKey(sessionKey)) return null;
+  const [platform, chatId, userId] = sessionKey.split(':');
+  return {
+    platform,
+    chatId: chatId?.trim() || undefined,
+    userId: userId?.trim() || undefined,
+  };
+}
+
+function getPlatformAllowValue(
+  record: Record<string, string> | undefined,
+  platform: string
+): string {
+  if (!record) return '';
+  if (FEISHU_LARK_KEYS.has(platform)) {
+    return record[platform] ?? record[platform === 'feishu' ? 'lark' : 'feishu'] ?? '';
+  }
+  return record[platform] ?? '';
+}
+
+function matchesAllowList(allowList: string, value: string | undefined): boolean {
+  const trimmed = allowList.trim();
+  if (!trimmed) return false;
+  if (trimmed === '*') return true;
+  if (!value) return false;
+  return trimmed
+    .split(/[\s,]+/)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .includes(value);
+}
+
+function scoreManifestForSession(
+  manifest: TeamManifest,
+  parsed: ExternalPlatformSessionKey
+): number {
+  const allowChat = getPlatformAllowValue(manifest.platformAllowChat, parsed.platform);
+  const allowFrom = getPlatformAllowValue(manifest.platformAllowFrom, parsed.platform);
+  let score = 0;
+
+  if (allowChat) {
+    if (!matchesAllowList(allowChat, parsed.chatId)) return 0;
+    score += allowChat.trim() === '*' ? 1 : 4;
+  }
+
+  if (allowFrom) {
+    if (!matchesAllowList(allowFrom, parsed.userId)) return 0;
+    score += allowFrom.trim() === '*' ? 1 : 3;
+  }
+
+  return score;
+}
+
+/**
+ * Resolves an external platform session key (for example `feishu:{chat}:{user}`)
+ * to a Hermit-managed team slug using local allow-list metadata. Returns null
+ * when no team matches or when multiple teams are equally plausible.
+ */
+export function resolveExternalPlatformSessionTeamSlug(
+  sessionKey: string,
+  manifests: readonly TeamManifest[]
+): string | null {
+  const parsed = parseExternalPlatformSessionKey(sessionKey);
+  if (!parsed) return null;
+
+  const ranked = manifests
+    .map((manifest) => ({ manifest, score: scoreManifestForSession(manifest, parsed) }))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (ranked.length === 0) return null;
+  if (ranked.length > 1 && ranked[0].score === ranked[1].score) return null;
+  return ranked[0].manifest.slug || ranked[0].manifest.bindProject;
+}