@deftai/directive-core 0.103.0 → 0.105.0

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/ceremony-dial-evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Consumer-environment evidence for ceremony-dial escalation (#3358).
+ *
+ * Session:start left `taskSize` and `modelTier` null unless CLI flags or
+ * provisional env/verb/file hints were set. Consumer runs then always
+ * declined with "insufficient evidence (size=- modelTier=-)".
+ *
+ * This module fills at least one input the consumer environment can supply:
+ *   1. stamped #3323 clause count on active/pending briefs (size proxy)
+ *   2. host-supplied model-tier env (`DEFT_HOST_MODEL_TIER` and aliases)
+ *   3. failing-gate count env (mid-session size proxy)
+ *
+ * ⊗ Change the rapid default or decline threshold when no evidence exists.
+ * Explicit CLI / session inputs still win at the merge site.
+ */
+import { type CeremonyDialInputs, type CeremonyModelTier, type CeremonyTaskSize } from "../policy/ceremony-dial.js";
+/** Host-supplied model-tier hint when `DEFT_CEREMONY_MODEL_TIER` is unset. */
+export declare const ENV_HOST_MODEL_TIER = "DEFT_HOST_MODEL_TIER";
+/** Mid-session failing-gate count the consumer/harness can supply. */
+export declare const ENV_FAILING_GATE_COUNT = "DEFT_FAILING_GATE_COUNT";
+export interface CeremonyDialConsumerEvidence {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+    readonly clauseCount: number | null;
+    readonly failingGateCount: number | null;
+    readonly reasons: readonly string[];
+}
+export declare function taskSizeFromClauseCount(count: number): CeremonyTaskSize | null;
+export declare function taskSizeFromFailingGateCount(count: number): CeremonyTaskSize | null;
+/** Max stamped clause count across `xbrief/{active,pending}` (#3323). */
+export declare function readStampedClauseCount(projectRoot: string): {
+    readonly count: number;
+    readonly source: string;
+} | null;
+export declare function collectCeremonyDialConsumerEvidence(projectRoot: string, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+}): CeremonyDialConsumerEvidence;
+/** Explicit non-null wins; consumer evidence fills only missing fields. */
+export declare function mergeCeremonyDialInputsWithConsumerEvidence(explicit: CeremonyDialInputs | undefined, evidence: CeremonyDialConsumerEvidence): CeremonyDialInputs;
+export declare function formatCeremonyDialEvidenceLine(evidence: CeremonyDialConsumerEvidence): string | null;
+export declare function ceremonyDialEvidenceToDict(evidence: CeremonyDialConsumerEvidence): Record<string, unknown>;
+//# sourceMappingURL=ceremony-dial-evidence.d.ts.map

package/dist/session/ceremony-dial-evidence.js

@@ -0,0 +1,194 @@
+/**
+ * Consumer-environment evidence for ceremony-dial escalation (#3358).
+ *
+ * Session:start left `taskSize` and `modelTier` null unless CLI flags or
+ * provisional env/verb/file hints were set. Consumer runs then always
+ * declined with "insufficient evidence (size=- modelTier=-)".
+ *
+ * This module fills at least one input the consumer environment can supply:
+ *   1. stamped #3323 clause count on active/pending briefs (size proxy)
+ *   2. host-supplied model-tier env (`DEFT_HOST_MODEL_TIER` and aliases)
+ *   3. failing-gate count env (mid-session size proxy)
+ *
+ * ⊗ Change the rapid default or decline threshold when no evidence exists.
+ * Explicit CLI / session inputs still win at the merge site.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENV_CEREMONY_MODEL_HINT, ENV_CEREMONY_MODEL_TIER, normalizeCeremonyModelTier, } from "../policy/ceremony-dial.js";
+/** Host-supplied model-tier hint when `DEFT_CEREMONY_MODEL_TIER` is unset. */
+export const ENV_HOST_MODEL_TIER = "DEFT_HOST_MODEL_TIER";
+/** Mid-session failing-gate count the consumer/harness can supply. */
+export const ENV_FAILING_GATE_COUNT = "DEFT_FAILING_GATE_COUNT";
+const LIFECYCLE_DIRS = ["active", "pending"];
+export function taskSizeFromClauseCount(count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return null;
+    if (count === 1)
+        return "S";
+    if (count <= 3)
+        return "M";
+    if (count <= 6)
+        return "L";
+    return "XL";
+}
+export function taskSizeFromFailingGateCount(count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return null;
+    if (count <= 2)
+        return "M";
+    return "L";
+}
+function rankSize(size) {
+    switch (size) {
+        case "S":
+            return 0;
+        case "M":
+            return 1;
+        case "L":
+            return 2;
+        case "XL":
+            return 3;
+    }
+}
+function maxSize(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return rankSize(a) >= rankSize(b) ? a : b;
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function clauseCountFromBrief(raw) {
+    const root = asRecord(raw);
+    const plan = asRecord(root?.plan);
+    const acceptance = asRecord(plan?.acceptance);
+    if (acceptance === null)
+        return null;
+    if (Array.isArray(acceptance.clauses) && acceptance.clauses.length > 0) {
+        return acceptance.clauses.length;
+    }
+    const stamped = acceptance.clause_count;
+    if (typeof stamped === "number" && Number.isFinite(stamped) && stamped > 0) {
+        return stamped;
+    }
+    return null;
+}
+function parseNonNegativeInt(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+        return Math.trunc(raw);
+    }
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return Math.trunc(n);
+}
+/** Max stamped clause count across `xbrief/{active,pending}` (#3323). */
+export function readStampedClauseCount(projectRoot) {
+    let best = null;
+    for (const dir of LIFECYCLE_DIRS) {
+        const folder = join(projectRoot, "xbrief", dir);
+        if (!existsSync(folder))
+            continue;
+        let names = [];
+        try {
+            names = readdirSync(folder);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".xbrief.json") || name === "PROJECT-DEFINITION.xbrief.json") {
+                continue;
+            }
+            const path = join(folder, name);
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                const count = clauseCountFromBrief(parsed);
+                if (count === null)
+                    continue;
+                if (best === null || count > best.count) {
+                    best = { count, source: `xbrief/${dir}/${name}` };
+                }
+            }
+            catch {
+                // fail-open — a malformed brief is not an evidence source
+            }
+        }
+    }
+    return best;
+}
+export function collectCeremonyDialConsumerEvidence(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const reasons = [];
+    const stamped = readStampedClauseCount(projectRoot);
+    const clauseCount = stamped?.count ?? null;
+    let taskSize = null;
+    if (stamped !== null) {
+        const fromClauses = taskSizeFromClauseCount(stamped.count);
+        if (fromClauses !== null) {
+            taskSize = fromClauses;
+            reasons.push(`taskSize=${fromClauses} from stamped clauseCount=${stamped.count} (${stamped.source})`);
+        }
+    }
+    const failingGateCount = parseNonNegativeInt(env[ENV_FAILING_GATE_COUNT]);
+    if (failingGateCount !== null) {
+        const fromGates = taskSizeFromFailingGateCount(failingGateCount);
+        if (fromGates !== null) {
+            const next = maxSize(taskSize, fromGates);
+            if (next !== taskSize) {
+                taskSize = next;
+                reasons.push(`taskSize=${next} from failingGateCount=${failingGateCount}`);
+            }
+            else if (taskSize === fromGates) {
+                reasons.push(`failingGateCount=${failingGateCount} (size already ${taskSize})`);
+            }
+        }
+    }
+    const modelTier = normalizeCeremonyModelTier(env[ENV_CEREMONY_MODEL_TIER]) ??
+        normalizeCeremonyModelTier(env[ENV_CEREMONY_MODEL_HINT]) ??
+        normalizeCeremonyModelTier(env[ENV_HOST_MODEL_TIER]);
+    if (modelTier !== null) {
+        reasons.push(`modelTier=${modelTier} from host env`);
+    }
+    return {
+        taskSize,
+        modelTier,
+        clauseCount,
+        failingGateCount,
+        reasons,
+    };
+}
+/** Explicit non-null wins; consumer evidence fills only missing fields. */
+export function mergeCeremonyDialInputsWithConsumerEvidence(explicit, evidence) {
+    return {
+        taskSize: explicit?.taskSize ?? evidence.taskSize ?? null,
+        modelTier: explicit?.modelTier ?? evidence.modelTier ?? null,
+        projectShape: explicit?.projectShape ?? null,
+    };
+}
+export function formatCeremonyDialEvidenceLine(evidence) {
+    if (evidence.reasons.length === 0)
+        return null;
+    return `[deft ceremony-dial] evidence: ${evidence.reasons.join("; ")}`;
+}
+export function ceremonyDialEvidenceToDict(evidence) {
+    return {
+        taskSize: evidence.taskSize,
+        modelTier: evidence.modelTier,
+        clauseCount: evidence.clauseCount,
+        failingGateCount: evidence.failingGateCount,
+        reasons: [...evidence.reasons],
+    };
+}
+//# sourceMappingURL=ceremony-dial-evidence.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,15 +1,19 @@
 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";
 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";
@@ -17,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,15 +1,19 @@
 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";
 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";
@@ -17,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