hungry-ghost-hive 0.44.0 → 0.46.0

package/src/orchestrator/scheduler.test.ts

@@ -1,8 +1,11 @@
 // Licensed under the Hungry Ghost Hive License. See LICENSE.
 
+import { existsSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
 import type { Database } from 'sql.js';
 import initSqlJs from 'sql.js';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { getLogsByEventType } from '../db/queries/logs.js';
 import { createPullRequest } from '../db/queries/pull-requests.js';
@@ -17,6 +20,7 @@ import {
 import { createTeam } from '../db/queries/teams.js';
 import * as worktreeModule from '../git/worktree.js';
 import * as tmuxModule from '../tmux/manager.js';
+import { generateSessionName } from '../tmux/manager.js';
 import { getAgentWorkload, selectAgentWithLeastWorkload } from './agent-selector.js';
 import {
   getCapacityPoints,
@@ -107,13 +111,15 @@ CREATE TABLE IF NOT EXISTS teams (
 
 CREATE TABLE IF NOT EXISTS agents (
     id TEXT PRIMARY KEY,
-    type TEXT NOT NULL CHECK (type IN ('tech_lead', 'senior', 'intermediate', 'junior', 'qa')),
+    type TEXT NOT NULL CHECK (type IN ('tech_lead', 'senior', 'intermediate', 'junior', 'qa', 'feature_test', 'auditor')),
     team_id TEXT REFERENCES teams(id),
     tmux_session TEXT,
     model TEXT,
     status TEXT DEFAULT 'idle' CHECK (status IN ('idle', 'working', 'blocked', 'terminated')),
     current_story_id TEXT,
     memory_state TEXT,
+    last_seen TIMESTAMP,
+    worktree_path TEXT,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
@@ -141,6 +147,7 @@ CREATE TABLE IF NOT EXISTS stories (
     assigned_agent_id TEXT REFERENCES agents(id),
     branch_name TEXT,
     pr_url TEXT,
+    markdown_path TEXT,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
@@ -793,6 +800,50 @@ describe('Scheduler Orphaned Story Recovery', () => {
     expect(recovered).toContain(story1.id);
     expect(recovered).toContain(story2.id);
   });
+
+  it('should write markdown files when storiesDir is provided during orphan recovery', () => {
+    const storiesDir = join(tmpdir(), `hive-test-stories-${Date.now()}`);
+    mkdirSync(storiesDir, { recursive: true });
+
+    try {
+      const team = createTeam(db, {
+        name: 'MD Test Team',
+        repoUrl: 'https://github.com/test/repo',
+        repoPath: 'test',
+      });
+
+      const terminatedAgentId = 'agent-md-terminated';
+      db.run(
+        `INSERT INTO agents (id, type, team_id, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))`,
+        [terminatedAgentId, 'intermediate', team.id, 'terminated']
+      );
+
+      const story = createStory(db, {
+        teamId: team.id,
+        title: 'Story with Markdown',
+        description: 'Should get a markdown file on recovery',
+      });
+      updateStory(db, story.id, {
+        assignedAgentId: terminatedAgentId,
+        status: 'in_progress',
+      });
+
+      const recovered = detectAndRecoverOrphanedStories(db, '/tmp', storiesDir);
+
+      expect(recovered).toContain(story.id);
+
+      // Verify markdown file was written
+      const mdPath = join(storiesDir, `${story.id}.md`);
+      expect(existsSync(mdPath)).toBe(true);
+
+      // Verify markdown_path was set in DB
+      const updatedStory = getStoryById(db, story.id);
+      expect(updatedStory?.markdown_path).toBe(mdPath);
+    } finally {
+      rmSync(storiesDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('Scheduler Refactor Capacity Policy', () => {
@@ -945,6 +996,7 @@ describe('Scheduler Refactor Policy Test Matrix', () => {
       external_subtask_id: null,
       external_provider: null,
       in_sprint: 0,
+      markdown_path: null,
       created_at: new Date().toISOString(),
       updated_at: new Date().toISOString(),
     };
@@ -1904,6 +1956,9 @@ describe('Scheduler checkScaling', () => {
       repoPath: 'test',
     });
 
+    const gapHiveDir = join(mockConfig.rootDir, '.hive');
+    const gapSessionPrefix = generateSessionName('senior', team.name, undefined, gapHiveDir);
+
     for (const index of [2, 3, 4, 5]) {
       db.run(
         `INSERT INTO agents (id, type, team_id, tmux_session, status, current_story_id, created_at, updated_at)
@@ -1912,7 +1967,7 @@ describe('Scheduler checkScaling', () => {
           `senior-gap-${index}`,
           'senior',
           team.id,
-          `hive-senior-${team.name}-${index}`,
+          `${gapSessionPrefix}-${index}`,
           'working',
           `STORY-EXISTING-${index}`,
         ]
@@ -1934,7 +1989,7 @@ describe('Scheduler checkScaling', () => {
         db.run(
           `INSERT INTO agents (id, type, team_id, tmux_session, status, current_story_id, created_at, updated_at)
            VALUES (?, ?, ?, ?, ?, NULL, datetime('now'), datetime('now'))`,
-          ['senior-gap-6', 'senior', team.id, `hive-senior-${team.name}-6`, 'idle']
+          ['senior-gap-6', 'senior', team.id, `${gapSessionPrefix}-6`, 'idle']
         );
         return {
           id: 'senior-gap-6',
@@ -1942,7 +1997,7 @@ describe('Scheduler checkScaling', () => {
           team_id: team.id,
           status: 'idle',
           current_story_id: null,
-          tmux_session: `hive-senior-${team.name}-6`,
+          tmux_session: `${gapSessionPrefix}-6`,
         };
       });
 
@@ -2055,10 +2110,13 @@ describe('Scheduler checkScaling', () => {
       repoPath: 'test',
     });
 
+    const hiveDir = join(mockConfig.rootDir, '.hive');
+    const expectedSession = generateSessionName('senior', team.name, undefined, hiveDir);
+
     db.run(
       `INSERT INTO agents (id, type, team_id, tmux_session, status, current_story_id, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))`,
-      ['senior-guard-1', 'senior', team.id, `hive-senior-${team.name}`, 'working', 'STORY-ACTIVE']
+      ['senior-guard-1', 'senior', team.id, expectedSession, 'working', 'STORY-ACTIVE']
     );
 
     const isRunningSpy = vi.spyOn(tmuxModule, 'isTmuxSessionRunning').mockResolvedValue(true);
@@ -2170,6 +2228,72 @@ describe('Scheduler checkScaling', () => {
   });
 });
 
+describe('Scheduler Markdown File Writing', () => {
+  let storiesDir: string;
+
+  beforeEach(() => {
+    storiesDir = join(
+      tmpdir(),
+      `hive-test-stories-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    mkdirSync(storiesDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(storiesDir, { recursive: true, force: true });
+  });
+
+  it('should write markdown files when assigning stories via scheduler', async () => {
+    const team = createTeam(db, {
+      name: 'MD Write Team',
+      repoUrl: 'https://github.com/test/repo',
+      repoPath: 'test',
+    });
+
+    // Create an idle senior agent
+    db.run(
+      `INSERT INTO agents (id, type, team_id, status, created_at, updated_at)
+       VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))`,
+      ['senior-md-1', 'senior', team.id, 'idle']
+    );
+
+    const story = createStory(db, {
+      teamId: team.id,
+      title: 'Markdown Test Story',
+      description: 'Should get a markdown file on assignment',
+    });
+    updateStory(db, story.id, { status: 'planned', complexityScore: 10, storyPoints: 8 });
+
+    // Create scheduler with rootDir pointing to a temp dir that has .hive/stories/
+    const hiveRoot = join(tmpdir(), `hive-md-root-${Date.now()}`);
+    const hiveStoriesDir = join(hiveRoot, '.hive', 'stories');
+    mkdirSync(hiveStoriesDir, { recursive: true });
+
+    const mdScheduler = new Scheduler(db, {
+      ...mockConfig,
+      rootDir: hiveRoot,
+    } as any);
+
+    // Mock spawnSenior to avoid actual tmux operations
+    vi.spyOn(mdScheduler as any, 'sendAssignmentHandoff').mockResolvedValue(undefined);
+
+    const result = await mdScheduler.assignStories();
+
+    expect(result.assigned).toBe(1);
+
+    // Verify markdown file was written
+    const mdPath = join(hiveStoriesDir, `${story.id}.md`);
+    expect(existsSync(mdPath)).toBe(true);
+
+    // Verify markdown_path was set in DB
+    const updatedStory = getStoryById(db, story.id);
+    expect(updatedStory?.markdown_path).toBe(mdPath);
+    expect(updatedStory?.status).toBe('in_progress');
+
+    rmSync(hiveRoot, { recursive: true, force: true });
+  });
+});
+
 describe('Scheduler Target Branch Propagation', () => {
   it('should retrieve target_branch from requirement when creating story', () => {
     const team = createTeam(db, {

package/src/orchestrator/scheduler.ts

@@ -1,5 +1,6 @@
 // Licensed under the Hungry Ghost Hive License. See LICENSE.
 
+import { join } from 'path';
 import type { Database } from 'sql.js';
 import {
   getCliRuntimeBuilder,
@@ -45,7 +46,9 @@ import {
   spawnTmuxSession,
   startManager,
 } from '../tmux/manager.js';
+import { getTechLeadSessionName } from '../utils/instance.js';
 import * as logger from '../utils/logger.js';
+import { getHivePaths } from '../utils/paths.js';
 import { selectAgentWithLeastWorkload } from './agent-selector.js';
 import { getCapacityPoints, selectStoriesForCapacity } from './capacity-planner.js';
 import { areDependenciesSatisfied, topologicalSort } from './dependency-resolver.js';
@@ -104,6 +107,10 @@ export class Scheduler {
     this.pmQueue = new PMOperationQueue();
   }
 
+  private get storiesDir(): string {
+    return getHivePaths(this.config.rootDir).storiesDir;
+  }
+
   /**
    * Wait for all pending Jira operations to complete.
    * Call this before closing the database to prevent "Database closed" errors.
@@ -243,7 +250,12 @@ export class Scheduler {
       const activeSeniors = getAgentsByTeam(this.db, teamId).filter(
         a => a.type === 'senior' && a.status !== 'terminated'
       );
-      const seniorSessionPrefix = generateSessionName('senior', team.name);
+      const seniorSessionPrefix = generateSessionName(
+        'senior',
+        team.name,
+        undefined,
+        join(this.config.rootDir, '.hive')
+      );
       const indexedSeniorSessions = activeSeniors
         .map(senior => {
           if (!senior.tmux_session) return null;
@@ -389,10 +401,15 @@ export class Scheduler {
           await withTransaction(
             this.db,
             () => {
-              updateStory(this.db, story.id, {
-                assignedAgentId: targetAgent.id,
-                status: 'in_progress',
-              });
+              updateStory(
+                this.db,
+                story.id,
+                {
+                  assignedAgentId: targetAgent.id,
+                  status: 'in_progress',
+                },
+                this.storiesDir
+              );
 
               updateAgent(this.db, targetAgent.id, {
                 status: 'working',
@@ -544,10 +561,15 @@ export class Scheduler {
 
       if (subtask) {
         // Persist subtask reference back to the story
-        updateStory(this.db, freshStory.id, {
-          externalSubtaskKey: subtask.key,
-          externalSubtaskId: subtask.id,
-        });
+        updateStory(
+          this.db,
+          freshStory.id,
+          {
+            externalSubtaskKey: subtask.key,
+            externalSubtaskId: subtask.id,
+          },
+          this.storiesDir
+        );
         if (this.saveFn) this.saveFn();
 
         logger.info(`Created subtask ${subtask.key} for story ${freshStory.id}`);
@@ -670,7 +692,7 @@ export class Scheduler {
     `
     );
 
-    const liveSessions = await getHiveSessions();
+    const liveSessions = await getHiveSessions(join(this.config.rootDir, '.hive'));
     const liveSessionNames = new Set(liveSessions.map(s => s.name));
 
     let terminated = 0;
@@ -704,10 +726,15 @@ export class Scheduler {
 
         // If agent was working on a story, mark it for reassignment
         if (agent.current_story_id) {
-          updateStory(this.db, agent.current_story_id, {
-            status: 'planned',
-            assignedAgentId: null,
-          });
+          updateStory(
+            this.db,
+            agent.current_story_id,
+            {
+              status: 'planned',
+              assignedAgentId: null,
+            },
+            this.storiesDir
+          );
           revived.push(agent.current_story_id);
 
           // Sync status change to Jira (fire and forget)
@@ -717,7 +744,11 @@ export class Scheduler {
     }
 
     // Detect and recover orphaned stories (assigned to terminated agents)
-    const orphanedRecovered = detectAndRecoverOrphanedStories(this.db, this.config.rootDir);
+    const orphanedRecovered = detectAndRecoverOrphanedStories(
+      this.db,
+      this.config.rootDir,
+      this.storiesDir
+    );
 
     return { terminated, revived, orphanedRecovered };
   }
@@ -885,8 +916,9 @@ export class Scheduler {
   }
 
   private async ensureManagerRunning(): Promise<void> {
-    if (!(await isManagerRunning())) {
-      await startManager(DEFAULT_MANAGER_INTERVAL_SECONDS);
+    const hiveDir = join(this.config.rootDir, '.hive');
+    if (!(await isManagerRunning(hiveDir))) {
+      await startManager(DEFAULT_MANAGER_INTERVAL_SECONDS, hiveDir);
     }
   }
 
@@ -907,10 +939,11 @@ export class Scheduler {
     }
   ): Promise<AgentRow> {
     // Auditor uses a timestamp-based session name since it's ephemeral
+    const hiveDir = join(this.config.rootDir, '.hive');
     const sessionName =
       type === 'auditor'
-        ? `hive-auditor-${Date.now()}`
-        : generateSessionName(type, teamName, index);
+        ? generateSessionName('auditor', `${Date.now()}`, undefined, hiveDir)
+        : generateSessionName(type, teamName, index, hiveDir);
 
     // Prevent creating duplicate agents on same tmux session (for senior agents)
     if (type === 'senior') {
@@ -997,6 +1030,10 @@ export class Scheduler {
       // Build the initial prompt for this agent type
       const team = getTeamById(this.db, teamId);
       const includeProgressUpdates = this.shouldIncludeProgressUpdates();
+      const hiveDir = join(this.config.rootDir, '.hive');
+      const techLeadSession = getTechLeadSessionName(hiveDir);
+      const chromeEnabled =
+        this.config.hiveConfig?.agents?.chrome_enabled === true && cliTool === 'claude';
       let prompt: string;
 
       if (type === 'senior') {
@@ -1007,7 +1044,7 @@ export class Scheduler {
           worktreePath,
           stories,
           targetBranch,
-          { includeProgressUpdates },
+          { includeProgressUpdates, techLeadSession, chromeEnabled },
           sessionName
         );
       } else if (type === 'intermediate') {
@@ -1017,7 +1054,7 @@ export class Scheduler {
           worktreePath,
           sessionName,
           targetBranch,
-          { includeProgressUpdates }
+          { includeProgressUpdates, techLeadSession, chromeEnabled }
         );
       } else if (type === 'junior') {
         prompt = generateJuniorPrompt(
@@ -1026,7 +1063,7 @@ export class Scheduler {
           worktreePath,
           sessionName,
           targetBranch,
-          { includeProgressUpdates }
+          { includeProgressUpdates, techLeadSession, chromeEnabled }
         );
       } else if (type === 'feature_test' && featureTestContext) {
         prompt = generateFeatureTestPrompt(
@@ -1037,23 +1074,25 @@ export class Scheduler {
           featureTestContext.featureBranch,
           featureTestContext.requirementId,
           featureTestContext.e2eTestsPath,
-          { includeProgressUpdates }
+          { includeProgressUpdates, techLeadSession, chromeEnabled }
         );
       } else if (type === 'auditor') {
-        prompt = generateAuditorPrompt(sessionName, worktreePath, team?.repo_url || '');
+        prompt = generateAuditorPrompt(sessionName, worktreePath, team?.repo_url || '', {
+          techLeadSession,
+          chromeEnabled,
+        });
       } else {
         prompt = generateQAPrompt(
           teamName,
           team?.repo_url || '',
           worktreePath,
           sessionName,
-          targetBranch
+          targetBranch,
+          { chromeEnabled }
         );
       }
 
       // Build CLI command using the configured runtime
-      const chromeEnabled =
-        this.config.hiveConfig?.agents?.chrome_enabled === true && cliTool === 'claude';
       const commandArgs = getCliRuntimeBuilder(cliTool).buildSpawnCommand(
         runtimeModel,
         safetyMode,

package/src/tmux/manager.ts

@@ -4,6 +4,11 @@ import { execa } from 'execa';
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { dirname, isAbsolute, join, resolve } from 'path';
+import {
+  buildInstanceSessionName,
+  getInstancePrefix,
+  getManagerSessionName,
+} from '../utils/instance.js';
 
 // --- Named constants (extracted from inline magic numbers) ---
 
@@ -162,8 +167,12 @@ export async function listTmuxSessions(): Promise<TmuxSession[]> {
   }
 }
 
-export async function getHiveSessions(): Promise<TmuxSession[]> {
+export async function getHiveSessions(hiveDir?: string): Promise<TmuxSession[]> {
   const sessions = await listTmuxSessions();
+  if (hiveDir) {
+    const prefix = getInstancePrefix(hiveDir);
+    return sessions.filter(s => s.name.startsWith(prefix));
+  }
   return sessions.filter(s => s.name.startsWith('hive-'));
 }
 
@@ -235,8 +244,8 @@ export async function killTmuxSession(sessionName: string): Promise<void> {
   }
 }
 
-export async function killAllHiveSessions(): Promise<number> {
-  const sessions = await getHiveSessions();
+export async function killAllHiveSessions(hiveDir?: string): Promise<number> {
+  const sessions = await getHiveSessions(hiveDir);
   let killed = 0;
 
   for (const session of sessions) {
@@ -513,7 +522,15 @@ export async function autoApprovePermission(
   return false;
 }
 
-export function generateSessionName(agentType: string, teamName?: string, index?: number): string {
+export function generateSessionName(
+  agentType: string,
+  teamName?: string,
+  index?: number,
+  hiveDir?: string
+): string {
+  if (hiveDir) {
+    return buildInstanceSessionName(hiveDir, agentType, teamName, index);
+  }
   let name = `hive-${agentType}`;
   if (teamName) {
     name += `-${teamName}`;
@@ -526,12 +543,23 @@ export function generateSessionName(agentType: string, teamName?: string, index?
 
 const MANAGER_SESSION = 'hive-manager';
 
-export async function isManagerRunning(): Promise<boolean> {
-  return isTmuxSessionRunning(MANAGER_SESSION);
+export function getManagerSession(hiveDir?: string): string {
+  if (hiveDir) {
+    return getManagerSessionName(hiveDir);
+  }
+  return MANAGER_SESSION;
+}
+
+export async function isManagerRunning(hiveDir?: string): Promise<boolean> {
+  return isTmuxSessionRunning(getManagerSession(hiveDir));
 }
 
-export async function startManager(interval = DEFAULT_MANAGER_INTERVAL): Promise<boolean> {
-  if (await isManagerRunning()) {
+export async function startManager(
+  interval = DEFAULT_MANAGER_INTERVAL,
+  hiveDir?: string
+): Promise<boolean> {
+  const session = getManagerSession(hiveDir);
+  if (await isTmuxSessionRunning(session)) {
     return false; // Already running
   }
 
@@ -539,22 +567,23 @@ export async function startManager(interval = DEFAULT_MANAGER_INTERVAL): Promise
   const sessionEnv = buildTmuxSessionEnv(workDir);
 
   // Start the manager in a detached tmux session
-  await execa('tmux', ['new-session', '-d', '-s', MANAGER_SESSION, '-c', workDir], {
+  await execa('tmux', ['new-session', '-d', '-s', session, '-c', workDir], {
     env: sessionEnv,
   });
 
   // Send the manager command
   const managerCommand = `${buildHiveInvokeCommand()} manager start -i ${interval}`;
-  await execa('tmux', ['send-keys', '-t', MANAGER_SESSION, managerCommand, 'Enter']);
+  await execa('tmux', ['send-keys', '-t', session, managerCommand, 'Enter']);
 
   return true;
 }
 
-export async function stopManager(): Promise<boolean> {
-  if (!(await isManagerRunning())) {
+export async function stopManager(hiveDir?: string): Promise<boolean> {
+  const session = getManagerSession(hiveDir);
+  if (!(await isTmuxSessionRunning(session))) {
     return false; // Not running
   }
 
-  await killTmuxSession(MANAGER_SESSION);
+  await killTmuxSession(session);
   return true;
 }

package/src/utils/instance.test.ts

@@ -0,0 +1,129 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  buildInstanceSessionName,
+  getInstanceId,
+  getInstancePrefix,
+  getManagerLockPath,
+  getManagerSessionName,
+  getTechLeadSessionName,
+} from './instance.js';
+
+describe('instance', () => {
+  let testHiveDir: string;
+
+  beforeEach(() => {
+    testHiveDir = join(tmpdir(), `hive-test-instance-${Date.now()}`);
+    mkdirSync(testHiveDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testHiveDir, { recursive: true, force: true });
+  });
+
+  describe('getInstanceId', () => {
+    it('should return null if hive directory does not exist', () => {
+      const result = getInstanceId('/nonexistent/path/.hive');
+      expect(result).toBeNull();
+    });
+
+    it('should create and persist an instance ID', () => {
+      const id = getInstanceId(testHiveDir);
+      expect(id).toBeTruthy();
+      expect(typeof id).toBe('string');
+      expect(id!.length).toBe(6);
+
+      // Should be persisted
+      const fileContent = readFileSync(join(testHiveDir, 'instance.id'), 'utf-8').trim();
+      expect(fileContent).toBe(id);
+    });
+
+    it('should return the same ID on subsequent calls', () => {
+      const id1 = getInstanceId(testHiveDir);
+      const id2 = getInstanceId(testHiveDir);
+      expect(id1).toBe(id2);
+    });
+
+    it('should read existing instance ID from file', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'testid', 'utf-8');
+      const id = getInstanceId(testHiveDir);
+      expect(id).toBe('testid');
+    });
+  });
+
+  describe('getInstancePrefix', () => {
+    it('should return hive-<instanceId> when hive dir exists', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const prefix = getInstancePrefix(testHiveDir);
+      expect(prefix).toBe('hive-abc123');
+    });
+
+    it('should fall back to hive when hive dir does not exist', () => {
+      const prefix = getInstancePrefix('/nonexistent/path/.hive');
+      expect(prefix).toBe('hive');
+    });
+  });
+
+  describe('buildInstanceSessionName', () => {
+    it('should build instance-scoped session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team');
+      expect(name).toBe('hive-abc123-senior-my-team');
+    });
+
+    it('should include index when > 1', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team', 3);
+      expect(name).toBe('hive-abc123-senior-my-team-3');
+    });
+
+    it('should omit index when 1', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team', 1);
+      expect(name).toBe('hive-abc123-senior-my-team');
+    });
+
+    it('should fall back to old format when no hive dir', () => {
+      const name = buildInstanceSessionName('/nonexistent', 'senior', 'my-team');
+      expect(name).toBe('hive-senior-my-team');
+    });
+  });
+
+  describe('getTechLeadSessionName', () => {
+    it('should return instance-scoped tech lead session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const name = getTechLeadSessionName(testHiveDir);
+      expect(name).toBe('hive-xyz789-tech-lead');
+    });
+
+    it('should fall back to hive-tech-lead when no instance', () => {
+      const name = getTechLeadSessionName('/nonexistent');
+      expect(name).toBe('hive-tech-lead');
+    });
+  });
+
+  describe('getManagerSessionName', () => {
+    it('should return instance-scoped manager session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const name = getManagerSessionName(testHiveDir);
+      expect(name).toBe('hive-xyz789-manager');
+    });
+  });
+
+  describe('getManagerLockPath', () => {
+    it('should return instance-scoped lock path', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const lockPath = getManagerLockPath(testHiveDir);
+      expect(lockPath).toBe(join(testHiveDir, 'manager-xyz789.lock'));
+    });
+
+    it('should fall back to default lock path when no instance', () => {
+      const lockPath = getManagerLockPath('/nonexistent');
+      expect(lockPath).toBe(join('/nonexistent', 'manager.lock'));
+    });
+  });
+});