@hecer/yoke 0.2.0

package/dist/canon/frontmatter.js

@@ -0,0 +1,10 @@
+import { parse } from 'yaml';
+export function parseFrontmatter(content) {
+    const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m)
+        return null;
+    const parsed = parse(m[1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : null;
+}

package/dist/canon/manifest.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { parse } from 'yaml';
+import { readFileSync } from 'node:fs';
+export const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+export const SkillEntrySchema = z.object({
+    id: z.string().min(1),
+    path: z.string().min(1),
+    kind: z.enum(['methodology', 'role']),
+});
+export const ToolEntrySchema = z.object({
+    id: z.string().min(1),
+    path: z.string().min(1),
+});
+export const ManifestSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    agents: z.array(AgentSchema).min(1),
+    skills: z.array(SkillEntrySchema),
+    policy: z.array(z.object({ path: z.string().min(1) })),
+    loop: z.object({ spec: z.string().min(1), prdSchema: z.string().min(1) }),
+    tools: z.array(ToolEntrySchema),
+});
+export function loadManifest(file) {
+    const raw = parse(readFileSync(file, 'utf8'));
+    return ManifestSchema.parse(raw);
+}

package/dist/canon/validate.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadManifest } from './manifest.js';
+import { parseFrontmatter } from './frontmatter.js';
+export function validateCanon(canonDir) {
+    const issues = [];
+    const manifestPath = join(canonDir, 'manifest.yaml');
+    if (!existsSync(manifestPath)) {
+        return [{ level: 'error', message: `manifest.yaml not found in ${canonDir}` }];
+    }
+    let manifest;
+    try {
+        manifest = loadManifest(manifestPath);
+    }
+    catch (e) {
+        return [{ level: 'error', message: `manifest.yaml invalid: ${e.message}` }];
+    }
+    const seenSkill = new Set();
+    for (const s of manifest.skills) {
+        if (seenSkill.has(s.id))
+            issues.push({ level: 'error', message: `duplicate skill id: ${s.id}` });
+        seenSkill.add(s.id);
+        const dir = join(canonDir, s.path);
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            issues.push({ level: 'error', message: `skill ${s.id}: path not found: ${s.path}` });
+            continue;
+        }
+        const skillMd = join(dir, 'SKILL.md');
+        if (!existsSync(skillMd)) {
+            issues.push({ level: 'error', message: `skill ${s.id}: SKILL.md missing` });
+            continue;
+        }
+        const fm = parseFrontmatter(readFileSync(skillMd, 'utf8'));
+        if (!fm) {
+            issues.push({ level: 'error', message: `skill ${s.id}: SKILL.md has no frontmatter` });
+        }
+        else {
+            if (!fm.name)
+                issues.push({ level: 'error', message: `skill ${s.id}: frontmatter missing name` });
+            if (!fm.description)
+                issues.push({ level: 'error', message: `skill ${s.id}: frontmatter missing description` });
+        }
+    }
+    for (const p of manifest.policy) {
+        if (!existsSync(join(canonDir, p.path))) {
+            issues.push({ level: 'error', message: `policy file not found: ${p.path}` });
+        }
+    }
+    const loopChecks = [
+        ['loop.spec', manifest.loop.spec],
+        ['loop.prdSchema', manifest.loop.prdSchema],
+    ];
+    for (const [label, rel] of loopChecks) {
+        if (!existsSync(join(canonDir, rel))) {
+            issues.push({ level: 'error', message: `${label} not found: ${rel}` });
+        }
+    }
+    for (const name of ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md']) {
+        if (!existsSync(join(canonDir, 'context', name))) {
+            issues.push({ level: 'error', message: `context template not found: context/${name}` });
+        }
+    }
+    const seenTool = new Set();
+    for (const t of manifest.tools) {
+        if (seenTool.has(t.id))
+            issues.push({ level: 'error', message: `duplicate tool id: ${t.id}` });
+        seenTool.add(t.id);
+        if (!existsSync(join(canonDir, t.path))) {
+            issues.push({ level: 'error', message: `tool ${t.id}: path not found: ${t.path}` });
+        }
+    }
+    return issues;
+}

package/dist/cli.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { validateCanon } from './canon/validate.js';
+import { runRetrofit } from './retrofit/command.js';
+import { setLoopEnabled, loopStatus, runLoopCommand } from './loop/run-command.js';
+import { runContextInit, runContextStatus } from './context/command.js';
+import { runReview } from './review/command.js';
+import { scanDir } from './scan/design.js';
+import { runNew } from './new/command.js';
+import { runPrdDraft, runPrdCheck } from './prd/command.js';
+import { runLoopCleanup } from './loop/cleanup.js';
+import { runFlowSmoke } from './smoke/command.js';
+export { runRetrofit } from './retrofit/command.js';
+export function runValidate(canonDir) {
+    const issues = validateCanon(canonDir);
+    for (const i of issues) {
+        const line = `${i.level === 'error' ? 'ERROR' : 'warn '} ${i.message}`;
+        if (i.level === 'error')
+            console.error(line);
+        else
+            console.log(line);
+    }
+    const errors = issues.filter(i => i.level === 'error');
+    if (errors.length === 0) {
+        console.log(`✓ canon valid (${canonDir})`);
+        return 0;
+    }
+    console.log(`✗ ${errors.length} error(s)`);
+    return 1;
+}
+export function runDesignScan(targetDir, opts) {
+    const { findings, score } = scanDir(targetDir);
+    for (const f of findings) {
+        console.log(`  ${f.file}:${f.line}  ${f.tell}  — ${f.hint}`);
+    }
+    const label = `Design scan: score ${score} (${findings.length} tell${findings.length === 1 ? '' : 's'}), budget ${opts.max}`;
+    if (opts.report) {
+        console.log(`${label} — report only`);
+        return 0;
+    }
+    if (score > opts.max) {
+        console.log(`${label} — ✗ over budget`);
+        return 1;
+    }
+    console.log(`${label} — ✓`);
+    return 0;
+}
+function main(argv) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case 'validate':
+            return runValidate(rest[0] ?? 'canon');
+        case 'retrofit': {
+            const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
+            const loop = rest.includes('--loop');
+            const agentArg = rest.find(a => a.startsWith('--agent='))?.slice('--agent='.length);
+            const all = ['claude', 'codex', 'gemini'];
+            const agents = !agentArg || agentArg === 'all'
+                ? (agentArg === 'all' ? all : undefined)
+                : agentArg.split(',').filter((a) => all.includes(a));
+            if (agentArg && agentArg !== 'all' && agents !== undefined && agents.length === 0) {
+                console.warn('Unknown agent(s) in --agent; falling back to detection');
+            }
+            const cgArg = rest.find(a => a.startsWith('--code-graph='))?.slice('--code-graph='.length);
+            const codeGraph = cgArg === 'serena' || cgArg === 'graphify' ? cgArg : undefined;
+            if (cgArg && !codeGraph) {
+                console.error(`Invalid --code-graph value: ${cgArg} (expected graphify|serena)`);
+                return 1;
+            }
+            return runRetrofit(targetDir, { loop, agents, codeGraph });
+        }
+        case 'loop': {
+            const sub = rest[0];
+            const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            if (sub === 'on') {
+                setLoopEnabled(targetDir, true);
+                console.log('Loop enabled.');
+                return 0;
+            }
+            if (sub === 'off') {
+                setLoopEnabled(targetDir, false);
+                console.log('Loop disabled.');
+                return 0;
+            }
+            if (sub === 'status') {
+                console.log(loopStatus(targetDir));
+                return 0;
+            }
+            if (sub === 'cleanup')
+                return runLoopCleanup(targetDir);
+            if (sub === 'run') {
+                const maxArg = rest.find(a => a.startsWith('--max='));
+                const rawMax = maxArg ? Number(maxArg.slice('--max='.length)) : 25;
+                if (!Number.isFinite(rawMax) || rawMax <= 0) {
+                    console.error(`Invalid --max value: ${maxArg}`);
+                    return 1;
+                }
+                const runnerArg = rest.find(a => a.startsWith('--runner='))?.slice('--runner='.length);
+                const valid = ['claude', 'codex', 'gemini'];
+                const agent = runnerArg && valid.includes(runnerArg) ? runnerArg : undefined;
+                if (runnerArg && !agent) {
+                    console.error(`Invalid --runner value: ${runnerArg} (expected claude|codex|gemini)`);
+                    return 1;
+                }
+                const isolate = rest.includes('--isolate');
+                const reviewerArg = rest.find(a => a.startsWith('--reviewer='))?.slice('--reviewer='.length);
+                let reviewer;
+                if (reviewerArg) {
+                    if (!valid.includes(reviewerArg)) {
+                        console.error(`Invalid --reviewer value: ${reviewerArg} (expected claude|codex|gemini)`);
+                        return 1;
+                    }
+                    reviewer = reviewerArg;
+                }
+                const review = rest.includes('--review');
+                const toArg = rest.find(a => a.startsWith('--timeout='));
+                let timeoutMinutes;
+                if (toArg) {
+                    const v = Number(toArg.slice('--timeout='.length));
+                    if (!Number.isFinite(v) || v < 0) {
+                        console.error(`Invalid --timeout value: ${toArg}`);
+                        return 1;
+                    }
+                    timeoutMinutes = v;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes });
+            }
+            console.log('usage: yoke loop <on|off|status|cleanup|run [--max=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--isolate] [--timeout=<minutes>]> [targetDir]');
+            return 1;
+        }
+        case 'new': {
+            const dir = rest.find(a => !a.startsWith('-'));
+            if (!dir) {
+                console.error('usage: yoke new <dir> [--idea="..."] [--agent=claude,codex,gemini|all] [--runner=<claude|codex|gemini>] [--loop]');
+                return 1;
+            }
+            const idea = rest.find(a => a.startsWith('--idea='))?.slice('--idea='.length);
+            const loop = rest.includes('--loop');
+            const agentArg = rest.find(a => a.startsWith('--agent='))?.slice('--agent='.length);
+            const all = ['claude', 'codex', 'gemini'];
+            const agents = !agentArg || agentArg === 'all'
+                ? (agentArg === 'all' ? all : undefined)
+                : agentArg.split(',').filter((a) => all.includes(a));
+            if (agentArg && agentArg !== 'all' && agents !== undefined && agents.length === 0) {
+                console.warn('Unknown agent(s) in --agent; falling back to detection');
+            }
+            const runnerArg = rest.find(a => a.startsWith('--runner='))?.slice('--runner='.length);
+            if (runnerArg && !all.includes(runnerArg)) {
+                console.error(`Invalid --runner value: ${runnerArg} (expected claude|codex|gemini)`);
+                return 1;
+            }
+            return runNew(dir, { idea, agents, runner: runnerArg, loop });
+        }
+        case 'prd': {
+            const sub = rest[0];
+            const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            if (sub === 'draft') {
+                const idea = rest.find(a => a.startsWith('--idea='))?.slice('--idea='.length);
+                if (!idea) {
+                    console.error('usage: yoke prd draft [dir] --idea="..." [--runner=<claude|codex|gemini>] [--force] [--timeout=<minutes>]');
+                    return 1;
+                }
+                const valid = ['claude', 'codex', 'gemini'];
+                const runnerArg = rest.find(a => a.startsWith('--runner='))?.slice('--runner='.length);
+                if (runnerArg && !valid.includes(runnerArg)) {
+                    console.error(`Invalid --runner value: ${runnerArg} (expected claude|codex|gemini)`);
+                    return 1;
+                }
+                const force = rest.includes('--force');
+                const toArg = rest.find(a => a.startsWith('--timeout='));
+                let timeoutMinutes;
+                if (toArg) {
+                    const v = Number(toArg.slice('--timeout='.length));
+                    if (!Number.isFinite(v) || v < 0) {
+                        console.error(`Invalid --timeout value: ${toArg}`);
+                        return 1;
+                    }
+                    timeoutMinutes = v;
+                }
+                return runPrdDraft(targetDir, { idea, runner: runnerArg, force, timeoutMinutes });
+            }
+            if (sub === 'check')
+                return runPrdCheck(targetDir);
+            console.log('usage: yoke prd <draft|check> [dir] [--idea="..."] [--runner=<claude|codex|gemini>] [--force] [--timeout=<minutes>]');
+            return 1;
+        }
+        case 'context': {
+            const sub = rest[0];
+            const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            if (sub === 'init')
+                return runContextInit(targetDir);
+            if (sub === 'status')
+                return runContextStatus(targetDir);
+            console.log('usage: yoke context <init|status> [targetDir]');
+            return 1;
+        }
+        case 'review': {
+            const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
+            const valid = ['claude', 'codex', 'gemini'];
+            const reviewerArg = rest.find(a => a.startsWith('--reviewer='))?.slice('--reviewer='.length);
+            if (reviewerArg && !valid.includes(reviewerArg)) {
+                console.error(`Invalid --reviewer value: ${reviewerArg} (expected claude|codex|gemini)`);
+                return 1;
+            }
+            const base = rest.find(a => a.startsWith('--base='))?.slice('--base='.length);
+            const focus = rest.find(a => a.startsWith('--focus='))?.slice('--focus='.length);
+            const toArg = rest.find(a => a.startsWith('--timeout='));
+            let timeoutMinutes;
+            if (toArg) {
+                const v = Number(toArg.slice('--timeout='.length));
+                if (!Number.isFinite(v) || v < 0) {
+                    console.error(`Invalid --timeout value: ${toArg}`);
+                    return 1;
+                }
+                timeoutMinutes = v;
+            }
+            return runReview(targetDir, { reviewer: reviewerArg, base, focus, timeoutMinutes });
+        }
+        case 'flow-smoke': {
+            const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
+            const url = rest.find(a => a.startsWith('--url='))?.slice('--url='.length);
+            const label = rest.find(a => a.startsWith('--label='))?.slice('--label='.length);
+            return runFlowSmoke(targetDir, { url, label });
+        }
+        case 'design-scan': {
+            const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
+            const report = rest.includes('--report');
+            const maxArg = rest.find(a => a.startsWith('--max='));
+            const max = maxArg ? Number(maxArg.slice('--max='.length)) : 4;
+            if (!Number.isFinite(max) || max < 0) {
+                console.error(`Invalid --max value: ${maxArg}`);
+                return 1;
+            }
+            return runDesignScan(targetDir, { max, report });
+        }
+        default:
+            console.log('usage: yoke <new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | prd <draft|check> [dir] | loop <on|off|status|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>]>');
+            return cmd ? 1 : 0;
+    }
+}
+const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
+if (isMain) {
+    process.exit(await main(process.argv.slice(2)));
+}

package/dist/context/command.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCanonDir } from '../retrofit/canon-dir.js';
+import { baseContextActions } from '../retrofit/context-actions.js';
+import { applyActions } from '../retrofit/apply.js';
+import { contextDir } from './context.js';
+export function runContextInit(targetDir) {
+    const canonDir = resolveCanonDir();
+    const actions = baseContextActions(canonDir);
+    const applied = applyActions(actions, targetDir, { backupDir: join(targetDir, '.yoke', 'backup', 'context') });
+    for (const a of applied)
+        console.log(`  ${a.status.padEnd(11)} ${a.target}`);
+    return 0;
+}
+export function runContextStatus(targetDir) {
+    const dir = contextDir(targetDir);
+    const files = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md'];
+    if (!files.some(f => existsSync(join(dir, f)))) {
+        console.log('Context not initialised (no .yoke/context). Run: yoke context init');
+        return 0;
+    }
+    for (const f of files) {
+        const p = join(dir, f);
+        console.log(existsSync(p) ? `  ${f.padEnd(13)} ${statSync(p).size} bytes` : `  ${f.padEnd(13)} (missing)`);
+    }
+    const decisions = join(dir, 'DECISIONS.md');
+    if (existsSync(decisions)) {
+        const last = readFileSync(decisions, 'utf8').split('\n').filter(l => l.startsWith('## ')).pop();
+        if (last)
+            console.log(`  last decision: ${last.slice(3)}`);
+    }
+    return 0;
+}

package/dist/context/context.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+export const MAX_CONTEXT_CHARS = 2000;
+export function contextDir(targetDir) {
+    return join(targetDir, '.yoke', 'context');
+}
+function readIf(file) {
+    return existsSync(file) ? readFileSync(file, 'utf8') : '';
+}
+export function loadContext(dir) {
+    return {
+        project: readIf(join(dir, 'PROJECT.md')),
+        decisions: readIf(join(dir, 'DECISIONS.md')),
+        knowledge: readIf(join(dir, 'KNOWLEDGE.md')),
+    };
+}
+function boundHead(s, max) {
+    return s.length <= max ? s : s.slice(0, max) + '\n… (truncated)';
+}
+function boundTail(s, max) {
+    return s.length <= max ? s : '… (truncated)\n' + s.slice(s.length - max);
+}
+// `max` bounds the body of each file (after trimming), not the rendered section —
+// the `###` sub-heading and truncation marker add a small fixed overhead on top.
+export function formatForPrompt(ctx, max = MAX_CONTEXT_CHARS) {
+    const parts = [];
+    if (ctx.project.trim())
+        parts.push(`### North star (PROJECT.md)\n${boundHead(ctx.project.trim(), max)}`);
+    if (ctx.knowledge.trim())
+        parts.push(`### Known gotchas (KNOWLEDGE.md)\n${boundHead(ctx.knowledge.trim(), max)}`);
+    if (ctx.decisions.trim())
+        parts.push(`### Recent decisions (DECISIONS.md)\n${boundTail(ctx.decisions.trim(), max)}`);
+    if (parts.length === 0)
+        return '';
+    return ['## Project context (from .yoke/context — read before implementing)', ...parts].join('\n\n');
+}
+export function appendDecision(dir, entry, now = new Date()) {
+    const file = join(dir, 'DECISIONS.md');
+    const existed = existsSync(file);
+    const prior = existed ? readFileSync(file, 'utf8') : '';
+    const date = now.toISOString().slice(0, 10);
+    const block = `\n## ${date} — ${entry.storyId}: ${entry.title}\n${entry.summary}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, prior + block);
+    return {
+        rollback: () => {
+            if (existed)
+                writeFileSync(file, prior);
+            else {
+                try {
+                    rmSync(file);
+                }
+                catch { /* best-effort cleanup */ }
+            }
+        },
+    };
+}

package/dist/loop/cleanup.js

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { lockPath, readLock, isPidAlive } from './lock.js';
+// Cleans ONLY yoke-created runtime artifacts: .yoke/worktrees/* and a stale loop.lock.
+// Never touches user-created worktrees or a lock whose holder is alive.
+export function runLoopCleanup(targetDir, opts = {}) {
+    const git = opts.git ?? ((args, cwd) => { execFileSync('git', args, { cwd, stdio: 'pipe' }); });
+    const wtDir = join(targetDir, '.yoke', 'worktrees');
+    let removed = 0;
+    let failed = 0;
+    if (existsSync(wtDir)) {
+        for (const name of readdirSync(wtDir)) {
+            const path = join(wtDir, name);
+            try {
+                git(['worktree', 'remove', '--force', path], targetDir);
+                removed++;
+            }
+            catch (e) {
+                console.error(`Failed to remove worktree ${path}: ${e.message}`);
+                failed++;
+            }
+        }
+        try {
+            git(['worktree', 'prune'], targetDir);
+        }
+        catch { /* best-effort */ }
+    }
+    const lockFile = lockPath(targetDir);
+    if (existsSync(lockFile)) {
+        const holder = readLock(targetDir);
+        if (holder && isPidAlive(holder.pid)) {
+            console.log(`Loop lock held by a live process (pid ${holder.pid}) — left in place.`);
+        }
+        else {
+            rmSync(lockFile, { force: true });
+            console.log('Removed stale loop lock.');
+        }
+    }
+    console.log(removed === 0 && failed === 0 ? 'Nothing to clean.' : `Removed ${removed} worktree(s)${failed > 0 ? `, ${failed} failed` : ''}.`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/loop/gates.js

@@ -0,0 +1,12 @@
+export function stopTheLineGate(story) {
+    if (story.acceptance.length === 0) {
+        return { ok: false, reason: `story ${story.id} has no acceptance criteria (Stop-the-Line)` };
+    }
+    return { ok: true };
+}
+export function preDispatchGate(targetDir, git) {
+    if (!git.isClean(targetDir)) {
+        return { ok: false, reason: 'git worktree is dirty — commit or stash before running the loop' };
+    }
+    return { ok: true };
+}

package/dist/loop/git.js

@@ -0,0 +1,25 @@
+import { execFileSync } from 'node:child_process';
+export const realGitOps = {
+    isClean(dir) {
+        const out = execFileSync('git', ['status', '--porcelain'], { cwd: dir }).toString();
+        return out.trim() === '';
+    },
+    commitAll(dir, message) {
+        execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
+        const status = execFileSync('git', ['status', '--porcelain'], { cwd: dir }).toString().trim();
+        if (status === '') {
+            throw new Error('nothing to commit after agent run');
+        }
+        execFileSync('git', ['-c', 'commit.gpgsign=false', 'commit', '-m', message], { cwd: dir, stdio: 'pipe' });
+    },
+    addWorktree(repoDir, worktreePath) {
+        execFileSync('git', ['worktree', 'add', '--detach', worktreePath, 'HEAD'], { cwd: repoDir, stdio: 'pipe' });
+    },
+    removeWorktree(repoDir, worktreePath) {
+        execFileSync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: repoDir, stdio: 'pipe' });
+    },
+    integrate(repoDir, worktreePath) {
+        const sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: worktreePath }).toString().trim();
+        execFileSync('git', ['merge', '--ff-only', sha], { cwd: repoDir, stdio: 'pipe' });
+    },
+};

package/dist/loop/lock.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+export function lockPath(targetDir) {
+    return join(targetDir, '.yoke', 'loop.lock');
+}
+// Liveness probe via signal 0. EPERM means "exists but not ours" — alive.
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+export function readLock(targetDir) {
+    const file = lockPath(targetDir);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof parsed?.pid === 'number' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireLock(targetDir, pid = process.pid) {
+    const file = lockPath(targetDir);
+    const holder = readLock(targetDir);
+    if (holder && isPidAlive(holder.pid))
+        return { acquired: false, holderPid: holder.pid };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ pid, startedAt: new Date().toISOString() }));
+    return holder ? { acquired: true, stalePid: holder.pid } : { acquired: true };
+}
+// Best-effort: a missing file or an unwritable disk must never crash loop teardown.
+export function releaseLock(targetDir) {
+    try {
+        rmSync(lockPath(targetDir), { force: true });
+    }
+    catch { /* best-effort */ }
+}