@helmiq/crew 0.1.0

package/dist/context/context.test.js

@@ -0,0 +1,260 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assembleContext } from './assembler.js';
+import { extractSections } from './section-extractor.js';
+import { readArtifact } from './artifact-reader.js';
+import { readCodeFiles } from './code-reader.js';
+import { countTokens } from './token-budget.js';
+const runtimeRoot = join(fileURLToPath(import.meta.url), '..', '..', '..');
+const fixturesPath = join(runtimeRoot, 'test', 'fixtures');
+const testConfig = {
+    project: {
+        name: 'Test Project',
+        key: 'TEST',
+    },
+    workspace: {
+        path: '.',
+        work: 'work/{EPIC_ID}/',
+        runs: 'runs/',
+    },
+    source: {
+        repo: 'github:test/project',
+        path: join(runtimeRoot, 'test', 'fixtures-target'),
+    },
+    llm: {
+        default_model: 'claude-sonnet',
+        providers: {
+            anthropic: {
+                api_key_env: 'ANTHROPIC_API_KEY',
+                models: { 'claude-sonnet': 'claude-sonnet-4-20250514' },
+            },
+        },
+    },
+};
+describe('T-01-002a: artifact reading by type/scope', () => {
+    it('reads a requirements artifact by epic scope', async () => {
+        const result = await readArtifact({ artifact: 'requirements', scope: { epic: 'CREW-01' } }, testConfig, fixturesPath);
+        expect(result.found).toBe(true);
+        expect(result.content).toContain('CREW-01 delivers the execution runtime');
+    });
+    it('reads a design artifact by epic scope', async () => {
+        const result = await readArtifact({ artifact: 'design', scope: { epic: 'CREW-01' } }, testConfig, fixturesPath);
+        expect(result.found).toBe(true);
+        expect(result.content).toContain('packages/runtime/');
+    });
+    it('reads a standards artifact by type scope', async () => {
+        const result = await readArtifact({ artifact: 'standards', scope: { type: 'solution' } }, testConfig, fixturesPath);
+        expect(result.found).toBe(true);
+        expect(result.content).toContain('Solution Architecture');
+    });
+    it('reads code files from the target repo', async () => {
+        const targetPath = join(fixturesPath, '..', 'fixtures-target');
+        const files = await readCodeFiles(targetPath, ['src/config/loader.ts']);
+        expect(files).toHaveLength(1);
+        expect(files[0].relativePath).toBe('src/config/loader.ts');
+        expect(files[0].content).toContain('loadConfig');
+    });
+    it('reads a directory of code files recursively', async () => {
+        const targetPath = join(fixturesPath, '..', 'fixtures-target');
+        const files = await readCodeFiles(targetPath, ['src/config']);
+        expect(files.length).toBeGreaterThanOrEqual(2);
+        const paths = files.map((f) => f.relativePath);
+        expect(paths).toContain('src/config/loader.ts');
+        expect(paths).toContain('src/config/resolver.ts');
+    });
+    it('returns empty for nonexistent code paths', async () => {
+        const targetPath = join(fixturesPath, '..', 'fixtures-target');
+        const files = await readCodeFiles(targetPath, ['nonexistent/path.ts']);
+        expect(files).toHaveLength(0);
+    });
+});
+describe('T-01-002b: section extraction', () => {
+    const markdown = `# Title
+
+## Overview
+
+This is the overview section.
+
+## Functional Requirements
+
+- FR-001
+- FR-002
+
+## Non-Functional Requirements
+
+- Reliability
+
+## Scope Definition
+
+In scope items.
+`;
+    it('extracts a single named section', () => {
+        const result = extractSections(markdown, ['Overview']);
+        expect(result).toContain('This is the overview section.');
+        expect(result).not.toContain('FR-001');
+    });
+    it('extracts multiple named sections', () => {
+        const result = extractSections(markdown, [
+            'Functional Requirements',
+            'Non-Functional Requirements',
+        ]);
+        expect(result).toContain('FR-001');
+        expect(result).toContain('Reliability');
+        expect(result).not.toContain('overview');
+    });
+    it('is case-insensitive on section names', () => {
+        const result = extractSections(markdown, ['overview']);
+        expect(result).toContain('This is the overview section.');
+    });
+    it('returns empty string when no sections match', () => {
+        const result = extractSections(markdown, ['Nonexistent Section']);
+        expect(result).toBe('');
+    });
+    it('returns full content when no sections are specified', () => {
+        expect(extractSections(markdown, [])).toBe(markdown);
+        expect(extractSections(markdown, undefined)).toBe(markdown);
+    });
+});
+describe('T-01-002c: token budget enforcement', () => {
+    it('counts tokens for a string', () => {
+        const tokens = countTokens('Hello, world!');
+        expect(tokens).toBeGreaterThan(0);
+        expect(tokens).toBeLessThan(20);
+    });
+    it('respects a tight budget by excluding conditional refs', async () => {
+        const perception = {
+            always_read: [{ artifact: 'requirements', scope: { epic: 'CREW-01' } }],
+            per_task: {
+                'implement-story': [
+                    { artifact: 'design', scope: { epic: 'CREW-01' } },
+                    {
+                        artifact: 'standards',
+                        scope: { type: 'solution' },
+                        when: 'always',
+                    },
+                ],
+            },
+        };
+        const result = await assembleContext(perception, 'implement-story', { EPIC_ID: 'CREW-01' }, testConfig, fixturesPath, 50);
+        expect(result.budgetLimit).toBe(50);
+        const conditionalBlocks = result.blocks.filter((b) => b.priority === 'conditional');
+        expect(conditionalBlocks).toHaveLength(0);
+    });
+    it('includes conditional refs when budget is large enough', async () => {
+        const perception = {
+            per_task: {
+                'implement-story': [
+                    { artifact: 'requirements', scope: { epic: 'CREW-01' } },
+                    {
+                        artifact: 'standards',
+                        scope: { type: 'solution' },
+                        when: 'always',
+                    },
+                ],
+            },
+        };
+        const result = await assembleContext(perception, 'implement-story', { EPIC_ID: 'CREW-01' }, testConfig, fixturesPath, 100_000);
+        const conditionalBlocks = result.blocks.filter((b) => b.priority === 'conditional');
+        expect(conditionalBlocks.length).toBeGreaterThan(0);
+    });
+    it('totalTokens reflects the sum of all block tokens', async () => {
+        const perception = {
+            per_task: {
+                task: [{ artifact: 'requirements', scope: { epic: 'CREW-01' } }],
+            },
+        };
+        const result = await assembleContext(perception, 'task', { EPIC_ID: 'CREW-01' }, testConfig, fixturesPath);
+        const sum = result.blocks.reduce((acc, b) => acc + b.tokens, 0);
+        expect(result.totalTokens).toBe(sum);
+    });
+});
+describe('artifact reader: architecture artifact types', () => {
+    it('resolves adr-register artifact to architecture/decisions/register.md', async () => {
+        const result = await readArtifact({ artifact: 'adr-register', scope: {} }, testConfig, fixturesPath);
+        expect(result.path).toContain('architecture/decisions/register.md');
+    });
+    it('resolves architecture artifact to architecture/{type}.md via scope type', async () => {
+        const result = await readArtifact({ artifact: 'architecture', scope: { type: 'solution' } }, testConfig, fixturesPath);
+        expect(result.path).toContain('architecture/solution.md');
+    });
+});
+describe('T-01-002d: missing artifact handling', () => {
+    it('returns found=false for a nonexistent artifact', async () => {
+        const result = await readArtifact({ artifact: 'requirements', scope: { epic: 'NONEXISTENT' } }, testConfig, fixturesPath);
+        expect(result.found).toBe(false);
+        expect(result.content).toBeNull();
+    });
+    it('flags missing artifacts as gaps in assembled context', async () => {
+        const perception = {
+            per_task: {
+                task: [
+                    { artifact: 'requirements', scope: { epic: 'CREW-01' } },
+                    { artifact: 'requirements', scope: { epic: 'MISSING-EPIC' } },
+                    { artifact: 'design', scope: { epic: 'ALSO-MISSING' } },
+                ],
+            },
+        };
+        const result = await assembleContext(perception, 'task', {}, testConfig, fixturesPath);
+        expect(result.gaps).toHaveLength(2);
+        expect(result.gaps.some((g) => g.includes('MISSING-EPIC'))).toBe(true);
+        expect(result.gaps.some((g) => g.includes('ALSO-MISSING'))).toBe(true);
+        expect(result.blocks).toHaveLength(1);
+    });
+    it('does not throw on missing artifacts', async () => {
+        const perception = {
+            per_task: {
+                task: [{ artifact: 'requirements', scope: { epic: 'NOPE' } }],
+            },
+        };
+        const result = await assembleContext(perception, 'task', {}, testConfig, fixturesPath);
+        expect(result.blocks).toHaveLength(0);
+        expect(result.gaps).toHaveLength(1);
+        expect(result.totalTokens).toBe(0);
+    });
+});
+describe('assembleContext integration', () => {
+    it('assembles context with section extraction', async () => {
+        const perception = {
+            always_read: [
+                {
+                    artifact: 'standards',
+                    scope: { type: 'solution' },
+                    sections: ['Execution Runtime'],
+                },
+            ],
+            per_task: {
+                'implement-story': [
+                    {
+                        artifact: 'requirements',
+                        scope: { epic: 'CREW-01' },
+                        sections: ['Functional Requirements'],
+                    },
+                ],
+            },
+        };
+        const result = await assembleContext(perception, 'implement-story', { EPIC_ID: 'CREW-01' }, testConfig, fixturesPath);
+        expect(result.blocks).toHaveLength(2);
+        expect(result.blocks[0].content).toContain('persona tasks');
+        expect(result.blocks[0].content).not.toContain('Purpose');
+        expect(result.blocks[1].content).toContain('FR-001');
+        expect(result.blocks[1].content).not.toContain('Reliability');
+        expect(result.gaps).toHaveLength(0);
+        expect(result.totalTokens).toBeGreaterThan(0);
+    });
+    it('interpolates template variables in scope', async () => {
+        const perception = {
+            per_task: {
+                'implement-story': [
+                    {
+                        artifact: 'requirements',
+                        scope: { epic: '{{ .EPIC_ID }}' },
+                    },
+                ],
+            },
+        };
+        const result = await assembleContext(perception, 'implement-story', { EPIC_ID: 'CREW-01' }, testConfig, fixturesPath);
+        expect(result.blocks).toHaveLength(1);
+        expect(result.blocks[0].content).toContain('CREW-01 delivers the execution runtime');
+    });
+});

package/dist/context/index.d.ts

@@ -0,0 +1,9 @@
+export { assembleContext } from './assembler.js';
+export type { ContextBlock, AssembledContext } from './assembler.js';
+export { readArtifact } from './artifact-reader.js';
+export type { ArtifactReadResult } from './artifact-reader.js';
+export { readCodeFiles } from './code-reader.js';
+export type { CodeFileResult } from './code-reader.js';
+export { extractSections } from './section-extractor.js';
+export { countTokens, defaultTokenBudget } from './token-budget.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,5 @@
+export { assembleContext } from './assembler.js';
+export { readArtifact } from './artifact-reader.js';
+export { readCodeFiles } from './code-reader.js';
+export { extractSections } from './section-extractor.js';
+export { countTokens, defaultTokenBudget } from './token-budget.js';

package/dist/context/section-extractor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extract named sections from a Markdown document.
+ *
+ * Splits by level-2 headings (`## `), then returns only those sections
+ * whose heading text matches one of the requested section names (case-insensitive).
+ * If no sections are requested (empty array or undefined), returns the full content.
+ */
+export declare function extractSections(markdown: string, sectionNames?: string[]): string;
+//# sourceMappingURL=section-extractor.d.ts.map

package/dist/context/section-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-extractor.d.ts","sourceRoot":"","sources":["../../src/context/section-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAwBjF"}

package/dist/context/section-extractor.js

@@ -0,0 +1,32 @@
+/**
+ * Extract named sections from a Markdown document.
+ *
+ * Splits by level-2 headings (`## `), then returns only those sections
+ * whose heading text matches one of the requested section names (case-insensitive).
+ * If no sections are requested (empty array or undefined), returns the full content.
+ */
+export function extractSections(markdown, sectionNames) {
+    if (!sectionNames || sectionNames.length === 0)
+        return markdown;
+    const lowerNames = new Set(sectionNames.map((s) => s.toLowerCase().trim()));
+    const lines = markdown.split('\n');
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const headingMatch = /^##\s+(.+)$/.exec(line);
+        if (headingMatch) {
+            if (current)
+                sections.push(current);
+            current = { heading: headingMatch[1].trim(), lines: [line] };
+        }
+        else if (current) {
+            current.lines.push(line);
+        }
+    }
+    if (current)
+        sections.push(current);
+    const matched = sections.filter((s) => lowerNames.has(s.heading.toLowerCase()));
+    if (matched.length === 0)
+        return '';
+    return matched.map((s) => s.lines.join('\n')).join('\n\n');
+}

package/dist/context/token-budget.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Count tokens in a string using the cl100k_base encoding.
+ * This is a conservative approximation for Claude (slightly over-counts).
+ */
+export declare function countTokens(text: string): number;
+/**
+ * Default token budget: 100,000 tokens.
+ * Configurable via CREW_TOKEN_BUDGET environment variable.
+ */
+export declare function defaultTokenBudget(): number;
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/context/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/context/token-budget.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C"}

package/dist/context/token-budget.js

@@ -0,0 +1,22 @@
+import { encodingForModel } from 'js-tiktoken';
+const encoder = encodingForModel('gpt-4o');
+/**
+ * Count tokens in a string using the cl100k_base encoding.
+ * This is a conservative approximation for Claude (slightly over-counts).
+ */
+export function countTokens(text) {
+    return encoder.encode(text).length;
+}
+/**
+ * Default token budget: 100,000 tokens.
+ * Configurable via CREW_TOKEN_BUDGET environment variable.
+ */
+export function defaultTokenBudget() {
+    const env = process.env['CREW_TOKEN_BUDGET'];
+    if (env) {
+        const parsed = parseInt(env, 10);
+        if (!Number.isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return 100_000;
+}

package/dist/control/control.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=control.test.d.ts.map

package/dist/control/control.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.test.d.ts","sourceRoot":"","sources":["../../src/control/control.test.ts"],"names":[],"mappings":""}

package/dist/control/control.test.js

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtemp, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { acquireLock } from './lock-manager.js';
+import { transitionState, persistState, loadState } from './run-state.js';
+import { generateRunId, generateIdempotencyKey } from './id-generator.js';
+import { LockAcquisitionError, InvalidStateTransitionError } from '../common/errors.js';
+let runsDir;
+beforeEach(async () => {
+    runsDir = await mkdtemp(join(tmpdir(), 'crew-control-test-'));
+});
+describe('T-01-007a: lock acquisition and release', () => {
+    it('acquires a lock and creates a lock file', async () => {
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        expect(handle.runId).toBeTruthy();
+        expect(handle.lockPath).toContain('.locks');
+        expect(handle.lockPath).toContain('engineer-implement-CREW-01-001.lock');
+        const lockContent = await readFile(handle.lockPath, 'utf-8');
+        const parsed = JSON.parse(lockContent);
+        expect(parsed.runId).toBe(handle.runId);
+        expect(parsed.ttlMs).toBeGreaterThan(0);
+        await handle.release();
+    });
+    it('releases the lock by deleting the lock file', async () => {
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        await handle.release();
+        const secondHandle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        expect(secondHandle.runId).toBeTruthy();
+        await secondHandle.release();
+    });
+    it('release is idempotent', async () => {
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        await handle.release();
+        await expect(handle.release()).resolves.toBeUndefined();
+    });
+});
+describe('T-01-007b: duplicate run prevention', () => {
+    it('throws LockAcquisitionError when lock is held', async () => {
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        await expect(acquireLock('engineer', 'implement', 'CREW-01-001', runsDir)).rejects.toThrow(LockAcquisitionError);
+        await handle.release();
+    });
+    it('allows different scopes to lock concurrently', async () => {
+        const h1 = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir);
+        const h2 = await acquireLock('engineer', 'implement', 'CREW-01-002', runsDir);
+        const h3 = await acquireLock('reviewer', 'review', 'CREW-01-001', runsDir);
+        expect(h1.runId).not.toBe(h2.runId);
+        expect(h1.runId).not.toBe(h3.runId);
+        await h1.release();
+        await h2.release();
+        await h3.release();
+    });
+});
+describe('T-01-007c: state transitions', () => {
+    const baseRecord = {
+        run_id: 'run-test-001',
+        persona: 'engineer',
+        task: 'implement-story',
+        scope: 'CREW-01-001',
+        status: 'queued',
+        started_at: new Date().toISOString(),
+    };
+    it('transitions through the happy path', () => {
+        let r = transitionState(baseRecord, 'running');
+        expect(r.status).toBe('running');
+        r = transitionState(r, 'evaluating');
+        expect(r.status).toBe('evaluating');
+        r = transitionState(r, 'publishing');
+        expect(r.status).toBe('publishing');
+        r = transitionState(r, 'published');
+        expect(r.status).toBe('published');
+        expect(r.completed_at).toBeTruthy();
+    });
+    it('transitions to failed from running', () => {
+        const r = transitionState({ ...baseRecord, status: 'running' }, 'failed');
+        expect(r.status).toBe('failed');
+        expect(r.completed_at).toBeTruthy();
+    });
+    it('transitions to awaiting_review from publishing', () => {
+        const r = transitionState({ ...baseRecord, status: 'publishing' }, 'awaiting_review');
+        expect(r.status).toBe('awaiting_review');
+    });
+    it('rejects invalid transitions', () => {
+        expect(() => transitionState(baseRecord, 'evaluating')).toThrow(InvalidStateTransitionError);
+        expect(() => transitionState(baseRecord, 'published')).toThrow(InvalidStateTransitionError);
+        expect(() => transitionState({ ...baseRecord, status: 'published' }, 'running')).toThrow(InvalidStateTransitionError);
+    });
+    it('persists and loads state from disk', async () => {
+        const runDir = join(runsDir, 'run-test-001');
+        await persistState(runDir, baseRecord);
+        const loaded = await loadState(runDir);
+        expect(loaded).not.toBeNull();
+        expect(loaded.run_id).toBe('run-test-001');
+        expect(loaded.status).toBe('queued');
+    });
+    it('returns null for nonexistent state file', async () => {
+        const loaded = await loadState(join(runsDir, 'nonexistent'));
+        expect(loaded).toBeNull();
+    });
+});
+describe('T-01-007d: stale lock cleanup', () => {
+    it('auto-releases a stale lock and allows new acquisition', async () => {
+        const locksDir = join(runsDir, '.locks');
+        await mkdir(locksDir, { recursive: true });
+        const lockPath = join(locksDir, 'engineer-implement-CREW-01-001.lock');
+        const staleLock = {
+            runId: 'run-stale-old',
+            timestamp: new Date(Date.now() - 7_200_000).toISOString(), // 2 hours ago
+            ttlMs: 3_600_000, // 1 hour TTL -- expired
+        };
+        await writeFile(lockPath, JSON.stringify(staleLock), 'utf-8');
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir, 3_600_000);
+        expect(handle.runId).not.toBe('run-stale-old');
+        await handle.release();
+    });
+    it('does not release a fresh lock', async () => {
+        const handle = await acquireLock('engineer', 'implement', 'CREW-01-001', runsDir, 3_600_000);
+        await expect(acquireLock('engineer', 'implement', 'CREW-01-001', runsDir, 3_600_000)).rejects.toThrow(LockAcquisitionError);
+        await handle.release();
+    });
+});
+describe('id generation', () => {
+    it('generates a run ID containing persona, task, and scope', () => {
+        const id = generateRunId('engineer', 'implement-story', 'CREW-01-001');
+        expect(id).toContain('run-');
+        expect(id).toContain('engineer');
+        expect(id).toContain('implement-story');
+        expect(id).toContain('CREW-01-001');
+    });
+    it('generates unique idempotency keys', () => {
+        const k1 = generateIdempotencyKey();
+        const k2 = generateIdempotencyKey();
+        expect(k1).not.toBe(k2);
+        expect(k1).toHaveLength(32);
+    });
+});

package/dist/control/id-generator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate a run ID in the format:
+ * run-{ISO timestamp}-{persona}-{task}-{scope}
+ *
+ * The timestamp uses a filesystem-safe format (colons replaced with dashes).
+ */
+export declare function generateRunId(persona: string, task: string, scope: string): string;
+/**
+ * Generate an idempotency key: a random 16-byte hex string.
+ */
+export declare function generateIdempotencyKey(): string;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/control/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/control/id-generator.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/control/id-generator.js

@@ -0,0 +1,20 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Generate a run ID in the format:
+ * run-{ISO timestamp}-{persona}-{task}-{scope}
+ *
+ * The timestamp uses a filesystem-safe format (colons replaced with dashes).
+ */
+export function generateRunId(persona, task, scope) {
+    const ts = new Date()
+        .toISOString()
+        .replace(/:/g, '-')
+        .replace(/\.\d+Z$/, 'Z');
+    return `run-${ts}-${persona}-${task}-${scope}`;
+}
+/**
+ * Generate an idempotency key: a random 16-byte hex string.
+ */
+export function generateIdempotencyKey() {
+    return randomBytes(16).toString('hex');
+}

package/dist/control/index.d.ts

@@ -0,0 +1,5 @@
+export { acquireLock } from './lock-manager.js';
+export type { LockHandle } from './lock-manager.js';
+export { transitionState, persistState, loadState } from './run-state.js';
+export { generateRunId, generateIdempotencyKey } from './id-generator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/control/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/control/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/control/index.js

@@ -0,0 +1,3 @@
+export { acquireLock } from './lock-manager.js';
+export { transitionState, persistState, loadState } from './run-state.js';
+export { generateRunId, generateIdempotencyKey } from './id-generator.js';

package/dist/control/lock-manager.d.ts

@@ -0,0 +1,13 @@
+export interface LockHandle {
+    lockPath: string;
+    runId: string;
+    release(): Promise<void>;
+}
+/**
+ * Acquire a file-based lock scoped to persona + task + scope.
+ *
+ * If a lock file exists and is within TTL, throws LockAcquisitionError.
+ * If a lock file exists but is past TTL, it is automatically released (stale lock cleanup).
+ */
+export declare function acquireLock(persona: string, task: string, scope: string, runsDir: string, ttlMs?: number): Promise<LockHandle>;
+//# sourceMappingURL=lock-manager.d.ts.map

package/dist/control/lock-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-manager.d.ts","sourceRoot":"","sources":["../../src/control/lock-manager.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,CAwCrB"}

package/dist/control/lock-manager.js

@@ -0,0 +1,72 @@
+import { writeFile, readFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { LockAcquisitionError } from '../common/errors.js';
+const DEFAULT_TTL_MS = 3_600_000; // 1 hour
+function getLockTtl() {
+    const env = process.env['CREW_LOCK_TTL_MS'];
+    if (env) {
+        const parsed = parseInt(env, 10);
+        if (!Number.isNaN(parsed) && parsed >= 300_000)
+            return parsed;
+    }
+    return DEFAULT_TTL_MS;
+}
+function lockFileName(persona, task, scope) {
+    return `${persona}-${task}-${scope}.lock`;
+}
+/**
+ * Acquire a file-based lock scoped to persona + task + scope.
+ *
+ * If a lock file exists and is within TTL, throws LockAcquisitionError.
+ * If a lock file exists but is past TTL, it is automatically released (stale lock cleanup).
+ */
+export async function acquireLock(persona, task, scope, runsDir, ttlMs) {
+    const ttl = ttlMs ?? getLockTtl();
+    const locksDir = join(runsDir, '.locks');
+    await mkdir(locksDir, { recursive: true });
+    const lockFile = lockFileName(persona, task, scope);
+    const lockPath = join(locksDir, lockFile);
+    const existing = await readLock(lockPath);
+    if (existing) {
+        const age = Date.now() - new Date(existing.timestamp).getTime();
+        if (age < existing.ttlMs) {
+            throw new LockAcquisitionError(`Lock held by run '${existing.runId}' (acquired ${existing.timestamp}, TTL ${existing.ttlMs}ms). Scope: ${persona}-${task}-${scope}`);
+        }
+        // Stale lock -- release it
+        await releaseLockFile(lockPath);
+    }
+    const runId = `run-${new Date()
+        .toISOString()
+        .replace(/:/g, '-')
+        .replace(/\.\d+Z$/, 'Z')}-${persona}-${task}-${scope}`;
+    const lockData = {
+        runId,
+        timestamp: new Date().toISOString(),
+        ttlMs: ttl,
+    };
+    await writeFile(lockPath, JSON.stringify(lockData, null, 2), 'utf-8');
+    return {
+        lockPath,
+        runId,
+        async release() {
+            await releaseLockFile(lockPath);
+        },
+    };
+}
+async function readLock(lockPath) {
+    try {
+        const raw = await readFile(lockPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function releaseLockFile(lockPath) {
+    try {
+        await unlink(lockPath);
+    }
+    catch {
+        /* file may already be gone */
+    }
+}