@deftai/directive-core 0.104.0 → 0.105.0

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

@@ -12,9 +12,10 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { DEFAULT_SURPLUS_THRESHOLD, resolveAcPassBanking, } from "../policy/ac-pass-banking.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { detectHardEffortBudget, formatDeepeningSkippedNote, recommendVerificationDepth, } from "./effort-budget.js";
 /** Durable bank ledger directory (gitignored under `.deft/`). */
 export const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
@@ -320,6 +321,7 @@ export function bankAcPass(input) {
         scopeId: input.scopeId,
         bankedAt,
         headSha: input.headSha ?? null,
+        productStateHash: input.productStateHash ?? prior?.productStateHash ?? null,
         remainingTurns: input.budget.remainingTurns,
         remainingBudget: input.budget.remainingBudget,
         maxTurns: input.budget.maxTurns,
@@ -358,25 +360,31 @@ export function bankAcPass(input) {
             durablePath = tmpPath;
         }
     }
-    appendBankEventToRunSummary({
-        environ: input.environ ?? process.env,
-        event: {
-            type: "ac_pass_bank",
-            schemaVersion: AC_PASS_BANK_SCHEMA_VERSION,
-            scopeId: record.scopeId,
-            bankedAt: record.bankedAt,
-            nextAction: record.nextAction,
-            hadSurplus: record.hadSurplus,
-            surplusThreshold: record.surplusThreshold,
-            remainingFraction: input.surplus.remainingFraction,
-            remainingTurns: record.remainingTurns,
-            remainingBudget: record.remainingBudget,
-            maxTurns: record.maxTurns,
-            maxBudget: record.maxBudget,
-            headSha: record.headSha,
+    try {
+        const env = { ...(input.environ ?? process.env) };
+        const emitter = new RunSummaryEmitter({
+            projectRoot: root,
+            env,
+            component: "ac-pass-banking",
+        });
+        emitter.emitAcPassBank({
+            scope_id: record.scopeId,
+            banked_at: record.bankedAt,
+            next_action: record.nextAction,
+            had_surplus: record.hadSurplus,
+            surplus_threshold: record.surplusThreshold,
+            remaining_fraction: input.surplus.remainingFraction,
+            remaining_turns: record.remainingTurns,
+            remaining_budget: record.remainingBudget,
+            max_turns: record.maxTurns,
+            max_budget: record.maxBudget,
+            head_sha: record.headSha,
             path: durablePath,
-        },
-    });
+        });
+    }
+    catch {
+        // fail-open
+    }
     return record;
 }
 /**
@@ -487,6 +495,7 @@ function recoveredStubRecord(scopeId, findings) {
         // valid primary ledger (#3285 Greptile residual).
         bankedAt: "1970-01-01T00:00:00Z",
         headSha: null,
+        productStateHash: null,
         remainingTurns: null,
         remainingBudget: null,
         maxTurns: null,
@@ -616,63 +625,6 @@ export function recordPostBankFinding(projectRoot, scopeId, finding) {
     }
     return updated;
 }
-/**
- * Format one JSONL bank-event line for run-summary telemetry (#3285 / #3282).
- */
-export function formatBankEventLine(event) {
-    return JSON.stringify({
-        ...event,
-        ts: typeof event.bankedAt === "string" ? event.bankedAt : utcIso(),
-        source: "ac-pass-banking",
-        issue: 3285,
-    });
-}
-/**
- * Append bank event to DEFT_RUN_SUMMARY_PATH when set.
- * Unset = silent. `-` = stdout. Failures warn once to stderr (fail-open).
- */
-export function appendBankEventToRunSummary(input) {
-    const environ = input.environ ?? process.env;
-    const raw = (environ[ENV_RUN_SUMMARY_PATH] ?? "").trim();
-    if (!raw) {
-        return { written: false, path: null };
-    }
-    const line = `${formatBankEventLine(input.event)}\n`;
-    if (raw === "-") {
-        process.stdout.write(line);
-        return { written: true, path: "-" };
-    }
-    try {
-        if (input.writeLine) {
-            input.writeLine(raw, line);
-        }
-        else {
-            const abs = resolve(raw);
-            const parent = dirname(abs);
-            if (!existsSync(parent)) {
-                mkdirSync(parent, { recursive: true });
-            }
-            // Contain under the parent directory of the summary file.
-            containedWrite({
-                root: parent,
-                target: abs,
-                data: line,
-                mode: "append",
-            });
-        }
-        return { written: true, path: raw };
-    }
-    catch (err) {
-        const msg = err instanceof ContainedWriteError
-            ? err.message
-            : err instanceof Error
-                ? err.message
-                : String(err);
-        const warn = input.warn ?? ((m) => process.stderr.write(`${m}\n`));
-        warn(`[deft ac-pass-banking] run-summary write failed path=${raw}: ${msg} (#3285)`);
-        return { written: false, path: raw };
-    }
-}
 /**
  * Simulated run used by the surplus-insufficient acceptance test (#3285):
  * AC passes → bank → extra checks would exceed budget → ship + report finding.
@@ -748,6 +700,7 @@ export function maybeBankOnAcPass(input) {
         surplus: decision.surplus,
         nextAction,
         headSha: input.headSha ?? null,
+        productStateHash: input.productStateHash ?? null,
         now: input.now,
         environ: input.environ,
     });

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