@agent-plan/core 0.2.25 → 0.2.27

package/dist/task-selection.js

@@ -1,8 +1,108 @@
 const unavailable = new Set(["blocked", "waiting", "deferred", "canceled", "rejected"]);
 const hardUnavailable = new Set(["blocked", "deferred", "canceled", "rejected"]);
 const terminal = new Set(["done", "canceled", "rejected"]);
-const priority = (entity) => entity.priority && entity.priority > 0 ? entity.priority : Number.MAX_SAFE_INTEGER;
+const priority = (entity) => entity.priority != null ? entity.priority : Number.MAX_SAFE_INTEGER;
 const compare = (a, b) => priority(a) - priority(b) || a.number - b.number;
+const summarizeFeature = (feature) => ({ id: feature.id, number: feature.number, priority: feature.priority, title: feature.name, status: feature.status });
+const summarizePhase = (phase) => ({ id: phase.id, number: phase.number, priority: phase.priority, title: phase.title, status: phase.status });
+const summarizeTask = (task) => ({ id: task.id, number: task.number, priority: task.priority, title: task.title, status: task.status });
+const RECOMMENDATION_CLAIM_LIMIT = 8;
+const selectionClaimKind = (selectionKind) => {
+    if (selectionKind === "priority")
+        return "recommendation";
+    if (selectionKind === "conflict")
+        return "conflict";
+    if (selectionKind === "none")
+        return "insufficient";
+    return "advisory";
+};
+const buildRecommendationClaims = (selection, evidence = {}, dependencyReadyCandidates = []) => {
+    const claims = [];
+    if (selection.candidate) {
+        claims.push({
+            kind: selectionClaimKind(selection.kind),
+            source: selection.kind === "resume" ? "resume-deviation" : selection.kind === "active" ? "active-task" : "priority",
+            ref: selection.candidate.task.id,
+            title: selection.candidate.task.title,
+            reason: selection.reason,
+            taskId: selection.candidate.task.id,
+            phaseId: selection.candidate.phase.id,
+            ...(selection.candidate.feature?.id ? { featureId: selection.candidate.feature.id } : {}),
+        });
+    }
+    for (const candidate of dependencyReadyCandidates) {
+        claims.push({
+            kind: "advisory",
+            source: "dependency-ready",
+            ref: candidate.task.id,
+            title: candidate.task.title,
+            reason: "All persisted task dependencies are done; this task is ready for explicit priority review.",
+            taskId: candidate.task.id,
+            phaseId: candidate.phase.id,
+            ...(candidate.feature?.id ? { featureId: candidate.feature.id } : {}),
+        });
+    }
+    if (selection.kind === "conflict") {
+        for (const activeCandidate of selection.activeCandidates ?? []) {
+            claims.push({
+                kind: "conflict",
+                source: "active-task",
+                ref: activeCandidate.task.id,
+                title: activeCandidate.task.title,
+                reason: "Multiple in-progress tasks are persisted; resolve the active-work conflict before automatic selection.",
+                taskId: activeCandidate.task.id,
+                phaseId: activeCandidate.phase.id,
+                ...(activeCandidate.feature?.id ? { featureId: activeCandidate.feature.id } : {}),
+            });
+        }
+    }
+    if (selection.deviation) {
+        const deviationTaskId = selection.candidate?.task.id ?? selection.deviation.resumeTaskId;
+        claims.push({
+            kind: "advisory",
+            source: "resume-deviation",
+            ref: deviationTaskId,
+            title: selection.candidate?.task.title ?? "Resume-required deviation",
+            reason: selection.deviation.state === "resume-required"
+                ? "Persisted deviation requires resuming the preserved task before new priority work can continue."
+                : "Persisted approved deviation competes with priority selection.",
+            taskId: deviationTaskId,
+        });
+    }
+    for (const handoff of evidence.handoffs ?? []) {
+        if (!handoff.resumeReady) {
+            claims.push({
+                kind: "insufficient",
+                source: "handoff",
+                ref: handoff.compositeRef,
+                title: handoff.firstLine || handoff.compositeRef,
+                reason: "Persisted handoff read-back is incomplete; it is not an actionable resume claim.",
+            });
+            continue;
+        }
+        claims.push({
+            kind: "advisory",
+            source: "handoff",
+            ref: handoff.compositeRef,
+            title: handoff.firstLine || handoff.compositeRef,
+            reason: "Persisted phase handoff is resume-ready and competes with fresh priority work.",
+        });
+    }
+    // Archived Markdown is historical context, not authoritative next-work
+    // evidence. A future explicit structured resume target may opt it in; never
+    // recover an action by parsing archived prose.
+    void evidence.archivedHandoffs;
+    if (claims.length === 0) {
+        claims.push({
+            kind: "insufficient",
+            source: "priority",
+            ref: "",
+            title: "No competing claim evidence",
+            reason: selection.reason,
+        });
+    }
+    return claims.slice(0, RECOMMENDATION_CLAIM_LIMIT);
+};
 /**
  * Validate an explicitly requested task start. Priority and existing active
  * work remain advisory for explicit user choices; availability and dependency
@@ -41,14 +141,21 @@ export function checkExplicitTaskStart(features, phases, taskId, deviations = []
  * may use its recommendation as a default while still allowing an explicitly
  * approved temporary deviation.
  */
-export function recommendNextTask(features, phases, deviations = [], currentPhaseId = "") {
+export function recommendNextTask(features, phases, deviations = [], currentPhaseId = "", sessionId = "") {
     const featureById = new Map(features.map((feature) => [feature.id, feature]));
     const candidates = phases.flatMap((phase) => phase.tasks.map((task) => ({ feature: phase.featureId ? featureById.get(phase.featureId) : undefined, phase, task })));
     const byTaskId = new Map(candidates.map((candidate) => [candidate.task.id, candidate]));
     const active = candidates.filter(({ task }) => task.status === "in-progress");
-    if (active.length > 1)
+    if (sessionId) {
+        const ownedActive = active.filter(({ task }) => task.activeOwnerSession === sessionId);
+        if (ownedActive.length > 1)
+            return { kind: "conflict", activeCandidates: ownedActive, reason: "This session owns more than one active task; resolve the active-work conflict before autonomous selection." };
+        if (ownedActive.length === 1)
+            return { kind: "active", candidate: ownedActive[0], reason: "Resume the single active task owned by this session." };
+    }
+    else if (active.length > 1)
         return { kind: "conflict", activeCandidates: active, reason: "More than one task is in progress; resolve the active-work conflict before autonomous selection." };
-    if (active.length === 1)
+    else if (active.length === 1)
         return { kind: "active", candidate: active[0], reason: "Resume the single active task." };
     const newestFirst = (left, right) => right.createdAt.localeCompare(left.createdAt);
     const resumable = (candidate) => candidate
@@ -105,11 +212,55 @@ export function recommendNextTask(features, phases, deviations = [], currentPhas
             reason: "Continue the current phase before selecting new work elsewhere.",
         };
     }
-    ready.sort((a, b) => compare(a.feature ?? { priority: 0, number: 0 }, b.feature ?? { priority: 0, number: 0 }) || compare(a.phase, b.phase) || compare(a.task, b.task));
-    return ready[0]
-        ? { kind: "priority", candidate: ready[0], reason: "Highest-priority ready task by feature, phase, then task." }
+    const bestTaskInPhase = (phaseId) => ready
+        .filter((candidate) => candidate.phase.id === phaseId)
+        .sort((a, b) => compare(a.task, b.task))[0];
+    const bestPhaseInFeature = (featureId) => {
+        const phaseIds = new Set(ready.filter((candidate) => candidate.feature?.id === featureId).map((candidate) => candidate.phase.id));
+        return phases
+            .filter((phase) => phase.featureId === featureId && phaseIds.has(phase.id))
+            .sort((a, b) => compare(a, b))[0];
+    };
+    const bestFeature = features
+        .filter((feature) => ready.some((candidate) => candidate.feature?.id === feature.id))
+        .sort((a, b) => compare(a, b))[0];
+    if (!bestFeature)
+        return { kind: "none", reason: "No ready task is available." };
+    const bestPhase = bestPhaseInFeature(bestFeature.id);
+    if (!bestPhase)
+        return { kind: "none", reason: "No ready task is available." };
+    const candidate = bestTaskInPhase(bestPhase.id);
+    return candidate
+        ? { kind: "priority", candidate, reason: "Select the lowest-priority ready feature, then phase, then task." }
         : { kind: "none", reason: "No ready task is available." };
 }
+export function recommendNextWork(features, phases, deviations = [], currentPhaseId = "", sessionId = "", evidence = {}) {
+    const selection = recommendNextTask(features, phases, deviations, currentPhaseId, sessionId);
+    const featureById = new Map(features.map((feature) => [feature.id, feature]));
+    const taskById = new Map(phases.flatMap((phase) => phase.tasks.map((task) => [task.id, task])));
+    const dependencyReadyCandidates = phases.flatMap((phase) => phase.tasks.map((task) => ({
+        feature: phase.featureId ? featureById.get(phase.featureId) : undefined,
+        phase,
+        task,
+    })))
+        .filter(({ feature, phase, task }) => task.status === "planned"
+        && task.dependsOn.length > 0
+        && !hardUnavailable.has(phase.status)
+        && !(feature && hardUnavailable.has(feature.status))
+        && task.dependsOn.every((id) => taskById.get(id)?.status === "done"))
+        .sort((left, right) => compare(left.feature ?? { priority: 0, number: 0 }, right.feature ?? { priority: 0, number: 0 }) || compare(left.phase, right.phase) || compare(left.task, right.task));
+    const activeTask = selection.kind === "active" && selection.candidate
+        ? summarizeTask(selection.candidate.task)
+        : null;
+    return {
+        selection,
+        activeTask,
+        nextFeature: selection.candidate?.feature ? summarizeFeature(selection.candidate.feature) : null,
+        nextPhase: selection.candidate ? summarizePhase(selection.candidate.phase) : null,
+        nextTask: selection.candidate ? summarizeTask(selection.candidate.task) : null,
+        claims: buildRecommendationClaims(selection, evidence, dependencyReadyCandidates),
+    };
+}
 /**
  * Build an explicit resume-required proposal. `ref` is the already-formatted
  * composite reference (F00x/P00x/T00x) supplied by the caller; `snapshot` is

package/dist/task-start-outcome.d.ts

@@ -1,4 +1,4 @@
-export declare const TASK_START_ERROR_CODES: readonly ["PLAN_NOT_FOUND", "TASK_NOT_FOUND", "TASK_DONE", "CONTEXT_READ_REQUIRED", "REQUIREMENTS_READ_REQUIRED", "START_NOT_ALLOWED", "ACTIVE_TASK_CONFLICT", "PERSISTENCE_VERIFICATION_FAILED"];
+export declare const TASK_START_ERROR_CODES: readonly ["PLAN_NOT_FOUND", "TASK_NOT_FOUND", "TASK_DONE", "PROJECT_GUIDELINES_READ_REQUIRED", "CONTEXT_READ_REQUIRED", "REQUIREMENTS_READ_REQUIRED", "START_NOT_ALLOWED", "ACTIVE_TASK_CONFLICT", "PERSISTENCE_VERIFICATION_FAILED"];
 export type TaskStartErrorCode = (typeof TASK_START_ERROR_CODES)[number];
 export interface TaskStartDeniedOutcome {
     started: false;

package/dist/task-start-outcome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-start-outcome.d.ts","sourceRoot":"","sources":["../src/task-start-outcome.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,mMASzB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,kBAAkB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG,yBAAyB,CAAC;AAElF,wBAAgB,eAAe,CAC7B,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3D,sBAAsB,CASxB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,UAAQ,GAAG,yBAAyB,CAEpG"}
+{"version":3,"file":"task-start-outcome.d.ts","sourceRoot":"","sources":["../src/task-start-outcome.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,uOAUzB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,kBAAkB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG,yBAAyB,CAAC;AAElF,wBAAgB,eAAe,CAC7B,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3D,sBAAsB,CASxB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,UAAQ,GAAG,yBAAyB,CAEpG"}

package/dist/task-start-outcome.js

@@ -2,6 +2,7 @@ export const TASK_START_ERROR_CODES = [
     "PLAN_NOT_FOUND",
     "TASK_NOT_FOUND",
     "TASK_DONE",
+    "PROJECT_GUIDELINES_READ_REQUIRED",
     "CONTEXT_READ_REQUIRED",
     "REQUIREMENTS_READ_REQUIRED",
     "START_NOT_ALLOWED",

package/dist/write-coordination.d.ts

@@ -0,0 +1,27 @@
+interface WriterOwner {
+    token: string;
+    pid: number;
+    hostname: string;
+    cwd: string;
+    acquiredAt: string;
+}
+export interface PlanWriterBusyDetails {
+    errorCode: "PLAN_WRITER_BUSY";
+    planRoot: string;
+    lockPath: string;
+    waitedMs: number;
+    owner?: WriterOwner | undefined;
+}
+export declare class PlanWriterBusyError extends Error {
+    readonly details: PlanWriterBusyDetails;
+    readonly code = "PLAN_WRITER_BUSY";
+    constructor(details: PlanWriterBusyDetails);
+}
+/**
+ * Serialize one logical planner mutation across processes for a planner root.
+ * Nested writes in the same async transaction are re-entrant. Reads never take
+ * this lock, so secondary processes remain available for inspection.
+ */
+export declare function withPlanRootWriteLock<T>(root: string, fn: () => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=write-coordination.d.ts.map

package/dist/write-coordination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-coordination.d.ts","sourceRoot":"","sources":["../src/write-coordination.ts"],"names":[],"mappings":"AAUA,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAGhB,OAAO,EAAE,qBAAqB;IAF1D,QAAQ,CAAC,IAAI,sBAAsB;gBAEP,OAAO,EAAE,qBAAqB;CAO3D;AAwLD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAa7F"}

package/dist/write-coordination.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_MS = 20;
+export class PlanWriterBusyError extends Error {
+    details;
+    code = "PLAN_WRITER_BUSY";
+    constructor(details) {
+        const owner = details.owner
+            ? ` Active writer: pid ${details.owner.pid} on ${details.owner.hostname}, acquired ${details.owner.acquiredAt}.`
+            : "";
+        super(`PLAN_WRITER_BUSY: another process is mutating ${details.planRoot}; waited ${details.waitedMs}ms.${owner} Read-only operations remain available; retry the write after the active mutation finishes.`);
+        this.details = details;
+        this.name = "PlanWriterBusyError";
+    }
+}
+const heldRoots = new AsyncLocalStorage();
+function positiveEnvMs(name, fallback) {
+    const raw = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+async function readOwner(lockPath) {
+    try {
+        const parsed = JSON.parse(await readFile(join(lockPath, "owner.json"), "utf8"));
+        if (typeof parsed.token !== "string"
+            || typeof parsed.pid !== "number"
+            || typeof parsed.hostname !== "string"
+            || typeof parsed.cwd !== "string"
+            || typeof parsed.acquiredAt !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownerIsActive(owner, heartbeatStale) {
+    if (owner.hostname !== hostname())
+        return !heartbeatStale;
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function acquirePlanRootLock(planRoot) {
+    const locksRoot = join(planRoot, ".local", "locks");
+    const lockPath = join(locksRoot, "writer.lock");
+    const recoveryPath = join(locksRoot, "writer-recovery.lock");
+    const startedAt = Date.now();
+    const timeoutMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+    const staleMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_STALE_MS", DEFAULT_STALE_MS);
+    const retryMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_RETRY_MS", DEFAULT_RETRY_MS);
+    const owner = {
+        token: randomUUID(),
+        pid: process.pid,
+        hostname: hostname(),
+        cwd: process.cwd(),
+        acquiredAt: new Date().toISOString(),
+    };
+    for (;;) {
+        try {
+            await mkdir(locksRoot, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+            continue;
+        }
+        if (await pathExists(recoveryPath)) {
+            try {
+                const recovery = await stat(recoveryPath);
+                if (Date.now() - recovery.mtimeMs > staleMs) {
+                    await rm(recoveryPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            const waitedMs = Date.now() - startedAt;
+            if (waitedMs >= timeoutMs) {
+                const currentOwner = await readOwner(lockPath);
+                throw new PlanWriterBusyError({
+                    errorCode: "PLAN_WRITER_BUSY",
+                    planRoot,
+                    lockPath,
+                    waitedMs,
+                    ...(currentOwner ? { owner: currentOwner } : {}),
+                });
+            }
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+            continue;
+        }
+        try {
+            await mkdir(lockPath);
+            try {
+                await writeFile(join(lockPath, "owner.json"), JSON.stringify(owner, null, 2), "utf8");
+                // A stale-owner recovery may have started after our initial check. Its
+                // sentinel wins: withdraw this new lock and retry after recovery ends.
+                if (await pathExists(recoveryPath)) {
+                    const persistedOwner = await readOwner(lockPath);
+                    if (persistedOwner?.token === owner.token) {
+                        await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    }
+                    await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+                    continue;
+                }
+            }
+            catch (error) {
+                const persistedOwner = await readOwner(lockPath);
+                if (!persistedOwner || persistedOwner.token === owner.token) {
+                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                }
+                throw error;
+            }
+            const heartbeat = setInterval(() => {
+                const now = new Date();
+                void utimes(lockPath, now, now).catch(() => { });
+            }, Math.max(250, Math.floor(staleMs / 3)));
+            heartbeat.unref();
+            return async () => {
+                clearInterval(heartbeat);
+                const persistedOwner = await readOwner(lockPath);
+                if (persistedOwner?.token === owner.token) {
+                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                }
+            };
+        }
+        catch (error) {
+            const fsError = error;
+            if (fsError.code === "ENOENT") {
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+                continue;
+            }
+            if (fsError.code !== "EEXIST")
+                throw error;
+            const currentOwner = await readOwner(lockPath);
+            let stale = false;
+            try {
+                const info = await stat(lockPath);
+                stale = Date.now() - info.mtimeMs > staleMs;
+            }
+            catch {
+                continue;
+            }
+            if (currentOwner ? !ownerIsActive(currentOwner, stale) : stale) {
+                try {
+                    await mkdir(recoveryPath);
+                    try {
+                        const confirmedOwner = await readOwner(lockPath);
+                        let confirmedStale = false;
+                        try {
+                            const info = await stat(lockPath);
+                            confirmedStale = Date.now() - info.mtimeMs > staleMs;
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (confirmedOwner ? !ownerIsActive(confirmedOwner, confirmedStale) : confirmedStale) {
+                            await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                        }
+                    }
+                    finally {
+                        await rm(recoveryPath, { recursive: true, force: true }).catch(() => { });
+                    }
+                }
+                catch (recoveryError) {
+                    if (recoveryError.code !== "EEXIST")
+                        throw recoveryError;
+                }
+                continue;
+            }
+            const waitedMs = Date.now() - startedAt;
+            if (waitedMs >= timeoutMs) {
+                throw new PlanWriterBusyError({
+                    errorCode: "PLAN_WRITER_BUSY",
+                    planRoot,
+                    lockPath,
+                    waitedMs,
+                    ...(currentOwner ? { owner: currentOwner } : {}),
+                });
+            }
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+        }
+    }
+}
+/**
+ * Serialize one logical planner mutation across processes for a planner root.
+ * Nested writes in the same async transaction are re-entrant. Reads never take
+ * this lock, so secondary processes remain available for inspection.
+ */
+export async function withPlanRootWriteLock(root, fn) {
+    const planRoot = resolve(root);
+    const active = heldRoots.getStore();
+    if (active?.has(planRoot))
+        return fn();
+    const release = await acquirePlanRootLock(planRoot);
+    const next = new Set(active ?? []);
+    next.add(planRoot);
+    try {
+        return await heldRoots.run(next, fn);
+    }
+    finally {
+        await release();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/core",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "private": false,
   "description": "Harness-agnostic core for Agent Plan: schemas, persistence, ordering, status rollups, and markdown rendering.",
   "license": "MIT",
@@ -16,6 +16,8 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "planner-skill.md",
+    "skills/**/*.md",
     "README.md",
     "LICENSE"
   ],