@automagik/genie 4.260331.4 → 4.260331.6

package/src/lib/agent-registry.ts

@@ -340,14 +340,28 @@ export async function removeSubPane(workerId: string, paneId: string, _registryP
   await sql`UPDATE agents SET sub_panes = ${sql.json(filtered)} WHERE id = ${workerId}`;
 }
 
+/** Resolve the dynamic leader name for a team (null if only 'team-lead' applies). */
+async function resolveDynamicLeaderName(teamName: string): Promise<string | null> {
+  try {
+    const { getTeam } = await import('./team-manager.js');
+    const config = await getTeam(teamName);
+    return config?.leader && config.leader !== 'team-lead' ? config.leader : null;
+  } catch {
+    return null; // Fallback to team-lead only
+  }
+}
+
 export async function getTeamLeadEntry(teamName: string, session?: string, repoPath?: string): Promise<Agent | null> {
   const sql = await getConnection();
   if (session) return findTeamLeadBySession(sql, teamName, session, repoPath);
   const legacyId = buildLegacyTeamLeadEntryId(teamName);
   const lr = await sql`SELECT * FROM agents WHERE id = ${legacyId}`;
   if (lr.length > 0) return rowToAgent(lr[0]);
-  const sr =
-    await sql`SELECT * FROM agents WHERE role = 'team-lead' AND team = ${teamName} ORDER BY started_at DESC LIMIT 1`;
+
+  const leaderName = await resolveDynamicLeaderName(teamName);
+  const sr = leaderName
+    ? await sql`SELECT * FROM agents WHERE (role = 'team-lead' OR role = ${leaderName}) AND team = ${teamName} ORDER BY started_at DESC LIMIT 1`
+    : await sql`SELECT * FROM agents WHERE role = 'team-lead' AND team = ${teamName} ORDER BY started_at DESC LIMIT 1`;
   return sr.length > 0 ? rowToAgent(sr[0]) : null;
 }
 
@@ -375,9 +389,15 @@ async function findTeamLeadBySession(
     const a = rowToAgent(legRows[0]);
     if (a.session === session && (!repoPath || a.repoPath === repoPath)) return a;
   }
-  const scanRows = await sql<
-    AgentRow[]
-  >`SELECT * FROM agents WHERE role = 'team-lead' AND team = ${teamName} AND session = ${session} ${repoPath ? sql`AND repo_path = ${repoPath}` : sql``} LIMIT 1`;
+
+  const leaderName = await resolveDynamicLeaderName(teamName);
+  const scanRows = leaderName
+    ? await sql<
+        AgentRow[]
+      >`SELECT * FROM agents WHERE (role = 'team-lead' OR role = ${leaderName}) AND team = ${teamName} AND session = ${session} ${repoPath ? sql`AND repo_path = ${repoPath}` : sql``} LIMIT 1`
+    : await sql<
+        AgentRow[]
+      >`SELECT * FROM agents WHERE role = 'team-lead' AND team = ${teamName} AND session = ${session} ${repoPath ? sql`AND repo_path = ${repoPath}` : sql``} LIMIT 1`;
   return scanRows.length > 0 ? rowToAgent(scanRows[0]) : null;
 }
 

package/src/lib/claude-native-teams.ts

@@ -184,6 +184,7 @@ export async function ensureNativeTeam(
   teamName: string,
   description: string,
   leadSessionId: string,
+  leaderName?: string,
 ): Promise<NativeTeamConfig> {
   const dir = teamDir(teamName);
   const inboxDir = inboxesDir(teamName);
@@ -195,11 +196,12 @@ export async function ensureNativeTeam(
   if (existing) return existing;
 
   const sanitized = sanitizeTeamName(teamName);
+  const resolvedLeader = sanitizeTeamName(leaderName ?? 'team-lead');
   const config: NativeTeamConfig = {
     name: sanitized,
     description,
     createdAt: Date.now(),
-    leadAgentId: `team-lead@${sanitized}`,
+    leadAgentId: `${resolvedLeader}@${sanitized}`,
     leadSessionId,
     members: [],
   };
@@ -387,12 +389,61 @@ export async function deleteNativeTeam(teamName: string): Promise<boolean> {
 // Inbox Scanning
 // ============================================================================
 
+/** Extract the leader inbox name from a native team config's leadAgentId. */
+function extractLeaderInboxName(config: NativeTeamConfig | null): string {
+  if (!config?.leadAgentId) return 'team-lead';
+  const atIdx = config.leadAgentId.indexOf('@');
+  return atIdx > 0 ? config.leadAgentId.slice(0, atIdx) : 'team-lead';
+}
+
+/** Scan a single team directory for unread leader inbox messages. */
+async function scanTeamInbox(
+  base: string,
+  name: string,
+): Promise<{
+  teamName: string;
+  unreadCount: number;
+  workingDir: string | null;
+  firstUnreadText: string | null;
+} | null> {
+  let config: NativeTeamConfig | null = null;
+  try {
+    const cfgContent = await readFile(join(base, name, 'config.json'), 'utf-8');
+    config = JSON.parse(cfgContent);
+  } catch {
+    // Config missing or malformed
+  }
+
+  const leaderInboxName = extractLeaderInboxName(config);
+  const inboxFile = join(base, name, 'inboxes', `${leaderInboxName}.json`);
+
+  let messages: NativeInboxMessage[];
+  try {
+    const content = await readFile(inboxFile, 'utf-8');
+    messages = JSON.parse(content);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(messages)) return null;
+  const unread = messages.filter((m) => m.read === false);
+  if (unread.length === 0) return null;
+
+  let workingDir: string | null = null;
+  if (config) {
+    const leadMember = config.members.find((m) => m.agentId === config?.leadAgentId || m.name === leaderInboxName);
+    if (leadMember?.cwd) workingDir = leadMember.cwd;
+  }
+
+  return { teamName: name, unreadCount: unread.length, workingDir, firstUnreadText: unread[0]?.text ?? null };
+}
+
 /**
- * List all teams that have unread messages in their team-lead inbox.
+ * List all teams that have unread messages in their leader's inbox.
  *
- * Scans `~/.claude/teams/` for teams where `inboxes/team-lead.json`
+ * Scans `~/.claude/teams/` for teams where the leader's inbox
  * contains messages with `read: false`. Returns the team name, unread
- * count, and working directory (from config.json → members → team-lead → cwd).
+ * count, and working directory (from config.json → members → leader → cwd).
  */
 export async function listTeamsWithUnreadInbox(): Promise<
   Array<{ teamName: string; unreadCount: number; workingDir: string | null; firstUnreadText: string | null }>
@@ -402,7 +453,7 @@ export async function listTeamsWithUnreadInbox(): Promise<
   try {
     teamDirs = await readdir(base);
   } catch {
-    return []; // No teams directory
+    return [];
   }
 
   const results: Array<{
@@ -413,40 +464,8 @@ export async function listTeamsWithUnreadInbox(): Promise<
   }> = [];
 
   for (const name of teamDirs) {
-    // Read inbox messages
-    const inboxFile = join(base, name, 'inboxes', 'team-lead.json');
-    let messages: NativeInboxMessage[];
-    try {
-      const content = await readFile(inboxFile, 'utf-8');
-      messages = JSON.parse(content);
-    } catch {
-      continue; // No inbox or invalid JSON
-    }
-
-    if (!Array.isArray(messages)) continue;
-
-    const unread = messages.filter((m) => m.read === false);
-    if (unread.length === 0) continue;
-
-    // Get workingDir from config.json → members → team-lead → cwd
-    let workingDir: string | null = null;
-    try {
-      const cfgContent = await readFile(join(base, name, 'config.json'), 'utf-8');
-      const config: NativeTeamConfig = JSON.parse(cfgContent);
-      const leadMember = config.members.find((m) => m.name === 'team-lead' || m.agentId.startsWith('team-lead@'));
-      if (leadMember?.cwd) {
-        workingDir = leadMember.cwd;
-      }
-    } catch {
-      // Config missing or malformed — workingDir stays null
-    }
-
-    results.push({
-      teamName: name,
-      unreadCount: unread.length,
-      workingDir,
-      firstUnreadText: unread[0]?.text ?? null,
-    });
+    const entry = await scanTeamInbox(base, name);
+    if (entry) results.push(entry);
   }
 
   return results;
@@ -550,7 +569,8 @@ async function readSessionMetadata(filePath: string): Promise<SessionMetadata> {
  */
 function rootScore(metadata: { teamName?: string; agentName?: string }): number {
   if (!metadata.teamName && !metadata.agentName) return 2;
-  if (metadata.agentName === 'team-lead') return 1;
+  // Score leader sessions higher — matches both legacy "team-lead" and dynamic leader names
+  if (metadata.agentName === 'team-lead' || (metadata.teamName && !metadata.agentName)) return 1;
   return 0;
 }
 
@@ -663,6 +683,7 @@ export async function registerAsTeamLead(
     cwd?: string;
     tmuxPaneId?: string;
     color?: string;
+    leaderName?: string;
   },
 ): Promise<{ sessionId: string; config: NativeTeamConfig }> {
   const sessionId = await discoverClaudeSessionId(opts?.cwd);
@@ -673,8 +694,10 @@ export async function registerAsTeamLead(
     );
   }
 
+  const resolvedLeaderName = opts?.leaderName ?? 'team-lead';
+
   // Create or load the native team, using the real CC session ID
-  const config = await ensureNativeTeam(teamName, `Genie team: ${teamName}`, sessionId);
+  const config = await ensureNativeTeam(teamName, `Genie team: ${teamName}`, sessionId, resolvedLeaderName);
 
   // Update leadSessionId if the team already existed with a stale ID
   if (config.leadSessionId !== sessionId) {
@@ -684,13 +707,14 @@ export async function registerAsTeamLead(
 
   // Register the leader as a member (CC expects the lead in the members array)
   const sanitized = sanitizeTeamName(teamName);
-  const leadAgentId = `team-lead@${sanitized}`;
+  const sanitizedLeader = sanitizeTeamName(resolvedLeaderName);
+  const leadAgentId = `${sanitizedLeader}@${sanitized}`;
   const existingLead = config.members.find((m) => m.agentId === leadAgentId);
 
   const resolvedPaneId = opts?.tmuxPaneId ?? process.env.TMUX_PANE;
   if (!existingLead || !existingLead.isActive) {
     await registerNativeMember(teamName, {
-      agentName: 'team-lead',
+      agentName: resolvedLeaderName,
       agentType: 'general-purpose',
       color: opts?.color ?? 'blue',
       tmuxPaneId: resolvedPaneId,
@@ -702,8 +726,8 @@ export async function registerAsTeamLead(
     await saveConfig(teamName, config);
   }
 
-  // Ensure the team-lead inbox exists
-  const inbox = inboxPath(teamName, 'team-lead');
+  // Ensure the leader's inbox exists
+  const inbox = inboxPath(teamName, resolvedLeaderName);
   if (!existsSync(inbox)) {
     await writeFile(inbox, '[]');
   }

package/src/lib/protocol-router-spawn.ts

@@ -245,7 +245,16 @@ export async function spawnWorkerFromTemplate(
       tmuxPaneId: paneId,
       cwd: repoPath,
     });
-    await nativeTeams.writeNativeInbox(team, 'team-lead', {
+    // Resolve the actual leader name for inbox notification
+    let leaderInboxTarget = 'team-lead';
+    try {
+      const { getTeam } = await import('./team-manager.js');
+      const teamConfig = await getTeam(team);
+      if (teamConfig?.leader) leaderInboxTarget = teamConfig.leader;
+    } catch {
+      // Fallback to 'team-lead' for legacy teams
+    }
+    await nativeTeams.writeNativeInbox(team, leaderInboxTarget, {
       from: agentName,
       text: `Worker ${agentName} (${template.provider}) auto-spawned${resumeSessionId ? ' with --resume' : ''}. Ready for tasks.`,
       summary: `${agentName} auto-spawned`,

package/src/lib/qa-runner.ts

@@ -435,7 +435,7 @@ async function runPreparedSpec(
       team: teamName,
       session: teamName,
       cwd: worktreePath,
-      role: 'team-lead',
+      role: 'qa',
       extraArgs: ['--append-system-prompt-file', promptFile],
       initialPrompt: `Execute the QA spec "${spec.name}" end-to-end right now. Do not stop after partial progress or a wait step. Continue until you validate the expectations, publish qa-report, and run team done. Your full instructions are in the system prompt.`,
     });

package/src/lib/team-auto-spawn.ts

@@ -111,10 +111,15 @@ export async function ensureTeamLead(teamName: string, workingDir: string): Prom
     return { created: false, session: currentSession, window: sanitizeWindowName(teamName) };
   }
 
+  // Resolve the actual leader name from team config (falls back to 'team-lead' for legacy)
+  const { getTeam } = await import('./team-manager.js');
+  const teamConfig = await getTeam(teamName);
+  const leaderName = teamConfig?.leader || 'team-lead';
+
   // Create native team structure
-  await ensureNativeTeam(teamName, `Genie team: ${teamName}`, 'pending');
+  await ensureNativeTeam(teamName, `Genie team: ${teamName}`, 'pending', leaderName);
   await registerNativeMember(teamName, {
-    agentName: 'team-lead',
+    agentName: leaderName,
     agentType: 'general-purpose',
     color: 'blue',
     cwd: workingDir,

package/src/lib/team-manager.test.ts

@@ -17,7 +17,9 @@ import {
   hireAgent,
   listMembers,
   listTeams,
+  resolveLeaderName,
   setTeamStatus,
+  updateTeamConfig,
   validateBranchName,
 } from './team-manager.js';
 import { DB_AVAILABLE, setupTestSchema } from './test-db.js';
@@ -274,6 +276,49 @@ describe.skipIf(!DB_AVAILABLE)('pg', () => {
       });
     });
 
+    describe('leader and spawner', () => {
+      test('new team gets leader and spawner when set via updateTeamConfig', async () => {
+        const config = await createTeam('feat/leader-test', TEST_REPO, 'dev');
+        config.leader = 'fix-tmux-session-explosion';
+        config.spawner = 'sofia';
+        await updateTeamConfig(config.name, config);
+
+        const updated = await getTeam('feat/leader-test');
+        expect(updated!.leader).toBe('fix-tmux-session-explosion');
+        expect(updated!.spawner).toBe('sofia');
+      });
+
+      test('resolveLeaderName returns leader for teams with leader set', async () => {
+        const config = await createTeam('feat/leader-resolve', TEST_REPO, 'dev');
+        config.leader = 'my-wish-slug';
+        await updateTeamConfig(config.name, config);
+
+        const name = await resolveLeaderName('feat/leader-resolve');
+        expect(name).toBe('my-wish-slug');
+      });
+
+      test('resolveLeaderName falls back to team-lead for legacy teams', async () => {
+        await createTeam('feat/legacy-leader', TEST_REPO, 'dev');
+        // No leader set — legacy team
+        const name = await resolveLeaderName('feat/legacy-leader');
+        expect(name).toBe('team-lead');
+      });
+
+      test('resolveLeaderName throws for nonexistent team', async () => {
+        expect(resolveLeaderName('nonexistent-team')).rejects.toThrow('not found');
+      });
+
+      test('spawner persisted in PG teams table', async () => {
+        const config = await createTeam('feat/spawner-pg', TEST_REPO, 'dev');
+        config.spawner = 'genie-pm';
+        await updateTeamConfig(config.name, config);
+
+        const sql = await getConnection();
+        const rows = await sql`SELECT spawner FROM teams WHERE name = ${'feat/spawner-pg'}`;
+        expect(rows[0].spawner).toBe('genie-pm');
+      });
+    });
+
     describe('disbandTeam', () => {
       test('removes clone directory and config from PG', async () => {
         const config = await createTeam('feat/disband-test', TEST_REPO, 'dev');

package/src/lib/team-manager.ts

@@ -57,6 +57,8 @@ export interface TeamConfig {
   tmuxSessionName?: string;
   /** Wish slug this team is working on (set via --wish). */
   wishSlug?: string;
+  /** Agent name (or 'cli') that created this team — workers report completion here. */
+  spawner?: string;
   /** ISO timestamp when the team was archived (null if not archived). */
   archivedAt?: string;
 }
@@ -92,6 +94,7 @@ interface TeamConfigRow {
   native_teams_enabled?: boolean;
   tmux_session_name?: string;
   wish_slug?: string;
+  spawner?: string;
   archived_at?: Date | string | null;
 }
 
@@ -111,6 +114,7 @@ function rowToTeamConfig(row: TeamConfigRow): TeamConfig {
   if (row.native_teams_enabled) config.nativeTeamsEnabled = row.native_teams_enabled;
   if (row.tmux_session_name) config.tmuxSessionName = row.tmux_session_name;
   if (row.wish_slug) config.wishSlug = row.wish_slug;
+  if (row.spawner) config.spawner = row.spawner;
   if (row.archived_at) {
     config.archivedAt = row.archived_at instanceof Date ? row.archived_at.toISOString() : String(row.archived_at);
   }
@@ -311,7 +315,7 @@ export async function createTeam(name: string, repo: string, baseBranch = 'dev')
     INSERT INTO teams (
       name, repo, base_branch, worktree_path, leader,
       members, status, native_team_parent_session_id,
-      native_teams_enabled, tmux_session_name, wish_slug, created_at
+      native_teams_enabled, tmux_session_name, wish_slug, spawner, created_at
     ) VALUES (
       ${config.name}, ${config.repo}, ${config.baseBranch},
       ${config.worktreePath}, ${config.leader ?? null},
@@ -319,7 +323,7 @@ export async function createTeam(name: string, repo: string, baseBranch = 'dev')
       ${config.nativeTeamParentSessionId ?? null},
       ${config.nativeTeamsEnabled ?? false},
       ${config.tmuxSessionName ?? null}, ${config.wishSlug ?? null},
-      ${config.createdAt}
+      ${config.spawner ?? null}, ${config.createdAt}
     ) ON CONFLICT (name) DO NOTHING
   `;
 
@@ -570,7 +574,8 @@ export async function updateTeamConfig(name: string, config: TeamConfig): Promis
       native_team_parent_session_id = ${config.nativeTeamParentSessionId ?? null},
       native_teams_enabled = ${config.nativeTeamsEnabled ?? false},
       tmux_session_name = ${config.tmuxSessionName ?? null},
-      wish_slug = ${config.wishSlug ?? null}
+      wish_slug = ${config.wishSlug ?? null},
+      spawner = ${config.spawner ?? null}
     WHERE name = ${name}
   `;
 }
@@ -623,6 +628,18 @@ export async function killTeamMembers(teamName: string): Promise<void> {
   }
 }
 
+/**
+ * Resolve the leader name for a team.
+ * Returns config.leader for teams that have it set, falls back to "team-lead" for legacy teams.
+ */
+export async function resolveLeaderName(teamName: string): Promise<string> {
+  const config = await getTeam(teamName);
+  if (!config) {
+    throw new Error(`Team "${teamName}" not found.`);
+  }
+  return config.leader || 'team-lead';
+}
+
 /** Set team lifecycle status. */
 export async function setTeamStatus(teamName: string, status: TeamStatus): Promise<void> {
   const sql = await getConnection();

package/src/lib/wish-resolve.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for Wish Resolution — namespace/slug parsing and path resolution.
+ * Run with: bun test src/lib/wish-resolve.test.ts
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseWishRef, resolveWish } from './wish-resolve.js';
+
+// ============================================================================
+// parseWishRef (pure parsing — no filesystem)
+// ============================================================================
+
+describe('parseWishRef', () => {
+  test('parses namespace/slug format', () => {
+    const ref = parseWishRef('genie/fix-tmux-session-explosion');
+    expect(ref.namespace).toBe('genie');
+    expect(ref.slug).toBe('fix-tmux-session-explosion');
+  });
+
+  test('parses bare slug without namespace', () => {
+    const ref = parseWishRef('fix-tmux-session-explosion');
+    expect(ref.namespace).toBeUndefined();
+    expect(ref.slug).toBe('fix-tmux-session-explosion');
+  });
+
+  test('trims whitespace', () => {
+    const ref = parseWishRef('  genie/slug  ');
+    expect(ref.namespace).toBe('genie');
+    expect(ref.slug).toBe('slug');
+  });
+
+  test('throws on empty string', () => {
+    expect(() => parseWishRef('')).toThrow('cannot be empty');
+    expect(() => parseWishRef('  ')).toThrow('cannot be empty');
+  });
+
+  test('throws on empty namespace', () => {
+    expect(() => parseWishRef('/slug')).toThrow('namespace is empty');
+  });
+
+  test('throws on empty slug', () => {
+    expect(() => parseWishRef('genie/')).toThrow('slug is empty');
+  });
+
+  test('throws on slug with nested slashes', () => {
+    expect(() => parseWishRef('genie/a/b')).toThrow('slug cannot contain "/"');
+  });
+});
+
+// ============================================================================
+// resolveWish (filesystem-dependent)
+// ============================================================================
+
+describe('resolveWish', () => {
+  const TEST_DIR = '/tmp/wish-resolve-test';
+  const FAKE_REPOS = join(TEST_DIR, 'repos');
+
+  beforeAll(async () => {
+    await rm(TEST_DIR, { recursive: true, force: true });
+
+    // Create a fake repo with a wish
+    const repoDir = join(FAKE_REPOS, 'myrepo');
+    const wishDir = join(repoDir, '.genie', 'wishes', 'fix-bug');
+    await mkdir(wishDir, { recursive: true });
+    await writeFile(join(wishDir, 'WISH.md'), '# Fix Bug Wish');
+
+    // Create a bare .git dir so resolveRepoSession doesn't fail
+    await mkdir(join(repoDir, '.git'), { recursive: true });
+  });
+
+  afterAll(async () => {
+    await rm(TEST_DIR, { recursive: true, force: true });
+  });
+
+  test('throws for nonexistent repo namespace', async () => {
+    await expect(resolveWish('nonexistent/some-slug')).rejects.toThrow('not found at');
+  });
+
+  test('throws for nonexistent wish in valid repo', async () => {
+    // This test requires a repo at the expected REPOS_BASE location.
+    // Since we can't mock the path, we test the error message format.
+    await expect(resolveWish('nonexistent/slug')).rejects.toThrow('not found');
+  });
+
+  test('bare slug without namespace errors with helpful message', async () => {
+    // cwd won't have this wish
+    await expect(resolveWish('nonexistent-wish-slug')).rejects.toThrow('Use namespace/slug format');
+  });
+
+  test('bare slug found in cwd resolves correctly', async () => {
+    // Temporarily change cwd to a dir with a wish
+    const repoDir = join(FAKE_REPOS, 'myrepo');
+    const originalCwd = process.cwd();
+    process.chdir(repoDir);
+
+    try {
+      const result = await resolveWish('fix-bug');
+      expect(result.slug).toBe('fix-bug');
+      expect(result.repo).toBe(repoDir);
+      expect(result.wishPath).toContain('fix-bug/WISH.md');
+      expect(result.session).toBeTruthy();
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});

package/src/lib/wish-resolve.ts

@@ -0,0 +1,124 @@
+/**
+ * Wish Resolution — resolve namespace/slug references to concrete paths.
+ *
+ * Convention: `{namespace}/{slug}` where namespace = repo basename.
+ * Repos live at /home/genie/workspace/repos/{namespace}.
+ * WISH.md lives at {repo}/.genie/wishes/{slug}/WISH.md.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveRepoSession } from './tmux.js';
+
+const REPOS_BASE = '/home/genie/workspace/repos';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface WishRef {
+  namespace?: string;
+  slug: string;
+}
+
+interface ResolvedWish {
+  repo: string;
+  wishPath: string;
+  session: string;
+  slug: string;
+}
+
+// ============================================================================
+// Parsing
+// ============================================================================
+
+/**
+ * Parse a wish reference string into namespace and slug.
+ *
+ * Formats:
+ *   "namespace/slug"  → { namespace: "namespace", slug: "slug" }
+ *   "slug"            → { slug: "slug" }
+ *
+ * Only the first `/` is used as delimiter — slugs may not contain `/`.
+ */
+export function parseWishRef(ref: string): WishRef {
+  const trimmed = ref.trim();
+  if (!trimmed) {
+    throw new Error('Wish reference cannot be empty');
+  }
+
+  const slashIndex = trimmed.indexOf('/');
+  if (slashIndex === -1) {
+    return { slug: trimmed };
+  }
+
+  const namespace = trimmed.slice(0, slashIndex);
+  const slug = trimmed.slice(slashIndex + 1);
+
+  if (!namespace) {
+    throw new Error(`Invalid wish reference "${ref}": namespace is empty`);
+  }
+  if (!slug) {
+    throw new Error(`Invalid wish reference "${ref}": slug is empty`);
+  }
+  if (slug.includes('/')) {
+    throw new Error(`Invalid wish reference "${ref}": slug cannot contain "/"`);
+  }
+
+  return { namespace, slug };
+}
+
+// ============================================================================
+// Resolution
+// ============================================================================
+
+/**
+ * Resolve a wish reference to a concrete repo path, wish path, and tmux session.
+ *
+ * @param ref - Wish reference in "namespace/slug" or "slug" format
+ * @returns Resolved wish with repo, wishPath, session, and slug
+ * @throws If repo not found, wish not found, or bare slug without namespace
+ */
+export async function resolveWish(ref: string): Promise<ResolvedWish> {
+  const parsed = parseWishRef(ref);
+
+  if (!parsed.namespace) {
+    // Bare slug — check cwd first
+    const cwdWishPath = join(process.cwd(), '.genie', 'wishes', parsed.slug, 'WISH.md');
+    if (existsSync(cwdWishPath)) {
+      const repo = process.cwd();
+      const session = await resolveRepoSession(repo);
+      return {
+        repo,
+        wishPath: cwdWishPath,
+        session,
+        slug: parsed.slug,
+      };
+    }
+
+    throw new Error(
+      `Wish "${parsed.slug}" not found in current directory. Use namespace/slug format (e.g., genie/${parsed.slug}) to specify the repo.`,
+    );
+  }
+
+  // Namespace provided — resolve repo
+  const repo = join(REPOS_BASE, parsed.namespace);
+  if (!existsSync(repo)) {
+    throw new Error(`Repository "${parsed.namespace}" not found at ${repo}. Available repos are in ${REPOS_BASE}.`);
+  }
+
+  // Verify WISH.md exists
+  const wishPath = join(repo, '.genie', 'wishes', parsed.slug, 'WISH.md');
+  if (!existsSync(wishPath)) {
+    throw new Error(`Wish "${parsed.slug}" not found in repo "${parsed.namespace}". Expected: ${wishPath}`);
+  }
+
+  const session = await resolveRepoSession(repo);
+
+  return {
+    repo,
+    wishPath,
+    session,
+    slug: parsed.slug,
+  };
+}