@deftai/directive-core 0.104.0 → 0.106.0

package/dist/session/ac-pass-reuse.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Bank / same-session cache reuse for verify:ac and scope:complete (#3387).
+ *
+ * Green bank + matching product-state hash → accept without re-execution.
+ * Missing, stale, or mismatched hash → full walk. Empty/failing still refuse.
+ */
+import { type AcPassBankRecord } from "./ac-pass-banking.js";
+import { type HashProductStateInput } from "./product-state-hash.js";
+import { type CachedVerifyAcSnapshot, type VerifyAcSessionCacheRecord } from "./verify-ac-session-cache.js";
+export type { AcServedFrom } from "./verify-ac-session-cache.js";
+export type AcReuseDecision = {
+    readonly kind: "cache";
+    readonly servedFrom: "cache";
+    readonly hash: string;
+    readonly cache: VerifyAcSessionCacheRecord;
+} | {
+    readonly kind: "bank";
+    readonly servedFrom: "bank";
+    readonly hash: string;
+    readonly bank: AcPassBankRecord;
+} | {
+    readonly kind: "miss";
+    readonly servedFrom: "executed";
+    readonly hash: string | null;
+    readonly reason: string;
+};
+export interface ResolveAcReuseInput extends HashProductStateInput {
+    readonly scopeId?: string | null;
+    readonly sessionId?: string | null;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Default true. Complete walk uses bank; check uses cache then bank. */
+    readonly allowCache?: boolean;
+    readonly allowBank?: boolean;
+}
+export declare function resolveScopeIdForAcReuse(plan: Record<string, unknown>, explicit?: string | null): string | null;
+/**
+ * Decide whether a green bank or same-session cache can replace execution.
+ */
+export declare function resolveAcReuse(input: ResolveAcReuseInput): AcReuseDecision;
+export declare function snapshotFromReuseFields(input: {
+    readonly ok: boolean;
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly commands: readonly unknown[];
+    readonly runs: readonly unknown[];
+    readonly rejected?: readonly unknown[];
+    readonly sourceRung: string;
+    readonly noneStated: boolean;
+    readonly acceptance: unknown;
+    readonly resolution: string;
+    readonly resolvedCommandCount: number;
+}): CachedVerifyAcSnapshot;
+//# sourceMappingURL=ac-pass-reuse.d.ts.map

package/dist/session/ac-pass-reuse.js

@@ -0,0 +1,95 @@
+/**
+ * Bank / same-session cache reuse for verify:ac and scope:complete (#3387).
+ *
+ * Green bank + matching product-state hash → accept without re-execution.
+ * Missing, stale, or mismatched hash → full walk. Empty/failing still refuse.
+ */
+import { readAcPassBank } from "./ac-pass-banking.js";
+import { hashProductState } from "./product-state-hash.js";
+import { readVerifyAcSessionCache, resolveVerifyAcSessionId, } from "./verify-ac-session-cache.js";
+function isUsableBank(bank) {
+    if (bank.bankedAt === "1970-01-01T00:00:00Z")
+        return false;
+    const hash = bank.productStateHash;
+    return typeof hash === "string" && hash.length > 0;
+}
+export function resolveScopeIdForAcReuse(plan, explicit) {
+    const injected = explicit?.trim() ?? "";
+    if (injected.length > 0)
+        return injected;
+    if (typeof plan.id === "string" && plan.id.trim().length > 0) {
+        return plan.id.trim();
+    }
+    return null;
+}
+/**
+ * Decide whether a green bank or same-session cache can replace execution.
+ */
+export function resolveAcReuse(input) {
+    const allowCache = input.allowCache !== false;
+    const allowBank = input.allowBank !== false;
+    const scopeId = resolveScopeIdForAcReuse(input.plan, input.scopeId);
+    if (scopeId === null) {
+        return { kind: "miss", servedFrom: "executed", hash: null, reason: "no scope id" };
+    }
+    const hashed = hashProductState(input);
+    if (!hashed.complete) {
+        return {
+            kind: "miss",
+            servedFrom: "executed",
+            hash: hashed.digest,
+            reason: "incomplete product-state hash",
+        };
+    }
+    const sessionId = resolveVerifyAcSessionId(input.env, input.sessionId);
+    if (allowCache && sessionId !== null) {
+        const cache = readVerifyAcSessionCache(input.projectRoot, sessionId, scopeId);
+        if (cache !== null && cache.productStateHash === hashed.digest) {
+            return { kind: "cache", servedFrom: "cache", hash: hashed.digest, cache };
+        }
+    }
+    if (allowBank) {
+        const bank = readAcPassBank(input.projectRoot, scopeId);
+        if (bank !== null && isUsableBank(bank) && bank.productStateHash === hashed.digest) {
+            return { kind: "bank", servedFrom: "bank", hash: hashed.digest, bank };
+        }
+        if (bank !== null && !isUsableBank(bank)) {
+            return {
+                kind: "miss",
+                servedFrom: "executed",
+                hash: hashed.digest,
+                reason: "stale or incomplete bank",
+            };
+        }
+        if (bank !== null && bank.productStateHash !== hashed.digest) {
+            return {
+                kind: "miss",
+                servedFrom: "executed",
+                hash: hashed.digest,
+                reason: "product-state hash mismatch",
+            };
+        }
+    }
+    return {
+        kind: "miss",
+        servedFrom: "executed",
+        hash: hashed.digest,
+        reason: "no reusable result",
+    };
+}
+export function snapshotFromReuseFields(input) {
+    return {
+        ok: input.ok,
+        code: input.code,
+        message: input.message,
+        commands: input.commands,
+        runs: input.runs,
+        rejected: input.rejected,
+        sourceRung: input.sourceRung,
+        noneStated: input.noneStated,
+        acceptance: input.acceptance,
+        resolution: input.resolution,
+        resolvedCommandCount: input.resolvedCommandCount,
+    };
+}
+//# sourceMappingURL=ac-pass-reuse.js.map

package/dist/session/git.js

@@ -1,13 +1,28 @@
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
+function coerceGitBytes(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (typeof value === "string")
+        return Buffer.from(value, "utf8");
+    return Buffer.alloc(0);
+}
+/** `-z` porcelain is byte-oriented; UTF-8 would turn invalid names into U+FFFD. */
+function gitStdoutString(raw, args) {
+    if (args.includes("-z"))
+        return raw.toString("latin1");
+    const utf8 = raw.toString("utf8");
+    if (Buffer.from(utf8, "utf8").equals(raw))
+        return utf8.trimEnd();
+    return raw.toString("latin1").trimEnd();
+}
 export const defaultGitRunner = (projectRoot, args) => {
     try {
         const stdout = execFileSync("git", [...args], {
             cwd: projectRoot,
-            encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
         });
-        return { code: 0, stdout: stdout.trimEnd(), stderr: "" };
+        return { code: 0, stdout: gitStdoutString(coerceGitBytes(stdout), args), stderr: "" };
     }
     catch (err) {
         const e = err;
@@ -16,8 +31,8 @@ export const defaultGitRunner = (projectRoot, args) => {
         }
         return {
             code: typeof e.status === "number" ? e.status : 2,
-            stdout: typeof e.stdout === "string" ? e.stdout.trimEnd() : "",
-            stderr: typeof e.stderr === "string" ? e.stderr.trimEnd() : "",
+            stdout: gitStdoutString(coerceGitBytes(e.stdout), args),
+            stderr: coerceGitBytes(e.stderr).toString("utf8").trimEnd(),
         };
     }
 };

package/dist/session/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./ac-pass-banking.js";
+export * from "./ac-pass-reuse.js";
 export * from "./active-cli.js";
 export * from "./ceremony-dial-evidence.js";
 export * from "./compact-ritual.js";
@@ -6,11 +7,13 @@ export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./occupancy.js";
 export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./orientation-compression.js";
 export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
+export * from "./product-state-hash.js";
 export * from "./resume-conditions.js";
 export * from "./ritual-sentinel.js";
 export * from "./session-ready.js";
@@ -18,5 +21,6 @@ export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
 export * from "./toolchain-preflight.js";
+export * from "./verify-ac-session-cache.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/session/index.js

@@ -1,4 +1,5 @@
 export * from "./ac-pass-banking.js";
+export * from "./ac-pass-reuse.js";
 export * from "./active-cli.js";
 export * from "./ceremony-dial-evidence.js";
 export * from "./compact-ritual.js";
@@ -6,11 +7,13 @@ export * from "./deposit-sha.js";
 export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./occupancy.js";
 export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./orientation-compression.js";
 export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
+export * from "./product-state-hash.js";
 export * from "./resume-conditions.js";
 export * from "./ritual-sentinel.js";
 export * from "./session-ready.js";
@@ -18,5 +21,6 @@ export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
 export * from "./toolchain-preflight.js";
+export * from "./verify-ac-session-cache.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.js.map

package/dist/session/occupancy-stress-worker.d.ts

@@ -0,0 +1,7 @@
+export declare function runOccupancyStressRounds(input: {
+    readonly root: string;
+    readonly logPath: string;
+    readonly sessionId: string;
+    readonly rounds: number;
+}): void;
+//# sourceMappingURL=occupancy-stress-worker.d.ts.map

package/dist/session/occupancy-stress-worker.js

@@ -0,0 +1,36 @@
+import { basename } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { applyWorktreeOccupancy, releaseOccupancy } from "./occupancy.js";
+export function runOccupancyStressRounds(input) {
+    for (let i = 0; i < input.rounds; i += 1) {
+        const claimed = applyWorktreeOccupancy(input.root, {
+            sessionId: input.sessionId,
+            now: new Date(),
+        });
+        if (claimed.code !== 0)
+            continue;
+        containedWrite({
+            root: input.root,
+            target: basename(input.logPath),
+            data: `ENTER ${input.sessionId}\n`,
+            mode: "append",
+        });
+        containedWrite({
+            root: input.root,
+            target: basename(input.logPath),
+            data: `LEAVE ${input.sessionId}\n`,
+            mode: "append",
+        });
+        releaseOccupancy(input.root, { sessionId: input.sessionId, now: new Date() });
+    }
+}
+const root = process.env.OCCUPANCY_STRESS_ROOT ?? "";
+if (root.length > 0) {
+    runOccupancyStressRounds({
+        root,
+        logPath: process.env.OCCUPANCY_STRESS_LOG ?? "",
+        sessionId: process.env.OCCUPANCY_STRESS_SESSION ?? "",
+        rounds: Number(process.env.OCCUPANCY_STRESS_ROUNDS ?? "0"),
+    });
+}
+//# sourceMappingURL=occupancy-stress-worker.js.map

package/dist/session/occupancy.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 { type LockDeps } from "../slice/lock.js";
+export declare const OCCUPANCY_SCHEMA_VERSION = 1;
+export declare const OCCUPANCY_RELPATH: readonly [".deft", "occupancy.json"];
+/** Crash recovery TTL: 20 minutes without heartbeat (15–30 window). */
+export declare const OCCUPANCY_TTL_MS: number;
+export declare const OCCUPANCY_INTENTS: readonly ["mutation", "swarm", "review"];
+export type OccupancyIntent = (typeof OCCUPANCY_INTENTS)[number];
+export declare const OCCUPANCY_JOIN_PROTOCOLS: readonly ["none", "heartbeat-file", "parent-message"];
+export type OccupancyJoinProtocol = (typeof OCCUPANCY_JOIN_PROTOCOLS)[number];
+export interface OccupancyRecord {
+    readonly schemaVersion: number;
+    readonly sessionId: string;
+    readonly worktreePath: string;
+    readonly intent: OccupancyIntent;
+    readonly claimedAt: Date;
+    readonly heartbeatAt: Date;
+    readonly host: string;
+    readonly address: string;
+    readonly retainCapable: boolean;
+    readonly joinProtocol: OccupancyJoinProtocol;
+    readonly raw: Record<string, unknown>;
+}
+export type OccupancyAction = "claimed" | "heartbeat" | "stolen" | "denied" | "released";
+export interface OccupancyDecision {
+    readonly action: OccupancyAction;
+    readonly sessionId: string;
+    readonly record: OccupancyRecord | null;
+    readonly path: string;
+    readonly message: string;
+    readonly code: number;
+}
+export interface ApplyOccupancyInput {
+    readonly sessionId?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly intent?: OccupancyIntent;
+    readonly newSessionId?: () => string;
+    readonly steal?: boolean;
+    readonly confirm?: boolean;
+    readonly occupant?: string;
+    readonly host?: string;
+    readonly address?: string;
+    readonly retainCapable?: boolean;
+    readonly joinProtocol?: OccupancyJoinProtocol;
+    /** When false, evaluate only (no write). Steal still writes. */
+    readonly write?: boolean;
+    /** Test seam for lock wait / timeout. */
+    readonly lockDeps?: LockDeps;
+}
+export declare function occupancyPath(projectRoot: string): string;
+export declare function heartbeatAgeSeconds(record: OccupancyRecord, now?: Date): number;
+export declare function isOccupancyExpired(record: OccupancyRecord, now?: Date, ttlMs?: number): boolean;
+export declare function formatOccupancyRemediation(record: OccupancyRecord, now?: Date): string;
+export declare function resolveOccupancySessionId(input?: ApplyOccupancyInput): string;
+export declare function readOccupancy(projectRoot: string): OccupancyRecord | null;
+export declare function liveOccupant(projectRoot: string, now?: Date, ttlMs?: number): OccupancyRecord | null;
+export declare function applyWorktreeOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
+export declare function stealOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
+export declare function releaseOccupancy(projectRoot: string, input?: {
+    readonly sessionId?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly swarmCloseout?: boolean;
+    readonly lockDeps?: LockDeps;
+}): OccupancyDecision;
+export declare function evaluateOccupancyWriteGate(projectRoot: string, input?: {
+    readonly sessionId?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+}): {
+    allow: boolean;
+    message: string | null;
+    occupant: OccupancyRecord | null;
+};
+/** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
+export declare function releaseSwarmOccupancy(projectRoot: string, input?: {
+    readonly sessionId?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly lockDeps?: LockDeps;
+}): OccupancyDecision;
+export declare function runOccupancySteal(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
+//# sourceMappingURL=occupancy.d.ts.map