@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/dist/lib/task/review-artifacts.js

@@ -1,13 +1,15 @@
-// Shared helpers for review-artifact parsing.
-// Imported by typed artifact lifecycle and verification so the round/verdict vocabulary stays
-// in a single source of truth (prevents the cross-file drift this lifecycle
-// is designed to eliminate).
-import fs from "node:fs";
-import path from "node:path";
-export function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+import fs from 'node:fs';
+import path from 'node:path';
+const SUMMARY_HEADINGS = new Set(['审查摘要', 'Review Summary']);
+const PLACEHOLDERS = [
+    '{unresolved-blockers}',
+    '{unresolved-major}',
+    '{unresolved-minor}'
+];
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-export function maxRound(entries, stem) {
+function maxRound(entries, stem) {
     let max = 0;
     for (const entry of entries) {
         if (entry === `${stem}.md`) {
@@ -15,87 +17,169 @@ export function maxRound(entries, stem) {
             continue;
         }
         const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
-        if (match) {
+        if (match)
             max = Math.max(max, Number(match[1]));
-        }
     }
     return max;
 }
-export function artifactName(stem, round) {
+function artifactName(stem, round) {
     return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
 }
-export function normalizeVerdict(raw) {
+function normalizeVerdict(raw) {
     const value = String(raw).trim().toLowerCase();
-    if (value === "通过" || value === "approved") {
-        return "Approved";
-    }
-    if (value === "需要修改" || value === "changes requested") {
-        return "Changes Requested";
-    }
-    if (value === "拒绝" || value === "rejected") {
-        return "Rejected";
-    }
-    return "";
+    if (value === '通过' || value === 'approved')
+        return 'Approved';
+    if (value === '需要修改' || value === 'changes requested')
+        return 'Changes Requested';
+    if (value === '拒绝' || value === 'rejected')
+        return 'Rejected';
+    return '';
 }
-export function extractSection(content, names) {
+function extractSection(content, names) {
     const lines = content.split(/\r?\n/);
     const nameSet = new Set(names);
     const start = lines.findIndex((line) => {
         const match = line.trim().match(/^##\s+(.+?)\s*$/);
         return match ? nameSet.has(match[1]) : false;
     });
-    if (start === -1) {
-        return "";
-    }
+    if (start === -1)
+        return '';
     const sectionLines = [];
     for (let index = start + 1; index < lines.length; index += 1) {
-        if (/^##\s+/.test(lines[index])) {
+        if (/^##\s+/.test(lines[index]))
             break;
-        }
         sectionLines.push(lines[index]);
     }
-    return sectionLines.join("\n");
+    return sectionLines.join('\n');
 }
-// Parse the canonical verdict out of a review-* artifact.
-// Returns { ok, verdict, message }. Verdict collapses Approved into
-// "Approved-with-issues" when the findings counts are non-zero.
-export function parseVerdict(reviewPath) {
-    if (!fs.existsSync(reviewPath)) {
-        return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
+function summaryBounds(content) {
+    const headings = [...content.matchAll(/^##\s+(.+?)\s*$/gm)]
+        .map((match) => ({ index: match.index, end: match.index + match[0].length, name: match[1] }));
+    const summaries = headings.filter((heading) => SUMMARY_HEADINGS.has(heading.name));
+    if (summaries.length !== 1)
+        return null;
+    const summary = summaries[0];
+    const next = headings.find((heading) => heading.index > summary.index);
+    return { start: summary.end, end: next?.index ?? content.length };
+}
+function uniqueLine(content, bounds, pattern) {
+    const section = content.slice(bounds.start, bounds.end);
+    const matches = [...section.matchAll(pattern)];
+    if (matches.length !== 1)
+        return null;
+    const match = matches[0];
+    return {
+        value: match[1],
+        start: bounds.start + match.index,
+        end: bounds.start + match.index + match[0].length
+    };
+}
+function parseCounts(value) {
+    const zh = /^(\d+)\s*阻塞项，\s*(\d+)\s*主要，\s*(\d+)\s*次要(?:\s*\/.*)?$/.exec(value);
+    const en = /^(\d+)\s*blockers?,\s*(\d+)\s*majors?,\s*(\d+)\s*minors?(?:\s*\/.*)?$/i.exec(value);
+    const match = zh ?? en;
+    if (!match)
+        return null;
+    const [blocker, major, minor] = match.slice(1, 4).map(Number);
+    if (![blocker, major, minor].every(Number.isSafeInteger))
+        return null;
+    return { blocker: blocker, major: major, minor: minor };
+}
+function parseManualValidation(value) {
+    const match = /\*\*(?:人工校验|Manual[- ]validation)\*\*[:：]\s*(\d+)/i.exec(value);
+    if (!match)
+        return null;
+    const count = Number(match[1]);
+    return Number.isSafeInteger(count) ? count : null;
+}
+function hasCanonicalPlaceholders(value) {
+    const zh = /^\{unresolved-blockers\}\s*阻塞项，\s*\{unresolved-major\}\s*主要，\s*\{unresolved-minor\}\s*次要(?:\s*\/.*)?$/.test(value);
+    const en = /^\{unresolved-blockers\}\s*blockers?,\s*\{unresolved-major\}\s*majors?,\s*\{unresolved-minor\}\s*minors?(?:\s*\/.*)?$/i.test(value);
+    return zh || en;
+}
+function parseReviewSummary(content) {
+    const bounds = summaryBounds(content);
+    if (!bounds) {
+        return { ok: false, code: 'REVIEW_SUMMARY_NOT_FOUND', message: 'review artifact must contain one review summary section' };
     }
-    const content = fs.readFileSync(reviewPath, "utf8");
-    const summary = extractSection(content, ["审查摘要", "Review Summary"]);
-    const fileName = path.basename(reviewPath);
-    if (!summary) {
-        return { ok: false, verdict: null, message: `cannot locate review summary section in ${fileName}` };
+    const verdictLine = uniqueLine(content, bounds, /^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/gim);
+    const findingsLine = uniqueLine(content, bounds, /^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/gim);
+    const verdict = verdictLine ? normalizeVerdict(verdictLine.value) : '';
+    if (!verdict || !findingsLine) {
+        return { ok: false, code: 'REVIEW_SUMMARY_NOT_FOUND', message: 'review summary verdict or finding count line is missing or repeated' };
     }
-    const verdictMatch = summary.match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im);
-    if (!verdictMatch) {
-        return { ok: false, verdict: null, message: `cannot parse verdict in ${fileName}` };
+    const counts = parseCounts(findingsLine.value);
+    if (counts) {
+        return {
+            ok: true,
+            summary: { verdict, counts, manualValidation: parseManualValidation(findingsLine.value), countState: 'numeric' },
+            findingsStart: findingsLine.start,
+            findingsEnd: findingsLine.end
+        };
     }
-    const verdict = normalizeVerdict(verdictMatch[1]);
-    if (!verdict) {
+    const placeholderOccurrences = PLACEHOLDERS.map((token) => ([...findingsLine.value.matchAll(new RegExp(escapeRegExp(token), 'g'))].length));
+    if (hasCanonicalPlaceholders(findingsLine.value) && placeholderOccurrences.every((count) => count === 1)) {
         return {
-            ok: false,
-            verdict: null,
-            message: `unrecognized verdict '${verdictMatch[1].trim()}' in ${fileName}`
+            ok: true,
+            summary: { verdict, counts: null, manualValidation: parseManualValidation(findingsLine.value), countState: 'placeholders' },
+            findingsStart: findingsLine.start,
+            findingsEnd: findingsLine.end
         };
     }
-    if (verdict !== "Approved") {
-        return { ok: true, verdict };
+    return {
+        ok: false,
+        code: 'REVIEW_SUMMARY_PLACEHOLDER_INVALID',
+        message: 'review summary finding counts must be three canonical placeholders or non-negative integers'
+    };
+}
+function equalCounts(left, right) {
+    return left.blocker === right.blocker && left.major === right.major && left.minor === right.minor;
+}
+function finalizeReviewSummaryContent(content, counts) {
+    const parsed = parseReviewSummary(content);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.summary.countState === 'numeric') {
+        if (equalCounts(parsed.summary.counts, counts))
+            return { ok: true, changed: false, content };
+        return {
+            ok: false,
+            code: 'REVIEW_SUMMARY_COUNT_MISMATCH',
+            message: 'review summary finding counts do not match the ledger snapshot'
+        };
     }
-    const findingsMatch = summary.match(/^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im);
-    if (!findingsMatch) {
-        return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
+    let line = content.slice(parsed.findingsStart, parsed.findingsEnd);
+    line = line
+        .replace(PLACEHOLDERS[0], String(counts.blocker))
+        .replace(PLACEHOLDERS[1], String(counts.major))
+        .replace(PLACEHOLDERS[2], String(counts.minor));
+    return {
+        ok: true,
+        changed: true,
+        content: content.slice(0, parsed.findingsStart) + line + content.slice(parsed.findingsEnd)
+    };
+}
+function parseVerdict(reviewPath) {
+    if (!fs.existsSync(reviewPath)) {
+        return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
     }
-    const counts = findingsMatch[1].match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
-    if (!counts) {
-        return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
+    const parsed = parseReviewSummary(fs.readFileSync(reviewPath, 'utf8'));
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            verdict: null,
+            message: `cannot parse review summary in ${path.basename(reviewPath)}: ${parsed.message}`
+        };
     }
-    const [, blockers, majors, minors] = counts.map(Number);
+    const { verdict, counts } = parsed.summary;
+    if (verdict !== 'Approved')
+        return { ok: true, verdict };
     return {
         ok: true,
-        verdict: blockers === 0 && majors === 0 && minors === 0 ? "Approved" : "Approved-with-issues"
+        verdict: counts && equalCounts(counts, { blocker: 0, major: 0, minor: 0 })
+            ? 'Approved'
+            : 'Approved-with-issues'
     };
 }
+export { artifactName, equalCounts, escapeRegExp, extractSection, finalizeReviewSummaryContent, maxRound, normalizeVerdict, parseReviewSummary, parseVerdict };
 //# sourceMappingURL=review-artifacts.js.map

package/dist/lib/task/review-finalization.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { locateActivityLog, pairEntries } from './activity-log.js';
+import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
+import { finalizeReviewSummaryContent } from './review-artifacts.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { validateLifecycleExecution } from './lifecycle-execution.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+const STAGES = {
+    analysis: { family: 'review-analysis', action: 'Review Analysis' },
+    plan: { family: 'review-plan', action: 'Review Plan' },
+    code: { family: 'review-code', action: 'Review Code' }
+};
+const DEFAULT_FILE_SYSTEM = {
+    readFileSync: (file) => fs.readFileSync(file, 'utf8'),
+    statModeSync: (file) => fs.statSync(file).mode,
+    writeFileSync: (file, content, mode) => fs.writeFileSync(file, content, { encoding: 'utf8', flag: 'wx', mode }),
+    renameSync: (from, to) => fs.renameSync(from, to),
+    unlinkSync: (file) => fs.unlinkSync(file)
+};
+function failed(request, code, message, taskId = null, stageStatus = null) {
+    return {
+        status: 'failed',
+        changed: false,
+        intent: 'finalize-summary',
+        requestRef: request.taskRef,
+        taskId,
+        stage: request.stage,
+        artifact: request.artifact,
+        stageStatus,
+        operations: [],
+        error: { code, message }
+    };
+}
+function openReviewRound(content, action, round) {
+    const section = locateActivityLog(content);
+    if (!section)
+        return false;
+    const expected = `${action} (Round ${round})`;
+    return pairEntries(section.entries).filter((row) => (row.step === expected && Boolean(row.started) && !row.done)).length === 1;
+}
+function cleanupTemp(fileSystem, tempPath) {
+    try {
+        fileSystem.unlinkSync(tempPath);
+    }
+    catch {
+        // Best-effort cleanup preserves the primary failure.
+    }
+}
+function finalizeReviewSummaryUnlocked(request, options = {}) {
+    const stage = request.stage;
+    const spec = STAGES[stage];
+    if (!spec)
+        return failed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+    if (!request.taskRef || !request.artifact) {
+        return failed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+    }
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(request, resolved.code, resolved.message, resolved.taskId);
+    if (resolved.state !== 'active') {
+        return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    }
+    const parsedArtifact = parseArtifactName(request.artifact);
+    if (!parsedArtifact || parsedArtifact.family !== spec.family) {
+        return failed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+    }
+    const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact, parsedArtifact.round);
+    if (!validated.ok) {
+        const code = validated.error.code === 'ARTIFACT_NOT_REGULAR'
+            ? 'REVIEW_ARTIFACT_NOT_REGULAR'
+            : 'REVIEW_ARTIFACT_IDENTITY_INVALID';
+        return failed(request, code, validated.error.message, resolved.taskId);
+    }
+    const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+    let taskContent;
+    let artifactContent;
+    try {
+        taskContent = fileSystem.readFileSync(resolved.taskMdPath);
+        artifactContent = fileSystem.readFileSync(validated.artifact.path);
+    }
+    catch (error) {
+        return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+    }
+    if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
+        return failed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
+    }
+    const execution = validateLifecycleExecution(request.taskRef, {
+        mode: request.orchestrated ? 'orchestrated' : 'standalone',
+        identity: {
+            stage: spec.family,
+            round: parsedArtifact.round,
+            artifact: request.artifact,
+            role: 'reviewer'
+        },
+        dryRun: request.dryRun
+    }, { repoRoot: options.repoRoot });
+    if (!execution.ok) {
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+    }
+    let rows;
+    try {
+        rows = parseLedger(taskContent);
+    }
+    catch (error) {
+        return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
+    }
+    const ledgerError = validateLedgerRows(rows);
+    if (ledgerError) {
+        return failed(request, 'REVIEW_LEDGER_INVALID', `${ledgerError.code}: ${ledgerError.message}`, resolved.taskId);
+    }
+    const stageStatus = summarizeLedgerStage(rows, stage);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+    if (!transformed.ok) {
+        return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
+    }
+    if (!transformed.changed) {
+        return {
+            ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
+            status: 'no-op',
+            error: null
+        };
+    }
+    const operations = [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }];
+    if (request.dryRun) {
+        return {
+            ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
+            status: 'planned',
+            changed: true,
+            operations,
+            error: null
+        };
+    }
+    const tempPath = path.join(resolved.taskDir, `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`);
+    let mode;
+    try {
+        mode = fileSystem.statModeSync(validated.artifact.path);
+        fileSystem.writeFileSync(tempPath, transformed.content, mode);
+    }
+    catch (error) {
+        cleanupTemp(fileSystem, tempPath);
+        return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, stageStatus);
+    }
+    try {
+        if (fileSystem.readFileSync(validated.artifact.path) !== artifactContent) {
+            cleanupTemp(fileSystem, tempPath);
+            return failed(request, 'REVIEW_ARTIFACT_CONFLICT', `${request.artifact} changed during finalization`, resolved.taskId, stageStatus);
+        }
+        fileSystem.renameSync(tempPath, validated.artifact.path);
+    }
+    catch (error) {
+        cleanupTemp(fileSystem, tempPath);
+        return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
+    }
+    return {
+        status: 'applied',
+        changed: true,
+        intent: 'finalize-summary',
+        requestRef: request.taskRef,
+        taskId: resolved.taskId,
+        stage,
+        artifact: request.artifact,
+        stageStatus,
+        operations,
+        error: null
+    };
+}
+function finalizeReviewSummary(request, options = {}) {
+    if (request.dryRun)
+        return finalizeReviewSummaryUnlocked(request, options);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return finalizeReviewSummaryUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, options));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
+    }
+}
+export { finalizeReviewSummary };
+//# sourceMappingURL=review-finalization.js.map

package/dist/lib/task/review-fingerprint.js

@@ -40,6 +40,10 @@ export function extractReviewBaseline(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查基线提交|Review Baseline Commit)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";
 }
+export function extractReviewDiffBase(content) {
+    const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异基线|Reviewed Diff Base)\*\*[:：]\s*(.*?)\s*$/m);
+    return match ? match[1].trim().replace(/`/g, "") : "";
+}
 export function extractReviewDiffFingerprint(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异指纹|Reviewed Diff Fingerprint)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";

package/dist/lib/task/task-execution-lock.js

@@ -0,0 +1,231 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { getProcessStartTime, processIdentityMatches } from '../server/process-state.js';
+class TaskExecutionLockError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.name = 'TaskExecutionLockError';
+        this.code = code;
+        this.detail = detail;
+    }
+}
+function errno(error) {
+    const value = error?.code;
+    return typeof value === 'string' ? value : null;
+}
+function mapLinkError(operation, error, key) {
+    const code = errno(error);
+    if (code === 'EEXIST')
+        return 'exists';
+    if (operation === 'quarantine' && code === 'ENOENT')
+        return 'missing';
+    const detail = { operation, errno: code, key };
+    if (['EPERM', 'EACCES', 'ENOSYS', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(code ?? '')) {
+        return new TaskExecutionLockError('ORCHESTRATION_LOCK_UNSUPPORTED', `lifecycle lock hard-link operation '${operation}' is unsupported`, detail);
+    }
+    return new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', `lifecycle lock hard-link operation '${operation}' failed`, detail);
+}
+function lockKey(repoRoot, taskId) {
+    const canonicalRepoRoot = fs.realpathSync.native(repoRoot);
+    const key = createHash('sha256').update(`${canonicalRepoRoot}\0${taskId}`).digest('hex');
+    return { canonicalRepoRoot, key };
+}
+function parseOwner(raw, key) {
+    try {
+        const value = JSON.parse(raw);
+        if (value !== null
+            && value.version === 1
+            && Number.isSafeInteger(value.pid)
+            && (value.pid ?? 0) > 0
+            && typeof value.startTime === 'string'
+            && value.startTime.length > 0
+            && typeof value.token === 'string'
+            && value.token.length > 0
+            && typeof value.owner === 'string'
+            && typeof value.canonicalRepoRoot === 'string'
+            && typeof value.taskId === 'string'
+            && typeof value.acquiredAt === 'string') {
+            return value;
+        }
+    }
+    catch {
+        // Fall through to the stable lock failure below.
+    }
+    throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'lifecycle lock owner record is invalid', { operation: 'read', errno: null, key });
+}
+function unlinkIfPresent(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (error) {
+        if (errno(error) !== 'ENOENT')
+            throw error;
+    }
+}
+function sameInode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function reclaimStaleLock(fixed, quarantine, snapshot, key, link) {
+    let linked = false;
+    try {
+        link(fixed, quarantine);
+        linked = true;
+    }
+    catch (error) {
+        const disposition = mapLinkError('quarantine', error, key);
+        if (disposition === 'missing')
+            return;
+        if (disposition === 'exists') {
+            try {
+                const quarantineSnapshot = fs.readFileSync(quarantine, 'utf8');
+                const fixedStat = fs.statSync(fixed);
+                const quarantineStat = fs.statSync(quarantine);
+                if (quarantineSnapshot === snapshot && sameInode(fixedStat, quarantineStat)) {
+                    unlinkIfPresent(quarantine);
+                }
+            }
+            catch (readError) {
+                if (errno(readError) !== 'ENOENT')
+                    throw readError;
+            }
+            return;
+        }
+        if (disposition instanceof TaskExecutionLockError)
+            throw disposition;
+    }
+    try {
+        const fixedSnapshot = fs.readFileSync(fixed, 'utf8');
+        const fixedStat = fs.statSync(fixed);
+        const quarantineStat = fs.statSync(quarantine);
+        if (fixedSnapshot === snapshot && sameInode(fixedStat, quarantineStat))
+            unlinkIfPresent(fixed);
+    }
+    catch (error) {
+        if (errno(error) !== 'ENOENT')
+            throw error;
+    }
+    finally {
+        if (linked)
+            unlinkIfPresent(quarantine);
+    }
+}
+function cleanStaleCandidates(lockRoot, key, identityMatches) {
+    const prefix = `${key}.candidate.`;
+    for (const name of fs.readdirSync(lockRoot)) {
+        if (!name.startsWith(prefix))
+            continue;
+        const candidate = path.join(lockRoot, name);
+        try {
+            const owner = parseOwner(fs.readFileSync(candidate, 'utf8'), key);
+            if (!identityMatches(owner))
+                unlinkIfPresent(candidate);
+        }
+        catch {
+            // A malformed candidate never owns the fixed lock and is left for manual diagnosis.
+        }
+    }
+}
+function withTaskExecutionLock(repoRoot, taskId, ownerName, callback, options = {}) {
+    let identity;
+    try {
+        identity = lockKey(repoRoot, taskId);
+    }
+    catch (error) {
+        throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'failed to canonicalize the repository for lifecycle locking', { operation: 'canonicalize', errno: errno(error), key: 'unresolved' });
+    }
+    const { canonicalRepoRoot, key } = identity;
+    const lockRoot = options.lockRoot ?? path.join(os.tmpdir(), 'agent-infra-lifecycle-locks');
+    const token = (options.token ?? randomUUID)();
+    const candidate = path.join(lockRoot, `${key}.candidate.${process.pid}.${token}`);
+    const fixed = path.join(lockRoot, `${key}.lock`);
+    const link = options.linkSync ?? fs.linkSync;
+    const startTime = (options.getStartTime ?? getProcessStartTime)(process.pid);
+    if (startTime === null) {
+        throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'current process start time is unavailable', { operation: 'identity', errno: null, key });
+    }
+    const owner = {
+        version: 1,
+        pid: process.pid,
+        startTime,
+        token,
+        owner: ownerName,
+        canonicalRepoRoot,
+        taskId,
+        acquiredAt: (options.now ?? (() => new Date().toISOString()))()
+    };
+    const serialized = `${JSON.stringify(owner)}\n`;
+    let ownsFixed = false;
+    try {
+        fs.mkdirSync(lockRoot, { recursive: true });
+        cleanStaleCandidates(lockRoot, key, options.identityMatches ?? processIdentityMatches);
+        const descriptor = fs.openSync(candidate, 'wx', 0o600);
+        try {
+            fs.writeFileSync(descriptor, serialized);
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        for (let attempt = 0; attempt < 16; attempt += 1) {
+            try {
+                link(candidate, fixed);
+                ownsFixed = true;
+                break;
+            }
+            catch (error) {
+                const disposition = mapLinkError('acquire', error, key);
+                if (disposition instanceof TaskExecutionLockError)
+                    throw disposition;
+                let snapshot;
+                let current;
+                try {
+                    snapshot = fs.readFileSync(fixed, 'utf8');
+                    current = parseOwner(snapshot, key);
+                }
+                catch (readError) {
+                    if (errno(readError) === 'ENOENT')
+                        continue;
+                    throw readError;
+                }
+                if ((options.identityMatches ?? processIdentityMatches)(current)) {
+                    throw new TaskExecutionLockError('ORCHESTRATION_LOCK_BUSY', 'another lifecycle operation holds the task lock', { operation: 'acquire', errno: 'EEXIST', key });
+                }
+                reclaimStaleLock(fixed, `${fixed}.quarantine.${current.token}`, snapshot, key, link);
+            }
+        }
+        if (!ownsFixed) {
+            throw new TaskExecutionLockError('ORCHESTRATION_LOCK_BUSY', 'lifecycle task lock could not be acquired after stale recovery', { operation: 'acquire', errno: 'EEXIST', key });
+        }
+        unlinkIfPresent(candidate);
+        return callback();
+    }
+    catch (error) {
+        if (error instanceof TaskExecutionLockError)
+            throw error;
+        throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'lifecycle task lock operation failed', { operation: ownsFixed ? 'callback' : 'acquire', errno: errno(error), key });
+    }
+    finally {
+        try {
+            unlinkIfPresent(candidate);
+        }
+        catch {
+            // Candidate cleanup is best-effort and must not replace the primary result.
+        }
+        if (ownsFixed) {
+            try {
+                const current = parseOwner(fs.readFileSync(fixed, 'utf8'), key);
+                if (current.token === token)
+                    unlinkIfPresent(fixed);
+            }
+            catch {
+                // A missing or replaced fixed lock is not owned by this invocation.
+            }
+        }
+    }
+}
+export { TaskExecutionLockError, lockKey, mapLinkError, withTaskExecutionLock };
+//# sourceMappingURL=task-execution-lock.js.map