@pentoshi/clai 3.9.1 → 3.9.3

package/dist/store/plan.js

@@ -1,9 +1,10 @@
-import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm, stat, } from "node:fs/promises";
 import { fixOwner, fixOwnerSync, handlePermissionError, safeExists } from "../os/permissions.js";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { getConfig } from "./config.js";
 import { getPlanDir } from "./paths.js";
+import { evaluateTaskTransition } from "./task-transitions.js";
 import { applyPlanOperation, validatePlanDag, } from "../agent/task-plan.js";
 /**
  * Session-scoped plan + task persistence.
@@ -86,6 +87,14 @@ async function loadDatabase() {
         updated_at TEXT NOT NULL
       );
     `);
+        // A real version column so writes can compare-and-set. Legacy
+        // rows default to 1 and are corrected on the first successful mutation.
+        try {
+            cachedDb.exec("ALTER TABLE plans ADD COLUMN version INTEGER NOT NULL DEFAULT 1;");
+        }
+        catch {
+            // Column already exists.
+        }
         return cachedDb;
     }
     catch (err) {
@@ -124,37 +133,59 @@ export function tasksFromTitles(titles) {
     }));
 }
 /**
- * Heal dependency edges so the checklist order is the authority.
+ * Heal dependency edges without inventing scheduling.
  *
- * After id remaps (merge/rewrite), auto-generated chains often point at the
- * wrong ids (e.g. t2 depends on t9). Drop self-deps and any dependency that
- * appears later in the list (forward edges). If nothing valid remains, chain
- * to the previous task in list order.
+ * Only genuinely broken edges are removed: self-references, ids that no longer
+ * exist, and edges that would close a cycle. Valid forward references are kept
+ * so an authored DAG keeps its parallelism. `dependencies: []` is an explicit
+ * statement of independence and is never replaced; only a legacy row with no
+ * dependency field at all falls back to the previous foreground task, and a
+ * responder child never becomes a blocker.
  *
  * Returns true when any task's dependencies changed.
  */
 export function normalizeTaskDependencies(tasks) {
     let changed = false;
-    for (let i = 0; i < tasks.length; i++) {
-        const task = tasks[i];
-        const earlierTasks = tasks.slice(0, i);
-        const earlier = new Set(earlierTasks.map((candidate) => candidate.id));
-        const cleaned = [
-            ...new Set((task.dependencies ?? []).filter((dep) => dep !== task.id && earlier.has(dep))),
-        ];
-        const previousManual = [...earlierTasks]
-            .reverse()
-            .find((candidate) => !candidate.responderOwned);
-        const next = task.responderOwned
-            ? cleaned
-            : cleaned.length > 0
-                ? cleaned
-                : previousManual
-                    ? [previousManual.id]
-                    : [];
-        const prev = task.dependencies ?? [];
-        if (prev.length !== next.length ||
-            prev.some((id, idx) => id !== next[idx])) {
+    const known = new Set(tasks.map((task) => task.id));
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const wouldCycle = (from, to) => {
+        const seen = new Set();
+        const walk = (id) => {
+            if (id === from)
+                return true;
+            if (seen.has(id))
+                return false;
+            seen.add(id);
+            return (byId.get(id)?.dependencies ?? []).some(walk);
+        };
+        return walk(to);
+    };
+    for (const [index, task] of tasks.entries()) {
+        const declared = task.dependencies;
+        const cleaned = [];
+        for (const dependency of declared ?? []) {
+            if (dependency === task.id || !known.has(dependency))
+                continue;
+            if (cleaned.includes(dependency))
+                continue;
+            if (wouldCycle(task.id, dependency))
+                continue;
+            cleaned.push(dependency);
+        }
+        let next = cleaned;
+        if (declared === undefined && !task.responderOwned && cleaned.length === 0) {
+            const previousForeground = tasks
+                .slice(0, index)
+                .reverse()
+                .find((candidate) => !candidate.responderOwned);
+            if (previousForeground && !wouldCycle(task.id, previousForeground.id)) {
+                next = [previousForeground.id];
+            }
+        }
+        const previous = declared ?? [];
+        if (declared === undefined ||
+            previous.length !== next.length ||
+            previous.some((id, position) => id !== next[position])) {
             task.dependencies = next;
             changed = true;
         }
@@ -233,20 +264,202 @@ export function patchPlanMeta(plan, patch) {
     plan.meta = { ...(plan.meta ?? {}), ...patch };
     return plan;
 }
+/**
+ * Every plan write is serialized in-process.
+ *
+ * The JSONL backend rewrites the whole file (read → modify → write) and the
+ * SQLite backend used an unconditional UPSERT, so two concurrent writers (a
+ * foreground task transition and an asynchronous responder settlement) could
+ * each save their own `v+1` derived from the same base version. The later write
+ * silently reverted the earlier one — reopening completed parents or re-yellowing
+ * settled children.
+ */
+let planWriteQueue = Promise.resolve();
+let planWriteDepth = 0;
+function enqueuePlanWrite(task) {
+    // Re-entrancy: a queued mutation may load a plan that heals itself through
+    // savePlan. Waiting on the queue from inside the queue would deadlock.
+    if (planWriteDepth > 0)
+        return task();
+    const tracked = async () => {
+        planWriteDepth += 1;
+        try {
+            return await task();
+        }
+        finally {
+            planWriteDepth -= 1;
+        }
+    };
+    const run = planWriteQueue.then(tracked, tracked);
+    // Keep the chain alive regardless of individual failures.
+    planWriteQueue = run.then(() => undefined, () => undefined);
+    return run;
+}
+const jsonlLockDir = `${jsonlFile}.lock`;
+const JSONL_LOCK_STALE_MS = 10_000;
+let jsonlLockDepth = 0;
+/** Cross-process advisory lock for the JSONL fallback (atomic mkdir). */
+async function withJsonlLock(task) {
+    if (jsonlLockDepth > 0)
+        return task();
+    const deadline = Date.now() + 5_000;
+    try {
+        await mkdir(dirname(jsonlFile), { recursive: true });
+    }
+    catch {
+        // Directory creation is retried by appendJsonl.
+    }
+    for (;;) {
+        try {
+            await mkdir(jsonlLockDir);
+            break;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            // Break a stale lock left behind by a crashed process.
+            try {
+                const info = await stat(jsonlLockDir);
+                if (Date.now() - info.mtimeMs > JSONL_LOCK_STALE_MS) {
+                    await rm(jsonlLockDir, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                break; // proceed rather than deadlock
+            await new Promise((resolve) => setTimeout(resolve, 15));
+        }
+    }
+    try {
+        jsonlLockDepth += 1;
+        return await task();
+    }
+    finally {
+        jsonlLockDepth -= 1;
+        await rm(jsonlLockDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Persist unconditionally (no version check). Used for whole-plan replacement
+ * (creation, approval of a freshly built plan, migrations). Concurrent
+ * transitions must use {@link mutatePlan} instead.
+ */
 export async function savePlan(plan) {
     plan.updatedAt = new Date().toISOString();
     if (getConfig().privateMode)
         return; // never persist in private mode
-    const db = await loadDatabase();
-    if (db) {
-        db.prepare(`INSERT INTO plans (session_id, goal, detail, tasks_json, status, kind, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    await enqueuePlanWrite(async () => {
+        const db = await loadDatabase();
+        if (db) {
+            writePlanRowSqlite(db, plan);
+            return;
+        }
+        await withJsonlLock(() => appendJsonl(plan));
+    });
+}
+function writePlanRowSqlite(db, plan) {
+    db.prepare(`INSERT INTO plans (session_id, goal, detail, tasks_json, status, kind, created_at, updated_at, version)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(session_id) DO UPDATE SET
          goal=excluded.goal, detail=excluded.detail, tasks_json=excluded.tasks_json,
-         status=excluded.status, kind=excluded.kind, updated_at=excluded.updated_at`).run(plan.sessionId, plan.goal, plan.detail, serializeTasksPayload(plan), plan.status, plan.kind, plan.createdAt, plan.updatedAt);
-        return;
+         status=excluded.status, kind=excluded.kind, updated_at=excluded.updated_at,
+         version=excluded.version`).run(plan.sessionId, plan.goal, plan.detail, serializeTasksPayload(plan), plan.status, plan.kind, plan.createdAt, plan.updatedAt, plan.version ?? 1);
+}
+/** Compare-and-set write: only replaces a row still at `expectedVersion`. */
+function casPlanRowSqlite(db, plan, expectedVersion) {
+    const info = db
+        .prepare(`UPDATE plans SET goal=?, detail=?, tasks_json=?, status=?, kind=?, updated_at=?, version=?
+         WHERE session_id=? AND version=?`)
+        .run(plan.goal, plan.detail, serializeTasksPayload(plan), plan.status, plan.kind, plan.updatedAt, plan.version ?? expectedVersion + 1, plan.sessionId, expectedVersion);
+    return (info?.changes ?? 0) > 0;
+}
+const PLAN_MUTATION_RETRIES = 5;
+/**
+ * The authoritative plan mutation boundary.
+ *
+ * Loads the plan fresh, runs `reducer` on it, enforces domain invariants, then
+ * persists with a version compare-and-set. On a CAS conflict the reducer is
+ * re-run against the newer state (reducers must therefore be idempotent and
+ * expressed as "apply this transition", not "write this snapshot").
+ *
+ * Return `false` from the reducer to abort without writing.
+ */
+export async function mutatePlan(sessionId, reducer, opts) {
+    if (getConfig().privateMode) {
+        // Nothing is persisted in private mode; apply to a transient copy so
+        // callers still see a consistent in-memory result.
+        const plan = await loadPlan(sessionId);
+        if (!plan)
+            return { ok: false, reason: "missing-plan" };
+        if (reducer(plan) === false)
+            return { ok: false, reason: "no-change" };
+        const repairs = enforcePlanInvariants(plan);
+        plan.version = (plan.version ?? 1) + 1;
+        plan.updatedAt = new Date().toISOString();
+        return { ok: true, plan, ...(repairs.length ? { repairs } : {}) };
     }
-    await appendJsonl(plan);
+    const retries = opts?.retries ?? PLAN_MUTATION_RETRIES;
+    return enqueuePlanWrite(async () => {
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            const current = await loadPlan(sessionId);
+            if (!current)
+                return { ok: false, reason: "missing-plan" };
+            const baseVersion = current.version ?? 1;
+            if (opts?.expectedVersion !== undefined &&
+                opts.expectedVersion !== baseVersion) {
+                return { ok: false, reason: "version-conflict" };
+            }
+            const draft = clonePlan(current);
+            if (reducer(draft) === false) {
+                return { ok: false, reason: "no-change", plan: current };
+            }
+            const repairs = enforcePlanInvariants(draft);
+            const validation = validateSessionPlan(draft);
+            if (!validation.ok) {
+                return { ok: false, reason: "invalid", plan: current };
+            }
+            draft.version = baseVersion + 1;
+            draft.updatedAt = new Date().toISOString();
+            const db = await loadDatabase();
+            if (db) {
+                if (casPlanRowSqlite(db, draft, baseVersion)) {
+                    return {
+                        ok: true,
+                        plan: draft,
+                        ...(repairs.length ? { repairs } : {}),
+                    };
+                }
+                continue; // another writer won; re-run the reducer on fresh state
+            }
+            const committed = await withJsonlLock(async () => {
+                const stored = (await readAllJsonl()).find((candidate) => candidate.sessionId === sessionId);
+                if ((stored?.version ?? 1) !== baseVersion)
+                    return false;
+                await appendJsonl(draft);
+                return true;
+            });
+            if (committed) {
+                return { ok: true, plan: draft, ...(repairs.length ? { repairs } : {}) };
+            }
+        }
+        return { ok: false, reason: "version-conflict" };
+    });
+}
+function clonePlan(plan) {
+    return {
+        ...plan,
+        tasks: plan.tasks.map((task) => ({
+            ...task,
+            dependencies: [...(task.dependencies ?? [])],
+            resourceLocks: [...(task.resourceLocks ?? [])],
+            ...(task.evidence ? { evidence: { ...task.evidence } } : {}),
+            ...(task.aliases ? { aliases: [...task.aliases] } : {}),
+        })),
+        ...(plan.meta ? { meta: { ...plan.meta } } : {}),
+    };
 }
 async function appendJsonl(plan) {
     try {
@@ -283,6 +496,25 @@ async function readAllJsonl() {
     }
 }
 /** Upgrade legacy persisted plans without changing task ids or states. */
+/**
+ * Fill in dependencies for legacy rows that never stored the field. The previous
+ * foreground task is the default; a responder child is display-linked to its
+ * parent and must never become a blocker.
+ */
+function normalizeLegacyDependencies(tasks) {
+    return tasks.map((task, index) => {
+        const previousForeground = tasks
+            .slice(0, index)
+            .reverse()
+            .find((candidate) => !candidate.responderOwned);
+        const legacyDefault = task.responderOwned || !previousForeground ? [] : [previousForeground.id];
+        return {
+            ...task,
+            dependencies: [...(task.dependencies ?? legacyDefault)],
+            resourceLocks: [...(task.resourceLocks ?? [])],
+        };
+    });
+}
 function normalizePersistedPlan(plan) {
     return {
         ...plan,
@@ -290,13 +522,7 @@ function normalizePersistedPlan(plan) {
         version: typeof plan.version === "number" && plan.version >= 1
             ? plan.version
             : 1,
-        tasks: plan.tasks.map((task, index) => ({
-            ...task,
-            dependencies: [
-                ...(task.dependencies ?? (index > 0 ? [plan.tasks[index - 1].id] : [])),
-            ],
-            resourceLocks: [...(task.resourceLocks ?? [])],
-        })),
+        tasks: normalizeLegacyDependencies(plan.tasks),
     };
 }
 /** Heal plans that stored bare `t1`/`t2` strings as task titles. */
@@ -310,14 +536,18 @@ export async function loadPlan(sessionId) {
     const db = await loadDatabase();
     if (db) {
         const row = db
-            .prepare("SELECT session_id, goal, detail, tasks_json, status, kind, created_at, updated_at FROM plans WHERE session_id = ?")
+            .prepare("SELECT session_id, goal, detail, tasks_json, status, kind, created_at, updated_at, version FROM plans WHERE session_id = ?")
             .get(sessionId);
         if (!row)
             return undefined;
         const { tasks, meta, version } = deserializeTasksPayload(row.tasks_json);
+        // The column is authoritative once present (CAS writes maintain it).
+        const rowVersion = typeof row.version === "number" && row.version >= 1
+            ? Math.max(row.version, version)
+            : version;
         const plan = {
             schemaVersion: 2,
-            version,
+            version: rowVersion,
             sessionId: row.session_id,
             goal: row.goal,
             detail: row.detail,
@@ -332,7 +562,8 @@ export async function loadPlan(sessionId) {
         const needsNormalization = plan.tasks.some((task) => task.dependencies === undefined || task.resourceLocks === undefined);
         const normalized = normalizePersistedPlan(plan);
         const { plan: healed, healed: dirty } = healBareIdTasks(normalized);
-        if (dirty || needsNormalization) {
+        const repairs = enforcePlanInvariants(healed);
+        if (dirty || needsNormalization || repairs.length > 0) {
             // Persist upgrades so resumed SQLite and JSONL plans share dependency semantics.
             await savePlan(healed);
         }
@@ -344,7 +575,8 @@ export async function loadPlan(sessionId) {
     const needsNormalization = found.tasks.some((task) => task.dependencies === undefined || task.resourceLocks === undefined);
     const normalized = normalizePersistedPlan(found);
     const { plan: healed, healed: dirty } = healBareIdTasks(normalized);
-    if (dirty || needsNormalization)
+    const repairs = enforcePlanInvariants(healed);
+    if (dirty || needsNormalization || repairs.length > 0)
         await savePlan(healed);
     return healed;
 }
@@ -500,10 +732,123 @@ export function readyPlanTasks(plan) {
         (task.dependencies ?? []).every((dependency) => done.has(dependency)) &&
         !(task.resourceLocks ?? []).some((resource) => held.has(resource)));
 }
+/** Foreground (non-responder) tasks that are currently `in_progress`. */
+export function activeForegroundTasks(plan) {
+    return plan.tasks.filter((task) => !task.responderOwned && task.state === "in_progress");
+}
+/**
+ * `count(foreground tasks in_progress) <= 1` is a domain invariant,
+ * not a prompt convention. Applied on every {@link mutatePlan} commit and on
+ * load. The earliest dependency-valid active task is kept; later ones are
+ * demoted to `pending` with a repair note (evidence is preserved).
+ *
+ * A parent/child display relationship never implies a dependency, so responder
+ * children may run concurrently and are ignored here.
+ */
+export function enforcePlanInvariants(plan) {
+    const repairs = [...repairOrphanParents(plan)];
+    const active = activeForegroundTasks(plan);
+    if (active.length <= 1)
+        return repairs;
+    const settled = new Set(plan.tasks
+        .filter((task) => task.state === "done" || task.state === "skipped")
+        .map((task) => task.id));
+    const dependencyValid = (task) => (task.dependencies ?? []).every((dependency) => settled.has(dependency));
+    const keep = active.find(dependencyValid) ?? active[0];
+    for (const task of active) {
+        if (task === keep)
+            continue;
+        task.state = "pending";
+        task.note = task.note
+            ? `${task.note} (reopened later: only one foreground task may be active)`
+            : "Demoted to pending: only one foreground task may be active at a time.";
+        repairs.push(`demoted ${task.id} to pending (single-active invariant)`);
+    }
+    return repairs;
+}
+/**
+ * Never leave a child pointing at a task that no longer exists. A revision that
+ * removes a parent with live children keeps the ownership audit in the note and
+ * detaches the display link instead of silently orphaning the row.
+ */
+function repairOrphanParents(plan) {
+    const repairs = [];
+    const known = new Set(plan.tasks.map((task) => task.id));
+    for (const task of plan.tasks) {
+        if (!task.parentTaskId || known.has(task.parentTaskId))
+            continue;
+        const detached = task.parentTaskId;
+        delete task.parentTaskId;
+        task.note = task.note
+            ? `${task.note} (detached: parent ${detached} was removed)`
+            : `Detached responder work: parent ${detached} was removed by a revision.`;
+        repairs.push(`detached ${task.id} from removed parent ${detached}`);
+    }
+    return repairs;
+}
+/**
+ * Apply a foreground-authored plan snapshot onto fresh state.
+ *
+ * Whole-plan writes (plan.create, revisions, task.add reordering) are authored
+ * against a loaded copy. Replacing the stored plan with that copy dropped
+ * anything an asynchronous writer changed in the meantime. This applies the
+ * snapshot's foreground intent while treating responder children as owned by
+ * process settlement:
+ *
+ * - responder-owned rows keep their stored state/note/job linkage;
+ * - responder children created concurrently are retained;
+ * - stored evidence is kept when the snapshot has none for that task.
+ */
+export function applyForegroundSnapshot(draft, snapshot) {
+    const stored = new Map(draft.tasks.map((task) => [task.id, task]));
+    const next = [];
+    for (const task of snapshot.tasks) {
+        const existing = stored.get(task.id);
+        if (existing?.responderOwned) {
+            next.push(existing);
+            continue;
+        }
+        next.push({
+            ...task,
+            ...(task.evidence === undefined && existing?.evidence
+                ? { evidence: existing.evidence }
+                : {}),
+        });
+    }
+    const kept = new Set(next.map((task) => task.id));
+    for (const task of draft.tasks) {
+        if (kept.has(task.id))
+            continue;
+        // Only responder children may appear from a concurrent writer; a foreground
+        // task missing from the snapshot was intentionally removed by the author.
+        if (!task.responderOwned)
+            continue;
+        const parentIndex = task.parentTaskId
+            ? next.findIndex((candidate) => candidate.id === task.parentTaskId)
+            : -1;
+        if (parentIndex >= 0)
+            next.splice(parentIndex + 1, 0, task);
+        else
+            next.push(task);
+    }
+    draft.tasks = next;
+    draft.goal = snapshot.goal;
+    draft.detail = snapshot.detail;
+    draft.status = snapshot.status;
+    draft.kind = snapshot.kind;
+    if (snapshot.meta)
+        draft.meta = { ...(draft.meta ?? {}), ...snapshot.meta };
+}
+/**
+ * Apply a task transition. Rejects transitions the  table forbids so no
+ * caller can rewind terminal work; use a plan revision to supersede a task.
+ */
 export function markTask(plan, taskId, state, note) {
     const task = plan.tasks.find((t) => t.id === taskId);
     if (!task)
         return false;
+    if (!evaluateTaskTransition(task.state, state).allowed)
+        return false;
     task.state = state;
     if (note !== undefined)
         task.note = note;
@@ -522,9 +867,24 @@ export function markNextTask(plan, state) {
     plan.updatedAt = new Date().toISOString();
     return task;
 }
-function foregroundTasks(plan) {
+/** Tasks the model owns. Responder children advance from process lifecycle. */
+export function foregroundTasks(plan) {
     return plan.tasks.filter((task) => !task.responderOwned);
 }
+/** Foreground work that is neither settled nor skipped, in plan order. */
+export function foregroundRemaining(plan) {
+    return foregroundTasks(plan).filter((task) => task.state === "pending" || task.state === "in_progress");
+}
+/** The single active foreground task, or the next one to resume. */
+export function foregroundActiveTask(plan) {
+    const remaining = foregroundRemaining(plan);
+    return (remaining.find((task) => task.state === "in_progress") ?? remaining[0]);
+}
+/** Responder children that are still running or awaiting analysis. */
+export function responderOpenTasks(plan) {
+    return plan.tasks.filter((task) => task.responderOwned &&
+        (task.state === "pending" || task.state === "in_progress"));
+}
 export function planProgress(plan) {
     const foreground = foregroundTasks(plan);
     const done = foreground.filter((task) => task.state === "done").length;