@deftai/directive-core 0.106.0 → 0.107.0

package/dist/scope/decompose.js

@@ -17,6 +17,7 @@ import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveL
 import { resolveRepo } from "../triage/queue/repo.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { READY_REQUIRES_PARALLEL_SAFE } from "../vbrief-validation/story-quality.js";
 import { formatCoverageReportLine, validateCoverageMap } from "./coverage-map.js";
 import { buildParentLineageArtifact } from "./parent-lineage.js";
 import { formatBriefJson } from "./vbrief-json.js";
@@ -407,7 +408,7 @@ export function storyQualityIssues(opts) {
         issues.push(...fileScopeIssues(swarm));
         issues.push(...verifyCommandIssues(swarm));
         if (swarm.parallel_safe === false) {
-            issues.push("readiness=ready requires parallel_safe=true; use readiness=sequential or needs_refinement for non-concurrent work");
+            issues.push(READY_REQUIRES_PARALLEL_SAFE);
         }
         if (swarm.file_scope_confidence === "low") {
             issues.push("readiness=ready requires file_scope_confidence above low");

package/dist/scope/delivery-evidence.d.ts

@@ -16,6 +16,29 @@ export declare const NON_DELIVERY_DISPOSITIONS: readonly ["cancelled", "supersed
 export type NonDeliveryDisposition = (typeof NON_DELIVERY_DISPOSITIONS)[number];
 /** Delivery verification outcome for completion provenance. */
 export type DeliveryDisposition = "delivered" | "merged_to_integration" | "not_delivered" | NonDeliveryDisposition | "unknown" | "unverified";
+/**
+ * This is a historical audit snapshot stamped onto
+ * `plan.metadata.completionProvenance` at `scope:complete` (#3041 / #3690).
+ *
+ * Completed xBRIEFs have full standing as a record of *what is* and zero
+ * authority over *what to build next* (#3383). Fields stay because they
+ * answer a later reconstruction question after branches are deleted and
+ * refs move. A field does not need a current production-code reader.
+ *
+ * Reconstruction groups:
+ * - Identity and location: `repository`, `implementationCommit`, `prNumber`,
+ *   `prBase`, `deliveryBranch`
+ * - Delivery evidence: `mergeCommit`, `deliveryCommit`, `disposition`,
+ *   `handoffState`
+ * - Verification attribution: `verifiedAt`, `verifier`
+ * - Explicit operator-supplied facts: `deployed`, `uatVerified` (never
+ *   inferred from Git)
+ *
+ * `completedSessionId` is duplicated. This nested copy is stamped so the
+ * snapshot is self-contained. Consumers (`verify:ac` /
+ * `session-completed-ac`) read the sibling
+ * `plan.metadata.completedSessionId`, not this field.
+ */
 export interface CompletionProvenance {
     readonly repository: string | null;
     readonly implementationCommit: string | null;
@@ -32,7 +55,10 @@ export interface CompletionProvenance {
     readonly deployed: boolean | null;
     /** Always null unless explicitly supplied — never inferred from Git (#3041). */
     readonly uatVerified: boolean | null;
-    /** Session that completed the brief; used by check to target xbrief/completed (#3357). */
+    /**
+     * Nested session correlation for a self-contained snapshot.
+     * Consumers read sibling `plan.metadata.completedSessionId`, not this field.
+     */
     readonly completedSessionId?: string | null;
 }
 export interface DeliveryEvidenceInput {

package/dist/scope/index.d.ts

@@ -8,6 +8,7 @@ export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
+export * from "./lifecycle-write.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";

package/dist/scope/index.js

@@ -8,6 +8,7 @@ export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
+export * from "./lifecycle-write.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";

package/dist/scope/lifecycle-write.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Transition-write fingerprint for completed/ artifacts (#3679).
+ *
+ * Distinct from completionProvenance (#3686): this only records that
+ * runTransition wrote the blob. Non-code-bearing completes and scope:fail
+ * stamp this and still omit delivery provenance.
+ */
+export declare const LIFECYCLE_WRITE_KEY: "lifecycleWrite";
+export type LifecycleWriteAction = "complete" | "fail";
+export interface LifecycleWriteStamp {
+    readonly action: LifecycleWriteAction;
+    readonly writtenAt: string;
+}
+/** Worker-facing leftover-land path after a scope-provenance strip (#3476 / #3679). */
+export declare const LEFTOVER_LAND_PR_REMEDIATION: string;
+/** Stamp that runTransition wrote this plan into completed/. */
+export declare function stampLifecycleWrite(plan: Record<string, unknown>, action: LifecycleWriteAction, writtenAt: string): void;
+/**
+ * True when a completed/ blob shows verb evidence.
+ * Accepts the new stamp, legacy completedAt (pre-#3679 complete), or failed status
+ * (scope:fail never stamped provenance and must keep passing).
+ */
+export declare function hasTransitionWrite(plan: Record<string, unknown>): boolean;
+//# sourceMappingURL=lifecycle-write.d.ts.map

package/dist/scope/lifecycle-write.js

@@ -0,0 +1,64 @@
+/**
+ * Transition-write fingerprint for completed/ artifacts (#3679).
+ *
+ * Distinct from completionProvenance (#3686): this only records that
+ * runTransition wrote the blob. Non-code-bearing completes and scope:fail
+ * stamp this and still omit delivery provenance.
+ */
+export const LIFECYCLE_WRITE_KEY = "lifecycleWrite";
+/** Worker-facing leftover-land path after a scope-provenance strip (#3476 / #3679). */
+export const LEFTOVER_LAND_PR_REMEDIATION = "After a provenance-gated product PR strips active/ from the change set, " +
+    "the designed remainder is a leftover land PR (#3476): run `task scope:complete` " +
+    "after merge (it can stamp a brief already in completed/), then land that artifact. " +
+    "Do not git-add a completed/ husk to skip the verb.";
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function metadataRecord(plan) {
+    const existing = asRecord(plan.metadata);
+    if (existing !== null) {
+        return existing;
+    }
+    const created = {};
+    plan.metadata = created;
+    return created;
+}
+/** Stamp that runTransition wrote this plan into completed/. */
+export function stampLifecycleWrite(plan, action, writtenAt) {
+    const meta = metadataRecord(plan);
+    meta[LIFECYCLE_WRITE_KEY] = { action, writtenAt };
+}
+function hasLifecycleWriteStamp(plan) {
+    const meta = asRecord(plan.metadata);
+    if (meta === null) {
+        return false;
+    }
+    const stamp = asRecord(meta[LIFECYCLE_WRITE_KEY]);
+    if (stamp === null) {
+        return false;
+    }
+    const action = stamp.action;
+    const writtenAt = stamp.writtenAt;
+    return ((action === "complete" || action === "fail") &&
+        typeof writtenAt === "string" &&
+        writtenAt.trim().length > 0);
+}
+/**
+ * True when a completed/ blob shows verb evidence.
+ * Accepts the new stamp, legacy completedAt (pre-#3679 complete), or failed status
+ * (scope:fail never stamped provenance and must keep passing).
+ */
+export function hasTransitionWrite(plan) {
+    if (hasLifecycleWriteStamp(plan)) {
+        return true;
+    }
+    const meta = asRecord(plan.metadata);
+    if (meta !== null && typeof meta.completedAt === "string" && meta.completedAt.trim().length > 0) {
+        return true;
+    }
+    return String(plan.status ?? "") === "failed";
+}
+//# sourceMappingURL=lifecycle-write.js.map

package/dist/scope/main.js

@@ -17,10 +17,12 @@ import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoO
 const LIFECYCLE_USAGE_STDERR = "usage: deft scope:<action> [file] [--batch] [--from-issue N] [--repo OWNER/NAME]\n" +
     "                          [--force] [--project-root PATH] [--strict] [--force-no-cache]\n" +
     "                          [--path PATH]\n" +
+    "  complete also accepts: --merge-commit SHA --pr N [--pr-base BRANCH] [--delivery-branch BRANCH]\n" +
     "  actions: activate, block, cancel, complete, fail, promote, restore, unblock\n" +
     "The verb already encodes the action (e.g. deft scope:promote <file>). Do not pass the action again.\n" +
     "(promote --batch may omit file and promotes all proposed/ scopes; #3011)\n" +
-    "(promote --from-issue=N may omit file; #1136)\n";
+    "(promote --from-issue=N may omit file; #1136)\n" +
+    "(complete --merge-commit / --pr are required for code-bearing delivery evidence; #3041 / #3721)\n";
 function parseLifecycleArgv(argv) {
     if (argv.length < 1) {
         return { args: null, error: "usage" };

package/dist/scope/transition.js

@@ -16,6 +16,7 @@ import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRAN
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
 import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, resolveCompletionSessionId, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { evaluateEffortActivateGate } from "./effort-activate-gate.js";
+import { stampLifecycleWrite } from "./lifecycle-write.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { utcNowIso } from "./vbrief-json.js";
@@ -81,7 +82,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         };
     }
     const { allowedSources, targetFolder, targetStatus } = TRANSITIONS[act];
-    if (!allowedSources.includes(currentFolder)) {
+    const restampCompleted = act === "complete" && currentFolder === "completed";
+    if (!restampCompleted &&
+        !allowedSources.includes(currentFolder)) {
         const allowedStr = allowedSources.map((s) => `${s}/`).join(", ");
         return {
             ok: false,
@@ -103,15 +106,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
     const requiredStatus = STATUS_PRECONDITIONS[act];
     if (requiredStatus !== undefined) {
         if (currentStatus === targetStatus) {
-            // Surface legacy delivery disposition on already-completed briefs (#3041).
-            let dispositionSuffix = "";
-            if (act === "complete" && currentFolder === "completed") {
-                const disposition = classifyStoredDeliveryDisposition(planObj);
-                dispositionSuffix = ` (deliveryDisposition=${disposition})`;
-            }
             return {
                 ok: true,
-                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/${dispositionSuffix}`,
+                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/`,
             };
         }
         if (currentStatus !== requiredStatus) {
@@ -122,14 +119,30 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
     }
+    const nowIso = utcNowIso(now);
+    const vbriefRoot = dirname(dirname(resolvedPath));
+    const projectRoot = dirname(vbriefRoot);
+    // #3679: lift #3041 already-completed handling out of STATUS_PRECONDITIONS
+    // so complete can stamp a brief already in completed/ without a folder trip.
+    if (restampCompleted) {
+        return restampCompletedBrief({
+            resolvedPath,
+            basename,
+            data,
+            planObj,
+            projectRoot,
+            vbriefRoot,
+            now,
+            nowIso,
+            options,
+        });
+    }
     if (targetFolder !== null && targetFolder === currentFolder) {
         return {
             ok: true,
             message: `No-op: ${basename} is already in ${currentFolder}/ (status: ${currentStatus})`,
         };
     }
-    const vbriefRoot = dirname(dirname(resolvedPath));
-    const projectRoot = dirname(vbriefRoot);
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
         try {
@@ -144,7 +157,6 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             throw err;
         }
     }
-    const nowIso = utcNowIso(now);
     // #3360: hand-authored briefs run #3323 clause derivation on activate/promote.
     // #3355: stamp is state-observed (before vs after), not derivation-notice-bound.
     const previousAcceptance = planObj.acceptance;
@@ -190,6 +202,7 @@ export function runTransition(action, filePath, now = new Date(), options = {})
                 ? { ...gate.provenance, completedSessionId: sessionId }
                 : gate.provenance);
         }
+        stampLifecycleWrite(planObj, "complete", nowIso);
     }
     // #3240: per-criterion typed evidence or human-origin disposition before auto-advance.
     let acceptanceReports;
@@ -266,6 +279,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
     }
+    if (act === "fail") {
+        stampLifecycleWrite(planObj, "fail", nowIso);
+    }
     const formatted = formatBriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
     if (targetFolder !== null) {
@@ -370,6 +386,69 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         acceptanceReports,
     };
 }
+/**
+ * Stamp a brief already in completed/ (#3679). Runs the #3041 delivery gate
+ * and writes in place so recovery does not need a folder round-trip.
+ * The #3041 deliveryDisposition suffix now actually executes for complete.
+ */
+function restampCompletedBrief(args) {
+    const { resolvedPath, basename, data, planObj, projectRoot, vbriefRoot, now, nowIso, options } = args;
+    const gate = evaluateDeliveryGate({
+        projectRoot,
+        plan: planObj,
+        nowIso,
+        evidence: options.deliveryEvidence,
+        nonDeliveryDisposition: options.nonDeliveryDisposition,
+        runGit: options.runGit,
+        verifier: options.verifier ?? "scope:complete",
+        assumeEvidenceValidated: options.assumeEvidenceValidated,
+    });
+    if (!gate.ok) {
+        return { ok: false, message: gate.message };
+    }
+    if (gate.provenance !== null) {
+        const sessionId = resolveCompletionSessionId(projectRoot);
+        stampDeliveryProvenance(planObj, sessionId !== null ? { ...gate.provenance, completedSessionId: sessionId } : gate.provenance);
+    }
+    planObj.status = "completed";
+    planObj.updated = nowIso;
+    stampEnvelopeUpdated(data, nowIso);
+    stampCompletionMetadata(planObj, projectRoot, nowIso, {
+        completedSessionId: resolveCompletionSessionId(projectRoot),
+    });
+    stampLifecycleWrite(planObj, "complete", nowIso);
+    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot, { projectRoot });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.message };
+    }
+    const crud = new InstrumentedVbriefCrud({ now: () => now });
+    crud.recordTrustedUpdate(resolvedPath, formatBriefJson(data));
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
+    const sessionId = resolveCompletionSessionId(projectRoot);
+    if (sessionId !== null) {
+        try {
+            writeSessionCompletedMarker(projectRoot, {
+                path: resolvedPath,
+                sessionId,
+                completedAt: nowIso,
+            });
+        }
+        catch {
+            return { ok: false, message: SESSION_COMPLETED_AC_REMEDIATION };
+        }
+    }
+    const disposition = classifyStoredDeliveryDisposition(planObj);
+    return {
+        ok: true,
+        message: `Restamped ${basename} in completed/ (status: completed, ` +
+            `deliveryDisposition=${disposition})`,
+    };
+}
 export function recordWipCapOverride(filePath, projectRoot, check, now = new Date()) {
     try {
         const rel = resolve(filePath).startsWith(resolve(projectRoot))

package/dist/scope-provenance/evaluate.js

@@ -209,7 +209,11 @@ function remediationForExpansion() {
         "`.deft/approved-scope/<plan-id>.json` with a humanApproval stamp). Commit that " +
         "approval on the merge base (or a prior PR) before expanding or activating the " +
         "scoped xBRIEF in the implementation change set. Editing the active xBRIEF alone " +
-        "does not authorize new paths (#3145 / #3205). See content/docs/scope-provenance.md.");
+        "does not authorize new paths (#3145 / #3205). See content/docs/scope-provenance.md. " +
+        "If you cannot mint a digest (human TTY required), drop active/ from this product " +
+        "change set and land the completed artifact in a leftover land PR after merge (#3476). " +
+        "Run `task scope:complete` on the brief (it can stamp a file already in completed/). " +
+        "Do not git-add a completed/ husk to skip that PR (#3679).");
 }
 /**
  * Parse + lightly validate an approved-scope JSON blob (base-ref `git show` or disk).

package/dist/session/git.d.ts

@@ -12,5 +12,23 @@ export declare function gitHead(projectRoot: string, runGit?: GitRunner): {
 export declare function worktreePath(projectRoot: string, runGit?: GitRunner): string;
 /** True when `ancestor` is reachable from `descendant` (same commit counts). */
 export declare function gitIsAncestor(projectRoot: string, ancestor: string, descendant: string, runGit?: GitRunner): boolean | null;
+/**
+ * Ceiling for one `git cat-file --batch` payload. The directive terminal
+ * corpus is ~8 MiB today; this leaves headroom without reintroducing
+ * per-blob `git show` on a truncated read.
+ */
+export declare const GIT_CAT_FILE_BATCH_MAX_BUFFER: number;
+/**
+ * Parse `git cat-file --batch` stdout for `paths.length` objects, in the
+ * same order the names were written to stdin. Returns null if the stream
+ * is truncated or a header is malformed so callers can fall back.
+ */
+export declare function parseGitCatFileBatch(stdout: Buffer, paths: readonly string[]): Map<string, string | null> | null;
+/**
+ * Read many `tip:path` blobs in one `git cat-file --batch` process.
+ * Falls back to per-path `git show` only when the batch stream cannot be
+ * parsed, so verdicts stay content-authoritative.
+ */
+export declare function showBlobsBatch(projectRoot: string, tip: string, paths: readonly string[], runGit?: GitRunner): Map<string, string | null>;
 export declare function detectBranch(projectRoot: string, runGit?: GitRunner): string | null;
 //# sourceMappingURL=git.d.ts.map

package/dist/session/git.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 function coerceGitBytes(value) {
     if (Buffer.isBuffer(value))
@@ -64,6 +64,86 @@ export function gitIsAncestor(projectRoot, ancestor, descendant, runGit = defaul
     }
     return null;
 }
+/**
+ * Ceiling for one `git cat-file --batch` payload. The directive terminal
+ * corpus is ~8 MiB today; this leaves headroom without reintroducing
+ * per-blob `git show` on a truncated read.
+ */
+export const GIT_CAT_FILE_BATCH_MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Parse `git cat-file --batch` stdout for `paths.length` objects, in the
+ * same order the names were written to stdin. Returns null if the stream
+ * is truncated or a header is malformed so callers can fall back.
+ */
+export function parseGitCatFileBatch(stdout, paths) {
+    const out = new Map();
+    let offset = 0;
+    for (const path of paths) {
+        const nl = stdout.indexOf(0x0a, offset);
+        if (nl < 0) {
+            return null;
+        }
+        const header = stdout.subarray(offset, nl).toString("utf8");
+        offset = nl + 1;
+        if (header.endsWith(" missing") || header.endsWith(" ambiguous")) {
+            out.set(path, null);
+            continue;
+        }
+        const match = /^[0-9a-fA-F]+ \S+ (\d+)$/.exec(header);
+        if (match === null) {
+            return null;
+        }
+        const size = Number(match[1]);
+        if (!Number.isInteger(size) || size < 0 || offset + size > stdout.length) {
+            return null;
+        }
+        const content = stdout.subarray(offset, offset + size);
+        offset += size;
+        if (offset < stdout.length && stdout[offset] === 0x0a) {
+            offset += 1;
+        }
+        else if (offset !== stdout.length) {
+            return null;
+        }
+        out.set(path, content.toString("utf8"));
+    }
+    return out;
+}
+function showBlobViaRunner(projectRoot, tip, path, runGit) {
+    const result = runGit(projectRoot, ["show", `${tip}:${path}`]);
+    if (result.code !== 0) {
+        return null;
+    }
+    return result.stdout;
+}
+/**
+ * Read many `tip:path` blobs in one `git cat-file --batch` process.
+ * Falls back to per-path `git show` only when the batch stream cannot be
+ * parsed, so verdicts stay content-authoritative.
+ */
+export function showBlobsBatch(projectRoot, tip, paths, runGit = defaultGitRunner) {
+    const out = new Map();
+    if (paths.length === 0) {
+        return out;
+    }
+    const input = Buffer.from(`${paths.map((path) => `${tip}:${path}`).join("\n")}\n`, "utf8");
+    const result = spawnSync("git", ["cat-file", "--batch"], {
+        cwd: projectRoot,
+        input,
+        maxBuffer: GIT_CAT_FILE_BATCH_MAX_BUFFER,
+        windowsHide: true,
+    });
+    if (result.error === undefined && result.status === 0 && result.stdout !== undefined) {
+        const parsed = parseGitCatFileBatch(coerceGitBytes(result.stdout), paths);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    for (const path of paths) {
+        out.set(path, showBlobViaRunner(projectRoot, tip, path, runGit));
+    }
+    return out;
+}
 export function detectBranch(projectRoot, runGit = defaultGitRunner) {
     const sym = runGit(projectRoot, ["symbolic-ref", "--short", "HEAD"]);
     if (sym.code === 0 && sym.stdout.trim()) {

package/dist/session/occupancy.d.ts

@@ -3,7 +3,8 @@
  *
  * 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.
+ * ritual-state.json. Ordinary end is occupancy:release / session:end (#3604).
+ * Join negotiation (`occupancy:request`) is out of scope.
  *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.

package/dist/session/occupancy.js

@@ -3,7 +3,8 @@
  *
  * 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.
+ * ritual-state.json. Ordinary end is occupancy:release / session:end (#3604).
+ * Join negotiation (`occupancy:request`) is out of scope.
  *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.
@@ -35,11 +36,16 @@ export function heartbeatAgeSeconds(record, now = new Date()) {
 export function isOccupancyExpired(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
     return now.getTime() - record.heartbeatAt.getTime() > ttlMs;
 }
+function occupancyClockLine(record) {
+    return `claimed_at=${timestampIso(record.claimedAt)} heartbeat_at=${timestampIso(record.heartbeatAt)}`;
+}
 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` +
+    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
+        `${occupancyClockLine(record)}).\n` +
         "Stay read-only (`session:start --read-only`), use another worktree,\n" +
-        "queue a join (`occupancy:request`), or steal (`occupancy:steal --confirm`).");
+        "queue a join (`occupancy:request`), or steal (`occupancy:steal --confirm`).\n" +
+        "The occupant may release (`occupancy:release` / `session:end`).");
 }
 export function resolveOccupancySessionId(input = {}) {
     const explicit = input.sessionId?.trim();
@@ -194,6 +200,7 @@ export function stealOccupancy(projectRoot, input = {}) {
             };
         }
         const incoming = resolveOccupancySessionId(input);
+        const priorClock = existingLocked !== null ? ` (${occupancyClockLine(existingLocked)})` : "";
         const record = writeOccupancyRecord(projectRoot, {
             sessionId: incoming,
             worktreePath: resolve(projectRoot),
@@ -210,7 +217,7 @@ export function stealOccupancy(projectRoot, input = {}) {
             sessionId: record.sessionId,
             record,
             path,
-            message: `occupancy stolen from ${named}; writer is now session ${record.sessionId}`,
+            message: `occupancy stolen from ${named}${priorClock}; writer is now session ${record.sessionId}`,
             code: 0,
         };
     }, input.lockDeps);

package/dist/session/session-start.d.ts

@@ -24,8 +24,20 @@ export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
 export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
 export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome", "verify_tools"];
+/** Session / full gated ritual set. Write dispatch uses a per-surface subset (#3738). */
 export declare const GATED_STEPS: readonly ["agent_hooks", "doctor", "cache_fresh"];
 export type GatedStepName = (typeof GATED_STEPS)[number];
+/**
+ * Gated steps a write/spawn mutation must prove from recorded ritual state (#3738).
+ * `cache_fresh` is a work-selection precondition, not a write-authorization one.
+ */
+export declare const WRITE_GATED_REQUIRED_STEPS: readonly ["agent_hooks", "doctor"];
+/**
+ * Gated steps the write path may execute (#3738).
+ * Hook readiness is deliberately non-cacheable; doctor and cache_fresh stay
+ * session-surface only.
+ */
+export declare const WRITE_GATED_EXECUTE_STEPS: readonly ["agent_hooks"];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export declare const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */

package/dist/session/session-start.js

@@ -50,7 +50,24 @@ export const QUICK_STEPS = [
     "triage_welcome",
     "verify_tools",
 ];
+/** Session / full gated ritual set. Write dispatch uses a per-surface subset (#3738). */
 export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
+/**
+ * Gated steps a write/spawn mutation must prove from recorded ritual state (#3738).
+ * `cache_fresh` is a work-selection precondition, not a write-authorization one.
+ */
+export const WRITE_GATED_REQUIRED_STEPS = [
+    "agent_hooks",
+    "doctor",
+];
+/**
+ * Gated steps the write path may execute (#3738).
+ * Hook readiness is deliberately non-cacheable; doctor and cache_fresh stay
+ * session-surface only.
+ */
+export const WRITE_GATED_EXECUTE_STEPS = [
+    "agent_hooks",
+];
 /** Per-clone ignore/index hide of lifecycle roots — warn-only (#3505). */
 function pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit) {
     try {

package/dist/session/verify-session-ritual.d.ts

@@ -1,8 +1,9 @@
 import { type ActiveCliCheckResult, type ActiveCliCheckSeams } from "./active-cli.js";
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
-import { type GatedStepName, type SessionCeremonyTier } from "./session-start.js";
+import { type GatedStepName, type SessionCeremonyTier, WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS } from "./session-start.js";
 export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
+export { WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS };
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<GatedStepName, readonly string[]>>;
@@ -81,7 +82,24 @@ export interface VerifySessionRitualOptions {
     readonly checkActiveCli?: (targetVersion: string | null, seams?: ActiveCliCheckSeams) => ActiveCliCheckResult;
     /** Injectable work-selection detector for gated `cache_fresh` (#3507). */
     readonly detectWorkSelection?: DetectWorkSelection;
+    /**
+     * Required gated steps for this surface. Defaults to all {@link GATED_STEPS}
+     * (session / full gated verify). Write dispatch uses
+     * {@link WRITE_GATED_REQUIRED_STEPS} (#3738).
+     */
+    readonly requiredGatedSteps?: readonly GatedStepName[];
+    /**
+     * Gated steps this surface may execute. Defaults to all {@link GATED_STEPS}.
+     * Write dispatch uses {@link WRITE_GATED_EXECUTE_STEPS} so `cache_fresh` and
+     * `doctor` cannot run as write-path repair (#3738).
+     */
+    readonly executeGatedSteps?: readonly GatedStepName[];
 }
+/**
+ * Options for the write/spawn mutation verifier (#3738).
+ * Required set omits `cache_fresh`; execution authority is `agent_hooks` only.
+ */
+export declare function writeGateRitualOptions(extras?: Omit<VerifySessionRitualOptions, "requiredGatedSteps" | "executeGatedSteps" | "tier">): VerifySessionRitualOptions;
 export interface InspectSessionRitualOptions {
     readonly tier?: "quick" | "gated";
     readonly now?: Date;
@@ -94,8 +112,9 @@ export interface InspectSessionRitualOptions {
  * Read-only ritual-state inspection for host hooks.
  *
  * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
- * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
- * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ * and never rewrites `.deft/ritual-state.json`. Write dispatch does **not** use
+ * this function: it must still execute `agent_hooks` (#3738). A PreToolUse
+ * decision must not become a hidden `doctor` / cache-refresh mutation boundary.
  */
 export declare function inspectSessionRitual(projectRoot: string, options?: InspectSessionRitualOptions): VerifyResult;
 export declare function verifySessionRitual(projectRoot: string, options?: VerifySessionRitualOptions): VerifyResult;