discoclaw 0.1.0

package/dist/onboarding/onboarding-flow.test.js

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest';
+import { OnboardingFlow } from './onboarding-flow.js';
+function startFlow(displayName = 'TestUser') {
+    const flow = new OnboardingFlow();
+    const greeting = flow.start(displayName);
+    return { flow, greeting };
+}
+/** Run a flow to CONFIRM step. */
+function flowToConfirm() {
+    const { flow } = startFlow();
+    flow.handleInput('David'); // NAME
+    flow.handleInput('America/New_York'); // TIMEZONE
+    flow.handleInput('yes'); // CHECKIN → CONFIRM
+    return flow;
+}
+describe('OnboardingFlow', () => {
+    it('start() returns greeting with first question', () => {
+        const { greeting } = startFlow('Dave');
+        expect(greeting.done).toBe(false);
+        expect(greeting.reply).toContain('Dave');
+        expect(greeting.reply).toContain('name');
+    });
+    it('updates lastActivityTimestamp on start and handleInput', () => {
+        const { flow } = startFlow();
+        const t1 = flow.lastActivityTimestamp;
+        expect(t1).toBeGreaterThan(0);
+        flow.handleInput('David');
+        expect(flow.lastActivityTimestamp).toBeGreaterThanOrEqual(t1);
+    });
+    // --- Happy path ---
+    it('full flow: name → timezone → check-in → confirm', () => {
+        const { flow } = startFlow();
+        let r = flow.handleInput('David');
+        expect(r.reply).toContain('David');
+        expect(r.done).toBe(false);
+        r = flow.handleInput('America/Chicago');
+        expect(r.reply).toContain('morning');
+        r = flow.handleInput('yes');
+        // Should show confirmation
+        expect(r.reply).toContain('David');
+        expect(r.reply).toContain('America/Chicago');
+        expect(r.reply).toContain('Morning check-in');
+    });
+    // --- Confirmation → write ---
+    it('confirmation with yes triggers WRITING', () => {
+        const flow = flowToConfirm();
+        const r = flow.handleInput('yes');
+        expect(r.done).toBe(false);
+        expect(r.writeResult).toBe('pending');
+        expect(r.reply).toContain('Writing');
+    });
+    it('confirmation accepts various affirmatives', () => {
+        for (const word of ['y', 'ok', 'confirm', 'looks good', 'YES']) {
+            const flow = flowToConfirm();
+            const r = flow.handleInput(word);
+            expect(r.writeResult).toBe('pending');
+        }
+    });
+    // --- Editing a field ---
+    it('editing field 1 (name) at confirmation returns to confirm with updated value', () => {
+        const flow = flowToConfirm();
+        let r = flow.handleInput('1'); // Edit name
+        expect(r.reply).toContain('name');
+        r = flow.handleInput('NewName');
+        expect(r.reply).toContain('NewName');
+        expect(r.reply).toContain('yes');
+    });
+    it('editing field 2 (timezone) at confirmation returns to confirm with updated value', () => {
+        const flow = flowToConfirm();
+        let r = flow.handleInput('2'); // Edit timezone
+        expect(r.reply).toContain('timezone');
+        r = flow.handleInput('Europe/London');
+        expect(r.reply).toContain('Europe/London');
+        expect(r.reply).toContain('yes');
+    });
+    it('editing field 3 (check-in) at confirmation returns to confirm with updated value', () => {
+        const flow = flowToConfirm();
+        let r = flow.handleInput('3'); // Edit check-in
+        expect(r.reply).toContain('morning');
+        r = flow.handleInput('no');
+        expect(r.reply).toContain('No');
+        expect(r.reply).toContain('yes');
+    });
+    // --- WRITING step ---
+    it('message during WRITING returns hang-on message', () => {
+        const flow = flowToConfirm();
+        flow.handleInput('yes'); // → WRITING
+        const r = flow.handleInput('hello?');
+        expect(r.done).toBe(false);
+        expect(r.reply).toContain('still writing');
+        expect(r.writeResult).toBeUndefined();
+    });
+    it('markWriteComplete transitions to DONE', () => {
+        const flow = flowToConfirm();
+        flow.handleInput('yes');
+        flow.markWriteComplete();
+        const r = flow.handleInput('anything');
+        expect(r.done).toBe(true);
+    });
+    it('markWriteFailed transitions to WRITE_ERROR', () => {
+        const flow = flowToConfirm();
+        flow.handleInput('yes');
+        flow.markWriteFailed('disk full');
+        const r = flow.handleInput('retry');
+        expect(r.writeResult).toBe('pending');
+    });
+    // --- Write error recovery ---
+    it('retry from WRITE_ERROR returns writeResult pending', () => {
+        const flow = flowToConfirm();
+        flow.handleInput('yes');
+        flow.markWriteFailed('oops');
+        const r = flow.handleInput('yes'); // "yes" also works as retry
+        expect(r.writeResult).toBe('pending');
+    });
+    it('edit field from WRITE_ERROR then confirm', () => {
+        const flow = flowToConfirm();
+        flow.handleInput('yes');
+        flow.markWriteFailed('oops');
+        let r = flow.handleInput('1'); // Edit name
+        expect(r.reply).toContain('name');
+        r = flow.handleInput('FixedName');
+        expect(r.reply).toContain('FixedName'); // Confirmation
+        r = flow.handleInput('yes');
+        expect(r.writeResult).toBe('pending');
+    });
+    // --- Input validation ---
+    it('empty input on required field re-prompts', () => {
+        const { flow } = startFlow();
+        const r = flow.handleInput('');
+        expect(r.reply).toContain('need something');
+    });
+    it('over-length input is rejected', () => {
+        const { flow } = startFlow();
+        const r = flow.handleInput('a'.repeat(201));
+        expect(r.reply).toContain('200 characters');
+    });
+    it('placeholder input is rejected', () => {
+        const { flow } = startFlow();
+        const r = flow.handleInput('My name is {{BOT_NAME}}');
+        expect(r.reply).toContain('template placeholder');
+    });
+    it('invalid confirmation number is rejected', () => {
+        const flow = flowToConfirm();
+        const r = flow.handleInput('99');
+        expect(r.reply).toContain('pick a number');
+    });
+    // --- Timezone validation ---
+    it.each([
+        ['PST', 'America/Los_Angeles'],
+        ['PDT', 'America/Los_Angeles'],
+        ['EST', 'America/New_York'],
+        ['EDT', 'America/New_York'],
+        ['CST', 'America/Chicago'],
+        ['MST', 'America/Denver'],
+        ['GMT', 'Etc/GMT'],
+        ['UTC', 'UTC'],
+        ['CET', 'Europe/Paris'],
+        ['BST', 'Europe/London'],
+        ['IST', 'Asia/Kolkata'],
+        ['JST', 'Asia/Tokyo'],
+    ])('timezone abbreviation %s maps to %s', (abbr, expected) => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        flow.handleInput(abbr);
+        const vals = flow.getValues();
+        expect(vals.timezone).toBe(expected);
+    });
+    it('IANA timezone name is accepted as-is', () => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        const r = flow.handleInput('Europe/Berlin');
+        expect(r.reply).toContain('morning'); // advanced to CHECKIN
+        expect(flow.getValues().timezone).toBe('Europe/Berlin');
+    });
+    it('invalid timezone re-prompts', () => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        const r = flow.handleInput('NotATimezone');
+        expect(r.done).toBe(false);
+        expect(r.reply).toContain('recognize');
+    });
+    // --- Morning check-in parsing ---
+    it.each(['yes', 'y', 'yeah', 'yep', 'sure', 'ok', '1', 'true'])('checkin "%s" is treated as yes', (input) => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        flow.handleInput('UTC');
+        flow.handleInput(input);
+        expect(flow.getValues().morningCheckin).toBe(true);
+    });
+    it.each(['no', 'n', 'nope', 'nah', '0', 'false'])('checkin "%s" is treated as no', (input) => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        flow.handleInput('UTC');
+        flow.handleInput(input);
+        expect(flow.getValues().morningCheckin).toBe(false);
+    });
+    it('invalid check-in input re-prompts', () => {
+        const { flow } = startFlow();
+        flow.handleInput('David');
+        flow.handleInput('UTC');
+        const r = flow.handleInput('maybe');
+        expect(r.done).toBe(false);
+        expect(r.reply).toContain('yes or no');
+    });
+    // --- Getters ---
+    it('getValues returns collected values', () => {
+        const flow = flowToConfirm();
+        const vals = flow.getValues();
+        expect(vals.userName).toBe('David');
+        expect(vals.timezone).toBe('America/New_York');
+        expect(vals.morningCheckin).toBe(true);
+    });
+    it('getValuesWithDefaults fills missing fields with defaults', () => {
+        const flow = new OnboardingFlow();
+        flow.start('Dave');
+        // No questions answered
+        const vals = flow.getValuesWithDefaults('Dave', 'America/Chicago');
+        expect(vals.userName).toBe('Dave');
+        expect(vals.timezone).toBe('America/Chicago');
+        expect(vals.morningCheckin).toBe(false);
+    });
+    it('getValuesWithDefaults preserves answered fields', () => {
+        const { flow } = startFlow();
+        flow.handleInput('David'); // userName answered, timezone/checkin not yet
+        const vals = flow.getValuesWithDefaults('Dave', 'UTC');
+        expect(vals.userName).toBe('David'); // answered value kept
+        expect(vals.timezone).toBe('UTC'); // default used
+        expect(vals.morningCheckin).toBe(false); // default used
+    });
+    // --- Public API surface ---
+    it('public properties exist', () => {
+        const flow = new OnboardingFlow();
+        expect(typeof flow.lastActivityTimestamp).toBe('number');
+        expect(flow.channelMode).toBe('dm');
+        expect(flow.hasRedirected).toBe(false);
+        expect(flow.channelId).toBeUndefined();
+    });
+});

package/dist/onboarding/onboarding-writer.js

@@ -0,0 +1,102 @@
+/**
+ * Onboarding writer — generates workspace files from collected onboarding values.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isOnboardingComplete } from '../workspace-bootstrap.js';
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/g;
+/**
+ * Generate IDENTITY.md content using the default bot name "Discoclaw".
+ * No template markers — ensures isOnboardingComplete() returns true.
+ */
+function generateIdentityContent() {
+    return [
+        `# IDENTITY.md - Who Am I?`,
+        ``,
+        `- **Name:** Discoclaw`,
+        `- **Creature:** Familiar — a persistent presence that lives in the tools, remembers the work, and shows up ready.`,
+        `- **Vibe:** Direct, competent, dry. Concise when the moment calls for it, thorough when it matters.`,
+        `- **Emoji:** None`,
+        ``,
+        `---`,
+        ``,
+        `This isn't just metadata. It's the start of figuring out who you are.`,
+    ].join('\n') + '\n';
+}
+/**
+ * Generate USER.md content from onboarding values.
+ */
+function generateUserContent(values) {
+    return [
+        `# USER.md - About Your Human`,
+        ``,
+        `- **Name:** ${values.userName}`,
+        `- **What to call them:** ${values.userName}`,
+        `- **Timezone:** ${values.timezone}`,
+        `- **Morning check-in:** ${values.morningCheckin ? 'Yes' : 'No'}`,
+        ``,
+        `---`,
+        ``,
+        `The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.`,
+    ].join('\n') + '\n';
+}
+/**
+ * Write IDENTITY.md and USER.md from onboarding values.
+ * Always writes both files. On retry, overwrites any previously-written file.
+ */
+export async function writeWorkspaceFiles(values, workspaceCwd) {
+    const result = { written: [], errors: [], warnings: [] };
+    // Generate IDENTITY.md
+    const identityContent = generateIdentityContent();
+    const identityPath = path.join(workspaceCwd, 'IDENTITY.md');
+    try {
+        await fs.writeFile(identityPath, identityContent, 'utf-8');
+        result.written.push('IDENTITY.md');
+    }
+    catch (err) {
+        result.errors.push(`Failed to write IDENTITY.md: ${err.message}`);
+    }
+    // Generate USER.md
+    const userContent = generateUserContent(values);
+    const userPath = path.join(workspaceCwd, 'USER.md');
+    try {
+        await fs.writeFile(userPath, userContent, 'utf-8');
+        result.written.push('USER.md');
+    }
+    catch (err) {
+        result.errors.push(`Failed to write USER.md: ${err.message}`);
+    }
+    // Check for unresolved placeholders in written files
+    for (const file of result.written) {
+        try {
+            const content = await fs.readFile(path.join(workspaceCwd, file), 'utf-8');
+            const remaining = content.match(PLACEHOLDER_RE);
+            if (remaining) {
+                result.warnings.push(`${file} has unresolved placeholders: ${remaining.join(', ')}. You can edit them manually later.`);
+            }
+        }
+        catch {
+            // File was written but can't be read back — unusual but not critical.
+        }
+    }
+    // Post-write validation
+    if (result.errors.length === 0) {
+        const complete = await isOnboardingComplete(workspaceCwd);
+        if (!complete) {
+            result.errors.push('Post-write validation failed: isOnboardingComplete() returned false.');
+        }
+        else {
+            // Clean up first-run instructions now that onboarding is done.
+            const bootstrapPath = path.join(workspaceCwd, 'BOOTSTRAP.md');
+            try {
+                await fs.unlink(bootstrapPath);
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT') {
+                    throw new Error(`Failed to clean up BOOTSTRAP.md: ${err.message}`);
+                }
+            }
+        }
+    }
+    return result;
+}

package/dist/onboarding/onboarding-writer.test.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { writeWorkspaceFiles } from './onboarding-writer.js';
+import { isOnboardingComplete } from '../workspace-bootstrap.js';
+vi.mock('../workspace-bootstrap.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, isOnboardingComplete: vi.fn(actual.isOnboardingComplete) };
+});
+describe('writeWorkspaceFiles', () => {
+    const dirs = [];
+    afterEach(async () => {
+        for (const d of dirs)
+            await fs.rm(d, { recursive: true, force: true });
+        dirs.length = 0;
+    });
+    const baseValues = {
+        userName: 'David',
+        timezone: 'America/New_York',
+        morningCheckin: false,
+    };
+    it('writes IDENTITY.md and USER.md with correct content', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        const result = await writeWorkspaceFiles(baseValues, workspace);
+        expect(result.written).toContain('IDENTITY.md');
+        expect(result.written).toContain('USER.md');
+        expect(result.errors).toHaveLength(0);
+        const identity = await fs.readFile(path.join(workspace, 'IDENTITY.md'), 'utf-8');
+        expect(identity).toContain('Discoclaw');
+        expect(identity).not.toContain('*(pick something you like)*');
+        const user = await fs.readFile(path.join(workspace, 'USER.md'), 'utf-8');
+        expect(user).toContain('David');
+        expect(user).toContain('America/New_York');
+        expect(user).toContain('**Morning check-in:** No');
+    });
+    it('passes isOnboardingComplete after writing', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        await writeWorkspaceFiles(baseValues, workspace);
+        expect(await isOnboardingComplete(workspace)).toBe(true);
+    });
+    it('produces no unresolved placeholders', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        const result = await writeWorkspaceFiles(baseValues, workspace);
+        expect(result.warnings).toHaveLength(0);
+    });
+    it('writes morning check-in preference correctly', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        const values = {
+            userName: 'Dave',
+            timezone: 'Europe/London',
+            morningCheckin: true,
+        };
+        const result = await writeWorkspaceFiles(values, workspace);
+        expect(result.errors).toHaveLength(0);
+        const user = await fs.readFile(path.join(workspace, 'USER.md'), 'utf-8');
+        expect(user).toContain('Europe/London');
+        expect(user).toContain('**Morning check-in:** Yes');
+    });
+    it('deletes BOOTSTRAP.md on successful onboarding', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        // Simulate a pre-existing BOOTSTRAP.md from scaffolding
+        await fs.writeFile(path.join(workspace, 'BOOTSTRAP.md'), '# First run\n', 'utf-8');
+        const result = await writeWorkspaceFiles(baseValues, workspace);
+        expect(result.errors).toHaveLength(0);
+        // BOOTSTRAP.md should be gone
+        await expect(fs.access(path.join(workspace, 'BOOTSTRAP.md'))).rejects.toThrow();
+    });
+    it('succeeds when BOOTSTRAP.md does not exist', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        // No BOOTSTRAP.md present — ENOENT should be silently swallowed
+        const result = await writeWorkspaceFiles(baseValues, workspace);
+        expect(result.errors).toHaveLength(0);
+        expect(result.written).toContain('IDENTITY.md');
+        expect(result.written).toContain('USER.md');
+    });
+    it('overwrites existing files on retry', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        // First write
+        await writeWorkspaceFiles(baseValues, workspace);
+        // Second write with different values
+        const newValues = {
+            userName: 'NewUser',
+            timezone: 'Asia/Tokyo',
+            morningCheckin: true,
+        };
+        const result = await writeWorkspaceFiles(newValues, workspace);
+        expect(result.errors).toHaveLength(0);
+        const user = await fs.readFile(path.join(workspace, 'USER.md'), 'utf-8');
+        expect(user).toContain('NewUser');
+        expect(user).toContain('Asia/Tokyo');
+        expect(user).not.toContain('America/New_York');
+    });
+});
+describe('writeWorkspaceFiles — BOOTSTRAP.md cleanup', () => {
+    const dirs = [];
+    let isOnboardingCompleteSpy;
+    afterEach(async () => {
+        vi.restoreAllMocks();
+        for (const d of dirs)
+            await fs.rm(d, { recursive: true, force: true });
+        dirs.length = 0;
+    });
+    const baseValues = {
+        userName: 'David',
+        timezone: 'America/New_York',
+        morningCheckin: false,
+    };
+    it('preserves BOOTSTRAP.md when post-write validation fails', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        // Place a BOOTSTRAP.md so we can verify it survives
+        const bootstrapPath = path.join(workspace, 'BOOTSTRAP.md');
+        await fs.writeFile(bootstrapPath, '# First run\n', 'utf-8');
+        // Force isOnboardingComplete to return false after files are written
+        const { isOnboardingComplete } = await import('../workspace-bootstrap.js');
+        isOnboardingCompleteSpy = vi.mocked(isOnboardingComplete).mockResolvedValue(false);
+        const result = await writeWorkspaceFiles(baseValues, workspace);
+        // Validation failed → errors array is non-empty
+        expect(result.errors.length).toBeGreaterThan(0);
+        // BOOTSTRAP.md should still exist — it must not be deleted on failure
+        await expect(fs.access(bootstrapPath)).resolves.toBeUndefined();
+    });
+    it('re-throws non-ENOENT unlink errors', async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writer-'));
+        dirs.push(workspace);
+        // Ensure isOnboardingComplete returns true so the cleanup branch runs
+        const { isOnboardingComplete } = await import('../workspace-bootstrap.js');
+        isOnboardingCompleteSpy = vi.mocked(isOnboardingComplete).mockResolvedValue(true);
+        // Make fs.unlink throw EPERM
+        const eperm = Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+        const unlinkSpy = vi.spyOn(fs, 'unlink').mockRejectedValue(eperm);
+        await expect(writeWorkspaceFiles(baseValues, workspace)).rejects.toThrow('Failed to clean up BOOTSTRAP.md');
+        unlinkSpy.mockRestore();
+    });
+});

package/dist/pidlock.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+/** Lock dirs younger than this with missing/corrupt metadata are treated as initializing. */
+const GRACE_PERIOD_MS = 2000;
+const heldLocks = new Map();
+function lockDirPath(lockPath) {
+    return `${lockPath}.lock`;
+}
+function generateToken() {
+    return crypto.randomBytes(16).toString('hex');
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+/**
+ * Read Linux process start time from /proc/{pid}/stat (field 22).
+ * Returns null on non-Linux or any read/parse failure.
+ */
+async function getProcessStartTime(pid) {
+    try {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf-8');
+        const closeParenIdx = stat.lastIndexOf(')');
+        if (closeParenIdx === -1)
+            return null;
+        const fields = stat.slice(closeParenIdx + 2).split(' ');
+        const startTime = Number(fields[19]);
+        return Number.isFinite(startTime) ? startTime : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readMeta(dirPath) {
+    try {
+        const raw = await fs.readFile(path.join(dirPath, 'meta.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.pid !== 'number' || typeof parsed?.token !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMeta(dirPath, meta) {
+    const metaPath = path.join(dirPath, 'meta.json');
+    const tmpPath = `${metaPath}.tmp.${process.pid}`;
+    await fs.writeFile(tmpPath, JSON.stringify(meta) + '\n', 'utf-8');
+    await fs.rename(tmpPath, metaPath);
+}
+async function handleLegacyLockFile(lockPath) {
+    try {
+        const stat = await fs.stat(lockPath);
+        if (!stat.isFile())
+            return;
+        let pid = NaN;
+        try {
+            const content = await fs.readFile(lockPath, 'utf-8');
+            pid = Number(content.trim());
+        }
+        catch {
+            // Treat unreadable legacy files as stale.
+        }
+        if (Number.isFinite(pid) && pid > 0 && isPidAlive(pid)) {
+            throw new Error(`Another discoclaw instance is already running (PID ${pid}). ` +
+                `Legacy lock file: ${lockPath}`);
+        }
+        await fs.rm(lockPath, { force: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+}
+/**
+ * Acquire a PID lock directory. Throws if another live process holds the lock.
+ */
+export async function acquirePidLock(lockPath) {
+    await handleLegacyLockFile(lockPath);
+    const dirPath = lockDirPath(lockPath);
+    const token = generateToken();
+    const startTime = await getProcessStartTime(process.pid);
+    const meta = {
+        pid: process.pid,
+        token,
+        acquiredAt: new Date().toISOString(),
+        ...(startTime != null ? { startTime } : {}),
+    };
+    // Attempt 1: atomic directory create.
+    try {
+        await fs.mkdir(dirPath);
+        await writeMeta(dirPath, meta);
+        heldLocks.set(dirPath, token);
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    // Existing lock — determine if stale or held.
+    const existingMeta = await readMeta(dirPath);
+    if (!existingMeta) {
+        let dirAge = Infinity;
+        try {
+            const stat = await fs.stat(dirPath);
+            dirAge = Date.now() - stat.mtimeMs;
+        }
+        catch {
+            // Can't stat: treat as stale.
+        }
+        if (dirAge < GRACE_PERIOD_MS) {
+            throw new Error(`PID lock initializing (dir age: ${Math.round(dirAge)}ms). Lock dir: ${dirPath}`);
+        }
+        await fs.rm(dirPath, { recursive: true, force: true });
+    }
+    else {
+        const alive = isPidAlive(existingMeta.pid);
+        if (alive) {
+            const existingStartTime = await getProcessStartTime(existingMeta.pid);
+            const metaHasStartTime = existingMeta.startTime != null;
+            const procHasStartTime = existingStartTime != null;
+            if (metaHasStartTime && procHasStartTime && existingMeta.startTime !== existingStartTime) {
+                // PID reuse — stale lock.
+                await fs.rm(dirPath, { recursive: true, force: true });
+            }
+            else {
+                throw new Error(`Another discoclaw instance is already running (PID ${existingMeta.pid}). ` +
+                    `Lock dir: ${dirPath}`);
+            }
+        }
+        else {
+            // Dead PID — stale lock.
+            await fs.rm(dirPath, { recursive: true, force: true });
+        }
+    }
+    // Attempt 2: retry after stale cleanup.
+    try {
+        await fs.mkdir(dirPath);
+        await writeMeta(dirPath, meta);
+        heldLocks.set(dirPath, token);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new Error(`PID lock contention (lost race). Lock dir: ${dirPath}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Release the PID lock directory, but only if it's owned by this process token.
+ */
+export async function releasePidLock(lockPath) {
+    const dirPath = lockDirPath(lockPath);
+    const heldToken = heldLocks.get(dirPath);
+    try {
+        const meta = await readMeta(dirPath);
+        if (!meta)
+            return;
+        if (heldToken) {
+            if (meta.token === heldToken) {
+                await fs.rm(dirPath, { recursive: true, force: true });
+            }
+            return;
+        }
+        // Fallback path: best-effort cleanup for older call sites.
+        if (meta.pid === process.pid) {
+            await fs.rm(dirPath, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Lock dir already gone or unreadable — nothing to do.
+    }
+    finally {
+        heldLocks.delete(dirPath);
+    }
+}