@deftai/directive-core 0.104.0 → 0.106.0

package/dist/session/occupancy.js

@@ -0,0 +1,422 @@
+/**
+ * Worktree occupancy lease (#3433).
+ *
+ * Ritual-state is "this session completed ceremony." Occupancy is "who may
+ * mutate this tree right now." Those lifetimes differ; do not overload
+ * ritual-state.json. Join negotiation (`occupancy:request`) is out of scope.
+ *
+ * Concurrency model:
+ * - Assumptions: local filesystem; cooperating processes on one machine.
+ * - Guarantees: mutual exclusion under crash-free operation; detect-and-abort
+ *   if the sidecar lock is compromised (fence before rename/unlink).
+ * - Non-goals: network filesystems; Byzantine processes; perfect off-Linux
+ *   PID-reuse detection (hard age cap + fence instead).
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { containedRemove, containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { assertAppendLockOwned, withAppendLock } from "../slice/lock.js";
+import { stableJson } from "./json.js";
+import { parseTimestamp, timestampIso } from "./time.js";
+export const OCCUPANCY_SCHEMA_VERSION = 1;
+export const OCCUPANCY_RELPATH = [".deft", "occupancy.json"];
+/** Crash recovery TTL: 20 minutes without heartbeat (15–30 window). */
+export const OCCUPANCY_TTL_MS = 20 * 60 * 1000;
+export const OCCUPANCY_INTENTS = ["mutation", "swarm", "review"];
+export const OCCUPANCY_JOIN_PROTOCOLS = ["none", "heartbeat-file", "parent-message"];
+export function occupancyPath(projectRoot) {
+    return join(resolve(projectRoot), ...OCCUPANCY_RELPATH);
+}
+export function heartbeatAgeSeconds(record, now = new Date()) {
+    return Math.max(0, Math.round((now.getTime() - record.heartbeatAt.getTime()) / 1000));
+}
+export function isOccupancyExpired(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
+    return now.getTime() - record.heartbeatAt.getTime() > ttlMs;
+}
+export function formatOccupancyRemediation(record, now = new Date()) {
+    const age = heartbeatAgeSeconds(record, now);
+    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago).\n` +
+        "Stay read-only (`session:start --read-only`), use another worktree,\n" +
+        "queue a join (`occupancy:request`), or steal (`occupancy:steal --confirm`).");
+}
+export function resolveOccupancySessionId(input = {}) {
+    const explicit = input.sessionId?.trim();
+    if (explicit)
+        return explicit;
+    const envId = (input.env ?? process.env).DEFT_SESSION_ID?.trim();
+    if (envId)
+        return envId;
+    return (input.newSessionId ?? randomUUID)();
+}
+export function readOccupancy(projectRoot) {
+    const path = occupancyPath(projectRoot);
+    try {
+        if (!existsSync(path))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+    }
+    catch {
+        return null;
+    }
+    return parseOccupancy(payload, resolve(projectRoot));
+}
+export function liveOccupant(projectRoot, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
+    const record = readOccupancy(projectRoot);
+    if (record === null || isOccupancyExpired(record, now, ttlMs))
+        return null;
+    return record;
+}
+export function applyWorktreeOccupancy(projectRoot, input = {}) {
+    const now = input.now ?? new Date();
+    const path = occupancyPath(projectRoot);
+    const incoming = resolveOccupancySessionId(input);
+    const existing = readOccupancy(projectRoot);
+    const live = existing !== null && !isOccupancyExpired(existing, now) ? existing : null;
+    if (input.steal === true) {
+        return stealOccupancy(projectRoot, { ...input, sessionId: incoming, now });
+    }
+    if (live !== null && live.sessionId !== incoming) {
+        return {
+            action: "denied",
+            sessionId: incoming,
+            record: live,
+            path,
+            message: formatOccupancyRemediation(live, now),
+            code: 1,
+        };
+    }
+    if (input.write === false) {
+        return {
+            action: live !== null ? "heartbeat" : "claimed",
+            sessionId: incoming,
+            record: live,
+            path,
+            message: live !== null
+                ? `occupancy heartbeat session ${incoming} (intent=${live.intent})`
+                : `occupancy claimed session ${incoming} (intent=${input.intent ?? "mutation"})`,
+            code: 0,
+        };
+    }
+    return withOccupancyLock(projectRoot, (fence) => {
+        const existingLocked = readOccupancy(projectRoot);
+        const liveLocked = existingLocked !== null && !isOccupancyExpired(existingLocked, now) ? existingLocked : null;
+        if (liveLocked !== null && liveLocked.sessionId !== incoming) {
+            return {
+                action: "denied",
+                sessionId: incoming,
+                record: liveLocked,
+                path,
+                message: formatOccupancyRemediation(liveLocked, now),
+                code: 1,
+            };
+        }
+        const record = writeOccupancyRecord(projectRoot, {
+            sessionId: incoming,
+            worktreePath: resolve(projectRoot),
+            intent: input.intent ?? liveLocked?.intent ?? "mutation",
+            claimedAt: liveLocked?.claimedAt ?? now,
+            heartbeatAt: now,
+            host: input.host ?? liveLocked?.host ?? occupancyHost(input.env),
+            address: input.address ?? liveLocked?.address ?? occupancyAddress(input.env),
+            retainCapable: input.retainCapable ?? liveLocked?.retainCapable ?? false,
+            joinProtocol: input.joinProtocol ?? liveLocked?.joinProtocol ?? "none",
+        }, fence);
+        const action = liveLocked !== null ? "heartbeat" : "claimed";
+        return {
+            action,
+            sessionId: record.sessionId,
+            record,
+            path,
+            message: action === "heartbeat"
+                ? `occupancy heartbeat session ${record.sessionId} (intent=${record.intent})`
+                : `occupancy claimed session ${record.sessionId} (intent=${record.intent})`,
+            code: 0,
+        };
+    }, input.lockDeps);
+}
+export function stealOccupancy(projectRoot, input = {}) {
+    const now = input.now ?? new Date();
+    const path = occupancyPath(projectRoot);
+    if (input.confirm !== true) {
+        return {
+            action: "denied",
+            sessionId: resolveOccupancySessionId(input),
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:steal requires --confirm after naming the occupant.",
+            code: 2,
+        };
+    }
+    const named = input.occupant?.trim() ?? "";
+    if (named.length === 0) {
+        return {
+            action: "denied",
+            sessionId: resolveOccupancySessionId(input),
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:steal requires --occupant <session-id> to name the current occupant.",
+            code: 2,
+        };
+    }
+    const existing = readOccupancy(projectRoot);
+    const live = existing !== null && !isOccupancyExpired(existing, now) ? existing : null;
+    if (live !== null && live.sessionId !== named) {
+        return {
+            action: "denied",
+            sessionId: resolveOccupancySessionId(input),
+            record: live,
+            path,
+            message: `occupancy:steal named occupant ${named} does not match live occupant ${live.sessionId}.\n` +
+                formatOccupancyRemediation(live, now),
+            code: 1,
+        };
+    }
+    return withOccupancyLock(projectRoot, (fence) => {
+        const existingLocked = readOccupancy(projectRoot);
+        const liveLocked = existingLocked !== null && !isOccupancyExpired(existingLocked, now) ? existingLocked : null;
+        if (liveLocked !== null && liveLocked.sessionId !== named) {
+            return {
+                action: "denied",
+                sessionId: resolveOccupancySessionId(input),
+                record: liveLocked,
+                path,
+                message: `occupancy:steal named occupant ${named} does not match live occupant ${liveLocked.sessionId}.\n` +
+                    formatOccupancyRemediation(liveLocked, now),
+                code: 1,
+            };
+        }
+        const incoming = resolveOccupancySessionId(input);
+        const record = writeOccupancyRecord(projectRoot, {
+            sessionId: incoming,
+            worktreePath: resolve(projectRoot),
+            intent: input.intent ?? "mutation",
+            claimedAt: now,
+            heartbeatAt: now,
+            host: input.host ?? occupancyHost(input.env),
+            address: input.address ?? occupancyAddress(input.env),
+            retainCapable: input.retainCapable ?? false,
+            joinProtocol: input.joinProtocol ?? "none",
+        }, fence);
+        return {
+            action: "stolen",
+            sessionId: record.sessionId,
+            record,
+            path,
+            message: `occupancy stolen from ${named}; writer is now session ${record.sessionId}`,
+            code: 0,
+        };
+    }, input.lockDeps);
+}
+export function releaseOccupancy(projectRoot, input = {}) {
+    const now = input.now ?? new Date();
+    const path = occupancyPath(projectRoot);
+    const caller = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    return withOccupancyLock(projectRoot, (fence) => {
+        const existing = readOccupancy(projectRoot);
+        if (existing === null) {
+            return {
+                action: "released",
+                sessionId: caller,
+                record: null,
+                path,
+                message: "occupancy already free",
+                code: 0,
+            };
+        }
+        const expired = isOccupancyExpired(existing, now);
+        const owns = caller.length > 0 && caller === existing.sessionId;
+        if (!expired && !owns) {
+            return {
+                action: "denied",
+                sessionId: caller,
+                record: existing,
+                path,
+                message: formatOccupancyRemediation(existing, now),
+                code: 1,
+            };
+        }
+        fence();
+        const still = readOccupancy(projectRoot);
+        if (still === null) {
+            return {
+                action: "released",
+                sessionId: caller,
+                record: null,
+                path,
+                message: "occupancy already free",
+                code: 0,
+            };
+        }
+        if (still.sessionId !== existing.sessionId) {
+            throw new Error("lock compromised: occupancy session changed before release");
+        }
+        if (!expired && caller !== still.sessionId) {
+            return {
+                action: "denied",
+                sessionId: caller,
+                record: still,
+                path,
+                message: formatOccupancyRemediation(still, now),
+                code: 1,
+            };
+        }
+        removeOccupancyFile(projectRoot, fence);
+        return {
+            action: "released",
+            sessionId: still.sessionId,
+            record: null,
+            path,
+            message: `occupancy released session ${still.sessionId}`,
+            code: 0,
+        };
+    }, input.lockDeps);
+}
+export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
+    const now = input.now ?? new Date();
+    const live = liveOccupant(projectRoot, now);
+    if (live === null)
+        return { allow: true, message: null, occupant: null };
+    const incoming = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    if (incoming.length > 0 && incoming === live.sessionId) {
+        return { allow: true, message: null, occupant: live };
+    }
+    return {
+        allow: false,
+        message: formatOccupancyRemediation(live, now),
+        occupant: live,
+    };
+}
+/** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
+export function releaseSwarmOccupancy(projectRoot, input = {}) {
+    const env = input.env ?? process.env;
+    const sessionId = input.sessionId?.trim() || env.DEFT_SESSION_ID?.trim() || "";
+    if (sessionId.length === 0) {
+        const occupant = readOccupancy(projectRoot);
+        return {
+            action: "denied",
+            sessionId: "",
+            record: occupant,
+            path: occupancyPath(projectRoot),
+            message: "swarm close-out has no occupancy_session_id (manifest missing or predates the field) " +
+                "and DEFT_SESSION_ID is unset. Steal with occupancy:steal --confirm --occupant <id>.",
+            code: 1,
+        };
+    }
+    return releaseOccupancy(projectRoot, {
+        env,
+        now: input.now,
+        lockDeps: input.lockDeps,
+        sessionId,
+    });
+}
+export function runOccupancySteal(projectRoot, input = {}) {
+    return stealOccupancy(projectRoot, { ...input, steal: true });
+}
+function occupancyHost(env) {
+    const value = (env ?? process.env).DEFT_AGENT_ID?.trim();
+    return value && value.length > 0 ? value : "none";
+}
+function occupancyAddress(env) {
+    const value = (env ?? process.env).DEFT_SESSION_NAME?.trim();
+    return value && value.length > 0 ? value : "none";
+}
+function parseOccupancy(payload, fallbackWorktree) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const obj = payload;
+    const sessionId = typeof obj.session_id === "string" ? obj.session_id.trim() : "";
+    if (sessionId.length === 0)
+        return null;
+    const intentRaw = typeof obj.intent === "string" ? obj.intent : "mutation";
+    const intent = OCCUPANCY_INTENTS.includes(intentRaw)
+        ? intentRaw
+        : "mutation";
+    const claimedAt = parseTimestamp(obj.claimed_at) ?? parseTimestamp(obj.heartbeat_at);
+    const heartbeatAt = parseTimestamp(obj.heartbeat_at) ?? claimedAt;
+    if (claimedAt === null || heartbeatAt === null)
+        return null;
+    const joinRaw = typeof obj.join_protocol === "string" ? obj.join_protocol : "none";
+    const joinProtocol = OCCUPANCY_JOIN_PROTOCOLS.includes(joinRaw)
+        ? joinRaw
+        : "none";
+    const worktreePath = typeof obj.worktree_path === "string" && obj.worktree_path.trim().length > 0
+        ? obj.worktree_path
+        : fallbackWorktree;
+    return {
+        schemaVersion: typeof obj.schemaVersion === "number" ? obj.schemaVersion : OCCUPANCY_SCHEMA_VERSION,
+        sessionId,
+        worktreePath,
+        intent,
+        claimedAt,
+        heartbeatAt,
+        host: typeof obj.host === "string" && obj.host.length > 0 ? obj.host : "none",
+        address: typeof obj.address === "string" && obj.address.length > 0 ? obj.address : "none",
+        retainCapable: obj.retain_capable === true,
+        joinProtocol,
+        raw: { ...obj },
+    };
+}
+function occupancyPayload(record) {
+    return {
+        schemaVersion: OCCUPANCY_SCHEMA_VERSION,
+        session_id: record.sessionId,
+        worktree_path: record.worktreePath,
+        intent: record.intent,
+        claimed_at: timestampIso(record.claimedAt),
+        heartbeat_at: timestampIso(record.heartbeatAt),
+        host: record.host,
+        address: record.address,
+        retain_capable: record.retainCapable,
+        join_protocol: record.joinProtocol,
+    };
+}
+function writeOccupancyRecord(projectRoot, record, fence) {
+    const root = resolve(projectRoot);
+    const target = occupancyPath(root);
+    assertWriteTargetSafe(root, target);
+    const dir = dirname(target);
+    const tmpName = join(dir, `.occupancy.${process.pid}.occupancy.json.tmp`);
+    const payload = occupancyPayload(record);
+    const text = `${stableJson(payload, 2)}\n`;
+    try {
+        containedWrite({ root, target: tmpName, data: text, mode: "create" });
+        fence();
+        renameSync(tmpName, target);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpName, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+    const parsed = parseOccupancy(payload, record.worktreePath);
+    if (parsed === null) {
+        throw new Error("occupancy write produced an unreadable record");
+    }
+    return parsed;
+}
+function removeOccupancyFile(projectRoot, fence) {
+    const root = resolve(projectRoot);
+    fence();
+    containedRemove({ root, target: occupancyPath(root) });
+}
+function withOccupancyLock(projectRoot, fn, deps = {}) {
+    return withAppendLock(occupancyPath(projectRoot), (held) => {
+        const fence = () => {
+            assertAppendLockOwned(held);
+        };
+        return fn(fence);
+    }, deps);
+}
+//# sourceMappingURL=occupancy.js.map

package/dist/session/openclaw-soft-rebind-deposit.js

@@ -5,11 +5,11 @@
  * in compact-ritual.ts. Fail-closed when OpenClaw is not detected (unless
  * forceDeposit for tests). Real directory copy — not symlink-escape into npm.
  */
-import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { detectOpenClaw, isEscapingSkillSymlink, listInScopeSkillsDirs, } from "../doctor/openclaw-skills.js";
-import { containedWrite } from "../fs/contained-write.js";
+import { containedMkdir, containedRemove, containedRename, containedWrite, } from "../fs/contained-write.js";
 import { formatOpenClawSoftRebindSkillMarkdown, isManagedOpenClawSoftRebindSkill, OPENCLAW_SOFT_REBIND_SKILL_ID, } from "./compact-ritual.js";
 function defaultIsDir(path) {
     try {
@@ -98,7 +98,7 @@ export function depositOpenClawSoftRebindSkill(options = {}) {
         if (kind === "symlink" && isEscapingSkillSymlink(skillsDir, skillDir)) {
             // Replace unusable escaping symlink with a real copy.
             try {
-                rmSync(skillDir, { recursive: true, force: true });
+                containedRemove({ root: skillsDir, target: skillDir, recursive: true });
             }
             catch {
                 // best-effort
@@ -121,7 +121,7 @@ export function depositOpenClawSoftRebindSkill(options = {}) {
                 continue;
             }
         }
-        mkdirSync(skillDir, { recursive: true });
+        containedMkdir({ root: skillsDir, target: skillDir });
         const tmpName = `SKILL.md.deft-${process.pid}-${Date.now().toString(36)}.tmp`;
         const staging = join(skillDir, tmpName);
         try {
@@ -132,11 +132,11 @@ export function depositOpenClawSoftRebindSkill(options = {}) {
                 data: expected,
                 mode: "replace",
             });
-            renameSync(staging, skillFile);
+            containedRename({ root: skillsDir, from: staging, to: skillFile, mutation: false });
         }
         catch (err) {
             try {
-                rmSync(staging, { force: true });
+                containedRemove({ root: skillsDir, target: staging, mutation: false });
             }
             catch {
                 /* best-effort */

package/dist/session/process-cost.d.ts

@@ -1,13 +1,3 @@
-/**
- * Local process-cost ceremony events (#2994).
- *
- * Always-on, best-effort appends to `.deft-cache/events.jsonl`.
- * Not gated on valueFeedback (distinct from #1709 attribution).
- * No remote / Product Insights upload (#2603 not required).
- *
- * Types are declared locally (not imported from session-start) so this module
- * does not form an import cycle with session-start call sites.
- */
 import { type BehavioralEventRecord } from "../lifecycle/events.js";
 export { PROCESS_COST_EVENT_NAMES, PROCESS_COST_REQUIRED_PAYLOAD, type ProcessCostEventName, } from "./process-cost-constants.js";
 /** Ceremony tier labels mirror session-start cold|rearm (#2992 / #2994). */
@@ -50,4 +40,36 @@ export declare function emitSessionStartProcessCost(input: SessionStartProcessCo
  * Returns null on any failure (telemetry must not change deny verdict).
  */
 export declare function emitSessionRitualBlockedProcessCost(input: SessionRitualBlockedProcessCostInput, options: EmitProcessCostOptions): BehavioralEventRecord | null;
+export interface CeremonyCostRollup {
+    /** Discriminator: CLI process time, not agent-turn wall clock (#3500 / #3508). */
+    readonly kind: "cli_process_time";
+    readonly windowLabel: string;
+    readonly lastColdDurationMs: number | null;
+    readonly lastRearmDurationMs: number | null;
+    readonly lastColdSteps: readonly ProcessCostStepTiming[];
+    readonly lastRearmSteps: readonly ProcessCostStepTiming[];
+    readonly blockedRitualCount: number;
+    readonly recoveryTierDistribution: Readonly<Record<string, number>>;
+}
+/**
+ * Roll up ceremony cost from `.deft-cache/events.jsonl` (#3508).
+ * Measures CLI process time, not agent-turn wall clock (#3500).
+ */
+export declare function computeCeremonyCostRollup(options: {
+    projectRoot: string;
+    logPath?: string | null;
+    windowMs?: number;
+    now?: Date;
+    windowLabel?: string;
+}): CeremonyCostRollup;
+/**
+ * Human rollup for the composed `value:show` reader (#3508).
+ * CLI process time, not agent-turn wall clock (#3500).
+ */
+export declare function formatCeremonyCostReport(rollup: CeremonyCostRollup): string;
+/**
+ * Operator-visible mutation `session:start` line (#3508).
+ * CLI process time only. ⊗ not #3286 Later graduation input.
+ */
+export declare function formatSessionStartCeremonyCostLine(ceremonyTier: ProcessCostCeremonyTier, durationMs: number): string;
 //# sourceMappingURL=process-cost.d.ts.map