nawabari 0.3.0 → 0.5.0

package/dist/registry/atomic.d.ts

@@ -1,3 +1,4 @@
+import { RegistryError } from "./errors.js";
 export interface AtomicWritePaths {
     temporaryPath: string;
     targetPath: string;
@@ -10,6 +11,29 @@ export interface AtomicWriteOptions {
     ensureParent?: boolean;
     hooks?: AtomicWriteHooks;
 }
+/**
+ * A failure observed after the target file was already renamed into place.
+ * Callers must not read this as "the write succeeded" — durability past
+ * that point is unproven — but they must also not treat it as an ordinary
+ * pre-effect failure: the renamed document may already be the one readers
+ * observe. `cause` always carries the original thrown value verbatim
+ * (whatever it was — an Error, a frozen object, a primitive), since a
+ * classification that depended on mutating or reading properties off the
+ * original thrown value would silently fail for values that reject writes
+ * (frozen/non-extensible objects) or carry no properties at all
+ * (primitives). Wrapping in a fresh, always-extensible error is fail-safe
+ * regardless of what the underlying I/O call happened to throw.
+ */
+export declare class AtomicWritePostRenameFailure extends RegistryError {
+    constructor(paths: AtomicWritePaths, cause: unknown);
+}
+/**
+ * True when `writeJsonAtomically`/`writeJsonAtomicallySync` failed only
+ * after the rename had already committed the new document. Recovery must
+ * reconcile authoritative state instead of assuming the mutation never
+ * happened.
+ */
+export declare function isPostRenameFailure(error: unknown): error is AtomicWritePostRenameFailure;
 /**
  * Persist JSON by writing and syncing a same-directory temporary file, then
  * replacing the target with rename. Readers therefore observe either the

package/dist/registry/atomic.js

@@ -14,6 +14,37 @@ function isUnsupportedDirectorySync(error) {
     const code = errorCode(error);
     return code === "EINVAL" || code === "ENOTSUP" || code === "EISDIR";
 }
+/**
+ * A failure observed after the target file was already renamed into place.
+ * Callers must not read this as "the write succeeded" — durability past
+ * that point is unproven — but they must also not treat it as an ordinary
+ * pre-effect failure: the renamed document may already be the one readers
+ * observe. `cause` always carries the original thrown value verbatim
+ * (whatever it was — an Error, a frozen object, a primitive), since a
+ * classification that depended on mutating or reading properties off the
+ * original thrown value would silently fail for values that reject writes
+ * (frozen/non-extensible objects) or carry no properties at all
+ * (primitives). Wrapping in a fresh, always-extensible error is fail-safe
+ * regardless of what the underlying I/O call happened to throw.
+ */
+export class AtomicWritePostRenameFailure extends RegistryError {
+    constructor(paths, cause) {
+        super("REGISTRY_DURABILITY_UNCERTAIN", `Rename to ${paths.targetPath} may have already committed, but durable persistence past that point could not be proven`, { ...paths }, { cause });
+        this.name = "AtomicWritePostRenameFailure";
+    }
+}
+function toPostRenameFailure(error, paths) {
+    return new AtomicWritePostRenameFailure(paths, error);
+}
+/**
+ * True when `writeJsonAtomically`/`writeJsonAtomicallySync` failed only
+ * after the rename had already committed the new document. Recovery must
+ * reconcile authoritative state instead of assuming the mutation never
+ * happened.
+ */
+export function isPostRenameFailure(error) {
+    return error instanceof AtomicWritePostRenameFailure;
+}
 async function syncDirectory(directory) {
     let handle;
     try {
@@ -86,8 +117,9 @@ export async function writeJsonAtomically(targetPath, value, options = {}) {
         }
         if (!renamed) {
             await rm(temporaryPath, { force: true });
+            throw error;
         }
-        throw error;
+        throw toPostRenameFailure(error, { temporaryPath, targetPath });
     }
 }
 /** Synchronous counterpart used by the legacy synchronous registry boundary. */
@@ -121,8 +153,9 @@ export function writeJsonAtomicallySync(targetPath, value, options = {}) {
         }
         if (!renamed) {
             fs.rmSync(temporaryPath, { force: true });
+            throw error;
         }
-        throw error;
+        throw toPostRenameFailure(error, { temporaryPath, targetPath });
     }
 }
 //# sourceMappingURL=atomic.js.map

package/dist/registry/atomic.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/registry/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiB5C,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAc;IAChD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ,CAAC;AACtE,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC5C,IAAI,MAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACpC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACzC,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,KAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QACnC,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACrG,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAClD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CAAC,mBAAmB,EAAE,iCAAiC,EAAE;YAC9E,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAA8B,CAAC;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAChD,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,UAAU,IAAI,EAAE,MAAM,CAAC,CAAC;QAClD,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,GAAG,SAAS,CAAC;QAEnB,MAAM,KAAK,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;QAC5C,MAAM,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QACxC,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,uBAAuB,CACrC,UAAkB,EAClB,KAAc,EACd,UAAoD,EAAE;IAEtD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QACnC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACrG,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAClD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CAAC,mBAAmB,EAAE,iCAAiC,EAAE;YAC9E,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAED,IAAI,UAA8B,CAAC;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,UAAU,GAAG,EAAE,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACrD,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,GAAG,UAAU,IAAI,EAAE,MAAM,CAAC,CAAC;QACxD,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACzB,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACzB,UAAU,GAAG,SAAS,CAAC;QAEvB,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QACzC,OAAO,GAAG,IAAI,CAAC;QACf,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/registry/atomic.ts"],"names":[],"mappings":"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"}

package/dist/registry/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const REGISTRY_ERROR_CODES: readonly ["REGISTRY_NOT_FOUND", "REGISTRY_CORRUPT", "REGISTRY_UNSUPPORTED_SCHEMA", "REGISTRY_REPOSITORY_MISMATCH", "REGISTRY_DUPLICATE_SESSION", "REGISTRY_DUPLICATE_WORKTREE", "REGISTRY_DUPLICATE_BRANCH", "REGISTRY_IO_ERROR", "REGISTRY_MUTATION_FAILED", "LOCK_BUSY", "LOCK_STALE", "LOCK_INVALID", "LOCK_IO_ERROR", "LOCK_RELEASE_FAILED"];
+export declare const REGISTRY_ERROR_CODES: readonly ["REGISTRY_NOT_FOUND", "REGISTRY_CORRUPT", "REGISTRY_UNSUPPORTED_SCHEMA", "REGISTRY_REPOSITORY_MISMATCH", "REGISTRY_DUPLICATE_SESSION", "REGISTRY_DUPLICATE_WORKTREE", "REGISTRY_DUPLICATE_BRANCH", "REGISTRY_IO_ERROR", "REGISTRY_DURABILITY_UNCERTAIN", "REGISTRY_MUTATION_FAILED", "LOCK_BUSY", "LOCK_STALE", "LOCK_INVALID", "LOCK_IO_ERROR", "LOCK_RELEASE_FAILED"];
 export type RegistryErrorCode = (typeof REGISTRY_ERROR_CODES)[number];
 export declare class RegistryError extends Error {
     readonly code: RegistryErrorCode;

package/dist/registry/errors.js

@@ -7,6 +7,7 @@ export const REGISTRY_ERROR_CODES = [
     "REGISTRY_DUPLICATE_WORKTREE",
     "REGISTRY_DUPLICATE_BRANCH",
     "REGISTRY_IO_ERROR",
+    "REGISTRY_DURABILITY_UNCERTAIN",
     "REGISTRY_MUTATION_FAILED",
     "LOCK_BUSY",
     "LOCK_STALE",

package/dist/registry/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/registry/errors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oBAAoB;IACpB,kBAAkB;IAClB,6BAA6B;IAC7B,8BAA8B;IAC9B,4BAA4B;IAC5B,6BAA6B;IAC7B,2BAA2B;IAC3B,mBAAmB;IACnB,0BAA0B;IAC1B,WAAW;IACX,YAAY;IACZ,cAAc;IACd,eAAe;IACf,qBAAqB;CACb,CAAC;AAIX,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtB,IAAI,CAAoB;IACxB,OAAO,CAAoC;IAE3D,YACE,IAAuB,EACvB,OAAe,EACf,UAA6C,EAAE,EAC/C,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,aAAa,CAAC;AACxC,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/registry/errors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oBAAoB;IACpB,kBAAkB;IAClB,6BAA6B;IAC7B,8BAA8B;IAC9B,4BAA4B;IAC5B,6BAA6B;IAC7B,2BAA2B;IAC3B,mBAAmB;IACnB,+BAA+B;IAC/B,0BAA0B;IAC1B,WAAW;IACX,YAAY;IACZ,cAAc;IACd,eAAe;IACf,qBAAqB;CACb,CAAC;AAIX,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtB,IAAI,CAAoB;IACxB,OAAO,CAAoC;IAE3D,YACE,IAAuB,EACvB,OAAe,EACf,UAA6C,EAAE,EAC/C,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,aAAa,CAAC;AACxC,CAAC"}

package/dist/session-registry.d.ts

@@ -14,6 +14,7 @@ export declare const REGISTRY_LOCK_FILE_NAME = "session-registry.lock";
 export declare const DEFAULT_STALE_AFTER_MS: number;
 export declare const CLEANUP_DECISION_SCHEMA_VERSION: 1;
 export declare const RECONCILIATION_SCHEMA_VERSION: 1;
+export declare const SESSION_DIAGNOSTIC_SCHEMA_VERSION: 1;
 /** Bounds a caller-declared commit-message pattern before it is compiled. */
 export declare const MAX_MESSAGE_PATTERN_LENGTH: 512;
 export type RegistrySchemaVersion = typeof REGISTRY_SCHEMA_VERSION;
@@ -40,6 +41,7 @@ export interface CreateSessionOptions {
 }
 export interface ProvisionSessionOptions {
     readonly worktreePath?: string;
+    readonly worktreeRoot?: string;
     readonly branchName?: string;
     readonly baseRef?: string;
     readonly label?: string;
@@ -52,10 +54,23 @@ export interface CloseSessionResult {
     readonly worktreeRemoved: boolean;
     readonly branchRemoved: boolean;
     readonly idempotent: boolean;
+    readonly integrationProof?: IntegrationProof;
 }
 export interface CloseSessionOptions {
     readonly sessionId?: string | null;
     readonly session_id?: string | null;
+    /** Caller-supplied authoritative revision proving non-ancestry integration (e.g. a squash-merge commit). Independently re-verified by exact Git tree-object equivalence; never trusted blindly. */
+    readonly integratedRevision?: string | null;
+    readonly integrated_revision?: string | null;
+}
+/** Caller-supplied non-ancestry integration evidence, already normalized to camelCase. */
+export interface IntegrationEvidenceInput {
+    readonly integratedRevision: string;
+}
+/** Deterministic Git-native evidence proving a branch is safely reclaimable. */
+export interface IntegrationProof {
+    readonly method: "ancestor" | "tree-equivalence";
+    readonly integratedRevision?: string;
 }
 export interface GarbageCollectOptions {
     readonly apply?: boolean;
@@ -94,6 +109,44 @@ export interface CleanupDecision {
     readonly blockers: readonly CleanupBlocker[];
     readonly recoveryHints: readonly string[];
 }
+/**
+ * Explicit close/cleanup readiness states. `external_evidence_required`
+ * marks the #123 non-ancestry-integration case: ancestry alone could not
+ * prove the branch safe to reclaim, and a caller-supplied integration
+ * revision (independently re-verified, never trusted blindly) may resolve
+ * it. `not_due` only applies to cleanup readiness: the session is otherwise
+ * safely closable but has not yet met the garbage-collection staleness
+ * threshold.
+ */
+export type ReadinessState = "ready" | "not_due" | "blocked" | "external_evidence_required" | "ambiguous";
+/** How complete/certain this diagnostic snapshot is, independent of readiness. */
+export type DiagnosticCompleteness = "complete" | "ambiguous" | "stale" | "external_evidence_required";
+export interface SessionDiagnosticBlocker extends CleanupBlocker {
+    /** Stable, kebab-case next-action identifiers; reusable by orchestrators. */
+    readonly safeActions: readonly string[];
+}
+export interface SessionDiagnosticIntegrationEvidence {
+    readonly supplied: boolean;
+    readonly integratedRevision?: string;
+    readonly proof?: IntegrationProof;
+}
+export interface SessionDiagnostic {
+    readonly schemaVersion: typeof SESSION_DIAGNOSTIC_SCHEMA_VERSION;
+    readonly operation: "diagnostic";
+    readonly repositoryId: string;
+    readonly worktreePath: string;
+    readonly branchName: string;
+    readonly session: SessionRecord;
+    readonly claims: readonly ResourceClaim[];
+    readonly physicalState: string;
+    readonly closeReadiness: ReadinessState;
+    readonly cleanupReadiness: ReadinessState;
+    readonly resultState: DiagnosticCompleteness;
+    readonly idempotent: boolean;
+    readonly blockers: readonly SessionDiagnosticBlocker[];
+    readonly safeActions: readonly string[];
+    readonly integrationEvidence: SessionDiagnosticIntegrationEvidence;
+}
 export type ReconciliationSessionStatus = "healthy" | "candidate" | "drift" | "closed";
 export interface ReconciliationSession {
     readonly session: SessionRecord;
@@ -321,6 +374,22 @@ export declare class SessionRegistry {
     createSession(options?: CreateSessionOptions): SessionRecord;
     /** Provision one isolated Git worktree and commit its ownership atomically. */
     provision(options?: ProvisionSessionOptions): SessionRecord;
+    /**
+     * 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.
+     */
+    private absenceProvenAfterProvisioningFailure;
     provisionSession(options?: ProvisionSessionOptions): SessionRecord;
     createProvisionedSession(options?: ProvisionSessionOptions): SessionRecord;
     register(record: SessionRecord): SessionRecord;
@@ -336,6 +405,16 @@ export declare class SessionRegistry {
     private verifyEvidenceSession;
     /** Shared physical/protected/ownership path for every governed decision. */
     private verifyGovernedExecutionContext;
+    /**
+     * 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.
+     */
+    private protectedExecutionContextError;
     private resolveSessionOwnership;
     /**
      * Evaluate the current worktree as a Nawabari mutation context without taking
@@ -380,6 +459,14 @@ export declare class SessionRegistry {
     cleanupDecision(sessionIdOrOptions?: string | null | CloseSessionOptions): CleanupDecision;
     /** Compatibility alias for callers that name the same authority an assessment. */
     assessCleanup(sessionIdOrOptions?: string | null | CloseSessionOptions): CleanupDecision;
+    /**
+     * 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?: string | null | CloseSessionOptions): SessionDiagnostic;
     /**
      * Reconcile registry ownership with Git's physical worktree inventory.
      * This is deliberately diagnostic-only: no stale metadata is repaired and
@@ -402,15 +489,48 @@ export declare class SessionRegistry {
     private closeUnsafe;
     private inspectCleanupResources;
     private cleanupDecisionUnsafe;
+    private diagnoseUnsafe;
     private assertCleanupAllowed;
     private reconcileSessionUnsafe;
     private protectedWorktree;
     private protectedBranch;
+    /**
+     * 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.
+     */
     private branchIsReachableFromIntegration;
+    /**
+     * 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.
+     */
+    private proveNonAncestryIntegration;
     private resolveProvisioningResources;
     private resolveCreationResources;
     private readStateUnsafe;
     private readUnsafe;
+    /**
+     * 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.
+     */
     private writeUnsafe;
     private mutate;
     private withLock;