@deftai/directive-core 0.104.0 → 0.105.0

package/dist/slice/lock.js

@@ -1,12 +1,127 @@
-import { closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
 import { dirname } from "node:path";
 const threadLocked = { held: false };
+/** 10× occupancy heartbeat TTL. Off-Linux PID reuse / stalled holder reclaim. */
+export const STALE_LOCK_HARD_CAP_MS = 20 * 60 * 1000 * 10;
 function defaultSleep(ms) {
     const end = Date.now() + ms;
     while (Date.now() < end) {
         /* spin */
     }
 }
+export function parseLockRecord(lockPath) {
+    try {
+        const lines = readFileSync(lockPath, { encoding: "utf8" }).trim().split(/\r?\n/);
+        const pidRaw = Number(lines[0]);
+        const pid = Number.isInteger(pidRaw) && pidRaw > 0 ? pidRaw : null;
+        if (lines.length >= 3) {
+            const acquiredRaw = Number(lines[2]);
+            return {
+                pid,
+                token: lines[1] ?? "",
+                acquiredAt: Number.isInteger(acquiredRaw) && acquiredRaw > 0 ? acquiredRaw : null,
+            };
+        }
+        const acquiredRaw = Number(lines[1]);
+        return {
+            pid,
+            token: "",
+            acquiredAt: Number.isInteger(acquiredRaw) && acquiredRaw > 0 ? acquiredRaw : null,
+        };
+    }
+    catch {
+        return { pid: null, token: "", acquiredAt: null };
+    }
+}
+export function assertAppendLockOwned(held) {
+    const rec = parseLockRecord(held.lockPath);
+    if (rec.pid !== held.pid || rec.token !== held.token || rec.token.length === 0) {
+        throw new Error(`lock compromised: ${held.lockPath}`);
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+function linuxPidStartedAfter(pid, acquiredAt) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, { encoding: "utf8" });
+        const closeParen = stat.lastIndexOf(")");
+        if (closeParen < 0)
+            return false;
+        const startTicks = Number(stat.slice(closeParen + 2).split(" ")[19]);
+        if (!Number.isFinite(startTicks))
+            return false;
+        const btime = /(?:^|\n)btime (\d+)/.exec(readFileSync("/proc/stat", { encoding: "utf8" }));
+        if (btime === null)
+            return false;
+        const startMs = Number(btime[1]) * 1000 + (startTicks * 1000) / 100;
+        return startMs > acquiredAt + 1000;
+    }
+    catch {
+        return false;
+    }
+}
+function lockMtimeMs(lockPath) {
+    try {
+        return statSync(lockPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+function isAbandoned(rec, now, lockPath) {
+    if (rec.pid === null) {
+        const mtime = lockMtimeMs(lockPath);
+        return mtime !== null && now - mtime > STALE_LOCK_HARD_CAP_MS;
+    }
+    if (!processExists(rec.pid))
+        return true;
+    if (rec.acquiredAt !== null && linuxPidStartedAfter(rec.pid, rec.acquiredAt))
+        return true;
+    if (rec.acquiredAt !== null && now - rec.acquiredAt > STALE_LOCK_HARD_CAP_MS)
+        return true;
+    return false;
+}
+function recordsMatch(a, b) {
+    return a.pid === b.pid && a.token === b.token && a.acquiredAt === b.acquiredAt;
+}
+/** Atomic rename reclaim: one waiter wins; losers see ENOENT. */
+function tryReclaimAbandonedOwner(lockPath, now) {
+    const observed = parseLockRecord(lockPath);
+    if (!isAbandoned(observed, now, lockPath))
+        return false;
+    const quarantine = `${lockPath}.reclaim.${process.pid}.${randomUUID()}`;
+    try {
+        renameSync(lockPath, quarantine);
+    }
+    catch {
+        return false;
+    }
+    const quarantined = parseLockRecord(quarantine);
+    if (recordsMatch(observed, quarantined)) {
+        try {
+            unlinkSync(quarantine);
+        }
+        catch {
+            /* already gone */
+        }
+        return true;
+    }
+    try {
+        renameSync(quarantine, lockPath);
+    }
+    catch {
+        /* best-effort restore */
+    }
+    return false;
+}
 /** Serialise appenders across threads AND processes (sidecar lock file). */
 export function withAppendLock(logPath, fn, deps = {}) {
     const sleepMs = deps.sleepMs ?? defaultSleep;
@@ -18,13 +133,18 @@ export function withAppendLock(logPath, fn, deps = {}) {
     }
     threadLocked.held = true;
     let fd;
+    let held;
+    let reclaimedStale = false;
     try {
         const deadline = now() + 30_000;
         while (true) {
             try {
                 fd = openSync(lockPath, "wx");
-                writeSync(fd, Buffer.from("\0"));
-                break;
+                const token = randomUUID();
+                const acquiredAt = now();
+                writeSync(fd, Buffer.from(`${process.pid}\n${token}\n${acquiredAt}\n`));
+                held = { lockPath, pid: process.pid, token, acquiredAt };
+                return fn(held);
             }
             catch (err) {
                 const code = err.code;
@@ -32,26 +152,32 @@ export function withAppendLock(logPath, fn, deps = {}) {
                     throw err;
                 }
                 if (now() > deadline) {
+                    if (!reclaimedStale && tryReclaimAbandonedOwner(lockPath, now())) {
+                        reclaimedStale = true;
+                        continue;
+                    }
                     throw new Error(`timed out acquiring lock for ${logPath}`);
                 }
                 sleepMs(20);
             }
         }
-        return fn();
     }
     finally {
         if (fd !== undefined) {
             closeSync(fd);
         }
-        threadLocked.held = false;
-        try {
-            if (existsSync(lockPath)) {
-                unlinkSync(lockPath);
+        if (held !== undefined) {
+            try {
+                assertAppendLockOwned(held);
+                if (existsSync(lockPath)) {
+                    unlinkSync(lockPath);
+                }
+            }
+            catch {
+                /* not ours anymore */
             }
         }
-        catch {
-            /* best-effort */
-        }
+        threadLocked.held = false;
     }
 }
 /** Public alias mirroring Python append_lock. */

package/dist/story-ready/evaluate.d.ts

@@ -20,6 +20,8 @@ export interface EvaluateOptions {
     readonly projectRoot?: string;
     /** Skip parent-lineage check (tests / opt-out). Default false. */
     readonly skipParentLineage?: boolean;
+    /** Skip project-invariant coverage (#3425). Default false. */
+    readonly skipProjectInvariants?: boolean;
 }
 /**
  * Pure evaluator — returns exit code + human message. Faithful to

package/dist/story-ready/evaluate.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { evaluateProjectInvariantsGate, resolveProjectRootForInvariants, } from "../preflight/project-invariants-gate.js";
 import { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 import { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND, VALID_DISPATCH_KINDS, } from "./allocation.js";
 export const ACTIVE_FOLDER = "active";
@@ -168,6 +169,18 @@ export function evaluate(vbriefPath, options = {}) {
                 `\n${formatParentLineageLine(lineage)}`,
         };
     }
+    const invariants = evaluateProjectInvariantsGate(vbriefCheck.payload, {
+        projectRoot: resolveProjectRootForInvariants(vbriefCheck.path, options.projectRoot),
+        skip: options.skipProjectInvariants === true,
+    });
+    if (!invariants.ok) {
+        return {
+            exitCode: 1,
+            dispatchKind: null,
+            parentLineage: lineage,
+            message: `not ready: ${invariants.message}`,
+        };
+    }
     const lineageNote = lineage.applicable
         ? `parent lineage OK (${lineage.parent_requirement_ids.length} req IDs` +
             (lineage.negative_invariant_ids.length > 0

package/dist/swarm/complete-cohort.d.ts

@@ -45,9 +45,12 @@ export declare function completeCohort(args: {
     emitJson?: boolean;
     /** Per-story delivery evidence; without it code-bearing stories fail closed (#3041). */
     delivery?: CohortDeliveryContext | null;
+    /** Optional launch allocation plan id so close-out reads this cohort's occupancy slot. */
+    allocationPlanId?: string | null;
 }): {
     exitCode: number;
     stdout: string;
     stderr: string;
+    sweep: SweepResult | null;
 };
 //# sourceMappingURL=complete-cohort.d.ts.map

package/dist/swarm/complete-cohort.js

@@ -1,11 +1,13 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { detectLifecycleFolder } from "../scope/decomposed-refs.js";
 import { classifyStoredDeliveryDisposition, } from "../scope/delivery-evidence.js";
 import { runTransition } from "../scope/transition.js";
 import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "../scope/vbrief-ref.js";
+import { readOccupancy, releaseSwarmOccupancy } from "../session/occupancy.js";
 import { MAX_FIXPOINT_PASSES, TERMINAL_FOLDERS } from "./constants.js";
+import { resolveLaunchOccupancySessionId } from "./launch.js";
 function loadPlan(path) {
     try {
         const data = JSON.parse(readFileSync(path, "utf8"));
@@ -21,6 +23,14 @@ function loadPlan(path) {
         return null;
     }
 }
+function storyIdFromPath(path) {
+    const plan = loadPlan(path);
+    const id = plan !== null && typeof plan.id === "string" ? plan.id.trim() : "";
+    if (id.length > 0)
+        return id;
+    const name = basename(path);
+    return hasArtifactSuffix(name) ? stripArtifactSuffix(name) : name.replace(/\.[^.]+$/, "");
+}
 function rel(path, projectRoot) {
     try {
         return resolve(path)
@@ -226,6 +236,7 @@ function completeParent(args) {
     }
     let current = parentPath;
     let action = "complete";
+    let activateNotice = "";
     if (folder === "pending") {
         action = "activate+complete";
         const activateResult = runTransition("activate", current);
@@ -238,18 +249,22 @@ function completeParent(args) {
                 detail: `activate failed: ${activateResult.message}`,
             };
         }
+        activateNotice = activateResult.message.trim();
         current = join(vbriefDir, "active", parentPath.split(/[/\\]/).pop() ?? "");
     }
     const completeResult = runTransition("complete", current, new Date(), transitionOptionsFor(current, delivery));
     if (completeResult.ok) {
         settled.add(resolve(join(vbriefDir, "completed", parentPath.split(/[/\\]/).pop() ?? "")));
     }
+    const detail = activateNotice.length > 0
+        ? `${activateNotice}\n${completeResult.message}`
+        : completeResult.message;
     return {
         kind: "epic",
         path: relpath,
         action: completeResult.ok ? action : "failed",
         ok: completeResult.ok,
-        detail: completeResult.message,
+        detail,
     };
 }
 export function sweepCohort(storyPaths, projectRoot, dryRun, delivery) {
@@ -412,6 +427,7 @@ export function completeCohort(args) {
             exitCode: 2,
             stdout: "",
             stderr: `Error: project root does not exist: ${projectRoot}\n`,
+            sweep: null,
         };
     }
     if (!existsSync(resolveLifecycleRoot(projectRoot))) {
@@ -419,31 +435,33 @@ export function completeCohort(args) {
             exitCode: 2,
             stdout: "",
             stderr: `Error: no vbrief/ directory under project root: ${projectRoot}\n`,
+            sweep: null,
         };
     }
     const { paths, errors } = resolveCohortPaths(args.stories ?? [], args.cohortGlobs ?? [], projectRoot);
     if (paths.length === 0) {
         const msg = "Error: empty cohort. Pass one or more story vBRIEF paths as positional arguments and/or --cohort <glob>.";
+        const empty = {
+            project_root: projectRoot,
+            dry_run: args.dryRun ?? false,
+            stories: [],
+            parents: [],
+            errors: errors.length > 0 ? errors : [msg],
+            ok: false,
+        };
         if (args.emitJson) {
-            const empty = {
-                project_root: projectRoot,
-                dry_run: args.dryRun ?? false,
-                stories: [],
-                parents: [],
-                errors: errors.length > 0 ? errors : [msg],
-                ok: false,
-            };
             return {
                 exitCode: 2,
                 stdout: `${JSON.stringify(sweepResultToDict(empty), null, 2)}\n`,
                 stderr: "",
+                sweep: empty,
             };
         }
         let stderr = `${msg}\n`;
         for (const err of errors) {
             stderr += `  - ${err}\n`;
         }
-        return { exitCode: 2, stdout: "", stderr };
+        return { exitCode: 2, stdout: "", stderr, sweep: empty };
     }
     const result = sweepCohortWithArgs({
         storyPaths: paths,
@@ -452,17 +470,47 @@ export function completeCohort(args) {
         delivery: args.delivery ?? null,
     });
     result.errors.push(...errors);
+    if (result.ok && args.dryRun !== true) {
+        const envSession = process.env.DEFT_SESSION_ID?.trim() ?? "";
+        let sessionId = envSession;
+        if (sessionId.length === 0) {
+            const resolved = resolveLaunchOccupancySessionId(projectRoot, {
+                allocationPlanId: args.allocationPlanId ?? null,
+                storyIds: paths.map(storyIdFromPath),
+            });
+            if (resolved.reason === "ok" && resolved.sessionId.length > 0) {
+                sessionId = resolved.sessionId;
+            }
+            else if (readOccupancy(projectRoot) !== null) {
+                result.ok = false;
+                result.errors.push("swarm close-out occupancy record is missing or belongs to a different cohort. " +
+                    "Steal with occupancy:steal --confirm --occupant <id>.");
+            }
+        }
+        if (result.ok && sessionId.length > 0) {
+            const released = releaseSwarmOccupancy(projectRoot, {
+                env: process.env,
+                sessionId,
+            });
+            if (released.code !== 0) {
+                result.ok = false;
+                result.errors.push(released.message);
+            }
+        }
+    }
     if (args.emitJson) {
         return {
             exitCode: result.ok ? 0 : 1,
             stdout: `${JSON.stringify(sweepResultToDict(result), null, 2)}\n`,
             stderr: "",
+            sweep: result,
         };
     }
     return {
         exitCode: result.ok ? 0 : 1,
         stdout: `${renderSweepText(result)}\n`,
         stderr: "",
+        sweep: result,
     };
 }
 //# sourceMappingURL=complete-cohort.js.map

package/dist/swarm/finalize-cohort.js

@@ -51,6 +51,18 @@ function safeSegment(text) {
 function oneLine(text) {
     return text.replace(/\r?\n/g, " ");
 }
+/** Existing sweep records already carry refused-stamp remediations (#3398). */
+function sweepDetailLines(sweep) {
+    const lines = [];
+    for (const rec of [...sweep.stories, ...sweep.parents]) {
+        const detail = rec.detail.trim();
+        if (detail.length > 0) {
+            lines.push(`${rec.path}: ${detail}`);
+        }
+    }
+    lines.push(...sweep.errors);
+    return lines;
+}
 function parseRepo(repo) {
     const slash = repo.indexOf("/");
     if (slash <= 0 || slash >= repo.length - 1) {
@@ -640,8 +652,15 @@ export function finalizeCohort(args) {
             }
             : null,
     });
+    const sweep = sweepResult.sweep;
     if (sweepResult.exitCode !== 0) {
         errors.push("cohort completion sweep failed.");
+        if (sweep !== null) {
+            errors.push(...sweepDetailLines(sweep));
+        }
+        else if (sweepResult.stdout.trim().length > 0) {
+            errors.push(sweepResult.stdout.trim());
+        }
         return buildResponse({
             projectRoot,
             dryRun,
@@ -649,7 +668,7 @@ export function finalizeCohort(args) {
             prNumbers,
             storyPaths,
             closingIssues: [...closingIssues],
-            sweep: null,
+            sweep,
             commitSha: null,
             branch: null,
             prUrl: null,
@@ -688,7 +707,7 @@ export function finalizeCohort(args) {
         prNumbers,
         storyPaths,
         closingIssues: [...closingIssues],
-        sweep: null,
+        sweep,
         commitSha,
         branch,
         prUrl,
@@ -747,6 +766,18 @@ function buildResponse(input) {
             lines.push(`    - ${oneLine(path)}`);
         }
     }
+    if (input.sweep !== null) {
+        const records = [...input.sweep.stories, ...input.sweep.parents];
+        if (records.length > 0 || input.sweep.errors.length > 0) {
+            lines.push("  Sweep:");
+            for (const rec of records) {
+                lines.push(`    [${rec.ok ? "ok" : "FAILED"}] ${rec.action} ${rec.path} -- ${oneLine(rec.detail)}`);
+            }
+            for (const err of input.sweep.errors) {
+                lines.push(`    - ${oneLine(err)}`);
+            }
+        }
+    }
     if (input.branch !== null) {
         lines.push(`  Branch: ${input.branch}`);
     }

package/dist/swarm/launch.d.ts

@@ -37,6 +37,27 @@ export declare function enforceGates(resolved: readonly ResolvedStory[], project
     story: ResolvedStory;
     reason: string;
 } | null;
+export declare const SWARM_LAUNCH_MANIFEST_RELPATH: readonly [".deft", "swarm-launch-manifest.json"];
+export declare const SWARM_LAUNCH_OCCUPANCY_DIR: readonly [".deft", "swarm-launch-occupancy"];
+export declare function swarmLaunchManifestPath(projectRoot: string): string;
+export interface LaunchOccupancyRecord {
+    readonly allocation_plan_id: string | null;
+    readonly occupancy_session_id: string;
+    readonly story_ids: readonly string[];
+    readonly cohort_key: string;
+}
+export interface LaunchOccupancyQuery {
+    readonly allocationPlanId?: string | null;
+    readonly storyIds?: readonly string[];
+}
+export type LaunchOccupancyLookupReason = "ok" | "missing" | "wrong-cohort";
+export declare function occupancyCohortKey(allocationPlanId: string | null | undefined, storyIds?: readonly string[]): string;
+export declare function launchOccupancyRecordRelpath(cohortKey: string): string[];
+export declare function persistLaunchOccupancyRecord(projectRoot: string, record: LaunchOccupancyRecord): void;
+export declare function resolveLaunchOccupancySessionId(projectRoot: string, query?: LaunchOccupancyQuery): {
+    sessionId: string;
+    reason: LaunchOccupancyLookupReason;
+};
 export declare function buildManifest(resolved: readonly ResolvedStory[], options: {
     projectRoot: string;
     group?: string | null;
@@ -53,6 +74,7 @@ export declare function buildManifest(resolved: readonly ResolvedStory[], option
     modelSource?: string | null;
     runtimeMode?: string | null;
     githubAuthMode?: string | null;
+    occupancySessionId?: string | null;
 }): Record<string, unknown>[];
 export declare function orderCohort(resolved: readonly ResolvedStory[], _projectRoot: string): ResolvedStory[];
 export interface LaunchArgs {