@zigrivers/scaffold 3.13.0 → 3.14.0

package/dist/cli/commands/run.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { StateManager } from '../../state/state-manager.js';
-import { acquireLock, releaseLock } from '../../state/lock-manager.js';
+import { acquireLock, getLockPath, releaseLock } from '../../state/lock-manager.js';
 import { analyzeCrash } from '../../state/completion.js';
 import { AssemblyEngine } from '../../core/assembly/engine.js';
 import { getPackageKnowledgeDir } from '../../utils/fs.js';
@@ -18,6 +18,7 @@ import { createOutputContext } from '../../cli/output/context.js';
 import { displayErrors } from '../../cli/output/error-display.js';
 import { resolveOutputMode } from '../../cli/middleware/output-mode.js';
 import { findClosestMatch } from '../../utils/levenshtein.js';
+import { shutdown } from '../shutdown.js';
 const runCommand = {
     command: 'run <step>',
     describe: 'Run a pipeline step',
@@ -51,7 +52,8 @@ const runCommand = {
         if (!projectRoot) {
             process.stderr.write('✗ error [PROJECT_NOT_INITIALIZED]: No .scaffold/ directory found\n' +
                 '  Fix: Run `scaffold init` to initialize a project\n');
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
         const outputMode = resolveOutputMode(argv);
         const output = createOutputContext(outputMode);
@@ -61,9 +63,10 @@ const runCommand = {
         const context = loadPipelineContext(projectRoot, { includeTools: true });
         if (!context.config) {
             displayErrors(context.configErrors, context.configWarnings, output);
-            process.exit(1);
+            process.exitCode = 1;
             return;
         }
+        const config = context.config;
         const pipeline = resolvePipeline(context, { output });
         const metaPrompt = context.metaPrompts.get(step);
         if (!metaPrompt) {
@@ -76,7 +79,8 @@ const runCommand = {
                 exitCode: 1,
                 recovery: `Available steps: ${candidates.join(', ')}`,
             });
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
         // -----------------------------------------------------------------------
         // Step 3: Acquire lock
@@ -92,7 +96,8 @@ const runCommand = {
                     });
                 }
                 output.warn({ code: 'LOCK_HELD', message: 'Another scaffold process is running. Use --force to override.' });
-                process.exit(3);
+                process.exitCode = 3;
+                return;
             }
             // --force: proceed without lock
             lockAcquired = false;
@@ -101,337 +106,352 @@ const runCommand = {
             output.warn(lockResult.warning);
         }
         // -----------------------------------------------------------------------
-        // Step 4: Load and validate state
+        // Lock-protected body — wrapped in withResource when lock is acquired
         // -----------------------------------------------------------------------
-        const stateManager = new StateManager(projectRoot, pipeline.computeEligible);
-        let state = stateManager.loadState();
-        // Crash recovery: in_progress is non-null from a previous run
-        if (state.in_progress !== null) {
-            const crashAction = analyzeCrash(state, projectRoot);
-            if (crashAction.action === 'auto_complete') {
-                const lastDepth = (state.steps[state.in_progress.step]?.depth ?? 3);
-                stateManager.markCompleted(state.in_progress.step, [], 'scaffold-crash-recovery', lastDepth);
-                stateManager.clearInProgress();
-            }
-            else if (crashAction.action === 'ask_user') {
-                if (outputMode === 'auto' || outputMode === 'json') {
-                    const crashedStep = state.in_progress.step;
-                    output.warn({
-                        code: 'CRASH_RECOVERY_NEEDED',
-                        message: `Previous run of '${crashedStep}' may be incomplete. ` +
-                            'Some artifacts present, some missing. ' +
-                            'Please manually verify and use --force to continue.',
-                    });
-                    if (lockAcquired)
-                        releaseLock(projectRoot);
-                    process.exit(4);
+        const lockProtectedBody = async () => {
+            // -----------------------------------------------------------------------
+            // Step 4: Load and validate state
+            // -----------------------------------------------------------------------
+            const stateManager = new StateManager(projectRoot, pipeline.computeEligible);
+            let state = stateManager.loadState();
+            // Crash recovery: in_progress is non-null from a previous run
+            if (state.in_progress !== null) {
+                const crashAction = analyzeCrash(state, projectRoot);
+                if (crashAction.action === 'auto_complete') {
+                    const lastDepth = (state.steps[state.in_progress.step]?.depth ?? 3);
+                    stateManager.markCompleted(state.in_progress.step, [], 'scaffold-crash-recovery', lastDepth);
+                    stateManager.clearInProgress();
                 }
-                else {
-                    // Interactive: prompt user
-                    const shouldComplete = await output.confirm(`Previous run of '${state.in_progress.step}' appears partially complete. Mark as completed?`, false);
-                    if (shouldComplete) {
-                        const lastDepth = (state.steps[state.in_progress.step]?.depth ?? 3);
-                        stateManager.markCompleted(state.in_progress.step, [], 'scaffold-crash-recovery', lastDepth);
-                        stateManager.clearInProgress();
+                else if (crashAction.action === 'ask_user') {
+                    if (outputMode === 'auto' || outputMode === 'json') {
+                        const crashedStep = state.in_progress.step;
+                        output.warn({
+                            code: 'CRASH_RECOVERY_NEEDED',
+                            message: `Previous run of '${crashedStep}' may be incomplete. ` +
+                                'Some artifacts present, some missing. ' +
+                                'Please manually verify and use --force to continue.',
+                        });
+                        process.exitCode = 4;
+                        return;
                     }
                     else {
-                        stateManager.clearInProgress();
+                        // Interactive: prompt user
+                        const shouldComplete = await shutdown.withPrompt(() => output.confirm(`Previous run of '${state.in_progress.step}' appears partially complete. Mark as completed?`, false));
+                        if (shouldComplete) {
+                            const lastDepth = (state.steps[state.in_progress.step]?.depth ?? 3);
+                            stateManager.markCompleted(state.in_progress.step, [], 'scaffold-crash-recovery', lastDepth);
+                            stateManager.clearInProgress();
+                        }
+                        else {
+                            stateManager.clearInProgress();
+                        }
                     }
                 }
+                else {
+                    // recommend_rerun: just clear
+                    stateManager.clearInProgress();
+                }
+                // Reload state after recovery
+                state = stateManager.loadState();
             }
-            else {
-                // recommend_rerun: just clear
-                stateManager.clearInProgress();
+            // -----------------------------------------------------------------------
+            // Step 5: Check dependencies
+            // -----------------------------------------------------------------------
+            const { graph } = pipeline;
+            const cycles = detectCycles(graph);
+            if (cycles.length > 0) {
+                displayErrors(cycles, [], output);
+                process.exitCode = 1;
+                return;
             }
-            // Reload state after recovery
-            state = stateManager.loadState();
-        }
-        // -----------------------------------------------------------------------
-        // Step 5: Check dependencies
-        // -----------------------------------------------------------------------
-        const { graph } = pipeline;
-        const cycles = detectCycles(graph);
-        if (cycles.length > 0) {
-            displayErrors(cycles, [], output);
-            if (lockAcquired)
-                releaseLock(projectRoot);
-            process.exit(1);
-        }
-        // Tools (category: 'tool') are not in the dependency graph — skip dep checking
-        const isTool = metaPrompt.frontmatter.category === 'tool';
-        const stepNode = isTool ? undefined : graph.nodes.get(step);
-        const deps = isTool
-            ? (pipeline.overlay.dependencies[step] ?? [])
-            : (stepNode?.dependencies ?? []);
-        if (!isTool) {
-            const unmetDeps = deps.filter(dep => {
-                // Overlay-disabled deps are treated as satisfied (matches eligibility.ts)
-                const depNode = graph?.nodes.get(dep);
-                if (depNode && !depNode.enabled)
-                    return false;
-                const depStatus = state.steps[dep]?.status;
-                return depStatus !== 'completed' && depStatus !== 'skipped';
-            });
-            if (unmetDeps.length > 0) {
-                output.error({
-                    code: 'DEP_UNMET',
-                    message: `Step '${step}' has unmet dependencies: ${unmetDeps.join(', ')}`,
-                    exitCode: 2,
-                    recovery: `Complete these steps first: ${unmetDeps.join(', ')}`,
+            // Tools (category: 'tool') are not in the dependency graph — skip dep checking
+            const isTool = metaPrompt.frontmatter.category === 'tool';
+            const stepNode = isTool ? undefined : graph.nodes.get(step);
+            const deps = isTool
+                ? (pipeline.overlay.dependencies[step] ?? [])
+                : (stepNode?.dependencies ?? []);
+            if (!isTool) {
+                const unmetDeps = deps.filter(dep => {
+                    // Overlay-disabled deps are treated as satisfied (matches eligibility.ts)
+                    const depNode = graph?.nodes.get(dep);
+                    if (depNode && !depNode.enabled)
+                        return false;
+                    const depStatus = state.steps[dep]?.status;
+                    return depStatus !== 'completed' && depStatus !== 'skipped';
                 });
-                if (lockAcquired)
-                    releaseLock(projectRoot);
-                process.exit(2);
-            }
-        }
-        // -----------------------------------------------------------------------
-        // Step 6: Check update mode and depth downgrade
-        // -----------------------------------------------------------------------
-        const cliDepth = argv.depth !== undefined ? argv.depth : undefined;
-        const { depth, provenance } = resolveDepth(step, context.config, pipeline.preset, cliDepth);
-        const updateModeResult = detectUpdateMode({ step, state, currentDepth: depth, projectRoot });
-        if (updateModeResult.isUpdateMode) {
-            if (!argv.force) {
-                if (outputMode === 'interactive') {
-                    const proceed = await output.confirm(`Step '${step}' is already completed. Re-run in update mode?`, true);
-                    if (!proceed) {
-                        if (lockAcquired)
-                            releaseLock(projectRoot);
-                        process.exit(4);
-                    }
-                }
-                else {
-                    output.info(`Re-running step '${step}' in update mode (auto)`);
+                if (unmetDeps.length > 0) {
+                    output.error({
+                        code: 'DEP_UNMET',
+                        message: `Step '${step}' has unmet dependencies: ${unmetDeps.join(', ')}`,
+                        exitCode: 2,
+                        recovery: `Complete these steps first: ${unmetDeps.join(', ')}`,
+                    });
+                    process.exitCode = 2;
+                    return;
                 }
             }
-            // Check for depth downgrade
-            const hasDowngrade = updateModeResult.warnings.some(w => w.code === 'ASM_DEPTH_DOWNGRADE');
-            if (hasDowngrade && !argv.force) {
-                if (outputMode === 'interactive') {
-                    const proceedWithDowngrade = await output.confirm('Depth downgrade detected. Continue?', false);
-                    if (!proceedWithDowngrade) {
-                        if (lockAcquired)
-                            releaseLock(projectRoot);
-                        process.exit(4);
+            // -----------------------------------------------------------------------
+            // Step 6: Check update mode and depth downgrade
+            // -----------------------------------------------------------------------
+            const cliDepth = argv.depth !== undefined ? argv.depth : undefined;
+            const { depth, provenance } = resolveDepth(step, config, pipeline.preset, cliDepth);
+            const updateModeResult = detectUpdateMode({ step, state, currentDepth: depth, projectRoot });
+            if (updateModeResult.isUpdateMode) {
+                if (!argv.force) {
+                    if (outputMode === 'interactive') {
+                        const proceed = await shutdown.withPrompt(() => output.confirm(`Step '${step}' is already completed. Re-run in update mode?`, true));
+                        if (!proceed) {
+                            process.exitCode = 4;
+                            return;
+                        }
+                    }
+                    else {
+                        output.info(`Re-running step '${step}' in update mode (auto)`);
                     }
                 }
-                else {
-                    for (const w of updateModeResult.warnings) {
-                        output.warn(w);
+                // Check for depth downgrade
+                const hasDowngrade = updateModeResult.warnings.some(w => w.code === 'ASM_DEPTH_DOWNGRADE');
+                if (hasDowngrade && !argv.force) {
+                    if (outputMode === 'interactive') {
+                        const proceedWithDowngrade = await shutdown.withPrompt(() => output.confirm('Depth downgrade detected. Continue?', false));
+                        if (!proceedWithDowngrade) {
+                            process.exitCode = 4;
+                            return;
+                        }
+                    }
+                    else {
+                        for (const w of updateModeResult.warnings) {
+                            output.warn(w);
+                        }
                     }
                 }
             }
-        }
-        // Check methodology change
-        const methodologyChangeResult = detectMethodologyChange({ state, config: context.config });
-        for (const w of methodologyChangeResult.warnings) {
-            output.warn(w);
-        }
-        // -----------------------------------------------------------------------
-        // Step 7: Set step to in_progress (skip for stateless steps)
-        // -----------------------------------------------------------------------
-        const isStateless = metaPrompt.frontmatter.stateless === true;
-        if (!isStateless) {
-            stateManager.setInProgress(step, 'scaffold-run');
-        }
-        try {
-            // Reload state after setInProgress
-            state = stateManager.loadState();
-            // -----------------------------------------------------------------------
-            // Step 8: Load assembly components
-            // -----------------------------------------------------------------------
-            const { instructions } = loadInstructions(projectRoot, step, argv.instructions);
-            const kbIndex = buildIndexWithOverrides(projectRoot, getPackageKnowledgeDir(projectRoot));
-            const { entries: knowledgeEntries, warnings: kbWarnings } = loadEntries(kbIndex, pipeline.overlay.knowledge[step] ?? metaPrompt.frontmatter.knowledgeBase ?? []);
-            for (const w of kbWarnings) {
+            // Check methodology change
+            const methodologyChangeResult = detectMethodologyChange({ state, config });
+            for (const w of methodologyChangeResult.warnings) {
                 output.warn(w);
             }
-            // Gather artifacts from completed dependency steps
-            const artifacts = [];
-            const gatheredPaths = new Set();
-            for (const dep of deps) {
-                const depEntry = state.steps[dep];
-                if (depEntry?.status === 'completed' && depEntry.produces) {
-                    for (const relPath of depEntry.produces) {
-                        const fullPath = path.resolve(projectRoot, relPath);
-                        if (fs.existsSync(fullPath)) {
-                            try {
-                                const content = fs.readFileSync(fullPath, 'utf8');
-                                artifacts.push({ stepName: dep, filePath: relPath, content });
-                                gatheredPaths.add(relPath);
+            // -----------------------------------------------------------------------
+            // Step 7: Set step to in_progress (skip for stateless steps)
+            // -----------------------------------------------------------------------
+            const isStateless = metaPrompt.frontmatter.stateless === true;
+            try {
+                await shutdown.withContext(() => {
+                    try {
+                        const ctxState = stateManager.loadState();
+                        return ctxState.in_progress !== null
+                            ? 'Cancelled. Step progress cleared.'
+                            : 'Cancelled.';
+                    }
+                    catch {
+                        return 'Cancelled.';
+                    }
+                }, async () => {
+                    // Note: Do NOT wrap in withResource('in-progress') — clearing in_progress
+                    // on Ctrl+C would break crash recovery. The existing analyzeCrash() logic
+                    // handles interrupted steps correctly on the next run.
+                    if (!isStateless) {
+                        stateManager.setInProgress(step, 'scaffold-run');
+                    }
+                    // Reload state after setInProgress
+                    state = stateManager.loadState();
+                    // -----------------------------------------------------------------------
+                    // Step 8: Load assembly components
+                    // -----------------------------------------------------------------------
+                    const { instructions } = loadInstructions(projectRoot, step, argv.instructions);
+                    const kbIndex = buildIndexWithOverrides(projectRoot, getPackageKnowledgeDir(projectRoot));
+                    const { entries: knowledgeEntries, warnings: kbWarnings } = loadEntries(kbIndex, pipeline.overlay.knowledge[step] ?? metaPrompt.frontmatter.knowledgeBase ?? []);
+                    for (const w of kbWarnings) {
+                        output.warn(w);
+                    }
+                    // Gather artifacts from completed dependency steps
+                    const artifacts = [];
+                    const gatheredPaths = new Set();
+                    for (const dep of deps) {
+                        const depEntry = state.steps[dep];
+                        if (depEntry?.status === 'completed' && depEntry.produces) {
+                            for (const relPath of depEntry.produces) {
+                                const fullPath = path.resolve(projectRoot, relPath);
+                                if (fs.existsSync(fullPath)) {
+                                    try {
+                                        const content = fs.readFileSync(fullPath, 'utf8');
+                                        artifacts.push({ stepName: dep, filePath: relPath, content });
+                                        gatheredPaths.add(relPath);
+                                    }
+                                    catch (err) {
+                                        output.warn({
+                                            code: 'ARTIFACT_READ_ERROR',
+                                            message: `Could not read artifact '${relPath}' from step '${dep}': ${err.message}`,
+                                        });
+                                    }
+                                }
                             }
-                            catch (err) {
-                                output.warn({
-                                    code: 'ARTIFACT_READ_ERROR',
-                                    message: `Could not read artifact '${relPath}' from step '${dep}': ${err.message}`,
-                                });
+                        }
+                    }
+                    // Gather artifacts from reads (optional cross-cutting references)
+                    // Note: graph defaults missing steps to enabled:true, which may not reflect
+                    // custom config overrides. This is a pre-existing graph builder limitation.
+                    const reads = pipeline.overlay.reads[step] ?? metaPrompt.frontmatter.reads ?? [];
+                    for (const readStep of reads) {
+                        // Check dependency graph for enablement (overlay-disabled steps)
+                        const readNode = graph?.nodes.get(readStep);
+                        if (readNode && !readNode.enabled)
+                            continue;
+                        // Check state — silently skip if not completed (reads are optional)
+                        const readEntry = state.steps[readStep];
+                        if (readEntry?.status !== 'completed' || !readEntry.produces)
+                            continue;
+                        for (const relPath of readEntry.produces) {
+                            // Deduplicate: skip paths already gathered from deps
+                            if (gatheredPaths.has(relPath))
+                                continue;
+                            const fullPath = path.resolve(projectRoot, relPath);
+                            if (fs.existsSync(fullPath)) {
+                                try {
+                                    const content = fs.readFileSync(fullPath, 'utf8');
+                                    artifacts.push({ stepName: readStep, filePath: relPath, content });
+                                    gatheredPaths.add(relPath);
+                                }
+                                catch (err) {
+                                    output.warn({
+                                        code: 'ARTIFACT_READ_ERROR',
+                                        message: `Could not read artifact '${relPath}' from step` +
+                                            ` '${readStep}': ${err.message}`,
+                                    });
+                                }
                             }
                         }
                     }
-                }
-            }
-            // Gather artifacts from reads (optional cross-cutting references)
-            // Note: graph defaults missing steps to enabled:true, which may not reflect
-            // custom config overrides. This is a pre-existing graph builder limitation.
-            const reads = pipeline.overlay.reads[step] ?? metaPrompt.frontmatter.reads ?? [];
-            for (const readStep of reads) {
-                // Check dependency graph for enablement (overlay-disabled steps)
-                const readNode = graph?.nodes.get(readStep);
-                if (readNode && !readNode.enabled)
-                    continue;
-                // Check state — silently skip if not completed (reads are optional)
-                const readEntry = state.steps[readStep];
-                if (readEntry?.status !== 'completed' || !readEntry.produces)
-                    continue;
-                for (const relPath of readEntry.produces) {
-                    // Deduplicate: skip paths already gathered from deps
-                    if (gatheredPaths.has(relPath))
-                        continue;
-                    const fullPath = path.resolve(projectRoot, relPath);
-                    if (fs.existsSync(fullPath)) {
+                    // Read decisions log
+                    const decisionsPath = path.join(projectRoot, '.scaffold', 'decisions.jsonl');
+                    let decisions = '';
+                    if (fs.existsSync(decisionsPath)) {
                         try {
-                            const content = fs.readFileSync(fullPath, 'utf8');
-                            artifacts.push({ stepName: readStep, filePath: relPath, content });
-                            gatheredPaths.add(relPath);
+                            decisions = fs.readFileSync(decisionsPath, 'utf8');
                         }
                         catch (err) {
                             output.warn({
-                                code: 'ARTIFACT_READ_ERROR',
-                                message: `Could not read artifact '${relPath}' from step '${readStep}': ${err.message}`,
+                                code: 'DECISIONS_READ_ERROR',
+                                message: `Could not read decisions log: ${err.message}`,
                             });
                         }
                     }
-                }
-            }
-            // Read decisions log
-            const decisionsPath = path.join(projectRoot, '.scaffold', 'decisions.jsonl');
-            let decisions = '';
-            if (fs.existsSync(decisionsPath)) {
-                try {
-                    decisions = fs.readFileSync(decisionsPath, 'utf8');
-                }
-                catch (err) {
-                    output.warn({
-                        code: 'DECISIONS_READ_ERROR',
-                        message: `Could not read decisions log: ${err.message}`,
+                    // -----------------------------------------------------------------------
+                    // Step 9: Assemble prompt
+                    // -----------------------------------------------------------------------
+                    const engine = new AssemblyEngine();
+                    const assemblyResult = engine.assemble(step, {
+                        config,
+                        state,
+                        metaPrompt,
+                        knowledgeEntries,
+                        instructions,
+                        arguments: argv.instructions,
+                        depth,
+                        depthProvenance: provenance,
+                        updateMode: updateModeResult.isUpdateMode,
+                        existingArtifact: updateModeResult.existingArtifact,
+                        artifacts,
+                        decisions,
                     });
-                }
-            }
-            // -----------------------------------------------------------------------
-            // Step 9: Assemble prompt
-            // -----------------------------------------------------------------------
-            const engine = new AssemblyEngine();
-            const assemblyResult = engine.assemble(step, {
-                config: context.config,
-                state,
-                metaPrompt,
-                knowledgeEntries,
-                instructions,
-                arguments: argv.instructions,
-                depth,
-                depthProvenance: provenance,
-                updateMode: updateModeResult.isUpdateMode,
-                existingArtifact: updateModeResult.existingArtifact,
-                artifacts,
-                decisions,
-            });
-            if (!assemblyResult.success) {
-                displayErrors(assemblyResult.errors, assemblyResult.warnings, output);
-                if (lockAcquired)
-                    releaseLock(projectRoot);
-                process.exit(5);
-            }
-            // -----------------------------------------------------------------------
-            // Step 10: Wait for completion (interactive) or exit (auto/json)
-            // -----------------------------------------------------------------------
-            if (outputMode === 'auto' || outputMode === 'json') {
-                // In auto/json mode: output the structured result and exit 0
-                // For stateful steps, step stays in_progress for crash recovery awareness
-                if (outputMode === 'json') {
-                    if (isStateless) {
-                        output.result({
-                            step,
-                            status: 'stateless',
-                            depth,
-                            depth_source: provenance,
-                            prompt: assemblyResult.prompt.text,
-                        });
+                    if (!assemblyResult.success) {
+                        displayErrors(assemblyResult.errors, assemblyResult.warnings, output);
+                        process.exitCode = 5;
+                        return;
                     }
-                    else {
-                        // Reload state for next eligible
-                        const stateForEligible = stateManager.loadState();
-                        const nextSteps = pipeline.computeEligible(stateForEligible.steps);
-                        output.result({
-                            step,
-                            status: 'in_progress',
-                            depth,
-                            depth_source: provenance,
-                            nextEligible: nextSteps,
-                            prompt: assemblyResult.prompt.text,
-                        });
+                    // -----------------------------------------------------------------------
+                    // Step 10: Wait for completion (interactive) or exit (auto/json)
+                    // -----------------------------------------------------------------------
+                    if (outputMode === 'auto' || outputMode === 'json') {
+                        // In auto/json mode: output the structured result and exit 0
+                        // For stateful steps, step stays in_progress for crash recovery awareness
+                        if (outputMode === 'json') {
+                            if (isStateless) {
+                                output.result({
+                                    step,
+                                    status: 'stateless',
+                                    depth,
+                                    depth_source: provenance,
+                                    prompt: assemblyResult.prompt.text,
+                                });
+                            }
+                            else {
+                                // Reload state for next eligible
+                                const stateForEligible = stateManager.loadState();
+                                const nextSteps = pipeline.computeEligible(stateForEligible.steps);
+                                output.result({
+                                    step,
+                                    status: 'in_progress',
+                                    depth,
+                                    depth_source: provenance,
+                                    nextEligible: nextSteps,
+                                    prompt: assemblyResult.prompt.text,
+                                });
+                            }
+                        }
+                        else {
+                            // auto mode: write prompt to stdout for AI consumption
+                            process.stdout.write(assemblyResult.prompt.text);
+                        }
+                        return;
                     }
-                }
-                else {
-                    // auto mode: write prompt to stdout for AI consumption
+                    // Write assembled prompt to stdout (raw, for AI consumption in interactive mode)
                     process.stdout.write(assemblyResult.prompt.text);
-                }
-                if (lockAcquired)
-                    releaseLock(projectRoot);
-                process.exit(0);
+                    // Interactive mode: prompt user for completion
+                    if (isStateless) {
+                        // Stateless steps don't track completion — just exit
+                        if (outputMode === 'interactive') {
+                            output.info(`Stateless step '${step}' executed. Available for re-use anytime.`);
+                        }
+                        return;
+                    }
+                    const isComplete = await shutdown.withPrompt(() => output.confirm(`Step '${step}' complete?`, true));
+                    if (!isComplete) {
+                        const shouldSkip = await shutdown.withPrompt(() => output.confirm('Mark as skipped instead?', false));
+                        if (shouldSkip) {
+                            stateManager.markSkipped(step, 'user-cancelled', 'scaffold-run');
+                        }
+                        else {
+                            stateManager.clearInProgress();
+                        }
+                        process.exitCode = 4;
+                        return;
+                    }
+                    // -----------------------------------------------------------------------
+                    // Step 11: Mark completed
+                    // -----------------------------------------------------------------------
+                    stateManager.markCompleted(step, metaPrompt.frontmatter.outputs ?? [], 'scaffold-run', depth);
+                    // -----------------------------------------------------------------------
+                    // Step 12: Show next eligible steps
+                    // -----------------------------------------------------------------------
+                    const finalState = stateManager.loadState();
+                    const nextSteps = pipeline.computeEligible(finalState.steps);
+                    if (outputMode === 'interactive') {
+                        if (nextSteps.length > 0) {
+                            output.info(`Next eligible: ${nextSteps.join(', ')}`);
+                        }
+                        else {
+                            output.info('No more eligible steps.');
+                        }
+                    }
+                });
             }
-            // Write assembled prompt to stdout (raw, for AI consumption in interactive mode)
-            process.stdout.write(assemblyResult.prompt.text);
-            // Interactive mode: prompt user for completion
-            if (isStateless) {
-                // Stateless steps don't track completion — just release lock and exit
-                if (lockAcquired)
-                    releaseLock(projectRoot);
-                if (outputMode === 'interactive') {
-                    output.info(`Stateless step '${step}' executed. Available for re-use anytime.`);
-                }
-                process.exit(0);
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                output.error({ code: 'RUN_UNEXPECTED_ERROR', message, exitCode: 1 });
+                process.exitCode = 1;
                 return;
             }
-            const isComplete = await output.confirm(`Step '${step}' complete?`, true);
-            if (!isComplete) {
-                const shouldSkip = await output.confirm('Mark as skipped instead?', false);
-                if (shouldSkip) {
-                    stateManager.markSkipped(step, 'user-cancelled', 'scaffold-run');
-                }
-                else {
-                    stateManager.clearInProgress();
-                }
-                if (lockAcquired)
-                    releaseLock(projectRoot);
-                process.exit(4);
-            }
-            // -----------------------------------------------------------------------
-            // Step 11: Mark completed
-            // -----------------------------------------------------------------------
-            stateManager.markCompleted(step, metaPrompt.frontmatter.outputs ?? [], 'scaffold-run', depth);
-            if (lockAcquired)
+        };
+        if (lockAcquired) {
+            shutdown.registerLockOwnership(getLockPath(projectRoot));
+            await shutdown.withResource('lock', () => {
                 releaseLock(projectRoot);
-            // -----------------------------------------------------------------------
-            // Step 12: Show next eligible steps
-            // -----------------------------------------------------------------------
-            const finalState = stateManager.loadState();
-            const nextSteps = pipeline.computeEligible(finalState.steps);
-            if (outputMode === 'interactive') {
-                if (nextSteps.length > 0) {
-                    output.info(`Next eligible: ${nextSteps.join(', ')}`);
-                }
-                else {
-                    output.info('No more eligible steps.');
-                }
-            }
-            process.exit(0);
+                shutdown.releaseLockOwnership();
+            }, lockProtectedBody);
         }
-        catch (err) {
-            if (lockAcquired)
-                releaseLock(projectRoot);
-            const message = err instanceof Error ? err.message : String(err);
-            output.error({ code: 'RUN_UNEXPECTED_ERROR', message, exitCode: 1 });
-            process.exit(1);
+        else {
+            await lockProtectedBody();
         }
     },
 };