hungry-ghost-hive 0.44.0 → 0.45.0

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'));
+    });
+  });
+});

package/src/utils/instance.ts

@@ -0,0 +1,95 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { nanoid } from 'nanoid';
+import { join } from 'path';
+
+const INSTANCE_ID_FILE = 'instance.id';
+
+/**
+ * Get or create the instance ID for a hive workspace.
+ * The ID is stored in .hive/instance.id.
+ * Returns null if the hive directory does not exist.
+ * Only creates the file if the .hive directory already exists
+ * (i.e., this is a real workspace, not a test environment).
+ */
+export function getInstanceId(hiveDir: string): string | null {
+  if (!existsSync(hiveDir)) {
+    return null;
+  }
+
+  const instancePath = join(hiveDir, INSTANCE_ID_FILE);
+
+  if (existsSync(instancePath)) {
+    const id = readFileSync(instancePath, 'utf-8').trim();
+    if (id) return id;
+  }
+
+  // Generate a short unique ID for this workspace instance
+  const id = nanoid(6);
+  try {
+    writeFileSync(instancePath, id, 'utf-8');
+  } catch {
+    // If write fails (e.g., read-only filesystem), use in-memory ID
+  }
+  return id;
+}
+
+/**
+ * Get the instance-scoped tmux session prefix.
+ * Falls back to 'hive' if no instance ID is available.
+ */
+export function getInstancePrefix(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return `hive-${instanceId}`;
+  }
+  return 'hive';
+}
+
+/**
+ * Build an instance-scoped session name.
+ * Pattern: hive-<instanceId>-<agentType>[-<teamName>][-<index>]
+ * Falls back to hive-<agentType>[-<teamName>][-<index>] if no instance ID.
+ */
+export function buildInstanceSessionName(
+  hiveDir: string,
+  agentType: string,
+  teamName?: string,
+  index?: number
+): string {
+  const prefix = getInstancePrefix(hiveDir);
+  let name = `${prefix}-${agentType}`;
+  if (teamName) {
+    name += `-${teamName}`;
+  }
+  if (index !== undefined && index > 1) {
+    name += `-${index}`;
+  }
+  return name;
+}
+
+/**
+ * Build the instance-scoped tech lead session name.
+ */
+export function getTechLeadSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'tech-lead');
+}
+
+/**
+ * Build the instance-scoped manager session name.
+ */
+export function getManagerSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'manager');
+}
+
+/**
+ * Build the instance-scoped manager lock path.
+ */
+export function getManagerLockPath(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return join(hiveDir, `manager-${instanceId}.lock`);
+  }
+  return join(hiveDir, 'manager.lock');
+}

package/src/utils/paths.test.ts

@@ -102,6 +102,7 @@ describe('paths utility', () => {
         agentsDir: join(rootDir, '.hive', 'agents'),
         logsDir: join(rootDir, '.hive', 'logs'),
         reposDir: join(rootDir, 'repos'),
+        storiesDir: join(rootDir, '.hive', 'stories'),
       });
     });
 
@@ -128,6 +129,7 @@ describe('paths utility', () => {
       expect(result.configPath).toContain(result.hiveDir);
       expect(result.agentsDir).toContain(result.hiveDir);
       expect(result.logsDir).toContain(result.hiveDir);
+      expect(result.storiesDir).toContain(result.hiveDir);
       expect(result.reposDir).not.toContain(result.hiveDir);
     });
 
@@ -154,6 +156,12 @@ describe('paths utility', () => {
 
       expect(result.logsDir).toContain(paths.LOGS_DIR_NAME);
     });
+
+    it('should use STORIES_DIR_NAME constant for stories directory', () => {
+      const result = paths.getHivePaths(rootDir);
+
+      expect(result.storiesDir).toBe(join(rootDir, '.hive', paths.STORIES_DIR_NAME));
+    });
   });
 
   describe('isHiveWorkspace', () => {

package/src/utils/paths.ts

@@ -7,6 +7,7 @@ export const HIVE_DIR_NAME = '.hive';
 export const REPOS_DIR_NAME = 'repos';
 export const AGENTS_DIR_NAME = 'agents';
 export const LOGS_DIR_NAME = 'logs';
+export const STORIES_DIR_NAME = 'stories';
 
 export interface HivePaths {
   root: string;
@@ -16,6 +17,7 @@ export interface HivePaths {
   agentsDir: string;
   logsDir: string;
   reposDir: string;
+  storiesDir: string;
 }
 
 export function findHiveRoot(startDir: string = process.cwd()): string | null {
@@ -43,6 +45,7 @@ export function getHivePaths(rootDir: string): HivePaths {
     agentsDir: join(hiveDir, AGENTS_DIR_NAME),
     logsDir: join(hiveDir, LOGS_DIR_NAME),
     reposDir: join(rootDir, REPOS_DIR_NAME),
+    storiesDir: join(hiveDir, STORIES_DIR_NAME),
   };
 }
 

package/src/utils/story-markdown.test.ts

@@ -0,0 +1,176 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { StoryRow } from '../db/client.js';
+import {
+  deleteStoryMarkdown,
+  generateStoryMarkdown,
+  writeStoryMarkdown,
+} from './story-markdown.js';
+
+const TEST_DIR = join('/tmp', `story-markdown-test-${Date.now()}`);
+
+function makeStory(overrides: Partial<StoryRow> = {}): StoryRow {
+  return {
+    id: 'STORY-TEST01',
+    requirement_id: null,
+    team_id: null,
+    title: 'Test Story',
+    description: 'A test story description.',
+    acceptance_criteria: null,
+    complexity_score: null,
+    story_points: null,
+    status: 'draft',
+    assigned_agent_id: null,
+    branch_name: null,
+    pr_url: null,
+    jira_issue_key: null,
+    jira_issue_id: null,
+    jira_project_key: null,
+    jira_subtask_key: null,
+    jira_subtask_id: null,
+    external_issue_key: null,
+    external_issue_id: null,
+    external_project_key: null,
+    external_subtask_key: null,
+    external_subtask_id: null,
+    external_provider: null,
+    in_sprint: 0,
+    markdown_path: null,
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+describe('generateStoryMarkdown', () => {
+  it('should generate a markdown document with title and description', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('# Test Story');
+    expect(md).toContain('**Story ID:** STORY-TEST01');
+    expect(md).toContain('**Status:** draft');
+    expect(md).toContain('A test story description.');
+  });
+
+  it('should include acceptance criteria as a checklist', () => {
+    const story = makeStory({
+      acceptance_criteria: JSON.stringify(['Criterion A', 'Criterion B']),
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('## Acceptance Criteria');
+    expect(md).toContain('- [ ] Criterion A');
+    expect(md).toContain('- [ ] Criterion B');
+  });
+
+  it('should include optional fields when present', () => {
+    const story = makeStory({
+      team_id: 'TEAM-1',
+      requirement_id: 'REQ-1',
+      assigned_agent_id: 'agent-123',
+      complexity_score: 5,
+      story_points: 5,
+      branch_name: 'feature/STORY-TEST01-test-story',
+      pr_url: 'https://github.com/test/repo/pull/42',
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('**Team:** TEAM-1');
+    expect(md).toContain('**Requirement:** REQ-1');
+    expect(md).toContain('**Assigned Agent:** agent-123');
+    expect(md).toContain('**Complexity:** 5');
+    expect(md).toContain('**Story Points:** 5');
+    expect(md).toContain('**Branch:** feature/STORY-TEST01-test-story');
+    expect(md).toContain('**PR:** https://github.com/test/repo/pull/42');
+  });
+
+  it('should include created and updated timestamps', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('*Created: 2026-01-01T00:00:00.000Z*');
+    expect(md).toContain('*Updated: 2026-01-01T00:00:00.000Z*');
+  });
+
+  it('should handle malformed acceptance_criteria gracefully', () => {
+    const story = makeStory({ acceptance_criteria: 'not-json' });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('not-json');
+  });
+});
+
+describe('writeStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should write a markdown file in storiesDir', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+
+    expect(existsSync(filePath)).toBe(true);
+    expect(filePath).toBe(join(TEST_DIR, 'STORY-TEST01.md'));
+  });
+
+  it('should create the directory if it does not exist', () => {
+    const nestedDir = join(TEST_DIR, 'nested', 'stories');
+    const story = makeStory();
+    writeStoryMarkdown(nestedDir, story);
+
+    expect(existsSync(nestedDir)).toBe(true);
+    expect(existsSync(join(nestedDir, 'STORY-TEST01.md'))).toBe(true);
+  });
+
+  it('should write valid markdown content', () => {
+    const story = makeStory({ description: 'My description.' });
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# Test Story');
+    expect(content).toContain('My description.');
+  });
+
+  it('should overwrite existing file on update', () => {
+    const story = makeStory({ title: 'Old Title' });
+    writeStoryMarkdown(TEST_DIR, story);
+
+    const updatedStory = makeStory({ title: 'New Title' });
+    const filePath = writeStoryMarkdown(TEST_DIR, updatedStory);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# New Title');
+    expect(content).not.toContain('# Old Title');
+  });
+});
+
+describe('deleteStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should delete the markdown file', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    expect(existsSync(filePath)).toBe(true);
+
+    deleteStoryMarkdown(TEST_DIR, story.id);
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it('should not throw if file does not exist', () => {
+    expect(() => deleteStoryMarkdown(TEST_DIR, 'STORY-NONEXISTENT')).not.toThrow();
+  });
+});

package/src/utils/story-markdown.ts

@@ -0,0 +1,94 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { StoryRow } from '../db/client.js';
+
+/**
+ * Generate markdown content for a story.
+ */
+export function generateStoryMarkdown(story: StoryRow): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${story.title}`);
+  lines.push('');
+  lines.push(`**Story ID:** ${story.id}`);
+  lines.push(`**Status:** ${story.status}`);
+
+  if (story.team_id) {
+    lines.push(`**Team:** ${story.team_id}`);
+  }
+  if (story.requirement_id) {
+    lines.push(`**Requirement:** ${story.requirement_id}`);
+  }
+  if (story.assigned_agent_id) {
+    lines.push(`**Assigned Agent:** ${story.assigned_agent_id}`);
+  }
+  if (story.complexity_score !== null) {
+    lines.push(`**Complexity:** ${story.complexity_score}`);
+  }
+  if (story.story_points !== null) {
+    lines.push(`**Story Points:** ${story.story_points}`);
+  }
+  if (story.branch_name) {
+    lines.push(`**Branch:** ${story.branch_name}`);
+  }
+  if (story.pr_url) {
+    lines.push(`**PR:** ${story.pr_url}`);
+  }
+
+  lines.push('');
+  lines.push('## Description');
+  lines.push('');
+  lines.push(story.description);
+
+  if (story.acceptance_criteria) {
+    lines.push('');
+    lines.push('## Acceptance Criteria');
+    lines.push('');
+    try {
+      const criteria = JSON.parse(story.acceptance_criteria) as string[];
+      for (const criterion of criteria) {
+        lines.push(`- [ ] ${criterion}`);
+      }
+    } catch {
+      lines.push(story.acceptance_criteria);
+    }
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(`*Created: ${story.created_at}*`);
+  lines.push(`*Updated: ${story.updated_at}*`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write a story as a markdown file in the storiesDir.
+ * Creates the directory if it does not exist.
+ * Returns the path to the written file.
+ */
+export function writeStoryMarkdown(storiesDir: string, story: StoryRow): string {
+  mkdirSync(storiesDir, { recursive: true });
+
+  const fileName = `${story.id}.md`;
+  const filePath = join(storiesDir, fileName);
+  const content = generateStoryMarkdown(story);
+
+  writeFileSync(filePath, content, 'utf-8');
+
+  return filePath;
+}
+
+/**
+ * Delete a story's markdown file if it exists.
+ */
+export function deleteStoryMarkdown(storiesDir: string, storyId: string): void {
+  const filePath = join(storiesDir, `${storyId}.md`);
+  if (existsSync(filePath)) {
+    rmSync(filePath);
+  }
+}