@devflow-tools/delivery-line 0.18.45 → 0.18.47

package/dist/facade/delivery-line-facade.js

@@ -53,6 +53,10 @@ function normalizeDecisionOptions(options) {
 function normalizeDecisionText(value) {
     return value.replace(/[\u0000-\u001f\u007f\ufffd]+/gu, ' ').replace(/\s+/gu, ' ').trim();
 }
+function intentFingerprint(input) {
+    const tokens = normalizeDecisionText(input.title).toLocaleLowerCase('en-US').split(/[^\p{L}\p{N}]+/u).filter(token => token.length > 1).sort();
+    return hash({ projectRoot: input.projectRoot, intent: [...new Set(tokens)] });
+}
 function optionsForExistingImplementations(paths) {
     const candidates = paths.slice(0, 3);
     return [
@@ -60,7 +64,7 @@ function optionsForExistingImplementations(paths) {
         ...candidates.map((path, index) => ({
             id: `existing-${index + 1}`,
             label: `Use existing implementation: ${path}`,
-            description: `Choose ${path}; the next question selects whether to extend, replace, or retain it.`,
+            description: `Choose ${path}; a follow-up asks whether to extend, replace, or retain it.`,
         })),
         ...(paths.length > candidates.length ? [{
                 id: 'existing-other',
@@ -69,13 +73,6 @@ function optionsForExistingImplementations(paths) {
             }] : []),
     ];
 }
-function optionsForExistingImplementationAction(path) {
-    return [
-        { id: 'extend', label: `Extend ${path}`, description: `Reuse ${path} and preserve its existing public behavior while adding the requested capability.` },
-        { id: 'replace', label: `Replace ${path}`, description: `Replace ${path}; the plan must preserve or explicitly revise every current behavior and caller.` },
-        { id: 'retain', label: `Retain ${path}`, description: `Keep ${path} unchanged and constrain the new work to a separate integration point.` },
-    ];
-}
 function nextActionsFor(record) {
     const nextActions = [];
     if (record.interaction.status === 'awaiting_user')
@@ -97,7 +94,9 @@ function nextActionsFor(record) {
         nextActions.push('approve');
     if (record.blockers?.some(blocker => blocker.code === 'WORKTREE_ADMISSION_REQUIRED'))
         nextActions.push('admit_worktree');
-    else if (record.blockers?.some(blocker => blocker.code === 'STALE_STACK_FACTS'))
+    else if (record.blockers?.some(blocker => blocker.code === 'REQUIRED_CONTEXT_MISSING'))
+        nextActions.push('repair_context');
+    else if (record.blockers?.some(blocker => blocker.code === 'STALE_STACK_FACTS' || blocker.code === 'HOST_MODEL_UNAVAILABLE' || blocker.code === 'HOST_AUTHENTICATION_REQUIRED'))
         nextActions.push('refresh_activation');
     else if (record.blockers?.some(blocker => blocker.code === 'EXTERNAL_CANDIDATE_REQUIRED'))
         nextActions.push('import_external_change');
@@ -113,6 +112,13 @@ function nextActionsFor(record) {
         nextActions.push('cancel');
     return nextActions;
 }
+function existingActionOptions(path) {
+    return [
+        { id: 'extend', label: `Extend ${path}`, description: `Reuse ${path} and preserve its existing public behavior while adding the requested capability.` },
+        { id: 'replace', label: `Replace ${path}`, description: `Replace ${path}; preserve or explicitly revise every current behavior and caller.` },
+        { id: 'retain', label: `Retain ${path}`, description: `Keep ${path} unchanged and constrain the new work to a separate integration point.` },
+    ];
+}
 function staleTurnError(record, receivedTurn) {
     const allowedActions = nextActionsFor(record);
     return new DeliveryLineError('STALE_INTERACTION_TURN', `interaction turn is stale; current turn is ${record.interaction.turn}`, {
@@ -208,6 +214,18 @@ export class DeliveryLineFacade {
         const projectRoot = this.projectRoot ?? input.projectRoot;
         const baseRef = this.ports.revision ? await this.ports.revision.resolveRevision({ repositoryPath: projectRoot, revision: input.baseRef }) : input.baseRef;
         const id = input.caseId ?? randomUUID();
+        const fingerprint = intentFingerprint({ projectRoot, title: input.title });
+        const duplicateFingerprint = await this.ports.store.findActiveCaseByFingerprint?.({ sessionId: input.sessionId, projectRoot, intentFingerprint: fingerprint });
+        if (duplicateFingerprint && !input.caseId) {
+            if (input.contextReceipt && duplicateFingerprint.contextReceipt !== input.contextReceipt)
+                throw new DeliveryLineError('MISSING_PREREQUISITE', 'context receipt is not authoritative');
+            if (duplicateFingerprint.baseRef !== baseRef || duplicateFingerprint.targetRef !== input.targetRef)
+                throw new DeliveryLineError('IDEMPOTENCY_CONFLICT', 'active intent is bound to a different repository target');
+            return this.view(duplicateFingerprint);
+        }
+        const priorCase = await this.ports.store.findCaseBySessionAndTitle?.({ sessionId: input.sessionId, projectRoot, title: input.title });
+        if (priorCase && !input.caseId)
+            return this.view(priorCase);
         if (await this.ports.store.hasIdempotencyKey(input.idempotencyKey)) {
             const existing = await this.ports.store.findCaseByIdempotencyKey?.(input.idempotencyKey);
             if (existing) {
@@ -270,13 +288,14 @@ export class DeliveryLineFacade {
         const admissionBlocked = Boolean(admission && !admission.clean && (worktreeMode === 'auto' || worktreeMode === 'clean'));
         const record = {
             id, projectRoot, baseRef, integrationRef: `refs/devflow/delivery/${id}`, targetRef: input.targetRef,
-            title: input.title, originalRequest: input.title, source: input.source ?? 'human', riskTier, autonomy: input.autonomy ?? 'manual', stage: 'clarifying',
+            title: input.title, intentFingerprint: fingerprint, originalRequest: input.title, source: input.source ?? 'human', riskTier, autonomy: input.autonomy ?? 'manual', stage: 'clarifying',
             budgets: { ...defaults, ...input.budgets }, artifacts: [], tasks: [], approvals: [], decisions: [], evidence: [],
             approvalStates: {},
             interaction: { phase: 'clarification', status: 'awaiting_user', turn: 1, openQuestions: [input.existingImplementations?.length ? `Existing implementations were detected (${input.existingImplementations.join(', ')}). Which implementation should be extended, replaced, or retained?` : unknownRegistry[0]?.question ?? 'What outcome and acceptance criteria should this change satisfy?'], blockingUnknowns: [input.existingImplementations?.length ? `Existing implementations were detected (${input.existingImplementations.join(', ')}). Which implementation should be extended, replaced, or retained?` : unknownRegistry[0]?.question ?? 'What outcome and acceptance criteria should this change satisfy?'], summaryRefs: [] },
             createdBy: input.actor, sessionId: input.sessionId, executionId: input.executionId, createdAt: now, updatedAt: now, version: 0, contextReceipt, worktreeMode,
             runtimeActivation: { ...activationBody, snapshotHash: hash(activationBody) },
             ...(input.existingImplementations?.length ? { existingImplementations: [...input.existingImplementations] } : {}),
+            ...(admission?.clean ? { worktreeAdmission: { mode: worktreeMode === 'auto' ? 'clean' : worktreeMode, effectiveWorktreePath: admission.effectiveWorktreePath ?? projectRoot, baseRevision: baseRef, currentRevision: admission.revision, dirtyFiles: [], admissionToken: hash({ projectRoot, baseRef, currentRevision: admission.revision, dirtyFiles: [] }), admittedAt: now } } : {}),
             ...(contextQuality ? { contextQuality } : {}),
             ...(stackFacts ? { stackFacts: { ...stackFacts, capturedAt: now } } : {}),
             taskSemantics,
@@ -305,7 +324,12 @@ export class DeliveryLineFacade {
         await appendLedgerEvent(this.ports.store, { caseId: id, type: 'case.created', actor: input.actor, idempotencyKey: input.idempotencyKey, payload: { stage: record.stage } });
         return this.view(record);
     }
-    async status(caseId) { return this.view(await this.ports.store.get(caseId)); }
+    async status(caseId, options) {
+        const view = await this.view(await this.ports.store.get(caseId));
+        return options?.sinceVersion !== undefined && options.sinceVersion === view.stateVersion
+            ? { ...view, unchanged: true }
+            : view;
+    }
     async pendingDecision(caseId) {
         const record = await this.ports.store.get(caseId);
         return this.ensurePendingDecision(record);
@@ -404,6 +428,13 @@ export class DeliveryLineFacade {
             throw new DeliveryLineError('UNAUTHORIZED_ROLE', 'only an agent may propose options; a trusted user must select one');
         const current = await this.ports.store.get(caseId);
         const pending = await this.ports.store.getPendingDecision?.(caseId);
+        if (!['clarifying', 'designing'].includes(current.stage)) {
+            throw new DeliveryLineError('INVALID_TRANSITION', 'options can only be proposed during clarification or design', {
+                currentStage: current.stage,
+                allowedActions: nextActionsFor(current),
+                recoveryAction: 'Refresh delivery_status and follow the returned nextActions; do not reopen a completed decision.',
+            });
+        }
         const enrichesInitialDecision = Boolean(pending && pending.status === 'pending' && pending.options.length === 0 && pending.turn === current.interaction.turn && current.stage === 'clarifying');
         const options = normalizeDecisionOptions(input.options);
         if (!input.question.trim() || options.length < 2)
@@ -452,6 +483,9 @@ export class DeliveryLineFacade {
     async answer(caseId, input) {
         requireIdentity(input);
         requireTrustedUserDecision(input);
+        const selectedExistingIndex = input.optionId?.match(/^existing-(\d+)$/u)?.[1];
+        const selectedExistingPath = selectedExistingIndex ? (await this.ports.store.get(caseId)).existingImplementations?.[Number(selectedExistingIndex) - 1] : undefined;
+        const followUpOptions = selectedExistingPath ? existingActionOptions(selectedExistingPath) : undefined;
         return this.mutate(caseId, input, 'interaction.answered', async (record) => {
             if (!['clarifying', 'designing'].includes(record.stage))
                 throw new DeliveryLineError('INVALID_TRANSITION', 'interaction answers are only accepted during clarification or design', { currentStage: record.stage, allowedStages: ['clarifying', 'designing'] });
@@ -471,6 +505,17 @@ export class DeliveryLineFacade {
             if (acceptanceCriteria.length === 0)
                 acceptanceCriteria.push(rawAnswer);
             record.interaction = answerInteraction(record.interaction, input.turn);
+            if (selectedExistingPath && followUpOptions) {
+                const nextTurn = record.interaction.turn + 1;
+                record.interaction = {
+                    ...record.interaction,
+                    status: 'awaiting_user',
+                    turn: nextTurn,
+                    openQuestions: [`How should ${selectedExistingPath} be handled?`],
+                    blockingUnknowns: [`How should ${selectedExistingPath} be handled?`],
+                };
+                return record;
+            }
             if (record.unknownRegistry) {
                 const answeredQuestion = normalizeDecisionText(question);
                 record.unknownRegistry = record.unknownRegistry.map(item => normalizeDecisionText(item.question) === answeredQuestion ? { ...item, blocking: false } : item);
@@ -482,13 +527,31 @@ export class DeliveryLineFacade {
             const optionsSnapshot = input.optionsSnapshot ?? (input.optionId ? [{ id: input.optionId, label: selectedLabel }] : []);
             const decisionHash = hash({ questionId, optionId: input.optionId, selectedLabel, rawAnswer, acceptanceCriteria, optionsSnapshot });
             record.decisions.push({ id: randomUUID(), kind: 'product', questionId, question, options: optionsSnapshot.map(option => option.label), optionsSnapshot, optionId: input.optionId, selectedLabel, rawAnswer, acceptanceCriteria, decisionHash, sessionId: input.sessionId, toolUseId: input.toolUseId, decision: selectedLabel, decidedBy: input.actor, artifactHash: decisionHash });
+            if (input.optionId === 'option-reuse')
+                record.reuseMode = 'reuse_as_is';
+            if (input.optionId === 'option-extend' || input.optionId === 'option-reuse-adjust')
+                record.reuseMode = 'extend';
             if (record.interaction.phase === 'clarification')
                 record.artifacts.push(await this.createArtifact(record, 'intent', renderIntentMarkdown({ title: record.title, originalRequest: record.originalRequest, problem: record.originalRequest ?? record.title, outcome: selectedLabel, answer: rawAnswer, contextQuality: record.contextQuality, affectedSystems: [record.projectRoot], constraints: ['Preserve existing behavior outside the confirmed scope.'], successCriteria: acceptanceCriteria, openQuestions: record.taskSemantics && record.taskSemantics.confidence > 0 ? (record.unknownRegistry?.filter(item => item.blocking).map(item => item.question) ?? []) : record.interaction.blockingUnknowns, unknownRegistry: record.taskSemantics && record.taskSemantics.confidence > 0 ? record.unknownRegistry : undefined, actor: input.actor }), input.actor));
             await this.createProjectionArtifact(record, 'stack-facts.md', 'Stack facts', 'Project stack evidence bound at case creation.', { baseRef: record.baseRef, targetRef: record.targetRef, projectRoot: record.projectRoot }, input.actor);
             await this.createProjectionArtifact(record, 'decisions.md', 'Decisions', 'Current-turn decision ledger projection.', { decisionHash, questionId, optionId: input.optionId, selectedLabel }, input.actor);
             record.interaction = appendInteractionSummary(record.interaction, { id: randomUUID(), phase: record.interaction.phase, turn: input.turn, question, answer: rawAnswer, rawAnswer, acceptanceCriteria, decision: selectedLabel, options: optionsSnapshot.map(option => option.label), contextReceipt: input.contextReceipt, artifactHashes: [decisionHash], actor: input.actor });
             return record;
-        });
+        }, selectedExistingPath && followUpOptions ? {
+            decisionId: `${caseId}:decision:${input.turn}`,
+            expectedCaseVersion: (await this.ports.store.getPendingDecision?.(caseId))?.caseVersion ?? 0,
+            replacement: record => ({
+                id: `${record.id}:decision:${record.interaction.turn}`,
+                caseId: record.id,
+                kind: 'clarification',
+                caseVersion: record.version + 1,
+                turn: record.interaction.turn,
+                targetDecisionHash: hash({ caseId: record.id, question: record.interaction.openQuestions[0], options: followUpOptions }),
+                options: followUpOptions,
+                status: 'pending',
+                createdAt: Date.now(),
+            }),
+        } : undefined);
     }
     async revise(caseId, input) {
         requireIdentity(input);
@@ -636,22 +699,47 @@ export class DeliveryLineFacade {
                 throw new DeliveryLineError('INVALID_TRANSITION', 'plan preparation requires a ready plan stage', { currentStage: record.stage, recoveryAction: 'Refresh delivery_status and follow its nextActions.' });
             if (record.artifacts.some(artifact => artifact.type === 'plan'))
                 throw new DeliveryLineError('IDEMPOTENCY_CONFLICT', 'a plan draft is already prepared; refresh delivery_status and approve the pending plan decision');
+            // Validate the model payload before doing retrieval or mutating context.
+            // This prevents malformed plans from consuming a retrieval turn and
+            // reporting an unrelated context failure as the primary error.
+            new PlanCompiler().compile({
+                caseId: record.id,
+                projectRoot: record.projectRoot,
+                baseRevision: record.baseRef,
+                planHash: 'preflight-plan-payload',
+                contextReceiptHash: input.contextReceipt,
+                hostSelectionSnapshotHash: 'preflight-host-selection',
+                executionAuthority: 'preflight-plan-authority',
+                plan: input.plan,
+            });
             if (this.ports.context) {
                 const planContextQuery = `${record.originalRequest ?? record.title} implementation plan ${(record.existingImplementations ?? []).join(' ')}`.trim();
                 const planContextIdentity = hash(planContextQuery).slice(0, 16);
-                const plannerReceipt = await this.ports.context.build({
-                    role: 'planner',
-                    ...(record.pluginSelection?.requiredContextChannels?.length ? { requiredChannels: record.pluginSelection.requiredContextChannels } : {}),
-                    retrieval: {
-                        taskRevision: record.version + 1,
-                        projectRoot: record.projectRoot,
-                        query: planContextQuery,
-                        sessionId: input.sessionId,
-                        executionId: input.executionId,
-                        requestId: `delivery:plan:${record.id}:${record.version}:${planContextIdentity}`,
-                        turnId: `delivery:plan:${record.id}:${record.interaction.turn}:${planContextIdentity}`,
-                    },
-                });
+                let plannerReceipt;
+                try {
+                    plannerReceipt = await this.ports.context.build({
+                        role: 'planner',
+                        ...(record.pluginSelection?.requiredContextChannels?.length ? { requiredChannels: record.pluginSelection.requiredContextChannels } : {}),
+                        retrieval: {
+                            taskRevision: record.version + 1,
+                            projectRoot: record.projectRoot,
+                            query: planContextQuery,
+                            sessionId: input.sessionId,
+                            executionId: input.executionId,
+                            requestId: `delivery:plan:${record.id}:${record.version}:${planContextIdentity}`,
+                            turnId: `delivery:plan:${record.id}:${record.interaction.turn}:${planContextIdentity}`,
+                        },
+                    });
+                }
+                catch (error) {
+                    if ((error instanceof DeliveryLineError && error.code === 'REQUIRED_CONTEXT_MISSING') || (error instanceof Error && /required context evidence|unrelated context evidence/i.test(error.message))) {
+                        record.stage = 'held';
+                        const metadata = error instanceof DeliveryLineError ? error.metadata : undefined;
+                        record.blockers = [{ code: 'REQUIRED_CONTEXT_MISSING', message: error instanceof Error ? error.message : 'required context evidence is missing', responsibleRole: 'context-owner', artifactRefs: [], evidenceRefs: [], recoveryAction: 'Repair the planner query, then call delivery_repair_context before preparing the plan again.', retryable: true, diagnostics: { ...(metadata ?? {}), repairAttempts: Number(metadata?.repairAttempts ?? 0) } }];
+                        return record;
+                    }
+                    throw error;
+                }
                 record.contextReceipt = plannerReceipt.receiptHash;
                 if (plannerReceipt.channelStatus && plannerReceipt.gaps && plannerReceipt.attribution)
                     record.contextQuality = { blocking: plannerReceipt.blocking ?? false, ...(plannerReceipt.channelAvailability ? { channelAvailability: plannerReceipt.channelAvailability } : {}), channelStatus: plannerReceipt.channelStatus, gaps: plannerReceipt.gaps, attribution: plannerReceipt.attribution, ...('quality' in plannerReceipt && plannerReceipt.quality ? { quality: plannerReceipt.quality } : {}) };
@@ -677,6 +765,37 @@ export class DeliveryLineFacade {
             return record;
         });
     }
+    async repairContext(caseId, input) {
+        requireIdentity(input);
+        if (input.actor.kind !== 'agent')
+            throw new DeliveryLineError('UNAUTHORIZED_ROLE', 'only an agent may repair retrieval context');
+        return this.mutate(caseId, input, 'context.repaired', async (record) => {
+            const blocker = record.blockers?.find(item => item.code === 'REQUIRED_CONTEXT_MISSING');
+            if (!blocker)
+                throw new DeliveryLineError('INVALID_TRANSITION', 'case is not waiting for context repair', { currentStage: record.stage });
+            const attempts = Number(blocker.diagnostics?.repairAttempts ?? 0);
+            if (attempts >= 2)
+                throw new DeliveryLineError('REQUIRED_CONTEXT_MISSING', 'context repair budget exhausted; a human must provide the missing repository anchor', { repairAttempts: attempts, recoveryAction: 'Provide an exact file, symbol, or repository path, then create a new context request.' });
+            if (!this.ports.context)
+                throw new DeliveryLineError('MISSING_PREREQUISITE', 'context adapter is required for repair');
+            const query = `${record.originalRequest ?? record.title} implementation plan exact files symbols current repository anchor repair-${attempts + 1}`.trim();
+            try {
+                const receipt = await this.ports.context.build({ role: 'planner', retrieval: { taskRevision: record.version + 1, projectRoot: record.projectRoot, query, sessionId: input.sessionId, executionId: input.executionId, requestId: `delivery:context-repair:${record.id}:${attempts + 1}`, turnId: `delivery:context-repair:${record.id}:${record.interaction.turn}:${attempts + 1}` } });
+                record.contextReceipt = receipt.receiptHash;
+                record.contextQuality = { blocking: receipt.blocking ?? false, ...(receipt.channelAvailability ? { channelAvailability: receipt.channelAvailability } : {}), channelStatus: receipt.channelStatus ?? { code: 'degraded', memory: 'degraded', knowledge: 'degraded' }, gaps: receipt.gaps ?? [], attribution: receipt.attribution ?? { selected: [], consumed: [], verified: [] }, ...(receipt.quality ? { quality: receipt.quality } : {}) };
+                record.blockers = undefined;
+                record.stage = 'plan_ready';
+                return record;
+            }
+            catch (error) {
+                if (error instanceof DeliveryLineError && error.code === 'REQUIRED_CONTEXT_MISSING') {
+                    record.blockers = [{ ...blocker, diagnostics: { ...(error.metadata ?? {}), repairAttempts: attempts + 1 }, recoveryAction: attempts + 1 >= 2 ? 'Provide an exact repository anchor and create a new context request.' : 'Retry delivery_repair_context once with the current case identity.' }];
+                    return record;
+                }
+                throw error;
+            }
+        });
+    }
     async approve(caseId, input) {
         requireIdentity(input);
         requireTrustedUserDecision(input);
@@ -736,8 +855,21 @@ export class DeliveryLineFacade {
                 record.interaction = { ...record.interaction, status: 'awaiting_approval' };
                 return record;
             }
-            if (input.stage === 'intent')
-                record.stage = 'designing';
+            if (input.stage === 'intent') {
+                if (record.reuseMode === 'reuse_as_is') {
+                    record.evidence.push({
+                        id: randomUUID(),
+                        kind: 'verification',
+                        hash: hash({ caseId: record.id, mode: 'reuse_as_is', implementations: record.existingImplementations ?? [], contextReceipt: record.contextReceipt }),
+                        createdAt: Date.now(),
+                        metadata: { mode: 'reuse_as_is', implementations: record.existingImplementations ?? [], verification: 'existing implementation confirmed by user and context evidence' },
+                    });
+                    record.interaction = { ...record.interaction, status: 'active', openQuestions: [], blockingUnknowns: [] };
+                    record.stage = 'delivered';
+                }
+                else
+                    record.stage = 'designing';
+            }
             if (input.stage === 'spec')
                 record.stage = 'plan_ready';
             if (input.stage === 'plan') {
@@ -923,7 +1055,7 @@ export class DeliveryLineFacade {
             if (input.mode === 'clean' && admission && !admission.clean)
                 return hold(record, { code: 'WORKTREE_ADMISSION_REQUIRED', message: 'The project worktree is still dirty.', responsibleRole: 'delivery-owner', requiredRole: 'delivery-owner', recoveryAction: 'Clean the listed files or choose isolated/external admission.', retryable: true, diagnostics: { dirtyFiles: admission.dirtyFiles, choices: ['isolated', 'external', 'clean'] } });
             record.worktreeMode = input.mode;
-            record.worktreeAdmission = { mode: input.mode, baseRevision: record.baseRef, currentRevision: admission?.revision, dirtyFiles: admission?.dirtyFiles ?? [], admissionToken: input.admissionToken, admittedAt: Date.now() };
+            record.worktreeAdmission = { mode: input.mode, effectiveWorktreePath: admission?.effectiveWorktreePath ?? record.projectRoot, baseRevision: record.baseRef, currentRevision: admission?.revision, dirtyFiles: admission?.dirtyFiles ?? [], admissionToken: input.admissionToken, admittedAt: Date.now() };
             record.stage = 'clarifying';
             record.blockers = [];
             record.interaction.status = 'awaiting_user';
@@ -1126,7 +1258,12 @@ export class DeliveryLineFacade {
         const next = await fn(structuredClone(record));
         next.version = record.version + 1;
         next.updatedAt = Date.now();
-        if (pendingDecisionUpdate) {
+        if (pendingDecisionUpdate && input.trustedDecision) {
+            if (!this.ports.store.saveAndConsumePendingDecision)
+                throw new DeliveryLineError('MISSING_PREREQUISITE', 'trusted decision storage transaction is unavailable', { recoveryAction: 'Use a Delivery store with atomic pending-decision consumption.' });
+            await this.ports.store.saveAndConsumePendingDecision(next, record.version, { decisionId: input.trustedDecision.pendingDecisionId, expectedCaseVersion: input.trustedDecision.pendingCaseVersion, nonce: input.trustedDecision.nonce, replacement: pendingDecisionUpdate.replacement(next) });
+        }
+        else if (pendingDecisionUpdate) {
             if (!this.ports.store.saveAndReplacePendingDecision)
                 throw new DeliveryLineError('MISSING_PREREQUISITE', 'pending decision storage transaction is unavailable', { recoveryAction: 'Use a Delivery store with atomic pending-decision replacement.' });
             await this.ports.store.saveAndReplacePendingDecision(next, record.version, { decisionId: pendingDecisionUpdate.decisionId, expectedCaseVersion: pendingDecisionUpdate.expectedCaseVersion, replacement: pendingDecisionUpdate.replacement(next) });
@@ -1158,12 +1295,13 @@ export class DeliveryLineFacade {
         return this.ports.artifact.create({
             caseId: record.id,
             repoId: record.projectRoot,
-            repositoryPath: record.projectRoot,
+            repositoryPath: record.worktreeAdmission?.effectiveWorktreePath ?? record.projectRoot,
             type,
             path: projection?.artifactPath ?? `${type}.md`,
             content,
             parentBlobHashes: record.artifacts.map(artifact => artifact.blobHash),
             createdBy: actor,
+            ...(record.worktreeAdmission?.dirtyFiles?.length ? { allowedDirtyFiles: record.worktreeAdmission.dirtyFiles } : {}),
             ...(projection ? { projection } : {}),
             version: record.artifacts.filter(item => item.type === type).length + 1,
         });
@@ -1193,7 +1331,10 @@ export class DeliveryLineFacade {
         }));
         const nextActions = nextActionsFor(record);
         const blockers = record.blockers ?? (['held', 'failed', 'needs_changes', 'blocked'].includes(record.stage) ? [this.defaultBlocker(record)] : []);
-        return { caseId: record.id, currentTurn: record.interaction.turn, contextReceipt: record.contextReceipt, ...(record.contextQuality ? { contextQuality: record.contextQuality } : {}), ...(record.sessionId && record.executionId ? { canonicalIdentity: { sessionId: record.sessionId, executionId: record.executionId, actorId: record.createdBy.id } } : {}), ...(record.runtimeActivation ? { runtimeActivationHash: record.runtimeActivation.snapshotHash } : {}), stage: record.stage, pendingDecisions, nextActions, blockers, artifactRefs: record.artifacts, evidenceRefs: record.evidence, taskSummaries: record.tasks.map(task => ({ taskId: task.id, status: task.status, attempt: task.attempt })), budget: { interactionsUsed: record.interaction.turn, taskAttemptsUsed: record.tasks.reduce((sum, task) => sum + task.attempt, 0), wallTimeMs: Math.max(0, Date.now() - (record.createdAt ?? record.updatedAt)), toolCalls: 0 } };
+        const snapshotInput = { caseId: record.id, version: record.version, turn: record.interaction.turn, stage: record.stage, pending: pending ? { id: pending.id, targetDecisionHash: pending.targetDecisionHash, caseVersion: pending.caseVersion } : null, blockers, artifacts: record.artifacts.map(item => item.contentHash), tasks: record.tasks.map(task => ({ id: task.id, status: task.status, attempt: task.attempt })) };
+        const snapshotHash = hash(snapshotInput);
+        const cursor = await this.ports.store.latestEventCursor?.(record.id);
+        return { caseId: record.id, stateVersion: record.version, snapshotHash, ...(cursor ? { lastEventId: cursor.id } : {}), currentTurn: record.interaction.turn, contextReceipt: record.contextReceipt, ...(record.contextQuality ? { contextQuality: record.contextQuality } : {}), ...(record.sessionId && record.executionId ? { canonicalIdentity: { sessionId: record.sessionId, executionId: record.executionId, actorId: record.createdBy.id } } : {}), ...(record.runtimeActivation ? { runtimeActivationHash: record.runtimeActivation.snapshotHash } : {}), stage: record.stage, pendingDecisions, nextActions, blockers, artifactRefs: record.artifacts, evidenceRefs: record.evidence, taskSummaries: record.tasks.map(task => ({ taskId: task.id, status: task.status, attempt: task.attempt })), budget: { interactionsUsed: record.interaction.turn, taskAttemptsUsed: record.tasks.reduce((sum, task) => sum + task.attempt, 0), wallTimeMs: Math.max(0, Date.now() - (record.createdAt ?? record.updatedAt)), toolCalls: 0 } };
     }
     async ensurePendingDecision(record) {
         const current = await this.ports.store.getPendingDecision?.(record.id);