nawabari 0.2.0 → 0.3.0

package/dist/session-registry.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
-import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, readCurrentHead, resolveRepositoryContext, verifyPhysicalExecutionContext, } from "./git.js";
+import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, observeGitCheckpoint, observeGitMutationPaths, readBoundedGitDiff, readCanonicalCommitChangedPaths, readGitPathStats, readCurrentHead, resolveRepositoryContext, verifyPhysicalExecutionContext, } from "./git.js";
 import { SessionRegistryError } from "./errors.js";
 import { generateSessionId, isSessionId } from "./session-id.js";
 import { RegistryLockError, RepositoryLock } from "./registry/lock.js";
-import { assertCanonicalClaimResource, canonicalClaimId, canonicalizeClaimInput, canonicalizeClaimResource, claimError, claimsConflict, claimsOverlap, cloneResourceClaim, compareCodePointStrings, createResourceClaim, isResourceClaimMode, resourceClaimConflictsWithAccess, resourceMatchesClaim, RESOURCE_CLAIM_SCHEMA_VERSION, sortResourceClaims, } from "./resource-claims.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";
+import { EVIDENCE_MAX_DIFF_BYTES, EVIDENCE_MAX_DIFF_HUNKS, EVIDENCE_MAX_DIFF_PATHS, evidenceHash, } from "./repository-evidence.js";
+export { DIFF_EVIDENCE_SCHEMA_VERSION, EVIDENCE_MAX_DIFF_BYTES, EVIDENCE_MAX_DIFF_HUNKS, EVIDENCE_MAX_DIFF_PATHS, REPOSITORY_EVIDENCE_SCHEMA_VERSION, } from "./repository-evidence.js";
 export const REGISTRY_SCHEMA_VERSION = 1;
 export { RESOURCE_CLAIM_SCHEMA_VERSION };
 export const REGISTRY_DIRECTORY_NAME = "nawabari";
@@ -15,6 +17,8 @@ export const DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1_000;
 export const CLEANUP_DECISION_SCHEMA_VERSION = 1;
 export const RECONCILIATION_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;
 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"]);
@@ -75,6 +79,10 @@ export class SessionRegistry {
             metadataGraceMs: this.lockMetadataGraceMs,
         });
     }
+    /** Resolved repository-local root used for default managed session worktrees. */
+    get managedWorktreeRoot() {
+        return this.worktreeRoot;
+    }
     read() {
         return this.readUnsafe().map(cloneSessionRecord);
     }
@@ -105,16 +113,18 @@ export class SessionRegistry {
         return claim === undefined ? undefined : cloneResourceClaim(claim);
     }
     /**
-     * Explicitly materialize the v0.1.0 registry's empty claim section. This is
-     * also performed by the first ownership mutation after a legacy read.
+     * Explicitly materialize a claim section or upgrade its semantics. A v1
+     * claim registry is intentionally unreadable through ordinary operations;
+     * only this locked, explicit migration rewrites it as v2.
      */
     migrate() {
         return this.withLock(() => {
-            const state = this.readStateUnsafe();
-            if (state.legacyClaimsAbsent)
+            const state = this.readStateUnsafe(true);
+            const migrated = state.legacyClaimsAbsent || state.legacyClaimsSchemaVersion !== undefined;
+            if (migrated)
                 this.writeUnsafe(state.sessions, state.claims);
             return {
-                migrated: state.legacyClaimsAbsent,
+                migrated,
                 registrySchemaVersion: REGISTRY_SCHEMA_VERSION,
                 claimSchemaVersion: RESOURCE_CLAIM_SCHEMA_VERSION,
             };
@@ -248,6 +258,7 @@ export class SessionRegistry {
                     state: "active",
                     createdAt: timestamp,
                     updatedAt: timestamp,
+                    baseRevision: resources.baseRevision,
                     ...(options.label === undefined ? {} : { label: validateLabel(options.label) }),
                 });
                 assertNoOwnershipConflict(records, record);
@@ -282,13 +293,14 @@ export class SessionRegistry {
                 state: "active",
                 createdAt: timestamp,
                 updatedAt: timestamp,
+                baseRevision: resources.baseRevision,
                 ...(options.label === undefined ? {} : { label: validateLabel(options.label) }),
             });
             assertNoOwnershipConflict(state.sessions, record);
             assertGitResourcesAvailable(this.git, this.repository.worktreePath, resources);
             let gitProvisioned = false;
             try {
-                this.git.run(["worktree", "add", "--quiet", "-b", resources.branchName, resources.worktreePath, resources.baseRef], this.repository.worktreePath);
+                this.git.run(["worktree", "add", "--quiet", "-b", resources.branchName, resources.worktreePath, resources.baseRevision], this.repository.worktreePath);
                 gitProvisioned = true;
                 verifyPhysicalExecutionContext({
                     repository: this.repository,
@@ -359,6 +371,36 @@ export class SessionRegistry {
         const session = this.resolveSessionOwnership(physical, options.sessionId ?? null);
         return Object.freeze({ ...physical, session: cloneSessionRecord(session) });
     }
+    /** Resolve and physically verify an explicitly addressed active session. */
+    verifyEvidenceSession(sessionId) {
+        assertSessionId(sessionId);
+        const record = this.readUnsafe().find((candidate) => candidate.sessionId === sessionId);
+        if (record === undefined || record.state === "closed") {
+            throw new SessionRegistryError("SESSION_NOT_FOUND", `Session was not found: ${sessionId}`, { sessionId });
+        }
+        if (record.state !== "active") {
+            throw new SessionRegistryError("STALE_REGISTRY", `Session is not active: ${sessionId}`, {
+                sessionId,
+                state: record.state,
+            });
+        }
+        const physical = verifyPhysicalExecutionContext({
+            repository: this.repository,
+            worktreePath: record.worktreePath,
+            branchName: record.branchName,
+            git: this.git,
+        });
+        if (physical.worktreeId !== record.worktreeId || physical.branchId !== record.branchId) {
+            throw new SessionRegistryError("OWNERSHIP_MISMATCH", "The selected session does not own the observed worktree", {
+                sessionId,
+                expectedWorktree: record.worktreePath,
+                actualWorktree: physical.worktreePath,
+                expectedBranch: record.branchName,
+                actualBranch: physical.branchName,
+            });
+        }
+        return Object.freeze({ session: cloneSessionRecord(record), physical });
+    }
     /** Shared physical/protected/ownership path for every governed decision. */
     verifyGovernedExecutionContext(requestedSessionId, observedPhysical) {
         const physical = observedPhysical ??
@@ -594,6 +636,14 @@ export class SessionRegistry {
                             ownerMode: conflictingClaim.mode,
                         });
                     }
+                    if (ownClaims.length > 0) {
+                        return deniedOperation("INSUFFICIENT_CLAIM_MODE", verified, {
+                            resource,
+                            requiredAccess,
+                            grantedModes: sortStrings(new Set(ownClaims.map((claim) => claim.mode))),
+                            sessionId: currentRecord.sessionId,
+                        });
+                    }
                     return deniedOperation("MISSING_RESOURCE_CLAIM", verified, {
                         resource,
                         requiredAccess,
@@ -634,13 +684,17 @@ export class SessionRegistry {
      * ownership or mutation authority.
      */
     commit(options) {
+        // Validated before the repository lock is acquired: a pathological
+        // caller-declared pattern must not hold the cross-session repository
+        // lock hostage while it backtracks.
+        const messagePattern = options.messagePattern ?? options.message_pattern ?? null;
+        assertFinalCommitMessage(options.message, messagePattern);
         return this.withLock(() => {
             const sessionId = operationSessionId(options.sessionId, options.session_id);
             const requestedResources = operationResources(options.resources ?? options.paths);
             const authorization = this.requireMutationAuthorization("commit", requestedResources, sessionId);
             const initial = this.verifyGovernedExecutionContext(sessionId);
-            assertFinalCommitMessage(options.message);
-            const before = observeMutationPaths(this.git, initial.worktreePath);
+            const before = observeGitMutationPaths(this.git, initial.worktreePath);
             assertNoUnexpectedMutationPaths(before.changed, authorization.resources.map((resource) => resource.resource));
             const stageResources = authorization.resources
                 .map((resource) => resource.resource)
@@ -652,7 +706,7 @@ export class SessionRegistry {
             }
             reverifyMutationContext(this, initial, sessionId, "stage");
             runMutationGit(this.git, ["add", "--", ...stageResources], initial.worktreePath, "stage", "COMMIT_STAGING_FAILED");
-            const afterStage = observeMutationPaths(this.git, initial.worktreePath);
+            const afterStage = observeGitMutationPaths(this.git, initial.worktreePath);
             assertNoUnexpectedMutationPaths(afterStage.changed, stageResources);
             if (!afterStage.staged.some((resource) => stageResources.includes(resource))) {
                 throw new SessionRegistryError("COMMIT_STAGING_FAILED", "Git staging produced no authorized staged paths", {
@@ -660,7 +714,7 @@ export class SessionRegistry {
                 });
             }
             reverifyMutationContext(this, initial, sessionId, "commit");
-            const beforeCommit = observeMutationPaths(this.git, initial.worktreePath);
+            const beforeCommit = observeGitMutationPaths(this.git, initial.worktreePath);
             assertNoUnexpectedMutationPaths(beforeCommit.changed, stageResources);
             if (!beforeCommit.staged.some((resource) => stageResources.includes(resource))) {
                 throw new SessionRegistryError("COMMIT_STAGING_FAILED", "Authorized staged paths disappeared before commit", {
@@ -677,11 +731,34 @@ export class SessionRegistry {
                     throw error;
                 throw new SessionRegistryError("COMMIT_RESULT_UNAVAILABLE", "Git committed the operation but the resulting commit SHA could not be resolved", { phase: "resolve-commit-result" }, error);
             }
+            // The Git commit succeeded and its SHA is known; every failure from here
+            // must retain commitSha so the caller can recover/reconcile the result
+            // instead of losing track of a commit that actually happened.
+            let committedPaths;
+            try {
+                committedPaths = readCanonicalCommitChangedPaths(this.git, initial.worktreePath, commitSha);
+            }
+            catch (error) {
+                if (error instanceof SessionRegistryError && isBoundedGitFailure(error.code)) {
+                    throw new SessionRegistryError(error.code, error.message, { ...error.details, commitSha }, error);
+                }
+                throw new SessionRegistryError("COMMIT_RESULT_UNAVAILABLE", "Git committed the operation but its actual changed paths could not be resolved", { commitSha, phase: "resolve-commit-paths" }, error);
+            }
+            const authorizedSet = new Set(stageResources);
+            const divergentResources = committedPaths.filter((resource) => !authorizedSet.has(resource));
+            if (divergentResources.length > 0) {
+                throw new SessionRegistryError("COMMIT_RESULT_DIVERGED", "The resulting commit contains paths outside the authorized/staged resource set", {
+                    commitSha,
+                    authorizedResources: [...stageResources],
+                    committedResources: [...committedPaths],
+                    divergentResources,
+                });
+            }
             return Object.freeze({
                 schemaVersion: GOVERNED_GIT_OPERATION_SCHEMA_VERSION,
                 commitSha,
                 message: options.message,
-                resources: Object.freeze([...stageResources]),
+                resources: committedPaths,
             });
         });
     }
@@ -705,7 +782,7 @@ export class SessionRegistry {
                     pushBranch: branch,
                 });
             }
-            const inspection = inspectPushTarget(this.git, initial.worktreePath, remote, branch);
+            const inspection = inspectPushTarget(this.git, initial.worktreePath, remote, branch, initial.headId);
             if (inspection.upstream !== undefined && inspection.upstream !== `${remote}/${branch}`) {
                 throw new SessionRegistryError("PUSH_TARGET_MISMATCH", "The explicit push target does not match the currently configured upstream", { upstream: inspection.upstream, remote, branch });
             }
@@ -719,32 +796,44 @@ export class SessionRegistry {
                 const code = inspection.relation === "behind" ? "PUSH_BEHIND" : "PUSH_DIVERGED";
                 throw new SessionRegistryError(code, `The local and remote branches are ${inspection.relation}; explicit force intent is required`, { remote, branch, relation: inspection.relation, forceRequired: true });
             }
-            const dirtyBefore = observeMutationPaths(this.git, initial.worktreePath);
+            const dirtyBefore = observeGitMutationPaths(this.git, initial.worktreePath);
             if (dirtyBefore.changed.length > 0) {
                 throw new SessionRegistryError("PUSH_DIRTY_WORKTREE", "Push requires a clean Git worktree", {
                     paths: [...dirtyBefore.changed],
                 });
             }
-            reverifyMutationContext(this, initial, sessionId, "push");
-            const dirtyBeforePush = observeMutationPaths(this.git, initial.worktreePath);
+            const finalContext = reverifyMutationContext(this, initial, sessionId, "push");
+            const dirtyBeforePush = observeGitMutationPaths(this.git, initial.worktreePath);
             if (dirtyBeforePush.changed.length > 0) {
                 throw new SessionRegistryError("PUSH_DIRTY_WORKTREE", "The worktree changed before push mutation", {
                     paths: [...dirtyBeforePush.changed],
                 });
             }
+            const targetRef = `refs/heads/${branch}`;
+            const leaseValue = inspection.observedRemoteSha ?? "";
             const pushArguments = [
                 "push",
-                ...(force ? ["--force-with-lease"] : []),
+                ...(force ? [`--force-with-lease=${targetRef}:${leaseValue}`] : ["--no-force"]),
                 ...(createUpstream ? ["--set-upstream"] : []),
                 remote,
-                `HEAD:refs/heads/${branch}`,
+                `${finalContext.headId}:${targetRef}`,
             ];
             runMutationGit(this.git, pushArguments, initial.worktreePath, "push", "PUSH_FAILED");
+            if (createUpstream) {
+                // A SHA:ref refspec is intentional: it cannot be redirected by a
+                // mutable symbolic HEAD. Git does not consistently infer the current
+                // branch's tracking configuration from a raw SHA source, so complete
+                // the explicitly requested local upstream setup after the push.
+                runMutationGit(this.git, ["branch", "--set-upstream-to", `${remote}/${branch}`, branch], initial.worktreePath, "set-upstream", "PUSH_FAILED");
+            }
             return Object.freeze({
                 schemaVersion: GOVERNED_GIT_OPERATION_SCHEMA_VERSION,
+                sourceSha: finalContext.headId,
                 remote,
                 branch,
                 target: `${remote}/${branch}`,
+                targetRef,
+                observedRemoteSha: inspection.observedRemoteSha,
                 relation: inspection.relation,
                 force,
                 upstreamCreated: createUpstream,
@@ -776,13 +865,7 @@ export class SessionRegistry {
         const execution = this.verifyGovernedExecutionContext(requestedSessionId);
         const physical = execution;
         const session = execution.session;
-        const observed = captureGitCheckpoint(this.git, physical.worktreePath);
-        const paths = {
-            changed: canonicalObservedPaths(observed.changed, physical.worktreePath),
-            staged: canonicalObservedPaths(observed.staged, physical.worktreePath),
-            unstaged: canonicalObservedPaths(observed.unstaged, physical.worktreePath),
-            untracked: canonicalObservedPaths(observed.untracked, physical.worktreePath),
-        };
+        const paths = observeGitCheckpoint(this.git, physical.worktreePath);
         const state = this.readStateUnsafe();
         const activeClaims = state.claims.filter((claim) => claim.sessionId === session.sessionId &&
             state.sessions.some((record) => record.sessionId === claim.sessionId && record.state === "active"));
@@ -810,6 +893,122 @@ export class SessionRegistry {
     captureCheckpoint(options = {}) {
         return this.checkpoint(options);
     }
+    /**
+     * Capture one deterministic, read-only physical repository generation for
+     * an explicitly addressed owned session.
+     */
+    repositoryEvidence(options) {
+        return this.withLock(() => {
+            const initial = this.verifyEvidenceSession(options.sessionId);
+            const paths = observeGitCheckpoint(this.git, initial.physical.worktreePath);
+            const stats = paths.changed.length === 0
+                ? []
+                : readGitPathStats(this.git, initial.physical.worktreePath, paths.changed, initial.physical.headId);
+            const final = this.verifyEvidenceSession(options.sessionId);
+            if (final.physical.branchName !== initial.physical.branchName ||
+                final.physical.headId !== initial.physical.headId ||
+                !sameCheckpointPaths(paths, observeGitCheckpoint(this.git, final.physical.worktreePath))) {
+                throw new SessionRegistryError("GIT_STATE_AMBIGUOUS", "Repository evidence changed during physical observation", {
+                    sessionId: options.sessionId,
+                    worktree: initial.physical.worktreePath,
+                });
+            }
+            const baseRevision = initial.session.baseRevision ?? null;
+            const incompleteReasons = stats.some((stat) => !stat.available) ? ["STAT_UNAVAILABLE"] : [];
+            const pathsEvidence = Object.freeze({
+                changed: paths.changed,
+                staged: paths.staged,
+                unstaged: paths.unstaged,
+                untracked: paths.untracked,
+                stats: Object.freeze([...stats]),
+            });
+            const snapshotWithoutHash = {
+                schemaVersion: 1,
+                source: "git",
+                guarantee: "git-observable-only",
+                repositoryId: initial.physical.repositoryId,
+                worktreePath: initial.physical.worktreePath,
+                branchId: initial.physical.branchId,
+                branchName: initial.physical.branchName,
+                sessionId: initial.session.sessionId,
+                sessionState: initial.session.state,
+                sessionCreatedAt: initial.session.createdAt,
+                sessionUpdatedAt: initial.session.updatedAt,
+                baseRevision,
+                baseRevisionProven: baseRevision !== null,
+                headId: initial.physical.headId,
+                clean: paths.changed.length === 0,
+                complete: incompleteReasons.length === 0,
+                incompleteReasons: Object.freeze(incompleteReasons),
+                paths: pathsEvidence,
+                bounds: Object.freeze({
+                    maxPaths: CHECKPOINT_MAX_PATHS,
+                    maxDiffPaths: EVIDENCE_MAX_DIFF_PATHS,
+                    maxDiffBytes: EVIDENCE_MAX_DIFF_BYTES,
+                    maxDiffHunks: EVIDENCE_MAX_DIFF_HUNKS,
+                }),
+            };
+            return Object.freeze({
+                ...snapshotWithoutHash,
+                evidenceHash: evidenceHash(snapshotWithoutHash),
+            });
+        });
+    }
+    evidenceSnapshot(options) {
+        return this.repositoryEvidence(options);
+    }
+    /** Inspect only explicitly selected paths with bounded stat/patch output. */
+    repositoryDiff(options) {
+        return this.withLock(() => {
+            const initial = this.verifyEvidenceSession(options.sessionId);
+            const diff = readBoundedGitDiff(this.git, initial.physical.worktreePath, {
+                paths: options.paths,
+                from: options.from,
+                to: options.to,
+                includePatch: options.includePatch,
+                maxBytes: options.maxBytes,
+                maxHunks: options.maxHunks,
+            });
+            const final = this.verifyEvidenceSession(options.sessionId);
+            if (final.physical.branchName !== initial.physical.branchName ||
+                final.physical.headId !== initial.physical.headId) {
+                throw new SessionRegistryError("GIT_STATE_AMBIGUOUS", "Repository diff changed during physical observation", {
+                    sessionId: options.sessionId,
+                    worktree: initial.physical.worktreePath,
+                });
+            }
+            const diffWithoutHash = {
+                schemaVersion: diff.schemaVersion,
+                source: "git",
+                guarantee: "git-observable-only",
+                repositoryId: initial.physical.repositoryId,
+                worktreePath: initial.physical.worktreePath,
+                branchId: initial.physical.branchId,
+                branchName: initial.physical.branchName,
+                sessionId: initial.session.sessionId,
+                sessionState: initial.session.state,
+                headId: initial.physical.headId,
+                fromRevision: diff.fromRevision,
+                toRevision: diff.toRevision,
+                paths: diff.paths,
+                stats: diff.stats,
+                complete: diff.stats.every((stat) => stat.available),
+                incompleteReasons: Object.freeze(diff.stats.some((stat) => !stat.available) ? ["STAT_UNAVAILABLE"] : []),
+                patch: diff.patch,
+                patchBytes: diff.patchBytes,
+                hunkCount: diff.hunkCount,
+                maxBytes: options.maxBytes ?? EVIDENCE_MAX_DIFF_BYTES,
+                maxHunks: options.maxHunks ?? EVIDENCE_MAX_DIFF_HUNKS,
+            };
+            return Object.freeze({
+                ...diffWithoutHash,
+                evidenceHash: evidenceHash(diffWithoutHash),
+            });
+        });
+    }
+    diff(options) {
+        return this.repositoryDiff(options);
+    }
     /**
      * Produce the authoritative, non-mutating cleanup decision for one session.
      * The decision observes registry claims and current Git/filesystem state in
@@ -1393,12 +1592,13 @@ export class SessionRegistry {
                 branch: shortBranchName,
             });
         }
-        const baseRef = resolveBaseRef(git, this.repository.worktreePath, options.baseRef ?? "HEAD");
+        const base = resolveBaseRef(git, this.repository.worktreePath, options.baseRef ?? "HEAD");
         return {
             worktreePath: requestedWorktreePath,
             branchId,
             branchName: shortBranchName,
-            baseRef,
+            baseRef: base.ref,
+            baseRevision: base.revision,
         };
     }
     resolveCreationResources(options) {
@@ -1413,9 +1613,10 @@ export class SessionRegistry {
             worktreePath: physical.worktreePath,
             branchId: physical.branchId,
             branchName: physical.branchName,
+            baseRevision: physical.headId,
         };
     }
-    readStateUnsafe() {
+    readStateUnsafe(allowLegacyClaimSchema = false) {
         let contents;
         try {
             contents = fs.readFileSync(this.paths.registry, "utf8");
@@ -1437,7 +1638,7 @@ export class SessionRegistry {
                 path: this.paths.registry,
             }, error);
         }
-        return parseRegistry(parsed, this.repository.repositoryId);
+        return parseRegistry(parsed, this.repository.repositoryId, allowLegacyClaimSchema);
     }
     readUnsafe() {
         return this.readStateUnsafe().sessions;
@@ -1676,7 +1877,7 @@ function canonicalOperationResources(resources, worktreePath) {
             });
         }
         try {
-            canonical.add(canonicalizeClaimResource(resource, worktreePath));
+            canonical.add(canonicalizeConcretePath(resource, worktreePath));
         }
         catch (error) {
             if (error instanceof SessionRegistryError &&
@@ -1702,13 +1903,28 @@ function operationSessionId(first, second) {
 function operationResources(resources) {
     return resources === undefined ? [] : [...resources];
 }
-function assertFinalCommitMessage(message) {
+function assertFinalCommitMessage(message, messagePattern) {
     if (typeof message !== "string" ||
         message.length === 0 ||
         message.trim().length === 0 ||
         message.includes("\u0000")) {
         throw new SessionRegistryError("INVALID_COMMIT_MESSAGE", "Commit message must be a non-empty final message without NUL bytes");
     }
+    if (messagePattern === null)
+        return;
+    if (messagePattern.length > MAX_MESSAGE_PATTERN_LENGTH) {
+        throw new SessionRegistryError("INVALID_COMMIT_MESSAGE", "The caller-declared commit-message pattern exceeds the maximum bounded length", { reason: "message-pattern-too-long", maxMessagePatternLength: MAX_MESSAGE_PATTERN_LENGTH });
+    }
+    let pattern;
+    try {
+        pattern = new RegExp(messagePattern, "u");
+    }
+    catch (error) {
+        throw new SessionRegistryError("INVALID_COMMIT_MESSAGE", "The caller-declared commit-message pattern is not a valid regular expression", { reason: "invalid-message-pattern", messagePattern }, error);
+    }
+    if (!pattern.test(message)) {
+        throw new SessionRegistryError("INVALID_COMMIT_MESSAGE", "Commit message does not match the caller-declared commit-message pattern", { reason: "message-pattern-mismatch", messagePattern, message });
+    }
 }
 function explicitRemote(remote) {
     if (typeof remote !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(remote)) {
@@ -1740,25 +1956,6 @@ function explicitRemoteBranch(branch, alias) {
         }, error);
     }
 }
-function observeMutationPaths(git, worktreePath) {
-    const observed = captureGitCheckpoint(git, worktreePath);
-    return Object.freeze({
-        changed: Object.freeze(canonicalMutationPaths(observed.changed, worktreePath)),
-        staged: Object.freeze(canonicalMutationPaths(observed.staged, worktreePath)),
-    });
-}
-function canonicalMutationPaths(paths, worktreePath) {
-    const canonical = new Set();
-    for (const resource of paths) {
-        try {
-            canonical.add(canonicalizeClaimResource(resource, worktreePath));
-        }
-        catch (error) {
-            throw new SessionRegistryError("GIT_STATE_AMBIGUOUS", "Git reported a path that cannot be represented as a canonical repository resource", { path: resource }, error);
-        }
-    }
-    return sortStrings(canonical);
-}
 function assertNoUnexpectedMutationPaths(paths, authorized) {
     const authorizedSet = new Set(authorized);
     const unexpected = paths.filter((resource) => !authorizedSet.has(resource));
@@ -1812,7 +2009,8 @@ function runMutationGit(git, args, cwd, phase, failureCode) {
         throw new SessionRegistryError(failureCode, `${phase} Git operation failed`, details, error);
     }
 }
-function inspectPushTarget(git, cwd, remote, branch) {
+function inspectPushTarget(git, cwd, remote, branch, sourceSha) {
+    const targetRef = `refs/heads/${branch}`;
     try {
         git.run(["remote", "get-url", remote], cwd);
     }
@@ -1821,7 +2019,7 @@ function inspectPushTarget(git, cwd, remote, branch) {
     }
     let remoteTargetOutput;
     try {
-        remoteTargetOutput = git.run(["ls-remote", "--heads", remote, `refs/heads/${branch}`], cwd);
+        remoteTargetOutput = git.run(["ls-remote", "--heads", remote, targetRef], cwd);
     }
     catch (error) {
         throwRemoteInspectionFailure(error, "ls-remote");
@@ -1847,7 +2045,13 @@ function inspectPushTarget(git, cwd, remote, branch) {
     if (upstream === undefined) {
         // The absence of an upstream is itself a first-class relation. A remote
         // branch may exist, but it must not silently become tracking state.
-        return { relation: "no-upstream", upstream: undefined };
+        return {
+            sourceSha,
+            relation: "no-upstream",
+            upstream: undefined,
+            targetRef,
+            observedRemoteSha: remoteTargetExists ? extractRemoteSha(remoteTargetOutput, remote, branch) : null,
+        };
     }
     const separator = upstream.indexOf("/");
     if (separator <= 0 || separator === upstream.length - 1) {
@@ -1870,19 +2074,57 @@ function inspectPushTarget(git, cwd, remote, branch) {
         });
     }
     const remoteSha = remoteShaMatch[1];
-    let headSha;
+    const temporaryRef = `refs/nawabari/push-inspection/${remoteSha}`;
+    let relationOutput;
+    let inspectionError;
     try {
-        headSha = git.run(["rev-parse", "HEAD"], cwd).trim();
+        try {
+            // Fetch only the explicitly inspected remote branch into a disposable
+            // ref. This obtains missing ancestry without mutating tracking refs or
+            // fetching unrelated branches/tags.
+            // Requires Git 2.29 or later for --no-write-fetch-head support.
+            // Unsupported Git versions will fail here and surface as
+            // PUSH_REMOTE_INSPECTION_FAILED via throwRemoteInspectionFailure.
+            git.run(["fetch", "--no-tags", "--no-write-fetch-head", "--refmap=", remote, `+${targetRef}:${temporaryRef}`], cwd);
+            const fetchedSha = git.run(["rev-parse", "--verify", temporaryRef], cwd).trim();
+            if (fetchedSha !== remoteSha) {
+                throw new SessionRegistryError("PUSH_REMOTE_INSPECTION_FAILED", "The remote branch changed while its observed generation was being fetched", {
+                    remote,
+                    branch,
+                    observedRemoteSha: remoteSha,
+                    fetchedRemoteSha: fetchedSha,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof SessionRegistryError && error.code === "PUSH_REMOTE_INSPECTION_FAILED")
+                throw error;
+            throwRemoteInspectionFailure(error, "remote-generation");
+        }
+        try {
+            relationOutput = git.run(["rev-list", "--left-right", "--count", `${sourceSha}...${temporaryRef}`], cwd);
+        }
+        catch (error) {
+            throwRemoteInspectionFailure(error, "relation");
+        }
     }
     catch (error) {
-        throwRemoteInspectionFailure(error, "HEAD");
+        inspectionError = error;
     }
-    let relationOutput;
     try {
-        relationOutput = git.run(["rev-list", "--left-right", "--count", `HEAD...${remoteSha}`], cwd);
+        git.run(["update-ref", "-d", temporaryRef], cwd);
     }
     catch (error) {
-        throwRemoteInspectionFailure(error, "relation");
+        if (inspectionError === undefined)
+            throwRemoteInspectionFailure(error, "remote-generation-cleanup");
+    }
+    if (inspectionError !== undefined)
+        throw inspectionError;
+    if (relationOutput === undefined) {
+        throw new SessionRegistryError("PUSH_REMOTE_INSPECTION_FAILED", "Remote ancestry relation was unavailable", {
+            remote,
+            branch,
+        });
     }
     const counts = relationOutput
         .trim()
@@ -1896,7 +2138,14 @@ function inspectPushTarget(git, cwd, remote, branch) {
     }
     const [ahead, behind] = counts;
     const relation = ahead > 0 && behind > 0 ? "diverged" : behind > 0 ? "behind" : ahead > 0 ? "ahead" : "up-to-date";
-    return { relation, upstream };
+    return { sourceSha, relation, upstream, targetRef, observedRemoteSha: remoteSha };
+}
+function extractRemoteSha(remoteTargetOutput, remote, branch) {
+    const remoteShaMatch = remoteTargetOutput.trim().match(/^([0-9a-f]{40,64})\s+/u);
+    if (remoteShaMatch === null) {
+        throw new SessionRegistryError("PUSH_REMOTE_INSPECTION_FAILED", "Could not extract remote SHA from ls-remote output", { remote, branch });
+    }
+    return remoteShaMatch[1];
 }
 function isExpectedMissingRef(error) {
     return (error instanceof SessionRegistryError &&
@@ -1913,35 +2162,18 @@ function throwRemoteInspectionFailure(error, phase) {
         ...(error instanceof SessionRegistryError ? { gitCode: error.code } : {}),
     }, error);
 }
-function canonicalObservedPaths(paths, worktreePath) {
-    const canonical = new Set();
-    for (const resource of paths) {
-        if (typeof resource !== "string" || resource.length === 0) {
-            continue;
-        }
-        try {
-            // Git-observed paths are concrete repository-relative paths reported by Git.
-            // They may contain literal * or ? characters in filenames (not wildcards).
-            // Canonicalize and bounds-check them without rejecting metacharacters.
-            // If canonicalization encounters traversal, symlink escape, or invalid
-            // syntax, skip the path so it is reported as outOfClaim rather than throwing.
-            canonical.add(canonicalizeClaimResource(resource, worktreePath));
-        }
-        catch (error) {
-            // Let observed paths that fail canonicalization appear in the outOfClaim
-            // set rather than causing checkpoint to throw. This ensures Git-reported
-            // paths with unusual names or structure are observable in evidence.
-            if (error instanceof SessionRegistryError) {
-                continue;
-            }
-            throw error;
-        }
-    }
-    return Object.freeze(sortStrings(canonical));
-}
 function sortStrings(values) {
     return [...new Set(values)].sort(compareCodePointStrings);
 }
+function sameCheckpointPaths(left, right) {
+    return (sameStringArray(left.changed, right.changed) &&
+        sameStringArray(left.staged, right.staged) &&
+        sameStringArray(left.unstaged, right.unstaged) &&
+        sameStringArray(left.untracked, right.untracked));
+}
+function sameStringArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 function assertWorktreeClean(git, worktreePath) {
     // Git is authoritative for this decision. --ignored=no means ignored or
     // generated artifacts alone are intentionally absent from the blocker set.
@@ -2263,21 +2495,35 @@ function resolveBaseRef(git, cwd, candidate) {
         candidate !== candidate.trim() ||
         candidate.startsWith("-") ||
         candidate.includes("\u0000")) {
-        throw new SessionRegistryError("INVALID_BASE_REF", `Invalid base ref: ${candidate}`, { baseRef: candidate });
+        throw invalidBaseRef(candidate, "invalid-format");
     }
     try {
-        git.run(["rev-parse", "--verify", `${candidate}^{commit}`], cwd);
-        return candidate;
+        const revision = git.run(["rev-parse", "--verify", `${candidate}^{commit}`], cwd);
+        if (!isRevision(revision)) {
+            throw new SessionRegistryError("GIT_STATE_AMBIGUOUS", "Git returned an invalid base revision", {
+                baseRef: candidate,
+                revision,
+            });
+        }
+        return { ref: candidate, revision };
     }
     catch (error) {
         if (isExpectedGitLookupFailure(error)) {
-            throw new SessionRegistryError("INVALID_BASE_REF", `Base ref does not resolve to a commit: ${candidate}`, {
-                baseRef: candidate,
-            });
+            throw invalidBaseRef(candidate, "does-not-resolve-to-commit");
         }
         throw error;
     }
 }
+function invalidBaseRef(candidate, reason) {
+    return new SessionRegistryError("INVALID_BASE_REF", reason === "invalid-format"
+        ? `Invalid base ref: ${candidate}`
+        : `Base ref does not resolve to a commit: ${candidate}`, {
+        baseRef: candidate,
+        reason,
+        defaultBaseRef: "HEAD",
+        recoveryHints: ["Omit --base to use HEAD, then retry session create."],
+    });
+}
 function isExpectedGitLookupFailure(error) {
     return (error instanceof SessionRegistryError &&
         error.code === "GIT_COMMAND_FAILED" &&
@@ -2320,6 +2566,7 @@ export function toPersistedSessionRecord(record, expectedRepositoryId = record.r
         state: validated.state,
         created_at: validated.createdAt,
         updated_at: validated.updatedAt,
+        ...(validated.baseRevision === undefined ? {} : { base_revision: validated.baseRevision }),
         ...(validated.label === undefined ? {} : { label: validated.label }),
     };
 }
@@ -2337,7 +2584,7 @@ export function toPersistedResourceClaim(claim, expectedRepositoryId = claim.rep
         updated_at: validated.updatedAt,
     };
 }
-function parseRegistry(value, expectedRepositoryId) {
+function parseRegistry(value, expectedRepositoryId, allowLegacyClaimSchema = false) {
     if (!isRecord(value)) {
         throw new SessionRegistryError("REGISTRY_CORRUPT", "Registry root must be an object");
     }
@@ -2368,17 +2615,27 @@ function parseRegistry(value, expectedRepositoryId) {
         // materialized on the next locked mutation or via migrate().
         return { sessions: records, claims: [], legacyClaimsAbsent: true };
     }
-    if (value.claims_schema_version !== RESOURCE_CLAIM_SCHEMA_VERSION) {
-        throw new SessionRegistryError("UNSUPPORTED_CLAIM_SCHEMA_VERSION", `Unsupported resource claim schema version: ${stringifyDetail(value.claims_schema_version)}`, { schemaVersion: value.claims_schema_version });
+    const claimSchemaVersion = value.claims_schema_version;
+    const isLegacyClaimSchema = claimSchemaVersion === LEGACY_RESOURCE_CLAIM_SCHEMA_VERSION;
+    if (claimSchemaVersion !== RESOURCE_CLAIM_SCHEMA_VERSION && !isLegacyClaimSchema) {
+        throw new SessionRegistryError("UNSUPPORTED_CLAIM_SCHEMA_VERSION", `Unsupported resource claim schema version: ${stringifyDetail(claimSchemaVersion)}`, { schemaVersion: claimSchemaVersion });
+    }
+    if (isLegacyClaimSchema && !allowLegacyClaimSchema) {
+        throw new SessionRegistryError("UNSUPPORTED_CLAIM_SCHEMA_VERSION", "Resource claim schema v1 requires explicit migration before use", { schemaVersion: LEGACY_RESOURCE_CLAIM_SCHEMA_VERSION, migrationRequired: true });
     }
     if (!Array.isArray(value.claims)) {
         throw new SessionRegistryError("REGISTRY_CORRUPT", "Registry claims must be an array");
     }
-    const claims = value.claims.map((candidate, index) => parseResourceClaim(candidate, index, expectedRepositoryId));
+    const claims = value.claims.map((candidate, index) => parseResourceClaim(candidate, index, expectedRepositoryId, isLegacyClaimSchema ? LEGACY_RESOURCE_CLAIM_SCHEMA_VERSION : undefined));
     validateRegistryClaims(records, claims, expectedRepositoryId);
-    return { sessions: records, claims: sortResourceClaims(claims), legacyClaimsAbsent: false };
+    return {
+        sessions: records,
+        claims: sortResourceClaims(claims),
+        legacyClaimsAbsent: false,
+        ...(isLegacyClaimSchema ? { legacyClaimsSchemaVersion: LEGACY_RESOURCE_CLAIM_SCHEMA_VERSION } : {}),
+    };
 }
-function parseResourceClaim(value, index, expectedRepositoryId) {
+function parseResourceClaim(value, index, expectedRepositoryId, expectedSchemaVersion = RESOURCE_CLAIM_SCHEMA_VERSION) {
     if (!isRecord(value))
         throw invalidRecord(index, "claim must be an object");
     assertExactKeys(value, [
@@ -2392,8 +2649,8 @@ function parseResourceClaim(value, index, expectedRepositoryId) {
         "created_at",
         "updated_at",
     ], [], index);
-    if (value.schema_version !== RESOURCE_CLAIM_SCHEMA_VERSION) {
-        throw new SessionRegistryError("UNSUPPORTED_CLAIM_SCHEMA_VERSION", `Unsupported resource claim schema version at index ${index}: ${stringifyDetail(value.schema_version)}`, { schemaVersion: value.schema_version, index });
+    if (value.schema_version !== expectedSchemaVersion) {
+        throw new SessionRegistryError("UNSUPPORTED_CLAIM_SCHEMA_VERSION", `Unsupported resource claim schema version at index ${index}: ${stringifyDetail(value.schema_version)}`, { schemaVersion: value.schema_version, index, expectedSchemaVersion });
     }
     const claim = {
         schemaVersion: RESOURCE_CLAIM_SCHEMA_VERSION,
@@ -2505,7 +2762,7 @@ function parseSessionRecord(value, index, expectedRepositoryId) {
         "state",
         "created_at",
         "updated_at",
-    ], ["label"], index);
+    ], ["base_revision", "label"], index);
     if (value.schema_version !== REGISTRY_SCHEMA_VERSION) {
         if (typeof value.schema_version === "number") {
             throw new SessionRegistryError("UNSUPPORTED_SCHEMA_VERSION", `Unsupported session schema version: ${value.schema_version}`, {
@@ -2526,6 +2783,9 @@ function parseSessionRecord(value, index, expectedRepositoryId) {
         state: requireState(value.state, index),
         createdAt: requireString(value.created_at, index, "created_at"),
         updatedAt: requireString(value.updated_at, index, "updated_at"),
+        ...(value.base_revision === undefined
+            ? {}
+            : { baseRevision: requireRevision(value.base_revision, index, "base_revision") }),
         ...(value.label === undefined ? {} : { label: requireString(value.label, index, "label") }),
     };
     return validateSessionRecord(record, expectedRepositoryId, index);
@@ -2571,6 +2831,9 @@ function validateSessionRecord(record, expectedRepositoryId, index) {
     if (Date.parse(record.updatedAt) < Date.parse(record.createdAt)) {
         throw invalidRecord(index, "updated_at cannot precede created_at");
     }
+    if (record.baseRevision !== undefined && !isRevision(record.baseRevision)) {
+        throw invalidRecord(index, "base_revision must be a full hexadecimal Git revision");
+    }
     if (record.label !== undefined && (typeof record.label !== "string" || record.label.length === 0)) {
         throw invalidRecord(index, "label must be a non-empty string");
     }
@@ -2660,6 +2923,16 @@ function requireString(value, index, field) {
     }
     return value;
 }
+function requireRevision(value, index, field) {
+    const revision = requireString(value, index, field);
+    if (!isRevision(revision)) {
+        throw invalidRecord(index, `${field} must be a full hexadecimal Git revision`);
+    }
+    return revision;
+}
+function isRevision(value) {
+    return /^[0-9a-f]{40,64}$/u.test(value);
+}
 function requireState(value, index) {
     if (typeof value !== "string" || !SESSION_STATES.has(value)) {
         throw invalidRecord(index, `state is invalid: ${stringifyDetail(value)}`);