nawabari 0.8.0 → 0.9.2

package/dist/session-registry.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, observeGitCheckpoint, observeGitMutationPaths, readBoundedGitDiff, readCanonicalCommitChangedPaths, readChangedPathNames, readGitPathStats, readCurrentHead, readTreePathStates, resolveRepositoryContext, treeEntriesEqual, verifyPhysicalExecutionContext, } from "./git.js";
+import { defaultGit, captureGitCheckpoint, listGitWorktrees, normalizeBranchId, observeGitCheckpoint, observeGitMutationPaths, readBoundedGitDiff, readCanonicalCommitChangedPaths, readChangedPathNames, canonicalizeGitObservedPaths, 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";
@@ -9,9 +9,10 @@ import { assertCanonicalClaimResource, canonicalClaimId, canonicalizeClaimInput,
 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";
 import { classifySessionLifecycle, } from "./session-lifecycle-classification.js";
+import { coordinateSessionLifecycle, } from "./state/session/actors.js";
 import { projectSessionLifecycleActions, } from "./session-lifecycle-actions.js";
 export { primarySessionLifecycleAction, primarySessionLifecycleNextAction, projectSessionLifecycleActions, projectSessionLifecycleNextActions, SESSION_LIFECYCLE_ACTION_SCHEMA_VERSION, } from "./session-lifecycle-actions.js";
-export { classifySessionLifecycle, lifecycleTransition, SESSION_LIFECYCLE_CLASSIFICATION_SCHEMA_VERSION, SESSION_LIFECYCLE_STATES, SESSION_LIFECYCLE_TRANSITION_TABLE, } from "./session-lifecycle-classification.js";
+export { availableLifecycleOperations, classifySessionLifecycle, lifecycleTransition, SESSION_LIFECYCLE_CLASSIFICATION_SCHEMA_VERSION, SESSION_LIFECYCLE_STATES, SESSION_LIFECYCLE_TRANSITION_TABLE, } from "./session-lifecycle-classification.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 };
@@ -23,6 +24,7 @@ export const CLEANUP_DECISION_SCHEMA_VERSION = 1;
 export const RECONCILIATION_SCHEMA_VERSION = 1;
 export const SESSION_DIAGNOSTIC_SCHEMA_VERSION = 1;
 export const DISCARD_RESULT_SCHEMA_VERSION = 1;
+export const DISCARD_PREVIEW_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;
@@ -944,7 +946,17 @@ export class SessionRegistry {
         assertFinalCommitMessage(options.message, messagePattern);
         return this.withLock(() => {
             const sessionId = operationSessionId(options.sessionId, options.session_id);
-            const requestedResources = operationResources(options.resources ?? options.paths);
+            const allClaimed = options.allClaimed === true || options.all_claimed === true;
+            const explicitResources = options.resources ?? options.paths;
+            if (allClaimed && explicitResources !== undefined && explicitResources.length > 0) {
+                throw new SessionRegistryError("INVALID_RESOURCE", "--all-claimed cannot be combined with explicit resources", {
+                    operation: "commit",
+                    selectors: ["--resource", "--all-claimed"],
+                });
+            }
+            const requestedResources = allClaimed
+                ? this.resolveAllClaimedResourcesUnsafe("commit", sessionId)
+                : operationResources(explicitResources);
             const authorization = this.requireMutationAuthorization("commit", requestedResources, sessionId);
             const initial = this.verifyGovernedExecutionContext(sessionId);
             const before = observeGitMutationPaths(this.git, initial.worktreePath);
@@ -1065,7 +1077,16 @@ export class SessionRegistry {
     push(options) {
         return this.withLock(() => {
             const sessionId = operationSessionId(options.sessionId, options.session_id);
-            const requestedResources = operationResources(options.resources);
+            const allClaimed = options.allClaimed === true || options.all_claimed === true;
+            if (allClaimed && options.resources !== undefined && options.resources.length > 0) {
+                throw new SessionRegistryError("INVALID_RESOURCE", "--all-claimed cannot be combined with explicit resources", {
+                    operation: "push",
+                    selectors: ["--resource", "--all-claimed"],
+                });
+            }
+            const requestedResources = allClaimed
+                ? this.resolveAllClaimedResourcesUnsafe("push", sessionId)
+                : operationResources(options.resources);
             this.requireMutationAuthorization("push", requestedResources, sessionId);
             const initial = this.verifyGovernedExecutionContext(sessionId);
             const remote = explicitRemote(options.remote);
@@ -1155,6 +1176,69 @@ export class SessionRegistry {
     pushSession(options) {
         return this.push(options);
     }
+    /**
+     * Resolve the opt-in all-claimed selector while the mutation lock is held.
+     * Claims remain the authority, but only concrete Git/repository evidence is
+     * ever handed to the existing concrete authorization path.
+     */
+    resolveAllClaimedResourcesUnsafe(operation, sessionId) {
+        const execution = this.verifyGovernedExecutionContext(sessionId);
+        const requiredAccess = requiredAccessForOperation(operation);
+        const state = this.readStateUnsafe();
+        const claims = sortResourceClaims(state.claims.filter((claim) => claim.sessionId === execution.session.sessionId &&
+            claim.repositoryId === execution.repositoryId &&
+            claim.worktreePath === execution.worktreePath));
+        const globClaims = claims.filter((claim) => claim.resource.includes("*") || claim.resource.includes("?"));
+        let candidates;
+        if (operation === "commit") {
+            candidates = observeGitMutationPaths(this.git, execution.worktreePath).changed;
+        }
+        else {
+            const exactClaims = claims.filter((claim) => !claim.resource.includes("*") && !claim.resource.includes("?"));
+            const selected = new Set(exactClaims.map((claim) => claim.resource));
+            if (globClaims.length === 0)
+                return Object.freeze(sortStrings(selected));
+            const baseRevision = execution.session.baseRevision;
+            if (baseRevision === undefined) {
+                throw new SessionRegistryError("INVALID_RESOURCE", "A glob claim cannot be projected to concrete push resources without a persisted base revision", { operation, reason: "non-enumerable-claim", claims: globClaims.map((claim) => claim.resource) });
+            }
+            const changed = readChangedPathNames(this.git, execution.worktreePath, baseRevision, execution.headId);
+            candidates = canonicalizeGitObservedPaths(changed, execution.worktreePath);
+            const ambiguousResource = candidates.find((resource) => resource.includes("*") || resource.includes("?"));
+            if (ambiguousResource !== undefined) {
+                throw new SessionRegistryError("INVALID_RESOURCE", "Git reported a concrete resource whose wildcard spelling is ambiguous", { operation, reason: "ambiguous-concrete-resource", resource: ambiguousResource });
+            }
+            for (const claim of globClaims) {
+                const matches = candidates.filter((resource) => resourceMatchesClaim(claim, resource));
+                if (matches.length === 0) {
+                    throw new SessionRegistryError("INVALID_RESOURCE", "A glob claim could not be deterministically projected to a concrete push resource", { operation, reason: "non-enumerable-claim", claim: claim.resource });
+                }
+                for (const match of matches)
+                    selected.add(match);
+            }
+            return Object.freeze(sortStrings(selected));
+        }
+        const selected = new Set();
+        for (const resource of candidates) {
+            if (resource.includes("*") || resource.includes("?")) {
+                throw new SessionRegistryError("INVALID_RESOURCE", "Git reported a concrete resource whose wildcard spelling is ambiguous", { operation, reason: "ambiguous-concrete-resource", resource });
+            }
+            const matchingClaims = claims.filter((claim) => resourceMatchesClaim(claim, resource));
+            if (matchingClaims.length === 0)
+                continue;
+            const qualifyingClaims = matchingClaims.filter((claim) => claimModeGrantsAccess(claim.mode, requiredAccess));
+            // Include mode-insufficient matches as concrete candidates so the
+            // existing authorization authority emits INSUFFICIENT_CLAIM_MODE.
+            // Unclaimed paths remain outside the selection and are still rejected by
+            // commit's existing UNEXPECTED_CHANGED_PATHS protection.
+            if (qualifyingClaims.length > 0 || matchingClaims.length > 0)
+                selected.add(resource);
+        }
+        // Let the existing authorization authority produce its normal missing-claim
+        // denial when every observed path is unclaimed; do not invent a selector
+        // denial with different semantics.
+        return Object.freeze(sortStrings(selected.size === 0 ? candidates : selected));
+    }
     requireMutationAuthorization(operation, resources, sessionId) {
         const decision = this.authorizeOperation({ operation, resources, sessionId });
         if (decision.allowed)
@@ -1492,7 +1576,22 @@ export class SessionRegistry {
             if (record === undefined) {
                 throw new SessionRegistryError("SESSION_NOT_FOUND", `Session was not found: ${sessionId}`, { sessionId });
             }
-            return this.observeCleanupReconciliation(record, operation ?? (record.terminalOperation === "discard" ? "discard" : "close"));
+            const cleanupOperation = operation ?? (record.terminalOperation === "discard" ? "discard" : "close");
+            let observed;
+            const result = coordinateSessionLifecycle({
+                operation: "reconcile",
+                adapter: {
+                    observe: (stage) => this.lifecycleActorInputUnsafe(record, this.readStateUnsafe(), undefined, false, stage === "after" ? "current" : "termination"),
+                    effect: () => {
+                        observed = this.observeCleanupReconciliation(record, cleanupOperation);
+                        return observed;
+                    },
+                },
+            });
+            if (result.phase !== "completed" || observed === undefined) {
+                throw this.lifecycleActorRejection(record, result.decision);
+            }
+            return observed;
         });
     }
     reconcileLifecycleCleanup(sessionIdOrOptions, operation) {
@@ -1507,7 +1606,7 @@ export class SessionRegistry {
             const selectedSessionId = sessionId ?? this.resolveCurrentSession().sessionId;
             assertSessionId(selectedSessionId);
             const evidence = closeIntegrationEvidence(sessionIdOrOptions ?? null);
-            return this.closeUnsafe(selectedSessionId, evidence);
+            return this.coordinateCleanupUnsafe("close", selectedSessionId, evidence);
         });
     }
     closeSession(sessionIdOrOptions) {
@@ -1523,12 +1622,95 @@ export class SessionRegistry {
                 throw new SessionRegistryError("SESSION_NOT_FOUND", "Explicit session identity is required for discard; the current session is never inferred");
             }
             assertSessionId(requestedSessionId);
-            return this.discardUnsafe(requestedSessionId);
+            return this.coordinateCleanupUnsafe("discard", requestedSessionId);
         });
     }
     discardSession(sessionIdOrOptions) {
         return this.discard(sessionIdOrOptions);
     }
+    /**
+     * Produce a bounded, side-effect-free summary of the same session/Git/claim
+     * authorities that an explicit discard observes. The preview never invokes
+     * the cleanup actor or writes registry, worktree, branch, or claim state.
+     */
+    previewDiscard(sessionIdOrOptions) {
+        return this.withLock(() => {
+            const requestedSessionId = typeof sessionIdOrOptions === "string"
+                ? sessionIdOrOptions
+                : (sessionIdOrOptions.sessionId ?? sessionIdOrOptions.session_id ?? null);
+            if (requestedSessionId === null) {
+                throw new SessionRegistryError("SESSION_NOT_FOUND", "Explicit session identity is required for discard preview; the current session is never inferred");
+            }
+            assertSessionId(requestedSessionId);
+            const state = this.readStateUnsafe();
+            const record = state.sessions.find((candidate) => candidate.sessionId === requestedSessionId);
+            if (record === undefined) {
+                throw new SessionRegistryError("SESSION_NOT_FOUND", `Session was not found: ${requestedSessionId}`, {
+                    sessionId: requestedSessionId,
+                });
+            }
+            const diagnostic = this.diagnoseUnsafe(record, state);
+            const reconciliation = this.observeCleanupReconciliation(record, "discard");
+            const blockers = diagnostic.blockers.map((blocker) => ({
+                code: blocker.code,
+                message: blocker.message,
+                details: { ...blocker.details },
+            }));
+            const recoverableEvidence = blockers.filter((blocker) => blocker.code === "RECOVERABLE_COMMITS");
+            const dirtyEvidence = blockers.filter((blocker) => blocker.code === "DIRTY_WORKTREE");
+            const branchEvidenceObservable = recoverableEvidence.length > 0 || blockers.length === 0;
+            const worktreeEvidenceObservable = dirtyEvidence.length > 0 || recoverableEvidence.length > 0 || blockers.length === 0;
+            const recoverableCommits = {
+                observable: branchEvidenceObservable,
+                present: recoverableEvidence.length > 0 ? true : branchEvidenceObservable ? false : null,
+                evidence: Object.freeze(recoverableEvidence.slice(0, 8)),
+            };
+            const uncommittedWork = {
+                observable: worktreeEvidenceObservable,
+                present: dirtyEvidence.length > 0 ? true : worktreeEvidenceObservable ? false : null,
+                evidence: Object.freeze(dirtyEvidence.slice(0, 8)),
+            };
+            const ownedClaims = sortResourceClaims(state.claims.filter((claim) => claim.sessionId === record.sessionId));
+            const boundedClaims = ownedClaims.slice(0, MAX_DISCARD_CLAIMS).map(cloneResourceClaim);
+            const worktreeHead = reconciliation.observedWorktreeHead;
+            const branchHead = reconciliation.observedBranchHead;
+            return Object.freeze({
+                schemaVersion: DISCARD_PREVIEW_SCHEMA_VERSION,
+                operation: "discard-preview",
+                destructive: true,
+                warning: "Actual session discard is destructive: it may remove the worktree and branch and discard recoverable work.",
+                session: cloneSessionRecord(record),
+                currentState: record.state,
+                persistedState: record.state,
+                physicalState: diagnostic.physicalState,
+                worktreePresent: reconciliation.worktreePresent,
+                branchPresent: reconciliation.branchPresent,
+                worktreeHead,
+                branchHead,
+                head: worktreeHead ?? branchHead ?? record.discardedHead ?? null,
+                expectedHead: reconciliation.expectedHead,
+                recoverableCommits,
+                uncommittedWork,
+                claims: Object.freeze(boundedClaims),
+                claimCount: ownedClaims.length,
+                claimsTruncated: ownedClaims.length > boundedClaims.length,
+                destructiveScope: Object.freeze({
+                    worktree: reconciliation.worktreePresent,
+                    branch: reconciliation.branchPresent,
+                    unintegratedCommits: recoverableCommits.present,
+                    uncommittedWork: uncommittedWork.present,
+                    claims: ownedClaims.length,
+                }),
+                diagnostic: Object.freeze({
+                    closeReadiness: diagnostic.closeReadiness,
+                    cleanupReadiness: diagnostic.cleanupReadiness,
+                    resultState: diagnostic.resultState,
+                    blockers: Object.freeze(blockers.slice(0, 8)),
+                    ...(diagnostic.lifecycle === undefined ? {} : { lifecycleState: diagnostic.lifecycle.state }),
+                }),
+            });
+        });
+    }
     /** Detect stale sessions, optionally applying only cleanup that passes close preflight. */
     garbageCollect(options = {}) {
         const apply = options.apply ?? false;
@@ -1543,20 +1725,39 @@ export class SessionRegistry {
             const worktrees = listGitWorktrees(this.git, this.repository.worktreePath);
             const assessments = records
                 .filter((record) => record.state !== "closed")
-                .map((record) => assessGarbageCollection(record, now, staleAfterMs, worktrees));
+                .map((record) => {
+                const assessment = assessGarbageCollection(record, now, staleAfterMs, worktrees);
+                const decision = this.cleanupDecisionUnsafe(record, state);
+                const lifecycle = classifySessionLifecycle({
+                    sessionState: record.state,
+                    physicalState: decision.physicalState,
+                    closeReadiness: decision.lifecycle?.closeReadiness ?? (decision.allowed ? "ready" : "blocked"),
+                    blockers: decision.blockers.map((blocker) => ({ code: blocker.code })),
+                    terminalOperation: record.terminalOperation,
+                    ageSuspicious: assessment.suspicion === "age",
+                    // GC's existing candidate assessment is the independent positive
+                    // authority; the machine still evaluates the complete observed
+                    // cleanup evidence and may reject the event.
+                    gcAuthorized: assessment.destructiveEligibility === "eligible",
+                    phase: "termination",
+                });
+                const nextActions = projectSessionLifecycleActions({
+                    classification: lifecycle,
+                    sessionId: record.sessionId,
+                    blockers: decision.blockers.map((blocker) => ({ code: blocker.code, details: blocker.details })),
+                });
+                return Object.freeze({ ...assessment, physicalState: decision.physicalState, lifecycle, nextActions });
+            });
             const candidates = assessments.filter((assessment) => assessment.suspicion !== "none");
             const eligible = assessments.filter((assessment) => {
                 if (assessment.terminalOperation === "discard")
                     return false;
-                const lifecycle = classifySessionLifecycle({
-                    sessionState: assessment.state,
-                    physicalState: assessment.physicalState,
-                    closeReadiness: "ready",
-                    gcAuthorized: true,
-                    phase: "termination",
-                });
+                // Eligibility is evaluated from the GC authority's own bounded
+                // evidence. Full cleanup blockers remain on `assessment.lifecycle`
+                // and are applied by the existing preflight below.
+                const gcLifecycle = projectGarbageCollectAuthorization(assessment);
                 if (assessment.destructiveEligibility === "eligible" &&
-                    (lifecycle.destructiveCleanupEligible || assessment.physicalState === "prunable-missing")) {
+                    (gcLifecycle.destructiveCleanupEligible || assessment.physicalState === "prunable-missing")) {
                     return true;
                 }
                 // A close that already removed one physical resource is represented
@@ -1601,7 +1802,7 @@ export class SessionRegistry {
                     this.writeUnsafe(records, claims, claimSetGeneration);
                 }
                 try {
-                    const result = this.closeUnsafe(candidate.sessionId, undefined, "gc");
+                    const result = this.coordinateCleanupUnsafe("gc", candidate.sessionId);
                     cleaned.push(result.session);
                 }
                 catch (error) {
@@ -1624,6 +1825,173 @@ export class SessionRegistry {
     gc(options = {}) {
         return this.garbageCollect(options);
     }
+    coordinateCleanupUnsafe(operation, sessionId, evidence, retryOverride) {
+        const state = this.readStateUnsafe();
+        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 retry = record.state === "closing" &&
+            (operation === "gc" ||
+                (operation === "close" && record.terminalOperation === undefined) ||
+                (operation === "discard" && record.terminalOperation === "discard"));
+        const actorRetry = retryOverride ?? retry;
+        const reconciliationOperation = operation === "close" ? "close" : operation === "discard" ? "discard" : "gc";
+        let observedDiagnostic;
+        let observedResources;
+        const result = coordinateSessionLifecycle({
+            operation,
+            retry: actorRetry,
+            adapter: {
+                retryAuthorized: actorRetry
+                    ? () => {
+                        const reconciliation = this.observeCleanupReconciliation(record, reconciliationOperation);
+                        if (reconciliation.retrySafe && reconciliation.outcome !== "unresolved")
+                            return true;
+                        // A cleanup that was not yet durably marked `closing` has no
+                        // captured head to reconcile. The existing cleanup preflight is
+                        // still the positive identity authority for prunable-missing
+                        // worktrees; do not infer permission from age or state alone.
+                        if (record.cleanupHead === undefined && record.discardedHead === undefined) {
+                            try {
+                                this.inspectCleanupResources(record, undefined, operation === "close" ? evidence : undefined, operation === "discard" ? "discard" : "close");
+                                return true;
+                            }
+                            catch {
+                                return false;
+                            }
+                        }
+                        return false;
+                    }
+                    : undefined,
+                observe: (stage) => {
+                    const observedState = this.readStateUnsafe();
+                    const observedRecord = observedState.sessions.find((candidate) => candidate.sessionId === sessionId);
+                    if (observedRecord === undefined) {
+                        throw new SessionRegistryError("SESSION_NOT_FOUND", `Session was not found: ${sessionId}`, { sessionId });
+                    }
+                    return this.lifecycleActorInputUnsafe(observedRecord, observedState, evidence, operation === "gc", stage === "after" ? "current" : "termination", (diagnostic) => {
+                        observedDiagnostic = diagnostic;
+                    }, operation === "discard"
+                        ? undefined
+                        : (resources) => {
+                            if (stage === "before")
+                                observedResources = resources;
+                        });
+                },
+                effect: () => {
+                    if (operation === "discard")
+                        return this.discardUnsafe(sessionId);
+                    return this.closeUnsafe(sessionId, operation === "close" ? evidence : undefined, operation, observedResources);
+                },
+                reconcile: (_error, _after, _decision) => {
+                    const reconciliation = this.observeCleanupReconciliation(record, reconciliationOperation);
+                    return {
+                        outcome: reconciliation.outcome,
+                        retrySafe: reconciliation.retrySafe,
+                        ...(reconciliation.reason === undefined ? {} : { reason: reconciliation.reason }),
+                    };
+                },
+            },
+        });
+        if (result.phase === "rejected" &&
+            !actorRetry &&
+            record.state !== "closed" &&
+            (operation === "close" || operation === "gc") &&
+            observedDiagnostic?.blockers.length === 0 &&
+            (observedDiagnostic.physicalState === "prunable-missing" ||
+                (operation === "close" && observedDiagnostic.physicalState === "unregistered-missing"))) {
+            if (operation === "close")
+                return this.coordinateCleanupUnsafe("close", sessionId, evidence, true);
+            return this.coordinateCleanupUnsafe("gc", sessionId, undefined, true);
+        }
+        if (result.phase === "rejected") {
+            // Preserve the durable terminal-intent guards that the existing effect
+            // adapters enforce before any physical observation can reinterpret the
+            // request.  These are persisted intent contracts, not a new actor
+            // authority: normal close never acquires discard authority, and an
+            // ordinary close already in progress cannot be converted to discard.
+            if (operation === "close" && record.terminalOperation === "discard") {
+                throw new SessionRegistryError("OPERATION_REJECTED", "An explicit discard is already in progress; retry session discard to complete it", { sessionId, state: record.state, terminalOperation: "discard", safeActions: ["retry-discard"] });
+            }
+            if (operation === "discard" && record.state === "closed" && record.terminalOperation !== "discard") {
+                throw new SessionRegistryError("OPERATION_REJECTED", "The selected session was already closed normally; discard cannot be retroactively applied", { sessionId, state: record.state, terminalOperation: "close" });
+            }
+            if (operation === "discard" && record.state === "closing" && record.terminalOperation !== "discard") {
+                throw new SessionRegistryError("OPERATION_REJECTED", "The selected session has an ordinary close in progress; retry close before choosing discard", { sessionId, state: record.state, safeActions: ["retry-close", "retain-session"] });
+            }
+            const blocker = observedDiagnostic?.blockers[0];
+            if (blocker !== undefined) {
+                throw enrichCloseBlockerError(new SessionRegistryError(blocker.code, blocker.message, {
+                    ...blocker.details,
+                    recoveryHints: [...blocker.recoveryHints],
+                    safeActions: [...blocker.safeActions],
+                }));
+            }
+            throw this.lifecycleActorRejection(record, result.decision, evidence);
+        }
+        if (result.error !== undefined)
+            throw result.error;
+        if (result.phase !== "completed" || result.value === undefined) {
+            throw new SessionRegistryError("OPERATION_REJECTED", "Lifecycle cleanup did not finalize", {
+                sessionId,
+                operation,
+                phase: result.phase,
+                reconciliation: result.reconciliation,
+            });
+        }
+        return result.value;
+    }
+    /** Build an actor input from one authoritative registry/physical diagnostic. */
+    lifecycleActorInputUnsafe(record, state, evidence, gcAuthorized, phase, diagnosticSink, resourcesSink) {
+        const diagnostic = this.diagnoseUnsafe(record, state, evidence, resourcesSink);
+        diagnosticSink?.(diagnostic);
+        return {
+            persisted: {
+                sessionId: record.sessionId,
+                state: record.state,
+                ...(record.terminalOperation === undefined ? {} : { terminalOperation: record.terminalOperation }),
+                ...(record.cleanupHead === undefined ? {} : { cleanupHead: record.cleanupHead }),
+                ...(record.discardedHead === undefined ? {} : { discardedHead: record.discardedHead }),
+            },
+            observation: {
+                sessionState: record.state,
+                physicalState: diagnostic.physicalState,
+                closeReadiness: diagnostic.closeReadiness === "not_due" ? "not-evaluated" : diagnostic.closeReadiness,
+                blockers: diagnostic.blockers.map((blocker) => ({ code: blocker.code })),
+                terminalOperation: record.terminalOperation,
+                ageSuspicious: diagnostic.garbageCollection.suspicion === "age",
+                gcAuthorized,
+                phase,
+            },
+        };
+    }
+    /** Preserve existing blocker/error contracts when the actor rejects a request. */
+    lifecycleActorRejection(record, decision, evidence) {
+        if (decision.operation === "close" || decision.operation === "discard" || decision.operation === "gc") {
+            try {
+                const resources = this.inspectCleanupResources(record, undefined, decision.operation === "close" ? evidence : undefined, decision.operation === "discard" ? "discard" : "close");
+                if (decision.operation === "discard" &&
+                    (resources.physicalState !== "healthy" || !resources.worktreePresent || !resources.branchPresent)) {
+                    throw ownershipMismatch(record, "Discard requires an unambiguous, currently owned worktree and branch", {
+                        physicalState: resources.physicalState,
+                        worktreePresent: resources.worktreePresent,
+                        branchPresent: resources.branchPresent,
+                        phase: "discard-preflight",
+                    });
+                }
+            }
+            catch (error) {
+                return enrichCloseBlockerError(error);
+            }
+        }
+        return new SessionRegistryError("OPERATION_REJECTED", "Lifecycle transition was rejected by the Session actor", {
+            sessionId: record.sessionId,
+            operation: decision.operation,
+            reason: decision.reason,
+            target: decision.target,
+        });
+    }
     resolveOwnerSession(records) {
         const matches = records.filter((record) => CURRENT_SESSION_STATES.has(record.state) && record.worktreeId === this.repository.worktreePath);
         if (matches.length === 1)
@@ -1916,7 +2284,7 @@ export class SessionRegistry {
         }
         return candidates;
     }
-    closeUnsafe(sessionId, evidence, cleanupOperation = "close") {
+    closeUnsafe(sessionId, evidence, cleanupOperation = "close", initialResources) {
         const state = this.readStateUnsafe();
         const records = state.sessions;
         const record = records.find((candidate) => candidate.sessionId === sessionId);
@@ -1939,7 +2307,7 @@ export class SessionRegistry {
         }
         let resources;
         try {
-            resources = this.inspectCleanupResources(record, undefined, evidence);
+            resources = initialResources ?? this.inspectCleanupResources(record, undefined, evidence);
         }
         catch (error) {
             throw enrichCloseBlockerError(error);
@@ -2237,7 +2605,7 @@ export class SessionRegistry {
             lifecycle,
         });
     }
-    diagnoseUnsafe(record, state, evidence) {
+    diagnoseUnsafe(record, state, evidence, resourcesSink) {
         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
@@ -2257,6 +2625,7 @@ export class SessionRegistry {
             });
             const nextActions = projectSessionLifecycleActions({ classification: lifecycle, sessionId: record.sessionId });
             const garbageCollection = closedGarbageCollectionAssessment(record, now);
+            const projectedGarbageCollection = projectGarbageCollectCandidateLifecycle(garbageCollection, lifecycle, []);
             return Object.freeze({
                 schemaVersion: SESSION_DIAGNOSTIC_SCHEMA_VERSION,
                 operation: "diagnostic",
@@ -2275,7 +2644,7 @@ export class SessionRegistry {
                 ...(nextActions.length === 0 ? {} : { nextAction: nextActions[0] }),
                 nextActions,
                 integrationEvidence: Object.freeze(integrationEvidence),
-                garbageCollection,
+                garbageCollection: projectedGarbageCollection,
                 lifecycle,
             });
         }
@@ -2290,6 +2659,7 @@ export class SessionRegistry {
             garbageCollection = assessGarbageCollection(record, now, this.staleAfterMs, worktrees);
             staleCandidate = garbageCollection.destructiveEligibility === "eligible";
             const resources = this.inspectCleanupResources(record, worktrees, evidence);
+            resourcesSink?.(resources);
             integrationProof = resources.integrationProof;
         }
         catch (error) {
@@ -2307,6 +2677,7 @@ export class SessionRegistry {
             ageSuspicious: Date.parse(now) - Date.parse(record.updatedAt) >= this.staleAfterMs,
             phase: "termination",
         });
+        garbageCollection = projectGarbageCollectCandidateLifecycle(garbageCollection, lifecycle, blockers);
         const safeActions = blockers.length > 0
             ? sortStrings(Array.from(new Set(blockers.flatMap((blocker) => blocker.safeActions))))
             : closeReadiness === "ready"
@@ -2988,6 +3359,17 @@ function assessGarbageCollection(record, now, staleAfterMs, worktrees) {
         destructiveEligibility = "ineligible";
         destructiveEligibilityReason = "age-only";
     }
+    const lifecycle = projectGarbageCollectAuthorization({
+        state: record.state,
+        physicalState: worktreeState.kind,
+        terminalOperation: record.terminalOperation,
+        suspicion,
+        destructiveEligibility,
+    });
+    const nextActions = projectSessionLifecycleActions({
+        classification: lifecycle,
+        sessionId: record.sessionId,
+    });
     return Object.freeze({
         ...cloneSessionRecord(record),
         physicalState: worktreeState.kind,
@@ -2995,9 +3377,35 @@ function assessGarbageCollection(record, now, staleAfterMs, worktrees) {
         suspicionReason,
         destructiveEligibility,
         destructiveEligibilityReason,
+        lifecycle,
+        nextActions,
+    });
+}
+/** Evaluate GC's independent authorization through the canonical machine. */
+function projectGarbageCollectAuthorization(candidate) {
+    return classifySessionLifecycle({
+        sessionState: candidate.state,
+        physicalState: candidate.physicalState,
+        closeReadiness: "ready",
+        blockers: [],
+        terminalOperation: candidate.terminalOperation,
+        ageSuspicious: candidate.suspicion === "age",
+        gcAuthorized: candidate.destructiveEligibility === "eligible",
+        phase: "termination",
     });
 }
 function closedGarbageCollectionAssessment(record, now) {
+    const lifecycle = classifySessionLifecycle({
+        sessionState: record.state,
+        physicalState: "closed",
+        closeReadiness: "ready",
+        terminalOperation: record.terminalOperation,
+        phase: "termination",
+    });
+    const nextActions = projectSessionLifecycleActions({
+        classification: lifecycle,
+        sessionId: record.sessionId,
+    });
     return Object.freeze({
         ...cloneSessionRecord(record),
         physicalState: "closed",
@@ -3005,6 +3413,8 @@ function closedGarbageCollectionAssessment(record, now) {
         suspicionReason: "none",
         destructiveEligibility: "ineligible",
         destructiveEligibilityReason: "not-suspected",
+        lifecycle,
+        nextActions,
     });
 }
 function isDestructiveGcEligible(record, worktrees) {
@@ -3166,6 +3576,15 @@ function toCleanupBlocker(error) {
         recoveryHints: Object.freeze(recoveryHints),
     });
 }
+/** Keep the nested GC assessment on the same observed lifecycle snapshot. */
+function projectGarbageCollectCandidateLifecycle(candidate, lifecycle, blockers) {
+    const nextActions = projectSessionLifecycleActions({
+        classification: lifecycle,
+        sessionId: candidate.sessionId,
+        blockers,
+    });
+    return Object.freeze({ ...candidate, lifecycle, nextActions });
+}
 function toDiagnosticBlocker(error) {
     const blocker = toCleanupBlocker(error);
     return Object.freeze({