@sublang/slc 0.9.0 → 0.10.0

package/dist/runner.js

@@ -13,11 +13,12 @@ import { mkdir, readFile, stat } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { artifactDir, planArtifacts, parseSource } from './artifacts.js';
+import { formatClarificationReport, } from './clarification.js';
 import { encodeLocator, invalidateBuildHistory, loadBuildHistory, recordBuild, verifiedInput, } from './build-history.js';
 import { emitEntryModule } from './entry-module.js';
 import { reconcileLinkObjectImportSpecifiers, unresolvableRelativeImports, } from './emitted-imports.js';
 import { messageOf } from './errors.js';
-import { assertSafeTarget, formatFailureReport, pathsAlias, runPhase, } from './execution.js';
+import { assertSafeTarget, formatFailureReport, phaseProtectedPaths, pathsAlias, runPhase, watchProtectedPaths, } from './execution.js';
 import { compareUtf8, hashBytes, isHash } from './hash.js';
 import { parseInvocation } from './invocation.js';
 import { unifiedLineDiff } from './line-diff.js';
@@ -30,9 +31,11 @@ import { PINS_FILE, PinError, loadPinFile, } from './pins.js';
 import { loadPipeline, resolvePipeline, } from './pipeline.js';
 import { RESERVED_SLC_PIPELINE, defaultPlaybookLinkTarget, isReservedPipeline, } from './resolver.js';
 import { readPlaybookRuntimeDeclaration, } from './runtime-contract.js';
-import { artifactSchemaForPlaybookProvenance, checkLinkedModuleContract, emitFsmCoverageTest, emitFsmIntrospectionTest, emitGearsFsmConformanceTest, emitPromptContractTest, findMachineConfig, loadFsmModule, loadLinkedModuleForVerification, playbookProvenanceForLinkTarget, resolveArtifactSchemaForVerification, } from './verify.js';
+import { artifactSchemaForPlaybookProvenance, checkFsmContinuationInputs, checkFsmChildSuspension, checkFsmCoverage, checkGearsActorContract, checkGearsFsmConformance, checkGearsResultContract, checkLinkedModuleContract, emitFsmCoverageTest, FsmCoverageDeadlineError, emitFsmIntrospectionTest, emitGearsFsmConformanceTest, emitPromptContractTest, findConcurrentRoleSets, inspectGearsRoleContract, findMachineConfig, loadFsmModule, loadLinkedModuleForVerification, playbookProvenanceForLinkTarget, resolveArtifactSchemaForVerification, } from './verify.js';
 import { VERIFIER_SUPPORT_MODULE, emitVerifierSupport, verifierSupportFiles, } from './verify-support.js';
 import { checkSourceGearsContract } from './verify-source.js';
+import { checkFsmTypeScript } from './verify-typescript.js';
+import { checkEntryOptions, ENTRY_OPTIONS_CONTRACT } from './entry-options.js';
 /**
  * Parses argv and runs the requested pipeline, phase, or link end-to-end.
  * Never rejects: malformed invocations, refusals, and phase failures all return
@@ -46,6 +49,24 @@ export async function runSlc(argv, deps) {
     catch (error) {
         return failure(messageOf(error));
     }
+    const finish = (result) => {
+        if (result.clarification === undefined)
+            return result;
+        const clarification = {
+            ...result.clarification,
+            sources: (invocation.kind === 'link'
+                ? invocation.objects
+                : [invocation.source]).map((path) => resolve(runCwd(deps), path)),
+        };
+        return {
+            ...result,
+            clarification,
+            diagnostics: [
+                ...result.diagnostics,
+                formatClarificationReport(clarification),
+            ],
+        };
+    };
     try {
         switch (invocation.kind) {
             case 'full':
@@ -53,20 +74,20 @@ export async function runSlc(argv, deps) {
                 // (self-hosting-13): a bare full run becomes a full-link against the
                 // installed @sublang/playbook runtime contract module (DR-014).
                 if (invocation.pipeline === 'playbook') {
-                    return await runFullLink({
+                    return finish(await runFullLink({
                         ...invocation,
                         kind: 'full-link',
                         linkTarget: defaultPlaybookLinkTarget(),
                         options: [],
-                    }, deps);
+                    }, deps));
                 }
-                return await runFull(invocation, deps);
+                return finish(await runFull(invocation, deps));
             case 'phase':
-                return await runSinglePhase(invocation, deps);
+                return finish(await runSinglePhase(invocation, deps));
             case 'link':
-                return await runDirectLink(invocation, deps);
+                return finish(await runDirectLink(invocation, deps));
             case 'full-link':
-                return await runFullLink(invocation, deps);
+                return finish(await runFullLink(invocation, deps));
         }
     }
     catch (error) {
@@ -101,6 +122,7 @@ async function runFull(invocation, deps) {
         optimize: !invocation.noOptimize,
         normalize: invocation.normalize || raw,
         sourceFidelity: invocation.pipeline !== RESERVED_SLC_PIPELINE,
+        signal: deps.signal,
     });
     const verification = {
         pipeline: invocation.pipeline,
@@ -139,6 +161,7 @@ async function runSinglePhase(invocation, deps) {
         sourceFormat: phase.source.format,
         ext: phase.source.ext,
         entry: pipeline.phases[0] === phase,
+        staged: phase.pass,
     });
     if (raw) {
         // A named phase cannot normalize (pipeline-37), so a raw entry source has no
@@ -153,7 +176,7 @@ async function runSinglePhase(invocation, deps) {
         // `.opt` sibling unless `-o` relocates it (DR-013).
         const target = (invocation.output === null ? null : resolve(cwd, invocation.output)) ??
             join(artDir, `${basename}.${phase.target.format}.opt${phase.target.ext}`);
-        const step = compileStep(pipeline, phase, source, target, sourceFidelity);
+        const step = compileStep(pipeline, phase, source, target, sourceFidelity, undefined, deps.signal);
         return executeSteps([step], pipeline, deps);
     }
     // Plan over the whole chain so the named phase keeps its pipeline role: a
@@ -166,7 +189,7 @@ async function runSinglePhase(invocation, deps) {
         output: invocation.output === null ? undefined : resolve(cwd, invocation.output),
     });
     const artifact = plan[pipeline.phases.indexOf(phase)];
-    const step = compileStep(pipeline, phase, source, artifact.path, sourceFidelity);
+    const step = compileStep(pipeline, phase, source, artifact.path, sourceFidelity, undefined, deps.signal);
     return executeSteps([step], pipeline, deps);
 }
 async function runDirectLink(invocation, deps) {
@@ -191,6 +214,7 @@ async function runDirectLink(invocation, deps) {
             linkTarget: resolve(cwd, invocation.linkTarget),
             options: invocation.options,
             linked,
+            signal: deps.signal,
         }),
     ], pipeline, deps);
 }
@@ -220,6 +244,8 @@ async function runFullLink(invocation, deps) {
         optimize: !invocation.noOptimize,
         normalize,
         sourceFidelity: invocation.pipeline !== RESERVED_SLC_PIPELINE,
+        signal: deps.signal,
+        linkTarget: resolve(cwd, invocation.linkTarget),
     });
     const linked = linkedArtifactPath({
         kind: 'full',
@@ -228,6 +254,14 @@ async function runFullLink(invocation, deps) {
         linked: link.target,
         output: invocation.output === null ? null : resolve(cwd, invocation.output),
     });
+    const gearsPlan = plan.find((artifact) => artifact.phase.target.format === 'gears');
+    const entryCandidate = invocation.pipeline === 'playbook' &&
+        invocation.output === null &&
+        gearsPlan !== undefined
+        ? resolve(cwd, `${basename}.ts`)
+        : null;
+    const entryAliasesSource = entryCandidate !== null && (await pathsAlias(entryCandidate, source));
+    const entryPath = entryAliasesSource ? null : entryCandidate;
     const steps = [
         ...compileSteps,
         linkStep({
@@ -237,16 +271,12 @@ async function runFullLink(invocation, deps) {
             linkTarget: resolve(cwd, invocation.linkTarget),
             options: invocation.options,
             linked,
+            signal: deps.signal,
+            ...(entryPath !== null && gearsPlan !== undefined
+                ? { entryGearsPath: gearsPlan.path }
+                : {}),
         }),
     ];
-    const gearsPlan = plan.find((artifact) => artifact.phase.target.format === 'gears');
-    const entryCandidate = invocation.pipeline === 'playbook' &&
-        invocation.output === null &&
-        gearsPlan !== undefined
-        ? resolve(cwd, `${basename}.ts`)
-        : null;
-    const entryAliasesSource = entryCandidate !== null && (await pathsAlias(entryCandidate, source));
-    const entryPath = entryAliasesSource ? null : entryCandidate;
     const verification = {
         pipeline: invocation.pipeline,
         plan,
@@ -500,6 +530,9 @@ function buildCompileSteps(opts) {
     if (opts.normalize) {
         const entry = pipeline.phases[0];
         const normalized = join(artDir, `${basename}.${entry.source.format}${entry.source.ext}`);
+        const gearsContract = entry.source.format === 'gears'
+            ? () => gearsContractFindings(normalized)
+            : undefined;
         steps.push({
             request: {
                 kind: 'compile',
@@ -507,9 +540,15 @@ function buildCompileSteps(opts) {
                 source: previous,
                 target: normalized,
                 references: [phaseDefinition(pipeline, entry.name)],
+                ...(gearsContract === undefined
+                    ? {}
+                    : { mechanicalReview: gearsContract }),
             },
             phase: 'normalize',
             targetExt: entry.source.ext,
+            ...(gearsContract === undefined
+                ? {}
+                : { compileFidelity: gearsContract }),
         });
         previous = normalized;
     }
@@ -519,46 +558,92 @@ function buildCompileSteps(opts) {
             ? pipeline.passes.filter((pass) => pass.source.format === phase.target.format)
             : [];
         if (passes.length === 0) {
-            steps.push(compileStep(pipeline, phase, previous, artifact.path, opts.sourceFidelity));
+            steps.push(compileStep(pipeline, phase, previous, artifact.path, opts.sourceFidelity, opts.linkTarget, opts.signal));
             previous = artifact.path;
             continue;
         }
         const raw = join(artDir, `${basename}.${phase.target.format}.raw${phase.target.ext}`);
-        steps.push(compileStep(pipeline, phase, previous, raw, opts.sourceFidelity));
+        steps.push(compileStep(pipeline, phase, previous, raw, opts.sourceFidelity, opts.linkTarget, opts.signal));
         previous = raw;
         passes.forEach((pass, index) => {
             const target = index === passes.length - 1
                 ? artifact.path
                 : join(artDir, `${basename}.${phase.target.format}.opt${index + 1}${phase.target.ext}`);
-            steps.push(compileStep(pipeline, pass, previous, target, opts.sourceFidelity));
+            steps.push(compileStep(pipeline, pass, previous, target, opts.sourceFidelity, opts.linkTarget, opts.signal));
             previous = target;
         });
     }
     return steps;
 }
-function compileStep(pipeline, phase, source, target, sourceFidelity) {
+function compileStep(pipeline, phase, source, target, sourceFidelity, linkTarget, signal) {
     // Only a text-to-GEARS phase conserves authored Source fragments, and the
     // reserved meta-pipeline compiles definitions under its own fidelity gate
     // (DR-029, phase-execution-51, verification-23).
     const gated = sourceFidelity &&
         phase.source.format === 'text' &&
         phase.target.format === 'gears';
+    const fsmConformance = phase.source.format === 'gears' && phase.target.format === 'fsm'
+        ? async () => {
+            if (phase.target.ext === '.ts') {
+                const findings = await checkFsmTypeScript(target, signal);
+                if (findings.length > 0)
+                    return findings;
+            }
+            return fsmConformanceFindings(source, target, linkTarget, signal);
+        }
+        : undefined;
+    const checks = [
+        ...(gated ? [() => sourceFidelityFindings(source, target)] : []),
+        ...(phase.target.format === 'gears'
+            ? [() => gearsContractFindings(target)]
+            : []),
+        ...(fsmConformance === undefined ? [] : [fsmConformance]),
+    ];
+    const mechanicalReview = checks.length === 0
+        ? undefined
+        : async () => (await Promise.all(checks.map((check) => check()))).flat();
     return {
         request: {
             kind: 'compile',
             definitionPath: phaseDefinition(pipeline, phase.name),
             source,
             target,
-            ...(gated
-                ? { mechanicalReview: () => sourceFidelityFindings(source, target) }
-                : {}),
+            ...(mechanicalReview === undefined ? {} : { mechanicalReview }),
         },
         phase: phase.name,
         pinKey: phase.name,
         targetExt: phase.target.ext,
-        ...(gated ? { sourceFidelity: true } : {}),
+        ...(mechanicalReview === undefined
+            ? {}
+            : { compileFidelity: mechanicalReview }),
+        ...(phase.source.format === 'gears'
+            ? { gearsSourceContract: () => gearsContractFindings(source) }
+            : {}),
+        ...(phase.source.format === 'fsm' && phase.source.ext === '.ts'
+            ? { fsmSourceTypecheck: () => checkFsmTypeScript(source, signal) }
+            : {}),
+        ...(phase.source.format === 'fsm'
+            ? {
+                fsmSourceContinuation: () => fsmContinuationFindings(source, linkTarget, signal),
+            }
+            : {}),
     };
 }
+/** Parser-only findings belong to the phase that can still edit the GEARS. */
+async function gearsContractFindings(path) {
+    try {
+        const gears = await readFile(path, 'utf8');
+        return [
+            ...checkGearsResultContract(gears),
+            ...checkGearsActorContract(gears),
+        ];
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        return [`GEARS contract could not be checked: ${messageOf(error)}`];
+    }
+}
 /**
  * The DR-029 gate over one text-to-GEARS phase's live target: the deterministic
  * conservation findings against the Source that phase reads (phase-execution-51,
@@ -587,6 +672,88 @@ async function sourceFidelityFindings(source, target) {
         return [`Source fidelity could not be checked: ${messageOf(error)}`];
     }
 }
+/** Reuses the emitted GEARS-to-FSM suite before accepting its input (DR-033). */
+async function fsmConformanceFindings(source, target, linkTarget, signal) {
+    signal?.throwIfAborted();
+    try {
+        await stat(target);
+    }
+    catch (error) {
+        // Absence belongs to the generic target check; all other failures are
+        // actionable findings rather than permission to skip the gate.
+        if (error.code === 'ENOENT')
+            return [];
+        return [`FSM conformance could not be checked: ${messageOf(error)}`];
+    }
+    try {
+        const [gears, fsm] = await Promise.all([
+            readFile(source, 'utf8'),
+            loadFsmModule(target),
+        ]);
+        const config = findMachineConfig(fsm);
+        const schema = await fsmSchema(config, linkTarget);
+        const findings = [
+            ...schema.findings,
+            ...checkGearsFsmConformance(gears, config, {
+                concurrentRoleSets: findConcurrentRoleSets(fsm),
+                ...(schema.artifactSchema === undefined
+                    ? {}
+                    : { artifactSchema: schema.artifactSchema }),
+            }),
+            ...(schema.artifactSchema === undefined || schema.findings.length > 0
+                ? []
+                : checkFsmContinuationInputs(config, schema.artifactSchema)),
+        ];
+        signal?.throwIfAborted();
+        return findings.length > 0
+            ? findings
+            : await checkFsmCoverage(fsm, {
+                sourceText: await readFile(target, 'utf8'),
+                signal,
+            });
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof FsmCoverageDeadlineError)
+            throw error;
+        return [`FSM conformance could not be checked: ${messageOf(error)}`];
+    }
+}
+async function fsmSchema(config, linkTarget) {
+    const provenance = linkTarget === undefined
+        ? undefined
+        : await playbookProvenanceForLinkTarget(linkTarget);
+    const runtimeDeclaration = linkTarget === undefined ||
+        artifactSchemaForPlaybookProvenance(provenance) !== undefined
+        ? undefined
+        : await linkTargetRuntimeDeclaration(linkTarget);
+    return resolveArtifactSchemaForVerification({
+        requireContinuationSchema: false,
+        config,
+        ...(provenance === undefined ? {} : { provenance }),
+        ...(runtimeDeclaration === undefined ? {} : { runtimeDeclaration }),
+    });
+}
+async function fsmContinuationFindings(source, linkTarget, signal) {
+    signal?.throwIfAborted();
+    const fsm = await loadFsmModule(source);
+    const config = findMachineConfig(fsm);
+    const schema = await fsmSchema(config, linkTarget);
+    signal?.throwIfAborted();
+    const findings = [
+        ...schema.findings,
+        ...checkFsmChildSuspension(config),
+        ...(schema.artifactSchema === undefined || schema.findings.length > 0
+            ? []
+            : checkFsmContinuationInputs(config, schema.artifactSchema)),
+    ];
+    return findings.length > 0
+        ? findings
+        : await checkFsmCoverage(fsm, {
+            sourceText: await readFile(source, 'utf8'),
+            signal,
+        });
+}
 /**
  * Builds one link step, gated by DR-030 when the link emits Playbook's
  * `playbook` module over exactly the one FSM object the checks read
@@ -596,8 +763,20 @@ async function sourceFidelityFindings(source, target) {
 function linkStep(opts) {
     const { link } = opts;
     const fsmObjects = opts.objects.filter((object) => object.endsWith(`.${link.source.format}${link.source.ext}`));
+    const entryRequired = async () => opts.entryGearsPath !== undefined &&
+        inspectGearsRoleContract(await readFile(opts.entryGearsPath, 'utf8'))
+            .generation === 'schema-3';
     const gated = link.target.format === PLAYBOOK_LINKED_FORMAT && fsmObjects.length === 1
-        ? () => linkFidelityFindings(opts.linked, fsmObjects[0])
+        ? async () => [
+            ...(await linkFidelityFindings(opts.linked, fsmObjects[0])),
+            ...((await entryRequired())
+                ? await checkEntryOptions({
+                    linkedPath: opts.linked,
+                    fsmPath: fsmObjects[0],
+                    signal: opts.signal,
+                })
+                : []),
+        ]
         : undefined;
     return {
         request: {
@@ -609,10 +788,27 @@ function linkStep(opts) {
             linked: opts.linked,
             ...(gated === undefined ? {} : { mechanicalReview: gated }),
         },
+        ...(gated !== undefined && opts.entryGearsPath !== undefined
+            ? {
+                outputContract: async () => (await entryRequired()) ? ENTRY_OPTIONS_CONTRACT : undefined,
+            }
+            : {}),
         phase: 'link',
         pinKey: 'link',
         targetExt: link.target.ext,
         ...(gated === undefined ? {} : { linkFidelity: gated }),
+        ...(gated !== undefined &&
+            link.source.format === 'fsm' &&
+            link.source.ext === '.ts'
+            ? {
+                fsmSourceTypecheck: () => checkFsmTypeScript(fsmObjects[0], opts.signal),
+            }
+            : {}),
+        ...(gated !== undefined && link.source.format === 'fsm'
+            ? {
+                fsmSourceContinuation: () => fsmContinuationFindings(fsmObjects[0], opts.linkTarget, opts.signal),
+            }
+            : {}),
     };
 }
 /**
@@ -736,7 +932,7 @@ async function executeSteps(steps, pipeline, deps, opts = {}) {
             : [
                 ...diagnostics,
                 ...state.accepted.map((accepted) => `accepted phase "${accepted.step.phase}" left its live target at ${accepted.target}`),
-                `resume from the last accepted target with: ${resumeCommand(state.pipelineName, steps[failedIndex], state.accepted[state.accepted.length - 1].target)}`,
+                `resume from the last accepted target with: ${resumeCommand(state.pipelineName, steps[failedIndex], state.accepted[state.accepted.length - 1].target, pipeline.passes)}`,
             ],
     });
     for (let index = 0; index < steps.length; index++) {
@@ -796,6 +992,71 @@ async function executeSteps(steps, pipeline, deps, opts = {}) {
             target,
             elapsedMs: Date.now() - startedAt,
         });
+        let request = mode.mode === 'update' && step.request.kind === 'compile'
+            ? {
+                ...step.request,
+                update: { priorInput: mode.priorInput, diff: mode.diff },
+            }
+            : step.request;
+        if (request.kind === 'link' && step.outputContract !== undefined) {
+            const outputContract = await step.outputContract();
+            if (outputContract !== undefined)
+                request = { ...request, outputContract };
+        }
+        // The consumer cannot repair its protected source. Reject these existing
+        // parser findings before selecting or constructing any execution strategy.
+        if (step.gearsSourceContract !== undefined) {
+            const findings = await step.gearsSourceContract();
+            if (findings.length > 0 && step.request.kind === 'compile') {
+                fail();
+                diagnostics.push(formatFailureReport({
+                    phase: step.phase,
+                    target,
+                    reasons: [
+                        `invalid GEARS source: ${step.request.source}`,
+                        ...findings,
+                    ],
+                }));
+                return stopped(index);
+            }
+        }
+        for (const [check, name] of [
+            [step.fsmSourceTypecheck, 'TypeScript'],
+            [step.fsmSourceContinuation, 'continuation'],
+        ]) {
+            if (check === undefined)
+                continue;
+            let reasons = [];
+            let checkProtectedPaths;
+            try {
+                if (name === 'continuation') {
+                    checkProtectedPaths = await watchProtectedPaths(phaseProtectedPaths(request, {
+                        definitions,
+                        protectedInputs: [...immutableInputs, ...stepDeclared.paths],
+                    }));
+                }
+                const findings = await check();
+                if (findings.length > 0)
+                    reasons = ['invalid FSM source', ...findings];
+            }
+            catch (error) {
+                reasons = [`FSM ${name} check could not run: ${messageOf(error)}`];
+            }
+            // Module imports can execute code even when the later probe fails or
+            // throws. Their mutations outrank every checker outcome, before selection.
+            const changes = await checkProtectedPaths?.();
+            if (changes !== undefined && changes.length > 0)
+                reasons = changes;
+            if (reasons.length > 0) {
+                fail();
+                diagnostics.push(formatFailureReport({
+                    phase: step.phase,
+                    target,
+                    reasons,
+                }));
+                return stopped(index);
+            }
+        }
         // Selecting a compiled executor can throw rather than return a verdict —
         // notably a pinned link target whose installed engine declares no
         // supported contract, which the host factory rejects (phase-execution-30).
@@ -825,19 +1086,15 @@ async function executeSteps(steps, pipeline, deps, opts = {}) {
                 text: `updating ${step.phase} → ${target}`,
             });
         }
-        const request = mode.mode === 'update' && step.request.kind === 'compile'
-            ? {
-                ...step.request,
-                update: { priorInput: mode.priorInput, diff: mode.diff },
-            }
-            : step.request;
         const result = await runPhase({
             request,
             phase: step.phase,
             targetExt: step.targetExt,
             executor: selection.executor,
             definitions,
-            protectedInputs: stepDeclared.paths,
+            // Original invocation inputs remain immutable even when a later phase
+            // reads an intermediate and asks the author to clarify that original.
+            protectedInputs: [...immutableInputs, ...stepDeclared.paths],
             aliasInputs: [
                 ...immutableInputs,
                 ...declaredInputs,
@@ -851,16 +1108,45 @@ async function executeSteps(steps, pipeline, deps, opts = {}) {
         });
         if (!result.ok) {
             fail();
+            if (result.clarification !== undefined) {
+                return {
+                    ok: false,
+                    outputs,
+                    diagnostics,
+                    outcome: 'clarification-required',
+                    clarification: {
+                        schema: 'sublang.slc.clarification.v1',
+                        phase: step.phase,
+                        target,
+                        sources: [],
+                        questions: result.clarification,
+                    },
+                };
+            }
             diagnostics.push(formatFailureReport(result.report));
             return stopped(index);
         }
         diagnostics.push(...result.diagnostics);
-        // The DR-029 gate on the accepted result: a reviewed loop already relayed
-        // its findings to the Coder for repair, so a finding surviving to here is
-        // an unreviewed — or unrepaired — Source-fidelity break and fails the phase
-        // closed (phase-execution-51).
-        if (step.sourceFidelity === true && step.request.kind === 'compile') {
-            const findings = await sourceFidelityFindings(step.request.source, target);
+        // Recheck even custom executors that do not consume mechanicalReview.
+        // runPhase has already enforced the unchanged generic protection checks.
+        if (step.compileFidelity !== undefined) {
+            let findings;
+            let checkProtectedPaths;
+            try {
+                checkProtectedPaths = await watchProtectedPaths(phaseProtectedPaths(request, {
+                    definitions,
+                    protectedInputs: [...immutableInputs, ...stepDeclared.paths],
+                }));
+                findings = await step.compileFidelity();
+            }
+            catch (error) {
+                findings = [`mechanical review could not run: ${messageOf(error)}`];
+            }
+            // Coverage executes artifact guards/actions after generic acceptance.
+            // Their protected-input mutations outrank success, findings and errors.
+            const changes = await checkProtectedPaths?.();
+            if (changes !== undefined && changes.length > 0)
+                findings = changes;
             if (findings.length > 0) {
                 fail();
                 diagnostics.push(formatFailureReport({
@@ -967,10 +1253,40 @@ async function executeSteps(steps, pipeline, deps, opts = {}) {
  * the run stopped at, so a stopped link step resumes through the direct-link
  * form with that target as its object.
  */
-function resumeCommand(pipelineName, next, lastTarget) {
-    return next.request.kind === 'link'
-        ? `slc ${pipelineName}.link ${lastTarget} ${next.request.linkTarget}`
-        : `slc ${pipelineName}.${next.phase} ${lastTarget}`;
+function resumeCommand(pipelineName, next, lastTarget, passes) {
+    const operands = next.request.kind === 'link'
+        ? [
+            `${pipelineName}.link`,
+            lastTarget,
+            next.request.linkTarget,
+            // The link phase's opaque options are part of the invocation
+            // (pipeline-14); dropping them would resume a different link.
+            ...next.request.options.flatMap((option) => [
+                '--link-option',
+                `${option.name}=${option.value}`,
+            ]),
+        ]
+        : [
+            `${pipelineName}.${next.phase}`,
+            lastTarget,
+            // A standalone pass otherwise writes the `.opt` sibling (pipeline-33);
+            // name the target the stopped run was writing so the resumed pass
+            // lands where its downstream phases read.
+            ...(passes.some((pass) => pass.name === next.phase)
+                ? ['-o', stepTarget(next)]
+                : []),
+        ];
+    return ['slc', ...operands.map(shellOperand)].join(' ');
+}
+// An operand the shell would not read back verbatim — a path with a space, say
+// — must be quoted, or the reported line is a different invocation than the one
+// it resumes (pipeline-9, pipeline-12).
+const VERBATIM_OPERAND = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/** One resume operand, POSIX-quoted only where the shell would reinterpret it. */
+function shellOperand(value) {
+    return VERBATIM_OPERAND.test(value)
+        ? value
+        : `'${value.replaceAll("'", `'\\''`)}'`;
 }
 function stepTarget(step) {
     return step.request.kind === 'compile'