@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

package/src/developer-agent/handoff.js

@@ -0,0 +1,698 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeveloperAgentHandoffError = exports.DEVELOPER_AGENT_RESUME_BINDINGS = exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_MAX_BYTES = exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_KIND = void 0;
+exports.parseDeveloperAgentHandoff = parseDeveloperAgentHandoff;
+exports.assessDeveloperAgentHandoffResume = assessDeveloperAgentHandoffResume;
+exports.inspectDeveloperAgentHandoffResume = inspectDeveloperAgentHandoffResume;
+exports.formatDeveloperAgentResumeAssessment = formatDeveloperAgentResumeAssessment;
+const node_buffer_1 = require("node:buffer");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const context_js_1 = require("./context.js");
+const generator_planning_js_1 = require("./generator-planning.js");
+const index_js_1 = require("../testing-evidence/index.js");
+const model_js_1 = require("./model.js");
+const ordering_js_1 = require("./ordering.js");
+const validation_js_1 = require("./validation.js");
+exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_KIND = 'developer-agent-resume-assessment';
+exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_MAX_BYTES = 60 * 1024;
+exports.DEVELOPER_AGENT_RESUME_BINDINGS = [
+    'repository',
+    'framework',
+    'blueprints',
+    'git',
+    'policy',
+    'markers',
+    'candidate-provenance',
+    'ownership',
+    'selection',
+    'operation',
+    'verification',
+    'evidence',
+    'external-state',
+];
+class DeveloperAgentHandoffError extends Error {
+    classification;
+    constructor(classification, message) {
+        super(message);
+        this.classification = classification;
+        this.name = 'DeveloperAgentHandoffError';
+    }
+}
+exports.DeveloperAgentHandoffError = DeveloperAgentHandoffError;
+const MAX_RETAINED_EVIDENCE_BYTES = 1024 * 1024;
+const FAILURE_ORDER = new Map(model_js_1.DEVELOPER_AGENT_FAILURE_CLASSIFICATIONS.map((classification, index) => [
+    classification,
+    index,
+]));
+const BLOCKING_CONTEXT_WARNINGS = new Set(model_js_1.DEVELOPER_AGENT_FAILURE_CLASSIFICATIONS.filter((classification) => classification !== 'unsupported-operation'));
+const CONTEXT_WARNING_SUMMARIES = {
+    'authority-required': 'The current context requires authority that the retained handoff does not grant.',
+    'cleanup-incomplete': 'The current context reports incomplete cleanup and cannot be resumed automatically.',
+    'dirty-worktree': 'The current worktree is dirty and must be reconciled before resumption.',
+    'external-proof-pending': 'The current context reports separately retained external proof as pending.',
+    'generated-drift': 'The current context reports generated-source drift.',
+    'invalid-input': 'The current context reports an invalid retained input.',
+    'marker-blocked': 'The current context reports a blocking work marker.',
+    'ownership-conflict': 'The current context reports an ownership conflict.',
+    'policy-conflict': 'The current context reports a repository-policy conflict.',
+    'prerequisite-missing': 'The current context is missing a required framework prerequisite.',
+    'stale-base': 'The current Git base or branch is stale.',
+    'tool-internal-error': 'The current context could not be established safely.',
+    'unsupported-operation': 'The current context contains an unsupported operation.',
+    'verification-failed': 'The current context reports failed required verification.',
+};
+function isContainedPath(root, candidate) {
+    const fromRoot = (0, node_path_1.relative)(root, candidate);
+    return (fromRoot === '' ||
+        (fromRoot !== '..' &&
+            !fromRoot.startsWith(`..${node_path_1.sep}`) &&
+            !(0, node_path_1.isAbsolute)(fromRoot)));
+}
+function readRetainedEvidenceFile(workspaceRoot, reference, maximumBytes, requirePrivate = false) {
+    const root = (0, node_fs_1.realpathSync)(workspaceRoot);
+    if ((0, node_path_1.isAbsolute)(reference) ||
+        reference.includes('\\') ||
+        reference
+            .split('/')
+            .some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error('non-canonical retained evidence reference');
+    }
+    const absolute = (0, node_path_1.resolve)(root, ...reference.split('/'));
+    if (!isContainedPath(root, absolute)) {
+        throw new Error('retained evidence escapes workspace');
+    }
+    const entry = (0, node_fs_1.lstatSync)(absolute);
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+        throw new Error('retained evidence is not a regular file');
+    }
+    const real = (0, node_fs_1.realpathSync)(absolute);
+    if (!isContainedPath(root, real)) {
+        throw new Error('retained evidence resolves outside workspace');
+    }
+    const descriptor = (0, node_fs_1.openSync)(real, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = (0, node_fs_1.fstatSync)(descriptor);
+        const currentUser = typeof process.getuid === 'function' ? process.getuid() : undefined;
+        if (!before.isFile() ||
+            before.size < 0 ||
+            before.size > maximumBytes ||
+            (requirePrivate &&
+                process.platform !== 'win32' &&
+                ((currentUser !== undefined && before.uid !== currentUser) ||
+                    (before.mode & 0o077) !== 0))) {
+            throw new Error('retained evidence exceeds its fixed bound');
+        }
+        const bytes = node_buffer_1.Buffer.alloc(before.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = (0, node_fs_1.readSync)(descriptor, bytes, offset, bytes.length - offset, offset);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        const after = (0, node_fs_1.fstatSync)(descriptor);
+        if (offset !== bytes.length ||
+            after.dev !== before.dev ||
+            after.ino !== before.ino ||
+            after.size !== before.size ||
+            after.mtimeMs !== before.mtimeMs ||
+            after.ctimeMs !== before.ctimeMs) {
+            throw new Error('retained evidence changed during inspection');
+        }
+        return {
+            bytes,
+            digest: `sha256:${(0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex')}`,
+            realpath: real,
+        };
+    }
+    finally {
+        (0, node_fs_1.closeSync)(descriptor);
+    }
+}
+function inspectRetainedEvidence(workspaceRoot, handoff) {
+    const cache = new Map();
+    const identities = new Set();
+    const inspect = (reference, expectedDigest, maximumBytes = MAX_RETAINED_EVIDENCE_BYTES) => {
+        const retained = cache.get(reference) ??
+            readRetainedEvidenceFile(workspaceRoot, reference, maximumBytes);
+        cache.set(reference, retained);
+        if (retained.bytes.length > maximumBytes ||
+            retained.digest !== expectedDigest) {
+            throw new Error('retained evidence identity mismatch');
+        }
+        identities.add(`${reference}\u0000${retained.realpath}\u0000${retained.digest}`);
+        return retained;
+    };
+    try {
+        for (const result of handoff.results) {
+            for (const artifact of result.artifacts) {
+                inspect(artifact.reference, artifact.digest);
+            }
+            if (!result.testingEvidence)
+                continue;
+            const retained = inspect(result.testingEvidence.reference, result.testingEvidence.digest, index_js_1.TESTING_EVIDENCE_RESULT_MAX_BYTES);
+            let parsed;
+            try {
+                parsed = JSON.parse(retained.bytes.toString('utf8'));
+            }
+            catch {
+                throw new Error('retained Testing/Evidence is not JSON');
+            }
+            const validation = (0, index_js_1.validateTestingEvidenceResult)(parsed);
+            if (!validation.valid ||
+                !(0, node_util_1.isDeepStrictEqual)(validation.value, result.testingEvidence.result)) {
+                throw new Error('retained Testing/Evidence result mismatch');
+            }
+        }
+        for (const operation of handoff.operations) {
+            const input = operation.generatorInput;
+            if (input?.generator !== 'upgrade' || input.preview === undefined) {
+                continue;
+            }
+            const retained = readRetainedEvidenceFile(workspaceRoot, input.preview.reference, model_js_1.DEVELOPER_AGENT_GENERATOR_PREVIEW_RECEIPT_MAX_BYTES, true);
+            cache.set(input.preview.reference, retained);
+            identities.add(`${input.preview.reference}\u0000${retained.realpath}\u0000${retained.digest}`);
+            let parsed;
+            try {
+                parsed = JSON.parse(retained.bytes.toString('utf8'));
+            }
+            catch {
+                throw new Error('retained Upgrade preview is not JSON');
+            }
+            const validation = (0, validation_js_1.validateDeveloperAgentGeneratorPreview)(parsed);
+            if (!validation.valid ||
+                retained.digest !== input.preview.digest ||
+                validation.value.input.name !== input.name) {
+                throw new Error('retained Upgrade preview identity mismatch');
+            }
+        }
+        return { findings: [], identities: [...identities].sort() };
+    }
+    catch {
+        return {
+            findings: [
+                {
+                    binding: 'evidence',
+                    classification: 'verification-failed',
+                    sanitizedSummary: 'A retained evidence reference is missing, changed, invalid, or does not match its nested result.',
+                },
+            ],
+            identities: [],
+        };
+    }
+}
+function invalidInput(message) {
+    throw new DeveloperAgentHandoffError('invalid-input', message);
+}
+function compareStrings(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sortedLeft = [...left].sort();
+    const sortedRight = [...right].sort();
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+function compareVersions(retained, current) {
+    const normalize = (records) => records.map(({ name, version }) => `${name}\u0000${version}`).sort();
+    return compareStrings(normalize(retained), normalize(current));
+}
+function compareCandidateReference(retained, current) {
+    if (!retained || !current)
+        return retained === current;
+    return (retained.reference === current.reference &&
+        retained.digest === current.digest);
+}
+function copyNextSafeAction(value, command) {
+    return {
+        approvalRequired: value.approvalRequired,
+        authority: value.authority,
+        ...(command
+            ? {
+                command: {
+                    args: [...command.args],
+                    ...(command.cwd ? { cwd: command.cwd } : {}),
+                    executable: command.executable,
+                },
+            }
+            : {}),
+        description: value.description,
+        ...(value.operationId ? { operationId: value.operationId } : {}),
+        ...(value.owner ? { owner: value.owner } : {}),
+    };
+}
+function blockedNextSafeAction(classification) {
+    const description = {
+        'dirty-worktree': 'Review and reconcile the current worktree without discarding changes, then inspect the handoff again.',
+        'generated-drift': 'Reconcile generated ownership and version drift, then create or inspect a new retained handoff.',
+        'marker-blocked': 'Resolve or explicitly retain the blocking work marker before continuing.',
+        'ownership-conflict': 'Return to the retained repository worktree or reconcile its ownership records before continuing.',
+        'policy-conflict': 'Reconcile the Repository Operating Policy and inspect the retained handoff again.',
+        'prerequisite-missing': 'Restore the required local framework prerequisites, then inspect the retained handoff again.',
+        'stale-base': 'Restore the exact retained branch, base, and head relationship or create a new reviewed handoff.',
+    };
+    return {
+        approvalRequired: false,
+        authority: 'read-only',
+        description: description[classification] ??
+            'Inspect and reconcile the reported conflict before continuing.',
+    };
+}
+function uniqueSortedFindings(values) {
+    const seen = new Set();
+    return values
+        .filter(({ binding, classification, sanitizedSummary, status }) => {
+        const key = `${binding ?? ''}\u0000${classification}\u0000${status ?? 'conflict'}\u0000${sanitizedSummary}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
+        .sort((left, right) => (FAILURE_ORDER.get(left.classification) ?? Number.MAX_SAFE_INTEGER) -
+        (FAILURE_ORDER.get(right.classification) ??
+            Number.MAX_SAFE_INTEGER) ||
+        (0, ordering_js_1.compareDeveloperAgentStrings)(left.binding ?? '', right.binding ?? '') ||
+        (0, ordering_js_1.compareDeveloperAgentStrings)(left.sanitizedSummary, right.sanitizedSummary));
+}
+function allBindings(findings, statusWhenUnmentioned) {
+    return exports.DEVELOPER_AGENT_RESUME_BINDINGS.map((name) => {
+        const finding = findings.find(({ binding }) => binding === name);
+        return finding
+            ? {
+                classification: finding.classification,
+                name,
+                status: finding.status ?? 'conflict',
+            }
+            : { name, status: statusWhenUnmentioned };
+    });
+}
+function createAssessment(handoff, findingsInput, statusWhenUnmentioned, readyNextSafeAction) {
+    const findings = uniqueSortedFindings(findingsInput);
+    const failureClassification = findings[0]?.classification;
+    const assessment = {
+        bindings: allBindings(findings, statusWhenUnmentioned),
+        ...(failureClassification ? { failureClassification } : {}),
+        findings: findings.map(({ classification, sanitizedSummary }) => ({
+            classification,
+            sanitizedSummary,
+        })),
+        handoffState: handoff.state,
+        kind: exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_KIND,
+        nextSafeAction: failureClassification
+            ? blockedNextSafeAction(failureClassification)
+            : (readyNextSafeAction ?? copyNextSafeAction(handoff.nextSafeAction)),
+        resumeAllowed: failureClassification === undefined,
+        schemaVersion: model_js_1.DEVELOPER_AGENT_CONTRACT_SCHEMA_VERSION,
+        status: failureClassification ? 'blocked' : 'ready',
+        workReference: handoff.work.reference,
+    };
+    if (node_buffer_1.Buffer.byteLength(JSON.stringify(assessment), 'utf8') >
+        exports.DEVELOPER_AGENT_RESUME_ASSESSMENT_MAX_BYTES) {
+        throw new DeveloperAgentHandoffError('tool-internal-error', 'Developer-Agent resume assessment exceeded its fixed output bound.');
+    }
+    return assessment;
+}
+/**
+ * Parses a retained handoff without retaining logs, transcripts, environment
+ * values, or unknown fields. Validation issues are reported by path only so an
+ * invalid value is never reflected into diagnostic output.
+ */
+function parseDeveloperAgentHandoff(serialized) {
+    if (node_buffer_1.Buffer.byteLength(serialized, 'utf8') > model_js_1.DEVELOPER_AGENT_HANDOFF_MAX_BYTES) {
+        return invalidInput(`Retained Developer-Agent handoff exceeds ${model_js_1.DEVELOPER_AGENT_HANDOFF_MAX_BYTES} bytes.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(serialized);
+    }
+    catch {
+        return invalidInput('Retained Developer-Agent handoff is not valid JSON.');
+    }
+    const validation = (0, validation_js_1.validateDeveloperAgentHandoff)(value);
+    if (!validation.valid) {
+        const firstPath = validation.issues[0]?.path ?? '$';
+        return invalidInput(`Retained Developer-Agent handoff is invalid at ${firstPath}.`);
+    }
+    const handoff = validation.value;
+    const sentinelPath = /^(?:0{40}|0{64})$/.test(handoff.repository.baseCommit)
+        ? '$.repository.baseCommit'
+        : /^(?:0{40}|0{64})$/.test(handoff.repository.headCommit)
+            ? '$.repository.headCommit'
+            : handoff.repository.branch.includes('REPLACE_WITH_')
+                ? '$.repository.branch'
+                : handoff.repository.worktree.includes('REPLACE_WITH_')
+                    ? '$.repository.worktree'
+                    : handoff.work.acceptanceCriteriaRevision.includes('REPLACE_WITH_')
+                        ? '$.work.acceptanceCriteriaRevision'
+                        : handoff.work.reference.includes('REPLACE_WITH_')
+                            ? '$.work.reference'
+                            : handoff.versions.effectivePolicyDigest ===
+                                `sha256:${'0'.repeat(64)}`
+                                ? '$.versions.effectivePolicyDigest'
+                                : handoff.versions.candidateEvidenceReference?.digest ===
+                                    `sha256:${'0'.repeat(64)}`
+                                    ? '$.versions.candidateEvidenceReference.digest'
+                                    : undefined;
+    if (sentinelPath) {
+        return invalidInput(`Retained Developer-Agent handoff contains an unresolved template sentinel at ${sentinelPath}.`);
+    }
+    return handoff;
+}
+/**
+ * Compares a validated handoff to a newly inspected repository context. The
+ * function is pure: it neither changes Git nor executes the retained next
+ * action. A different process or agent session receives the same assessment
+ * from the same retained document and repository facts.
+ */
+function assessDeveloperAgentHandoffResumeInternal(handoff, current, evidenceInspection) {
+    const validation = (0, validation_js_1.validateDeveloperAgentHandoff)(handoff);
+    if (!validation.valid) {
+        const firstPath = validation.issues[0]?.path ?? '$';
+        return invalidInput(`Retained Developer-Agent handoff is invalid at ${firstPath}.`);
+    }
+    const contextValidation = (0, validation_js_1.validateDeveloperAgentContext)(current);
+    if (!contextValidation.valid) {
+        return createAssessment(validation.value, [
+            {
+                classification: 'tool-internal-error',
+                sanitizedSummary: 'The newly inspected Developer-Agent context is not a valid bounded contract document.',
+            },
+        ], 'unchecked');
+    }
+    current = contextValidation.value;
+    const findings = [];
+    const add = (binding, classification, sanitizedSummary) => findings.push({ binding, classification, sanitizedSummary });
+    const hasRetainedEvidence = handoff.results.some((result) => result.artifacts.length > 0 || result.testingEvidence);
+    if (hasRetainedEvidence && evidenceInspection === undefined) {
+        findings.push({
+            binding: 'evidence',
+            classification: 'verification-failed',
+            sanitizedSummary: 'Retained evidence has not been reopened and digest-verified for this resume assessment.',
+            status: 'unchecked',
+        });
+    }
+    else if (evidenceInspection) {
+        findings.push(...evidenceInspection.findings);
+    }
+    if (handoff.externalState.length > 0) {
+        findings.push({
+            binding: 'external-state',
+            classification: 'cleanup-incomplete',
+            sanitizedSummary: 'Retained external state cannot be resumed without an owning status inspector.',
+            status: 'unchecked',
+        });
+    }
+    const nestedWorktreesMatch = handoff.results.every(({ source }) => source.worktree === handoff.repository.worktree);
+    if (current.workspace.identity !== handoff.repository.identity ||
+        current.workspace.repositoryRoot !== handoff.repository.worktree ||
+        current.git.worktreeRoot !== handoff.repository.worktree ||
+        !nestedWorktreesMatch) {
+        add('repository', 'ownership-conflict', 'The retained repository/worktree identity does not match the current context.');
+    }
+    const currentProjects = current.projects.map(({ name }) => name);
+    const currentAffectedTargets = current.affected?.targets ?? [];
+    const currentAffectedFiles = current.affected?.files ?? [];
+    if (current.affected === undefined ||
+        !compareStrings(handoff.selection.projects, currentProjects) ||
+        handoff.selection.slice !== current.selection.slice ||
+        handoff.selection.feature !== current.selection.feature ||
+        !compareStrings(handoff.selection.affectedTargets, currentAffectedTargets) ||
+        !compareStrings(handoff.changedFiles, currentAffectedFiles)) {
+        add('selection', 'ownership-conflict', 'The retained project, Slice, feature, affected-file, or affected-target selection differs from current Nx context.');
+    }
+    if (current.workspace.frameworkVersion !== handoff.versions.frameworkVersion) {
+        add('framework', 'generated-drift', 'The installed framework version differs from the retained handoff.');
+    }
+    if (!compareVersions(handoff.versions.blueprintVersions, current.workspace.blueprintVersions)) {
+        add('blueprints', 'generated-drift', 'The installed Blueprint versions differ from the retained handoff.');
+    }
+    const nestedCommitsMatch = handoff.results.every(({ source, testingEvidence }) => source.commit === handoff.repository.headCommit &&
+        (!testingEvidence ||
+            testingEvidence.result.source.commit === source.commit));
+    const staleGit = current.git.branch !== handoff.repository.branch ||
+        current.git.baseCommit !== handoff.repository.baseCommit ||
+        current.git.defaultBaseCommit !== handoff.repository.baseCommit ||
+        current.git.defaultBaseRef !== handoff.repository.baseRef ||
+        current.git.headCommit !== handoff.repository.headCommit ||
+        current.git.commit !== handoff.repository.headCommit ||
+        current.affected?.baseCommit !== handoff.repository.baseCommit ||
+        current.affected?.headCommit !== handoff.repository.headCommit ||
+        current.git.behind > 0 ||
+        !nestedCommitsMatch;
+    if (staleGit) {
+        add('git', 'stale-base', 'The retained branch/default-base/head binding does not match the current Git and affected context.');
+    }
+    if (current.git.dirty) {
+        add('git', 'dirty-worktree', 'The current worktree is dirty and cannot be adopted by a resumed session.');
+    }
+    if (current.policy.canonicalStage !== handoff.versions.canonicalStage ||
+        current.policy.effectivePolicyDigest !==
+            handoff.versions.effectivePolicyDigest ||
+        !compareStrings(handoff.versions.policyReferences, current.policy.effectivePolicyReferences)) {
+        add('policy', 'policy-conflict', 'The effective policy references differ from the retained handoff.');
+    }
+    const retainedMarkers = handoff.markerSnapshot.map(({ blocking, reference }) => `${blocking ? 'blocking' : 'nonblocking'}\0${reference}`);
+    const currentMarkers = current.markers.map(({ blocking, reference }) => `${blocking ? 'blocking' : 'nonblocking'}\0${reference}`);
+    if (!compareStrings(retainedMarkers, currentMarkers) ||
+        current.markers.some(({ blocking }) => blocking)) {
+        add('markers', 'marker-blocked', 'Current work markers do not match the retained non-blocking marker set.');
+    }
+    if (!compareCandidateReference(handoff.versions.candidateEvidenceReference, current.workspace.candidateProvenance)) {
+        add('candidate-provenance', 'generated-drift', 'The candidate provenance reference differs from the retained handoff.');
+    }
+    if (current.workspace.ownershipAgreement !== 'agrees') {
+        add('ownership', 'ownership-conflict', 'The current ownership and installed-package records do not agree.');
+    }
+    const reboundOperations = handoff.operations.flatMap((retained) => {
+        const operation = current.supportedOperations.find(({ id }) => id === retained.id);
+        if (!operation) {
+            add('operation', 'unsupported-operation', 'One retained performed operation is not supported by the current context.');
+            return [];
+        }
+        let reboundAuthority = operation.authority;
+        let currentContracts = operation.contracts;
+        let currentProjectsForOperation = operation.projects;
+        let currentVerification = operation.requiredVerification;
+        if (operation.owner === 'nx-generator') {
+            if (!retained.generatorInput) {
+                add('operation', 'ownership-conflict', 'One retained typed generator operation lacks its closed generator identity.');
+                return [];
+            }
+            try {
+                const rebound = (0, generator_planning_js_1.rebindDeveloperAgentGeneratorPlan)(current, operation, retained.generatorInput);
+                reboundAuthority = rebound.authority ?? operation.authority;
+                currentContracts = rebound.contracts;
+                currentProjectsForOperation = rebound.projects;
+                currentVerification = rebound.verification;
+                if (currentVerification.some((target) => !current.authenticatedTargets.includes(target))) {
+                    add('operation', 'unsupported-operation', 'One retained typed generator verification target is not authenticated by the current registry.');
+                    return [];
+                }
+            }
+            catch (error) {
+                add('operation', error instanceof generator_planning_js_1.DeveloperAgentGeneratorPlanError
+                    ? error.classification
+                    : 'ownership-conflict', 'One retained typed generator operation cannot be rebound to current repository facts.');
+                return [];
+            }
+        }
+        if (reboundAuthority !== retained.authority ||
+            operation.owner !== retained.owner) {
+            add('operation', 'authority-required', 'One retained performed operation differs from current owning-tool authority.');
+            return [];
+        }
+        const currentScope = {
+            contracts: currentContracts
+                .map(({ class: contractClass, reference }) => `${contractClass}\u0000${reference}`)
+                .sort(),
+            evidenceClasses: [...operation.evidenceClasses].sort(),
+            projects: [...currentProjectsForOperation].sort(),
+            requiredVerification: [...currentVerification].sort(),
+        };
+        const retainedScope = {
+            contracts: retained.scope.contracts
+                .map(({ class: contractClass, reference }) => `${contractClass}\u0000${reference}`)
+                .sort(),
+            evidenceClasses: [...retained.scope.evidenceClasses].sort(),
+            projects: [...retained.scope.projects].sort(),
+            requiredVerification: [...retained.scope.requiredVerification].sort(),
+        };
+        if (!(0, node_util_1.isDeepStrictEqual)(currentScope, retainedScope)) {
+            add('operation', 'ownership-conflict', 'One retained performed operation scope differs from the current registry scope.');
+            return [];
+        }
+        if (retained.scope.projects.some((project) => !currentProjects.includes(project))) {
+            add('selection', 'ownership-conflict', 'One retained effective operation names a project outside the current Nx graph.');
+            return [];
+        }
+        if (!operation.applicableStages.includes(current.policy.canonicalStage)) {
+            add('policy', 'policy-conflict', 'One retained performed operation is not applicable to the current canonical stage.');
+            return [];
+        }
+        if (operation.policyLifecycleAction) {
+            const decision = current.policy.effectiveDecisions.find(({ action, projects, stage }) => action === operation.policyLifecycleAction &&
+                stage === current.policy.canonicalStage &&
+                operation.projects.every((project) => projects.includes(project)));
+            if (!decision?.allowed) {
+                add('policy', 'policy-conflict', 'One retained performed operation is denied by the current effective lifecycle policy.');
+                return [];
+            }
+        }
+        const matchingResults = handoff.results.filter(({ operation: resultOperation }) => resultOperation.name === retained.id);
+        const operationContracts = retained.scope.contracts.map((contract) => `${contract.class}\u0000${contract.reference}`);
+        if (matchingResults.length === 0 ||
+            matchingResults.some((result) => result.outcome !== 'blocked' &&
+                (!compareStrings(retained.scope.projects, result.affected.projects) ||
+                    !compareStrings(operationContracts, result.affected.contracts.map((retainedContract) => `${retainedContract.class}\u0000${retainedContract.reference}`))))) {
+            add('selection', 'ownership-conflict', 'One retained result does not include its rebound operation project and contract scope.');
+            return [];
+        }
+        return [{ ...operation, authority: reboundAuthority }];
+    });
+    if (reboundOperations.length === handoff.operations.length) {
+        const expectedVerification = handoff.state === 'proposal-or-research-only'
+            ? []
+            : [
+                ...new Set(handoff.operations.flatMap(({ scope }) => scope.requiredVerification)),
+            ];
+        if (!compareStrings(handoff.requiredVerification, expectedVerification)) {
+            add('verification', 'verification-failed', 'Retained required verification differs from current performed-operation requirements.');
+        }
+        const expectedEvidence = handoff.state === 'proposal-or-research-only'
+            ? []
+            : [
+                ...new Set(handoff.operations.flatMap(({ scope }) => scope.evidenceClasses)),
+            ];
+        if (!compareStrings(handoff.requiredEvidence, expectedEvidence)) {
+            add('evidence', 'verification-failed', 'Retained required evidence differs from current performed-operation requirements.');
+        }
+    }
+    for (const warning of current.warnings) {
+        if (!BLOCKING_CONTEXT_WARNINGS.has(warning.classification))
+            continue;
+        const binding = warning.classification === 'dirty-worktree' ||
+            warning.classification === 'stale-base'
+            ? 'git'
+            : warning.classification === 'generated-drift'
+                ? 'framework'
+                : warning.classification === 'policy-conflict'
+                    ? 'policy'
+                    : warning.classification === 'marker-blocked'
+                        ? 'markers'
+                        : 'ownership';
+        add(binding, warning.classification, CONTEXT_WARNING_SUMMARIES[warning.classification]);
+    }
+    let reboundNextSafeAction = copyNextSafeAction(handoff.nextSafeAction);
+    if (handoff.nextSafeAction.operationId) {
+        const operation = current.supportedOperations.find(({ id }) => id === handoff.nextSafeAction.operationId);
+        if (!operation) {
+            add('operation', 'unsupported-operation', 'The retained next operation is not supported by the current context.');
+        }
+        else if (operation.owner === 'nx-generator') {
+            add('operation', 'unsupported-operation', 'Typed generator operations require fresh typed inputs and cannot be resumed from a handoff.');
+        }
+        else if (operation.authority !== handoff.nextSafeAction.authority ||
+            operation.approvalRequired !== handoff.nextSafeAction.approvalRequired ||
+            operation.owner !== handoff.nextSafeAction.owner) {
+            add('operation', 'authority-required', 'The retained next operation authority differs from the current owning tool.');
+        }
+        else if (!operation.applicableStages.includes(current.policy.canonicalStage)) {
+            add('policy', 'policy-conflict', 'The retained next operation is not applicable to the current canonical stage.');
+        }
+        else if (operation.policyLifecycleAction &&
+            !current.policy.effectiveDecisions.some(({ action, allowed, projects, stage }) => action === operation.policyLifecycleAction &&
+                allowed &&
+                stage === current.policy.canonicalStage &&
+                operation.projects.every((project) => projects.includes(project)))) {
+            add('policy', 'policy-conflict', 'The retained next operation is denied by the current effective lifecycle policy.');
+        }
+        else {
+            reboundNextSafeAction = copyNextSafeAction(handoff.nextSafeAction, operation.authority === 'protected-mutate' ||
+                operation.authority === 'destructive'
+                ? undefined
+                : operation.command);
+        }
+    }
+    return createAssessment(validation.value, findings, 'match', reboundNextSafeAction);
+}
+function assessDeveloperAgentHandoffResume(handoff, current) {
+    return assessDeveloperAgentHandoffResumeInternal(handoff, current);
+}
+/**
+ * Re-inspects context for the exact retained base/head and candidate reference
+ * before producing an advisory resume assessment. No retained command is run.
+ */
+async function inspectDeveloperAgentHandoffResume(cwd, serializedHandoff, dependencyOverrides = {}) {
+    const handoff = parseDeveloperAgentHandoff(serializedHandoff);
+    const evidenceBefore = inspectRetainedEvidence(cwd, handoff);
+    const inspectContext = dependencyOverrides.inspectContext ??
+        ((root, contextQuery) => (0, context_js_1.inspectDeveloperAgentContext)(root, contextQuery));
+    let context;
+    try {
+        context = await inspectContext(cwd, {
+            ...(handoff.selection.affectedTargets.length > 0
+                ? { affectedTargets: handoff.selection.affectedTargets }
+                : {}),
+            base: handoff.repository.baseCommit,
+            ...(handoff.versions.candidateEvidenceReference
+                ? {
+                    candidateProvenancePath: handoff.versions.candidateEvidenceReference.reference,
+                }
+                : {}),
+            canonicalStage: handoff.versions.canonicalStage,
+            head: handoff.repository.headCommit,
+            ...(handoff.selection.feature
+                ? { selectedFeature: handoff.selection.feature }
+                : {}),
+            selectedProjects: handoff.selection.projects,
+            ...(handoff.selection.slice
+                ? { selectedSlice: handoff.selection.slice }
+                : {}),
+        });
+    }
+    catch (error) {
+        const classification = error instanceof context_js_1.DeveloperAgentContextError
+            ? error.classification
+            : error instanceof DeveloperAgentHandoffError
+                ? error.classification
+                : 'tool-internal-error';
+        return createAssessment(handoff, [
+            {
+                classification,
+                sanitizedSummary: CONTEXT_WARNING_SUMMARIES[classification],
+            },
+        ], 'unchecked');
+    }
+    const evidenceAfter = inspectRetainedEvidence(cwd, handoff);
+    const evidenceInspection = evidenceBefore.findings.length > 0
+        ? evidenceBefore
+        : evidenceAfter.findings.length > 0
+            ? evidenceAfter
+            : compareStrings(evidenceBefore.identities, evidenceAfter.identities)
+                ? evidenceAfter
+                : {
+                    findings: [
+                        {
+                            binding: 'evidence',
+                            classification: 'verification-failed',
+                            sanitizedSummary: 'A retained evidence reference changed identity during context inspection.',
+                        },
+                    ],
+                    identities: [],
+                };
+    return assessDeveloperAgentHandoffResumeInternal(handoff, context, evidenceInspection);
+}
+function formatDeveloperAgentResumeAssessment(assessment) {
+    const lines = [
+        `Handoff: ${assessment.workReference}`,
+        `State: ${assessment.handoffState}`,
+        `Resume: ${assessment.resumeAllowed ? 'allowed' : 'blocked'}`,
+    ];
+    for (const finding of assessment.findings) {
+        lines.push(`- [${finding.classification}] ${finding.sanitizedSummary}`);
+    }
+    lines.push(`Next: ${assessment.nextSafeAction.description}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=handoff.js.map