nawabari 0.3.0 → 0.5.0

package/dist/session-registry.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, observeGitCheckpoint, observeGitMutationPaths, readBoundedGitDiff, readCanonicalCommitChangedPaths, readGitPathStats, readCurrentHead, resolveRepositoryContext, verifyPhysicalExecutionContext, } from "./git.js";
+import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, observeGitCheckpoint, observeGitMutationPaths, readBoundedGitDiff, readCanonicalCommitChangedPaths, readChangedPathNames, readGitPathStats, readCurrentHead, readTreePathStates, resolveRepositoryContext, treeEntriesEqual, verifyPhysicalExecutionContext, } from "./git.js";
 import { SessionRegistryError } from "./errors.js";
 import { generateSessionId, isSessionId } from "./session-id.js";
+import { isPostRenameFailure, writeJsonAtomicallySync } from "./registry/atomic.js";
 import { RegistryLockError, RepositoryLock } from "./registry/lock.js";
 import { assertCanonicalClaimResource, canonicalClaimId, canonicalizeClaimInput, canonicalizeConcretePath, claimError, claimsConflict, claimsOverlap, cloneResourceClaim, compareCodePointStrings, createResourceClaim, isResourceClaimMode, LEGACY_RESOURCE_CLAIM_SCHEMA_VERSION, resourceClaimConflictsWithAccess, resourceMatchesClaim, RESOURCE_CLAIM_SCHEMA_VERSION, sortResourceClaims, } from "./resource-claims.js";
 import { CHECKPOINT_EVIDENCE_SCHEMA_VERSION, CHECKPOINT_MAX_PATHS, OPERATION_AUTHORIZATION_SCHEMA_VERSION, claimModeGrantsAccess, isOperationName, requiredAccessForOperation, } from "./operation-authorization.js";
@@ -16,9 +17,13 @@ export const REGISTRY_LOCK_FILE_NAME = "session-registry.lock";
 export const DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1_000;
 export const CLEANUP_DECISION_SCHEMA_VERSION = 1;
 export const RECONCILIATION_SCHEMA_VERSION = 1;
+export const SESSION_DIAGNOSTIC_SCHEMA_VERSION = 1;
 const DEFAULT_LOCK_METADATA_GRACE_MS = 1_000;
 /** Bounds a caller-declared commit-message pattern before it is compiled. */
 export const MAX_MESSAGE_PATTERN_LENGTH = 512;
+function isCloseSessionOptions(value) {
+    return typeof value === "object" && value !== null;
+}
 export { CHECKPOINT_EVIDENCE_SCHEMA_VERSION, CHECKPOINT_MAX_PATHS, OPERATION_AUTHORIZATION_SCHEMA_VERSION, OPERATION_REQUIRED_ACCESS, OPERATION_VOCABULARY, } from "./operation-authorization.js";
 export const GOVERNED_GIT_OPERATION_SCHEMA_VERSION = 1;
 const ACTIVE_STATES = new Set(["new", "active", "closing", "stale"]);
@@ -166,7 +171,7 @@ export class SessionRegistry {
             const current = state.claims.filter((claim) => claim.sessionId === sessionId);
             const currentById = new Map(current.map((claim) => [claim.claimId, claim]));
             const timestamp = toTimestamp(this.clock());
-            const next = this.validateRequestedClaims(requested.map((input) => createResourceClaim(input, owner, timestamp)), owner, state.claims.filter((claim) => claim.sessionId !== sessionId));
+            const next = this.validateRequestedClaims(requested.map((input) => createResourceClaim(input, owner, timestamp)), owner, state.claims.filter((claim) => claim.sessionId !== sessionId), state.sessions);
             const nextIds = new Set(next.map((claim) => claim.claimId));
             const released = current.filter((claim) => !nextIds.has(claim.claimId));
             const added = next.filter((claim) => !currentById.has(claim.claimId));
@@ -312,13 +317,40 @@ export class SessionRegistry {
                 return cloneSessionRecord(record);
             }
             catch (error) {
-                if (gitProvisioned) {
+                if (gitProvisioned && this.absenceProvenAfterProvisioningFailure(error, sessionId)) {
                     rollbackProvisionedResources(this.git, this.repository.worktreePath, resources);
                 }
                 throw classifyProvisioningFailure(error, this.git, this.repository.worktreePath, resources);
             }
         });
     }
+    /**
+     * Decide whether it is safe to destroy the just-created worktree/branch
+     * after a provisioning failure. Only an ordinary (non-durability-uncertain)
+     * failure, or a durability-uncertain failure whose registry re-read
+     * positively proves the session record absent, licenses a rollback.
+     *
+     * A durability-uncertain write means the rename may have already
+     * committed this session as the registry's visible ownership record:
+     * rolling back the worktree/branch would then strand a registry entry
+     * pointing at resources we just deleted. Absence must be *proven*, not
+     * merely unconfirmed — if the reconciliation read itself cannot complete
+     * (I/O failure, corrupt registry state, or any other exception), that is
+     * not proof of absence, so no rollback happens and the original
+     * durability-uncertain outcome propagates unchanged.
+     */
+    absenceProvenAfterProvisioningFailure(error, sessionId) {
+        const durabilityUncertain = error instanceof SessionRegistryError && error.code === "REGISTRY_DURABILITY_UNCERTAIN";
+        if (!durabilityUncertain) {
+            return true;
+        }
+        try {
+            return !this.readUnsafe().some((candidate) => candidate.sessionId === sessionId);
+        }
+        catch {
+            return false;
+        }
+    }
     provisionSession(options = {}) {
         return this.provision(options);
     }
@@ -410,18 +442,46 @@ export class SessionRegistry {
                 git: this.git,
             });
         if (this.protectedWorktree(this.repository.worktreePath, physical.worktrees)) {
-            throw new SessionRegistryError("PROTECTED_WORKTREE", "The current worktree is protected", {
-                worktree: this.repository.worktreePath,
-            });
+            throw this.protectedExecutionContextError("PROTECTED_WORKTREE", "The current worktree is protected", { worktree: this.repository.worktreePath }, requestedSessionId);
         }
         if (this.protectedBranch(physical.branchName, physical.worktrees)) {
-            throw new SessionRegistryError("PROTECTED_BRANCH", "The current branch is protected", {
-                branch: physical.branchName,
-            });
+            throw this.protectedExecutionContextError("PROTECTED_BRANCH", "The current branch is protected", { branch: physical.branchName }, requestedSessionId);
         }
         const session = this.resolveSessionOwnership(physical, requestedSessionId);
         return Object.freeze({ ...physical, session: cloneSessionRecord(session) });
     }
+    /**
+     * Distinguish the current (protected) command execution context from the
+     * referenced/target session, so a caller does not have to separately
+     * re-discover where the operation should actually run. `phase: "execution"`
+     * marks this live-command rejection distinctly from the cleanup-time
+     * PROTECTED_WORKTREE/PROTECTED_BRANCH block, which `safeActionsForCode`
+     * and `recoveryHintsForCode` key on for a different, non-mutating safe
+     * action set.
+     */
+    protectedExecutionContextError(code, message, contextDetails, requestedSessionId) {
+        const target = requestedSessionId === null
+            ? undefined
+            : this.readUnsafe().find((record) => record.sessionId === requestedSessionId);
+        const details = {
+            ...contextDetails,
+            phase: "execution",
+            ...(requestedSessionId === null ? {} : { requestedSessionId }),
+            ...(target === undefined
+                ? {}
+                : {
+                    targetWorktree: target.worktreePath,
+                    targetBranch: target.branchName,
+                    targetState: target.state,
+                    ...(target.label === undefined ? {} : { targetLabel: target.label }),
+                }),
+        };
+        return new SessionRegistryError(code, message, {
+            ...details,
+            safeActions: [...safeActionsForCode(code, details)],
+            recoveryHints: recoveryHintsForCode(code, details),
+        });
+    }
     resolveSessionOwnership(physical, requestedSessionId) {
         const records = this.readUnsafe();
         const currentRecords = records.filter((record) => ACTIVE_STATES.has(record.state) && samePath(record.worktreeId, physical.worktreePath));
@@ -628,12 +688,11 @@ export class SessionRegistry {
                     const conflictingClaim = activeClaims.find((claim) => claim.sessionId !== currentRecord.sessionId &&
                         resourceClaimConflictsWithAccess(claim, resource, requiredAccess));
                     if (conflictingClaim !== undefined) {
+                        const conflictDetails = resourceClaimConflictDetails({ resource, mode: requiredAccess }, conflictingClaim, state.sessions);
                         return deniedOperation("RESOURCE_CLAIM_CONFLICT", verified, {
-                            resource,
-                            ownerSessionId: conflictingClaim.sessionId,
-                            ownerClaimId: conflictingClaim.claimId,
-                            ownerResource: conflictingClaim.resource,
-                            ownerMode: conflictingClaim.mode,
+                            ...conflictDetails,
+                            safeActions: [...safeActionsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails)],
+                            recoveryHints: recoveryHintsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails),
                         });
                     }
                     if (ownClaims.length > 0) {
@@ -1033,6 +1092,32 @@ export class SessionRegistry {
     assessCleanup(sessionIdOrOptions) {
         return this.cleanupDecision(sessionIdOrOptions);
     }
+    /**
+     * Side-effect-free close/cleanup readiness diagnostic for one session. This
+     * observes the exact same authoritative Git/session/claim truth `close()`
+     * uses (including the #123 non-ancestry integration proof contract when
+     * `integratedRevision` evidence is supplied) without mutating any session,
+     * claim, Git, or registry state.
+     */
+    diagnose(sessionIdOrOptions) {
+        return this.withLock(() => {
+            const state = this.readStateUnsafe();
+            const requestedSessionId = isCloseSessionOptions(sessionIdOrOptions)
+                ? (sessionIdOrOptions.sessionId ?? sessionIdOrOptions.session_id)
+                : sessionIdOrOptions;
+            const sessionId = requestedSessionId ?? this.resolveOwnerSession(state.sessions).sessionId;
+            assertSessionId(sessionId);
+            const record = state.sessions.find((candidate) => candidate.sessionId === sessionId);
+            if (record === undefined) {
+                throw new SessionRegistryError("SESSION_NOT_FOUND", `Session was not found: ${sessionId}`, { sessionId });
+            }
+            const integratedRevision = isCloseSessionOptions(sessionIdOrOptions)
+                ? (sessionIdOrOptions.integratedRevision ?? sessionIdOrOptions.integrated_revision ?? null)
+                : null;
+            const evidence = integratedRevision === null || integratedRevision === undefined ? undefined : { integratedRevision };
+            return this.diagnoseUnsafe(record, state, evidence);
+        });
+    }
     /**
      * Reconcile registry ownership with Git's physical worktree inventory.
      * This is deliberately diagnostic-only: no stale metadata is repaired and
@@ -1095,12 +1180,16 @@ export class SessionRegistry {
     /** Close one session only after its ownership and recoverability are proven safe. */
     close(sessionIdOrOptions) {
         return this.withLock(() => {
-            const sessionId = typeof sessionIdOrOptions === "object" && sessionIdOrOptions !== null
+            const sessionId = isCloseSessionOptions(sessionIdOrOptions)
                 ? (sessionIdOrOptions.sessionId ?? sessionIdOrOptions.session_id)
                 : sessionIdOrOptions;
             const selectedSessionId = sessionId ?? this.resolveCurrentSession().sessionId;
             assertSessionId(selectedSessionId);
-            return this.closeUnsafe(selectedSessionId);
+            const integratedRevision = isCloseSessionOptions(sessionIdOrOptions)
+                ? (sessionIdOrOptions.integratedRevision ?? sessionIdOrOptions.integrated_revision ?? null)
+                : null;
+            const evidence = integratedRevision === null || integratedRevision === undefined ? undefined : { integratedRevision };
+            return this.closeUnsafe(selectedSessionId, evidence);
         });
     }
     closeSession(sessionIdOrOptions) {
@@ -1254,7 +1343,7 @@ export class SessionRegistry {
         const candidates = requested.map((input) => createResourceClaim(input, owner, timestamp));
         const existing = state.claims.filter((claim) => claim.sessionId !== owner.sessionId);
         const current = state.claims.filter((claim) => claim.sessionId === owner.sessionId);
-        const added = this.validateRequestedClaims(candidates, owner, [...existing, ...current]);
+        const added = this.validateRequestedClaims(candidates, owner, [...existing, ...current], state.sessions);
         const nextClaims = sortResourceClaims([
             ...state.claims,
             ...added.filter((candidate) => !current.some((claim) => claim.claimId === candidate.claimId)),
@@ -1266,7 +1355,7 @@ export class SessionRegistry {
             added: added.filter((candidate) => !current.some((claim) => claim.claimId === candidate.claimId)),
         };
     }
-    validateRequestedClaims(candidates, owner, existing) {
+    validateRequestedClaims(candidates, owner, existing, sessions = []) {
         for (const candidate of candidates) {
             const exact = existing.find((claim) => claim.claimId === candidate.claimId);
             if (exact !== undefined) {
@@ -1299,21 +1388,19 @@ export class SessionRegistry {
                     });
                 }
                 if (claimsConflict(candidate, current)) {
+                    const conflictDetails = resourceClaimConflictDetails(candidate, current, sessions);
                     throw claimError("RESOURCE_CLAIM_CONFLICT", "Resource claim conflicts with an active session claim", {
                         claimId: candidate.claimId,
-                        resource: candidate.resource,
-                        mode: candidate.mode,
-                        ownerSessionId: current.sessionId,
-                        ownerClaimId: current.claimId,
-                        ownerResource: current.resource,
-                        ownerMode: current.mode,
+                        ...conflictDetails,
+                        safeActions: [...safeActionsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails)],
+                        recoveryHints: recoveryHintsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails),
                     });
                 }
             }
         }
         return candidates;
     }
-    closeUnsafe(sessionId) {
+    closeUnsafe(sessionId, evidence) {
         const state = this.readStateUnsafe();
         const records = state.sessions;
         const record = records.find((candidate) => candidate.sessionId === sessionId);
@@ -1330,15 +1417,22 @@ export class SessionRegistry {
                 idempotent: true,
             };
         }
-        const resources = this.inspectCleanupResources(record);
+        let resources;
+        try {
+            resources = this.inspectCleanupResources(record, undefined, evidence);
+        }
+        catch (error) {
+            throw enrichCloseBlockerError(error);
+        }
         const closingRecord = record.state === "closing" ? record : transitionSessionState(record, "closing", this.clock);
         let closingRecords = replaceRecord(records, closingRecord);
         validateRecords(closingRecords, this.repository.repositoryId);
         this.writeUnsafe(closingRecords, state.claims);
         let worktreeRemoved = false;
         let branchRemoved = false;
+        let integrationProof;
         if (resources.removeWorktree) {
-            const revalidated = this.inspectCleanupResources(record);
+            const revalidated = this.inspectCleanupResources(record, undefined, evidence);
             assertSameCleanupObservation(resources, revalidated, "worktree-remove");
             if (revalidated.removeWorktree) {
                 removeSessionWorktree(this.git, revalidated.gitCwd, record.worktreePath);
@@ -1349,13 +1443,18 @@ export class SessionRegistry {
         // no longer exist. Reobserve Git from the stable integration/peer cwd that
         // was selected during the authoritative preflight.
         const branchWorktrees = listGitWorktrees(this.git, resources.gitCwd);
-        const branchResources = this.inspectCleanupResources(record, branchWorktrees);
+        const branchResources = this.inspectCleanupResources(record, branchWorktrees, evidence);
         if (branchResources.branchPresent && branchResources.removeBranch) {
-            const branchRevalidated = this.inspectCleanupResources(record, listGitWorktrees(this.git, branchResources.gitCwd));
+            const branchRevalidated = this.inspectCleanupResources(record, listGitWorktrees(this.git, branchResources.gitCwd), evidence);
             assertSameCleanupObservation(branchResources, branchRevalidated, "branch-remove");
             if (branchRevalidated.branchPresent && branchRevalidated.removeBranch) {
-                removeSessionBranch(this.git, branchRevalidated.gitCwd, record.branchName);
+                // Git's own "-d" safety check is ancestry-only and cannot see a
+                // tree-equivalence proof. Force deletion is only ever selected after
+                // Nawabari has independently re-derived that proof itself.
+                const forceDelete = branchRevalidated.integrationProof?.method === "tree-equivalence";
+                removeSessionBranch(this.git, branchRevalidated.gitCwd, record.branchName, forceDelete);
                 branchRemoved = true;
+                integrationProof = branchRevalidated.integrationProof;
             }
         }
         const closedRecord = transitionSessionState(closingRecord, "closed", this.clock);
@@ -1367,9 +1466,10 @@ export class SessionRegistry {
             worktreeRemoved,
             branchRemoved,
             idempotent: false,
+            ...(integrationProof === undefined ? {} : { integrationProof }),
         };
     }
-    inspectCleanupResources(record, observedWorktrees = listGitWorktrees(this.git, this.repository.worktreePath)) {
+    inspectCleanupResources(record, observedWorktrees = listGitWorktrees(this.git, this.repository.worktreePath), evidence) {
         const git = this.git;
         const worktrees = observedWorktrees;
         const gitCwd = worktrees.find((worktree) => !worktree.prunable && !samePath(worktree.worktreePath, record.worktreePath))
@@ -1410,7 +1510,12 @@ export class SessionRegistry {
         assertNoRecoverableStashes(git, gitCwd, record.branchName);
         const worktreeProtection = this.protectedWorktree(record.worktreePath, worktrees);
         const branchProtection = this.protectedBranch(record.branchName, worktrees, gitCwd);
-        const removeBranch = branchPresent && !branchProtection && this.branchIsReachableFromIntegration(record, gitCwd);
+        let removeBranch = false;
+        let integrationProof;
+        if (branchPresent && !branchProtection) {
+            integrationProof = this.branchIsReachableFromIntegration(record, gitCwd, evidence);
+            removeBranch = true;
+        }
         return {
             gitCwd,
             physicalState: worktreeState.kind,
@@ -1421,6 +1526,7 @@ export class SessionRegistry {
             branchPresent,
             removeWorktree: registeredWorktree !== undefined && !worktreeProtection,
             removeBranch,
+            integrationProof,
         };
     }
     cleanupDecisionUnsafe(record, state) {
@@ -1451,6 +1557,80 @@ export class SessionRegistry {
             recoveryHints: Object.freeze(recoveryHints),
         });
     }
+    diagnoseUnsafe(record, state, evidence) {
+        const claims = state.claims.filter((claim) => claim.sessionId === record.sessionId).map(cloneResourceClaim);
+        // Used only to evaluate staleness below; deliberately not part of the
+        // returned diagnostic so repeated inspection of unchanged state is
+        // byte-identical, not just semantically equivalent.
+        const now = toTimestamp(this.clock());
+        const integrationEvidence = {
+            supplied: evidence !== undefined,
+            ...(evidence === undefined ? {} : { integratedRevision: evidence.integratedRevision }),
+        };
+        if (record.state === "closed") {
+            return Object.freeze({
+                schemaVersion: SESSION_DIAGNOSTIC_SCHEMA_VERSION,
+                operation: "diagnostic",
+                repositoryId: this.repository.repositoryId,
+                worktreePath: record.worktreePath,
+                branchName: record.branchName,
+                session: cloneSessionRecord(record),
+                claims: Object.freeze(claims),
+                physicalState: "closed",
+                closeReadiness: "ready",
+                cleanupReadiness: "ready",
+                resultState: "complete",
+                idempotent: true,
+                blockers: Object.freeze([]),
+                safeActions: Object.freeze([]),
+                integrationEvidence: Object.freeze(integrationEvidence),
+            });
+        }
+        let physicalState = "unavailable";
+        let blockers = [];
+        let integrationProof;
+        let staleCandidate = false;
+        try {
+            const worktrees = listGitWorktrees(this.git, this.repository.worktreePath);
+            physicalState = inspectWorktreeState(record.worktreePath, worktrees).kind;
+            staleCandidate = isStaleCandidate(record, now, this.staleAfterMs, worktrees);
+            const resources = this.inspectCleanupResources(record, worktrees, evidence);
+            integrationProof = resources.integrationProof;
+        }
+        catch (error) {
+            blockers = [toDiagnosticBlocker(error)];
+        }
+        const closeReadiness = closeReadinessForBlockers(blockers);
+        const cleanupReadiness = closeReadiness !== "ready" ? closeReadiness : staleCandidate ? "ready" : "not_due";
+        const resultState = resultStateForDiagnostic(closeReadiness, blockers);
+        const safeActions = blockers.length > 0
+            ? sortStrings(Array.from(new Set(blockers.flatMap((blocker) => blocker.safeActions))))
+            : closeReadiness === "ready"
+                ? cleanupReadiness === "ready"
+                    ? ["close-session", "run-garbage-collect"]
+                    : ["close-session"]
+                : [];
+        return Object.freeze({
+            schemaVersion: SESSION_DIAGNOSTIC_SCHEMA_VERSION,
+            operation: "diagnostic",
+            repositoryId: this.repository.repositoryId,
+            worktreePath: record.worktreePath,
+            branchName: record.branchName,
+            session: cloneSessionRecord(record),
+            claims: Object.freeze(claims),
+            physicalState,
+            closeReadiness,
+            cleanupReadiness,
+            resultState,
+            idempotent: false,
+            blockers: Object.freeze(blockers),
+            safeActions: Object.freeze(safeActions),
+            integrationEvidence: Object.freeze({
+                ...integrationEvidence,
+                ...(integrationProof === undefined ? {} : { proof: integrationProof }),
+            }),
+        });
+    }
     assertCleanupAllowed(record, state) {
         const decision = this.cleanupDecisionUnsafe(record, state);
         if (decision.allowed)
@@ -1538,7 +1718,15 @@ export class SessionRegistry {
         ];
         return protectedBranchIds.includes(normalizeBranchId(branchName));
     }
-    branchIsReachableFromIntegration(record, gitCwd = this.repository.worktreePath) {
+    /**
+     * Prove a session branch is safe to reclaim. Ordinary ancestry is the
+     * cheap/default path. When ancestry fails, a caller may supply bounded
+     * non-ancestry integration evidence (e.g. a squash/rebase-merge commit);
+     * Nawabari never trusts that assertion blindly and instead independently
+     * re-derives a deterministic, byte-exact Git tree-object equivalence proof
+     * before treating the branch as safely integrated.
+     */
+    branchIsReachableFromIntegration(record, gitCwd = this.repository.worktreePath, evidence) {
         const git = this.git;
         const worktrees = listGitWorktrees(git, gitCwd);
         const defaultBranchName = resolveDefaultBranchName(git, gitCwd, worktrees, this.defaultBranchName);
@@ -1546,27 +1734,79 @@ export class SessionRegistry {
             throw new SessionRegistryError("RECOVERABLE_COMMITS", `Cannot prove that commits on ${record.branchName} are safely retained: no integration branch is known`, { branch: record.branchName, recoveryHints: recoveryHintsForCode("RECOVERABLE_COMMITS") });
         }
         if (normalizeBranchId(defaultBranchName) === record.branchId)
-            return true;
+            return { method: "ancestor" };
         try {
             git.run(["merge-base", "--is-ancestor", record.branchId, normalizeBranchId(defaultBranchName)], gitCwd);
-            return true;
+            return { method: "ancestor" };
         }
         catch (error) {
-            if (isExpectedGitLookupFailure(error)) {
-                throw new SessionRegistryError("RECOVERABLE_COMMITS", `Commits on ${record.branchName} are not proven reachable from ${defaultBranchName}`, {
+            if (!isExpectedGitLookupFailure(error))
+                throw error;
+            if (evidence !== undefined) {
+                const proof = this.proveNonAncestryIntegration(record, gitCwd, defaultBranchName, evidence);
+                if (proof !== undefined)
+                    return proof;
+                throw new SessionRegistryError("RECOVERABLE_COMMITS", `Commits on ${record.branchName} could not be proven integrated via the supplied non-ancestry evidence`, {
                     branch: record.branchName,
                     integrationBranch: defaultBranchName,
+                    proofMethod: "tree-equivalence",
+                    proofResult: "unproven",
+                    integratedRevision: evidence.integratedRevision,
                     recoveryHints: recoveryHintsForCode("RECOVERABLE_COMMITS"),
                 }, error);
             }
+            throw new SessionRegistryError("RECOVERABLE_COMMITS", `Commits on ${record.branchName} are not proven reachable from ${defaultBranchName}`, {
+                branch: record.branchName,
+                integrationBranch: defaultBranchName,
+                proofMethod: "ancestry",
+                proofResult: "unproven",
+                recoveryHints: recoveryHintsForCode("RECOVERABLE_COMMITS"),
+            }, error);
+        }
+    }
+    /**
+     * Independently verify caller-supplied non-ancestry integration evidence.
+     * The caller's assertion only selects which revision to compare; the
+     * proof itself is re-derived from local Git truth. For every path the
+     * session branch touched relative to its own base, the exact tree-object
+     * identity (file mode, object type, and content-addressed blob/tree SHA)
+     * at the branch head must match the same path's identity at the supplied
+     * integrated revision — both absent, or byte-identical. Blob SHAs are
+     * content hashes, so this can never mistake a whitespace-only or other
+     * textual difference for equivalence the way a patch/diff comparison
+     * could; it is exact Git tree semantics, not textual normalization.
+     * Returns undefined, never false, so a missing proof always falls through
+     * to a fail-closed RECOVERABLE_COMMITS at the call site.
+     */
+    proveNonAncestryIntegration(record, gitCwd, defaultBranchName, evidence) {
+        const git = this.git;
+        const integratedRevision = resolveBaseRef(git, gitCwd, evidence.integratedRevision).revision;
+        let branchBase;
+        try {
+            branchBase = git.run(["merge-base", record.branchId, normalizeBranchId(defaultBranchName)], gitCwd);
+        }
+        catch (error) {
+            if (isExpectedGitLookupFailure(error))
+                return undefined;
             throw error;
         }
+        const changedPaths = readChangedPathNames(git, gitCwd, branchBase, record.branchId);
+        if (changedPaths.length === 0)
+            return undefined;
+        const branchStates = readTreePathStates(git, gitCwd, record.branchId, changedPaths);
+        const integratedStates = readTreePathStates(git, gitCwd, integratedRevision, changedPaths);
+        const proven = changedPaths.every((changedPath) => treeEntriesEqual(branchStates.get(changedPath), integratedStates.get(changedPath)));
+        return proven ? { method: "tree-equivalence", integratedRevision } : undefined;
     }
     resolveProvisioningResources(options, sessionId) {
         const git = this.git;
         const worktrees = listGitWorktrees(git, this.repository.worktreePath);
-        const requestedWorktreePath = resolveProvisionedWorktreePath(options.worktreePath ??
-            path.join(this.worktreeRoot, `${path.basename(this.repository.worktreePath)}-${sessionId}`), this.worktreeRoot);
+        const effectiveRoot = options.worktreePath !== undefined
+            ? this.worktreeRoot
+            : options.worktreeRoot !== undefined
+                ? resolveManagedWorktreeRoot(options.worktreeRoot)
+                : this.worktreeRoot;
+        const requestedWorktreePath = resolveProvisionedWorktreePath(options.worktreePath ?? path.join(effectiveRoot, `${path.basename(this.repository.worktreePath)}-${sessionId}`), effectiveRoot);
         const defaultWorktreePath = worktrees.find((worktree) => !worktree.prunable)?.worktreePath ?? this.repository.worktreePath;
         const configuredProtectedWorktrees = [
             ...this.protectedWorktreePaths,
@@ -1643,6 +1883,15 @@ export class SessionRegistry {
     readUnsafe() {
         return this.readStateUnsafe().sessions;
     }
+    /**
+     * The single authoritative persistence path for session/claim registry
+     * state, sharing its durability policy with `registry/atomic.ts`: the
+     * temporary file and target directory are fsynced around an atomic
+     * rename, and only known unsupported-directory-fsync conditions are
+     * tolerated. A failure observed after rename is reported as a distinct
+     * durability-uncertain outcome rather than an ordinary write failure,
+     * since the renamed document may already be the one readers observe.
+     */
     writeUnsafe(records, claims) {
         const registry = {
             schema_version: REGISTRY_SCHEMA_VERSION,
@@ -1651,24 +1900,19 @@ export class SessionRegistry {
             claims_schema_version: RESOURCE_CLAIM_SCHEMA_VERSION,
             claims: sortResourceClaims(claims).map((claim) => toPersistedResourceClaim(claim, this.repository.repositoryId)),
         };
-        const contents = `${JSON.stringify(registry, null, 2)}\n`;
-        const temporaryPath = `${this.paths.registry}.tmp-${process.pid}-${generateSessionId()}`;
-        let descriptor;
         try {
-            fs.mkdirSync(this.paths.directory, { recursive: true, mode: 0o700 });
-            descriptor = fs.openSync(temporaryPath, "wx", 0o600);
-            fs.writeFileSync(descriptor, contents, "utf8");
-            fs.fsyncSync(descriptor);
-            fs.closeSync(descriptor);
-            descriptor = undefined;
-            fs.renameSync(temporaryPath, this.paths.registry);
-            syncDirectory(this.paths.directory);
+            writeJsonAtomicallySync(this.paths.registry, registry);
         }
         catch (error) {
-            if (descriptor !== undefined) {
-                closeQuietly(descriptor);
+            if (isPostRenameFailure(error)) {
+                throw new SessionRegistryError("REGISTRY_DURABILITY_UNCERTAIN", `Registry rename to ${this.paths.registry} may have already committed, but durable persistence could not be proven`, {
+                    path: this.paths.registry,
+                    recoveryHints: [
+                        "Re-read the registry to check whether the mutation is already visible before retrying.",
+                        "Do not assume this operation did not happen.",
+                    ],
+                }, error);
             }
-            unlinkQuietly(temporaryPath);
             throw new SessionRegistryError("REGISTRY_IO_FAILURE", `Could not atomically write ${this.paths.registry}`, {
                 path: this.paths.registry,
             }, error);
@@ -1763,6 +2007,32 @@ function inspectWorktreeState(worktreePath, worktrees) {
 function replaceRecord(records, replacement) {
     return records.map((record) => (record.sessionId === replacement.sessionId ? replacement : record));
 }
+/**
+ * Bounded, deterministic RESOURCE_CLAIM_CONFLICT evidence: the blocking
+ * session's canonical identity plus the exact conflicting claim/overlap.
+ * Every RESOURCE_CLAIM_CONFLICT throw site builds its details through this
+ * one function so a caller never has to run a second repository-wide scan
+ * just to identify the owner.
+ */
+function resourceClaimConflictDetails(requested, owner, sessions) {
+    const ownerSession = sessions.find((record) => record.sessionId === owner.sessionId);
+    return {
+        resource: requested.resource,
+        mode: requested.mode,
+        ownerSessionId: owner.sessionId,
+        ownerClaimId: owner.claimId,
+        ownerResource: owner.resource,
+        ownerMode: owner.mode,
+        ...(ownerSession === undefined
+            ? {}
+            : {
+                ownerWorktree: ownerSession.worktreePath,
+                ownerBranch: ownerSession.branchName,
+                ownerState: ownerSession.state,
+                ...(ownerSession.label === undefined ? {} : { ownerLabel: ownerSession.label }),
+            }),
+    };
+}
 function transitionSessionState(record, state, clock) {
     const clockTimestamp = toTimestamp(clock());
     const updatedAt = new Date(Math.max(Date.parse(record.updatedAt), Date.parse(clockTimestamp))).toISOString();
@@ -1777,14 +2047,17 @@ function ownershipMismatch(record, message, details = {}) {
         ...(details.recoveryHints === undefined ? { recoveryHints: recoveryHintsForCode("OWNERSHIP_MISMATCH") } : {}),
     });
 }
-function recoveryHintsForCode(code) {
+function recoveryHintsForCode(code, details = {}) {
     switch (code) {
         case "DIRTY_WORKTREE":
             return ["Preserve, commit, or explicitly recover tracked and untracked changes, then retry cleanup."];
         case "NESTED_REPOSITORY":
             return ["Inspect and explicitly preserve or remove the nested repository before retrying cleanup."];
         case "RECOVERABLE_COMMITS":
-            return ["Retain or merge the session branch commits into an authoritative local branch before retrying cleanup."];
+            return [
+                "Retain or merge the session branch commits into an authoritative local branch before retrying cleanup.",
+                "If the branch was integrated via squash/rebase merge, retry close with an --integrated-revision proof instead.",
+            ];
         case "RECOVERABLE_STASHES":
             return ["Inspect and explicitly apply, export, or drop the session stash before retrying cleanup."];
         case "MISSING_WORKTREE":
@@ -1796,7 +2069,17 @@ function recoveryHintsForCode(code) {
             return ["Restore a stable, observable Git/worktree state and rerun reconciliation before cleanup."];
         case "PROTECTED_WORKTREE":
         case "PROTECTED_BRANCH":
-            return ["Use the owner of the protected integration resource; do not delete it as a session resource."];
+            return details.phase === "execution"
+                ? [
+                    "Run this command from the managed session worktree it targets, or pass --session to select it explicitly.",
+                    "Use `session list` or `status` to find the managed worktree for the intended session.",
+                ]
+                : ["Use the owner of the protected integration resource; do not delete it as a session resource."];
+        case "RESOURCE_CLAIM_CONFLICT":
+            return [
+                "Inspect the blocking session's conflicting claim, then either wait for its release or coordinate with its owner.",
+                "Do not force-release another session's claim; claim release is scoped to the owning session only.",
+            ];
         case "STALE_REGISTRY":
             return ["Reconcile the lifecycle record under the repository mutation lock before retrying cleanup."];
         default:
@@ -1817,6 +2100,117 @@ function toCleanupBlocker(error) {
         recoveryHints: Object.freeze(recoveryHints),
     });
 }
+function toDiagnosticBlocker(error) {
+    const blocker = toCleanupBlocker(error);
+    return Object.freeze({
+        ...blocker,
+        safeActions: Object.freeze(safeActionsForCode(blocker.code, blocker.details)),
+    });
+}
+/**
+ * Stable, kebab-case next-action identifiers per blocker code. This is the
+ * one place that maps a registry blocker to actionable next steps, so a
+ * later actionable-error surface (e.g. for RESOURCE_CLAIM_CONFLICT) can
+ * extend the same table instead of diverging from it.
+ */
+function safeActionsForCode(code, details) {
+    switch (code) {
+        case "DIRTY_WORKTREE":
+            return ["commit-or-discard-changes", "retain-session"];
+        case "NESTED_REPOSITORY":
+            return ["resolve-nested-repository", "retain-session"];
+        case "RECOVERABLE_COMMITS":
+            return details.proofMethod === "tree-equivalence"
+                ? ["retain-session", "supply-different-integrated-revision"]
+                : ["provide-integration-evidence", "merge-or-retain-branch", "retain-session"];
+        case "RECOVERABLE_STASHES":
+            return ["apply-or-export-stash", "retain-session"];
+        case "MISSING_WORKTREE":
+            return ["run-garbage-collect"];
+        case "OWNERSHIP_MISMATCH":
+        case "DUPLICATE_WORKTREE_OWNERSHIP":
+        case "DUPLICATE_BRANCH_OWNERSHIP":
+            return ["reconcile-ownership", "retain-session"];
+        case "PROTECTED_WORKTREE":
+        case "PROTECTED_BRANCH":
+            return details.phase === "execution"
+                ? ["run-from-managed-session-worktree", "select-target-session-explicitly"]
+                : ["retain-session"];
+        case "RESOURCE_CLAIM_CONFLICT":
+            return ["inspect-blocking-session", "wait-for-conflicting-claim-release", "retain-session"];
+        case "GIT_STATE_AMBIGUOUS":
+        case "PHYSICAL_OBSERVATION_UNAVAILABLE":
+        case "REPOSITORY_IDENTITY_AMBIGUOUS":
+        case "WORKTREE_IDENTITY_AMBIGUOUS":
+        case "GIT_COMMAND_FAILED":
+        case "GIT_SPAWN_FAILED":
+        case "GIT_TIMEOUT":
+        case "GIT_OUTPUT_LIMIT":
+            return ["stabilize-repository-state", "retry-diagnostic"];
+        case "STALE_REGISTRY":
+        case "RECONCILIATION_DRIFT":
+            return ["retry-diagnostic"];
+        default:
+            return ["retry-diagnostic"];
+    }
+}
+function isAmbiguousObservationCode(code) {
+    return (code === "GIT_STATE_AMBIGUOUS" ||
+        code === "PHYSICAL_OBSERVATION_UNAVAILABLE" ||
+        code === "REPOSITORY_IDENTITY_AMBIGUOUS" ||
+        code === "WORKTREE_IDENTITY_AMBIGUOUS" ||
+        code === "GIT_COMMAND_FAILED" ||
+        code === "GIT_SPAWN_FAILED" ||
+        code === "GIT_TIMEOUT" ||
+        code === "GIT_OUTPUT_LIMIT");
+}
+/** #123 non-ancestry integration: RECOVERABLE_COMMITS with no ancestry proof and no evidence attempted yet. */
+function isExternalEvidenceEligible(blocker) {
+    return blocker.code === "RECOVERABLE_COMMITS" && blocker.details.proofMethod === "ancestry";
+}
+function closeReadinessForBlockers(blockers) {
+    const blocker = blockers[0];
+    if (blocker === undefined)
+        return "ready";
+    if (isAmbiguousObservationCode(blocker.code))
+        return "ambiguous";
+    if (isExternalEvidenceEligible(blocker))
+        return "external_evidence_required";
+    return "blocked";
+}
+function resultStateForDiagnostic(closeReadiness, blockers) {
+    if (closeReadiness === "ambiguous")
+        return "ambiguous";
+    if (closeReadiness === "external_evidence_required")
+        return "external_evidence_required";
+    const blocker = blockers[0];
+    if (blocker !== undefined && (blocker.code === "STALE_REGISTRY" || blocker.code === "RECONCILIATION_DRIFT")) {
+        return "stale";
+    }
+    return "complete";
+}
+/**
+ * Enrich a direct `close()` rejection with the exact same #124 diagnostic
+ * classification `session inspect` would report for the identical blocked
+ * state (readiness, result state, stable safe actions), so a raw close
+ * failure and the diagnostic authority can never drift apart. This never
+ * mutates session/claim/Git/worktree state; it only reclassifies an error
+ * that `inspectCleanupResources` already raised before any mutation ran.
+ */
+function enrichCloseBlockerError(error) {
+    if (!(error instanceof SessionRegistryError))
+        throw error;
+    const blocker = toDiagnosticBlocker(error);
+    const closeReadiness = closeReadinessForBlockers([blocker]);
+    const resultState = resultStateForDiagnostic(closeReadiness, [blocker]);
+    return new SessionRegistryError(error.code, error.message, {
+        ...blocker.details,
+        safeActions: [...blocker.safeActions],
+        recoveryHints: [...blocker.recoveryHints],
+        closeReadiness,
+        resultState,
+    }, error.cause);
+}
 function toGarbageCollectBlocked(sessionId, error) {
     const blocker = toCleanupBlocker(error);
     return Object.freeze({
@@ -2246,8 +2640,8 @@ function removeSessionWorktree(git, cwd, worktreePath) {
     const force = !fs.existsSync(worktreePath);
     git.run(["worktree", "remove", ...(force ? ["--force"] : []), worktreePath], cwd);
 }
-function removeSessionBranch(git, cwd, branchName) {
-    git.run(["branch", "-d", "--", branchName], cwd);
+function removeSessionBranch(git, cwd, branchName, force = false) {
+    git.run(["branch", force ? "-D" : "-d", "--", branchName], cwd);
 }
 function generateUniqueSessionId(records, idGenerator) {
     for (let attempt = 0; attempt < MAX_ID_GENERATION_ATTEMPTS; attempt += 1) {
@@ -2739,10 +3133,12 @@ function validateRegistryClaims(records, claims, expectedRepositoryId) {
             }
             if (!claimsConflict(current, prior))
                 continue;
+            const conflictDetails = resourceClaimConflictDetails(current, prior, records);
             throw claimError("RESOURCE_CLAIM_CONFLICT", "Persisted claims contain an unresolved conflict", {
                 claimId: current.claimId,
-                ownerClaimId: prior.claimId,
-                ownerSessionId: prior.sessionId,
+                ...conflictDetails,
+                safeActions: [...safeActionsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails)],
+                recoveryHints: recoveryHintsForCode("RESOURCE_CLAIM_CONFLICT", conflictDetails),
             });
         }
     }
@@ -2992,36 +3388,4 @@ function toSessionRegistryLockError(error, lockPath) {
     }
     return new SessionRegistryError("REGISTRY_IO_FAILURE", `Could not operate on ${lockPath}`, { path: lockPath }, error);
 }
-function closeQuietly(descriptor) {
-    try {
-        fs.closeSync(descriptor);
-    }
-    catch {
-        // The original operation's error is more useful than a best-effort close error.
-    }
-}
-function unlinkQuietly(filePath) {
-    try {
-        fs.unlinkSync(filePath);
-    }
-    catch {
-        // A missing temporary file is already the desired state.
-    }
-}
-function syncDirectory(directory) {
-    let descriptor;
-    try {
-        descriptor = fs.openSync(directory, "r");
-        fs.fsyncSync(descriptor);
-    }
-    catch {
-        // Directory fsync is not available on every supported filesystem. The
-        // file itself was fsynced before rename, so continue on that limitation.
-    }
-    finally {
-        if (descriptor !== undefined) {
-            closeQuietly(descriptor);
-        }
-    }
-}
 //# sourceMappingURL=session-registry.js.map