@aiwg/cli 2026.9.3 → 2026.9.5

package/dist/src/network-analysis/termshark.js

@@ -0,0 +1,252 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import semver from 'semver';
+import { formatEvidenceCitation } from './citations.js';
+import { hashEvidenceFile, safeProcessSpec } from './governance.js';
+export const TERMSHARK_HANDOFF_SCHEMA = 'aiwg.network-analysis.termshark-handoff.v1';
+export function createDefaultTermsharkLaunchHost() {
+    return {
+        async run(spec, options) {
+            const cacheRoot = path.join(options.configRoot, 'cache');
+            const dataRoot = path.join(options.configRoot, 'data');
+            await mkdir(cacheRoot, { recursive: true, mode: 0o700 });
+            await mkdir(dataRoot, { recursive: true, mode: 0o700 });
+            return new Promise((resolve, reject) => {
+                const child = spawn(spec.file, [...spec.args], {
+                    shell: false,
+                    stdio: 'inherit',
+                    signal: options.signal,
+                    env: {
+                        PATH: path.dirname(options.tsharkPath),
+                        XDG_CONFIG_HOME: options.configRoot,
+                        XDG_CACHE_HOME: cacheRoot,
+                        XDG_DATA_HOME: dataRoot,
+                        HOME: options.configRoot,
+                        TERM: process.env.TERM || 'xterm-256color',
+                        LC_ALL: 'C',
+                        LANG: 'C',
+                    },
+                });
+                child.once('error', reject);
+                child.once('close', (exitCode, signal) => resolve({ exitCode, signal }));
+            });
+        },
+    };
+}
+export async function createTermsharkHandoff(options) {
+    validateHandoffOptions(options);
+    const context = findAnalysisContext(options.evidence, options.contextDigest);
+    if (context.tool?.name !== 'tshark' || context.tool?.executable_path !== options.tsharkPath) {
+        throw new Error('Termshark handoff TShark path does not match the evidence analysis context');
+    }
+    const sourceHash = String(options.evidence.capture.hashes?.source?.value ?? '');
+    const actual = await hashEvidenceFile(options.capturePath, 'source-capture');
+    if (sourceHash !== actual.value || options.evidence.capture.capture_digest !== `sha256:${actual.value}`) {
+        throw new Error('Termshark handoff capture does not match the evidence bundle identity');
+    }
+    const displayFilterDigest = `sha256:${sha256(options.displayFilter)}`;
+    if (context.display_filter_digest !== displayFilterDigest) {
+        throw new Error('Termshark handoff display filter does not match the evidence analysis context');
+    }
+    const canonicalConfigRoot = await validateDirectory(options.configRoot, 'Termshark config root');
+    const profile = await validateProfile(options.profile, canonicalConfigRoot);
+    const focus = normalizeFocus(options.focus);
+    validateFocusEvidence(options.evidence, options.contextDigest, focus);
+    const effectiveFilter = focusedDisplayFilter(options.displayFilter, focus);
+    const base = baseHandoff(options, profile, canonicalConfigRoot, focus, displayFilterDigest, effectiveFilter);
+    if (options.termshark.status === 'missing' || !options.termshark.path || !options.termshark.version) {
+        return {
+            ...base,
+            status: 'unavailable',
+            diagnostics: [...options.termshark.diagnostics, 'Termshark is optional; TShark evidence remains valid and available.'],
+            command: null,
+            commandPreview: null,
+        };
+    }
+    if (options.termshark.status !== 'supported' || !semver.valid(options.termshark.version)
+        || !semver.satisfies(options.termshark.version, '>=2.4.0 <3.0.0')) {
+        return {
+            ...base,
+            status: 'incompatible',
+            diagnostics: [...options.termshark.diagnostics, `Termshark ${options.termshark.version} is outside the supported >=2.4.0 <3.0.0 range; TShark evidence remains valid.`],
+            command: null,
+            commandPreview: null,
+        };
+    }
+    const command = safeProcessSpec(options.termshark.path, [
+        '-r', options.capturePath,
+        '-Y', effectiveFilter,
+        '-C', profile.name,
+    ]);
+    return {
+        ...base,
+        status: 'ready',
+        diagnostics: [...options.termshark.diagnostics],
+        command,
+        commandPreview: formatCommandPreview(command),
+    };
+}
+export async function launchTermsharkHandoff(handoff, action, host = createDefaultTermsharkLaunchHost()) {
+    if (action.explicitOperatorAction !== true)
+        throw new Error('Termshark launch requires an explicit operator action');
+    if (handoff.status !== 'ready' || !handoff.command)
+        throw new Error('Termshark handoff is not ready to launch');
+    await validateLaunchIdentity(handoff);
+    const actual = await hashEvidenceFile(handoff.capturePath, 'source-capture');
+    if (`sha256:${actual.value}` !== handoff.captureDigest) {
+        throw new Error('Termshark launch capture no longer matches the reviewed handoff');
+    }
+    return host.run(handoff.command, { configRoot: handoff.configRoot, tsharkPath: handoff.tsharkPath, signal: action.signal });
+}
+export function recordTermsharkReview(handoff, evidence, input) {
+    if (evidence.bundle_id !== handoff.evidenceBundleId || evidence.capture.capture_digest !== handoff.captureDigest) {
+        throw new Error('Operator note evidence does not match the reviewed Termshark handoff');
+    }
+    if (!input.analyst.trim() || !input.note.trim() || input.citations.length === 0)
+        throw new Error('Analyst, note, and at least one packet locator are required');
+    const evidenceCitations = new Set(evidence.evidence_items.flatMap(item => item.citations.map(formatEvidenceCitation)));
+    for (const citation of input.citations) {
+        if (citation.capture_digest !== handoff.captureDigest || !evidenceCitations.has(formatEvidenceCitation(citation))) {
+            throw new Error('Operator note citation is not present in the evidence bundle');
+        }
+    }
+    return {
+        analyst: input.analyst,
+        recordedAt: input.recordedAt ?? new Date().toISOString(),
+        note: input.note,
+        citations: structuredClone(input.citations),
+        source: 'operator-returned-note',
+    };
+}
+function baseHandoff(options, profile, configRoot, focus, displayFilterDigest, effectiveFilter) {
+    const fingerprint = sha256(JSON.stringify({
+        bundle: options.evidence.bundle_id,
+        capture: options.evidence.capture.capture_digest,
+        context: options.contextDigest,
+        filter: effectiveFilter,
+        profile,
+        tool: options.termshark,
+    }));
+    return {
+        schema: TERMSHARK_HANDOFF_SCHEMA,
+        handoffId: `termshark-handoff:${fingerprint.slice(0, 24)}`,
+        evidenceBundleId: options.evidence.bundle_id,
+        capturePath: options.capturePath,
+        captureDigest: String(options.evidence.capture.capture_digest),
+        analysisContextDigest: options.contextDigest,
+        displayFilterDigest,
+        effectiveFilterDigest: `sha256:${sha256(effectiveFilter)}`,
+        focus,
+        tool: { path: options.termshark.path, version: options.termshark.version },
+        profile,
+        configRoot,
+        tsharkPath: options.tsharkPath,
+        tsharkVersion: String(findAnalysisContext(options.evidence, options.contextDigest).tool.version),
+        createdAt: (options.now ?? (() => new Date()))().toISOString(),
+        completionClaim: 'operator-returned-notes-only',
+    };
+}
+function findAnalysisContext(evidence, digest) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(digest))
+        throw new Error('Termshark handoff requires a canonical analysis context digest');
+    const contexts = evidence.capture.analysis_contexts;
+    const context = contexts.find(candidate => candidate.context_digest === digest);
+    if (!context)
+        throw new Error('Termshark handoff analysis context is absent from the evidence bundle');
+    return context;
+}
+async function validateDirectory(directory, label) {
+    if (!path.isAbsolute(directory))
+        throw new Error(`${label} must be an explicit absolute path`);
+    const stat = await lstat(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`${label} must be a real non-symlink directory`);
+    return realpath(directory);
+}
+async function validateProfile(profile, configRoot) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(profile.name))
+        throw new Error('Termshark profile name is invalid');
+    if (!profile.path)
+        return { name: profile.name };
+    if (!path.isAbsolute(profile.path))
+        throw new Error('Termshark profile path must be explicit and absolute');
+    const canonical = await realpath(profile.path);
+    const relative = path.relative(configRoot, canonical);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('Termshark profile path must remain below the config root');
+    }
+    const identity = await hashEvidenceFile(canonical, 'derived-artifact');
+    return { name: profile.name, path: canonical, digest: `sha256:${identity.value}` };
+}
+function normalizeFocus(focus) {
+    if (!focus)
+        return {};
+    if (focus.frame !== undefined && (!Number.isSafeInteger(focus.frame) || focus.frame < 1))
+        throw new Error('Termshark frame focus is invalid');
+    if (focus.stream && (!['tcp', 'udp'].includes(focus.stream.protocol) || !Number.isSafeInteger(focus.stream.id) || focus.stream.id < 0)) {
+        throw new Error('Termshark stream focus is invalid');
+    }
+    return structuredClone(focus);
+}
+function validateFocusEvidence(evidence, contextDigest, focus) {
+    if (focus.frame === undefined && focus.stream === undefined)
+        return;
+    const citations = evidence.evidence_items.flatMap(item => (item.citations ?? []));
+    if (focus.frame !== undefined && !citations.some(citation => citation.locator.type === 'frame'
+        && citation.locator.frame_number === focus.frame)) {
+        throw new Error('Termshark frame focus is absent from the evidence bundle');
+    }
+    if (focus.stream && !citations.some(citation => citation.locator.type === 'stream'
+        && citation.locator.protocol === focus.stream?.protocol
+        && citation.locator.stream_id === focus.stream.id
+        && citation.locator.context_digest === contextDigest)) {
+        throw new Error('Termshark stream focus is absent from the selected analysis context');
+    }
+}
+async function validateLaunchIdentity(handoff) {
+    if (!handoff.command || handoff.command.shell !== false || handoff.command.file !== handoff.tool.path) {
+        throw new Error('Termshark launch command no longer matches the reviewed tool');
+    }
+    const args = handoff.command.args;
+    if (args.length !== 6 || args[0] !== '-r' || args[1] !== handoff.capturePath
+        || args[2] !== '-Y' || args[4] !== '-C' || args[5] !== handoff.profile.name
+        || `sha256:${sha256(args[3])}` !== handoff.effectiveFilterDigest) {
+        throw new Error('Termshark launch arguments no longer match the reviewed handoff');
+    }
+    const configRoot = await validateDirectory(handoff.configRoot, 'Termshark config root');
+    if (configRoot !== handoff.configRoot)
+        throw new Error('Termshark config root identity changed after review');
+    if (handoff.profile.path) {
+        const profile = await validateProfile({ name: handoff.profile.name, path: handoff.profile.path }, configRoot);
+        if (profile.path !== handoff.profile.path || profile.digest !== handoff.profile.digest) {
+            throw new Error('Termshark profile identity changed after review');
+        }
+    }
+}
+function focusedDisplayFilter(displayFilter, focus) {
+    if (!displayFilter.trim() || displayFilter.length > 8192 || displayFilter.includes('\0'))
+        throw new Error('Termshark display filter is invalid');
+    const additions = [];
+    if (focus.frame !== undefined)
+        additions.push(`frame.number == ${focus.frame}`);
+    if (focus.stream)
+        additions.push(`${focus.stream.protocol}.stream == ${focus.stream.id}`);
+    return [displayFilter, ...additions].map(expression => `(${expression})`).join(' && ');
+}
+function validateHandoffOptions(options) {
+    if (!path.isAbsolute(options.capturePath))
+        throw new Error('Termshark capture path must be explicit and absolute');
+    if (!path.isAbsolute(options.tsharkPath))
+        throw new Error('TShark path must be explicit and absolute');
+    if (options.termshark.path !== null && !path.isAbsolute(options.termshark.path))
+        throw new Error('Termshark path must be explicit and absolute');
+}
+function formatCommandPreview(spec) {
+    return [spec.file, ...spec.args].map(argument => `'${argument.replace(/'/g, `'"'"'`)}'`).join(' ');
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+//# sourceMappingURL=termshark.js.map

package/dist/src/network-analysis/verification.js

@@ -0,0 +1,171 @@
+export const PACKET_VERIFICATION_SCHEMA = 'aiwg.sdlc.packet-verification.v1';
+const METRICS = [
+    'summary.packet_count',
+    'summary.endpoint_count',
+    'summary.conversation_count',
+    'summary.duration_seconds',
+    'summary.tcp_retransmission_count',
+    'summary.tcp_reset_count',
+    'summary.encrypted_transport_frame_count',
+];
+export function comparePacketEvidenceForVerification(input) {
+    validateInput(input);
+    const baselineRecipe = recipeId(input.baseline.evidence);
+    const candidateRecipe = recipeId(input.candidate.evidence);
+    const baselineContext = analysisContext(input.baseline.evidence);
+    const candidateContext = analysisContext(input.candidate.evidence);
+    const hardReasons = [];
+    if (baselineRecipe !== candidateRecipe)
+        hardReasons.push(`Recipe mismatch: ${baselineRecipe} vs ${candidateRecipe}.`);
+    if (baselineContext.display_filter_digest !== candidateContext.display_filter_digest)
+        hardReasons.push('Display-filter digests differ.');
+    if (baselineContext.tool?.version !== candidateContext.tool?.version)
+        hardReasons.push('TShark versions differ.');
+    if (input.baseline.topologyFingerprint !== input.candidate.topologyFingerprint)
+        hardReasons.push('Environment topology fingerprints differ.');
+    if (!['completed', 'empty'].includes(input.baseline.evidence.status) || !['completed', 'empty'].includes(input.candidate.evidence.status)) {
+        hardReasons.push('At least one evidence bundle is partial or unusable.');
+    }
+    const excludedMetrics = [];
+    const clockReasons = [];
+    if (input.baseline.clockOffsetMs === null || input.candidate.clockOffsetMs === null) {
+        excludedMetrics.push('summary.duration_seconds');
+        clockReasons.push('Clock alignment is unknown; timing comparison is excluded.');
+    }
+    else if (Math.abs(input.baseline.clockOffsetMs - input.candidate.clockOffsetMs) > input.conditions.clockAlignment.toleranceMs) {
+        excludedMetrics.push('summary.duration_seconds');
+        clockReasons.push('Clock-offset difference exceeds the declared tolerance; timing comparison is excluded.');
+    }
+    const comparableMetrics = hardReasons.length > 0 ? [] : METRICS.filter(metric => !excludedMetrics.includes(metric));
+    const baselineMetrics = summaryMetrics(input.baseline.evidence);
+    const candidateMetrics = summaryMetrics(input.candidate.evidence);
+    const metricDifferences = comparableMetrics.flatMap(metric => {
+        const baseline = baselineMetrics.get(metric);
+        const candidate = candidateMetrics.get(metric);
+        return typeof baseline !== 'number' || typeof candidate !== 'number'
+            ? []
+            : [{ metric, baseline, candidate, delta: candidate - baseline }];
+    });
+    const protocolDifferences = hardReasons.length > 0 ? [] : compareProtocols(baselineMetrics, candidateMetrics);
+    const reasons = [...hardReasons, ...clockReasons];
+    return {
+        schema: PACKET_VERIFICATION_SCHEMA,
+        verificationId: input.verificationId,
+        useCase: input.useCase,
+        traceability: {
+            requirementIds: [...input.requirementIds],
+            testIds: [...input.testIds],
+            defectOrChangeId: input.defectOrChangeId,
+            baseline: traceSide(input.baseline, baselineRecipe),
+            candidate: traceSide(input.candidate, candidateRecipe),
+        },
+        comparability: {
+            status: hardReasons.length > 0 ? 'incomparable' : excludedMetrics.length > 0 ? 'partially-comparable' : 'comparable',
+            reasons,
+            excludedMetrics,
+        },
+        conditions: {
+            ...structuredClone(input.conditions),
+            environments: { baseline: input.baseline.environmentId, candidate: input.candidate.environmentId },
+            topologyFingerprints: { baseline: input.baseline.topologyFingerprint, candidate: input.candidate.topologyFingerprint },
+            clockOffsetsMs: { baseline: input.baseline.clockOffsetMs, candidate: input.candidate.clockOffsetMs },
+        },
+        normalization: {
+            comparedFields: [...comparableMetrics, 'summary.protocol_hierarchy'],
+            excludedVolatileFields: ['capture digest', 'frame number', 'stream ID', 'absolute timestamp', 'endpoint identity', 'ephemeral port'],
+        },
+        metricDifferences,
+        protocolDifferences,
+        attachments: [attachment('baseline', input.baseline, baselineRecipe), attachment('candidate', input.candidate, candidateRecipe)],
+        performanceInterpretation: {
+            causality: 'not-established',
+            statement: 'Differences are observations under the recorded traffic, load, topology, vantage-point, sample-window, and clock conditions; they do not establish that the build or change caused the result.',
+        },
+    };
+}
+function validateInput(input) {
+    for (const [label, value] of Object.entries({ verification: input.verificationId, change: input.defectOrChangeId }))
+        required(value, label);
+    if (input.requirementIds.length === 0 || input.testIds.length === 0)
+        throw new Error('Packet verification requires requirement and test identities');
+    stringArray(input.requirementIds, 'Requirement IDs');
+    stringArray(input.testIds, 'Test IDs');
+    stringArray(input.conditions.topologyAssumptions, 'Topology assumptions');
+    if (input.conditions.topologyAssumptions.length === 0)
+        throw new Error('Packet verification requires topology assumptions');
+    for (const value of [input.baseline.buildId, input.candidate.buildId, input.baseline.environmentId, input.candidate.environmentId,
+        input.baseline.topologyFingerprint, input.candidate.topologyFingerprint, input.conditions.vantagePoint, input.conditions.traffic.scenario,
+        input.conditions.traffic.isolation, input.conditions.load, input.conditions.clockAlignment.method])
+        required(value, 'Verification condition');
+    if (!Number.isFinite(input.conditions.sampleWindowSeconds) || input.conditions.sampleWindowSeconds <= 0
+        || !Number.isFinite(input.conditions.clockAlignment.toleranceMs) || input.conditions.clockAlignment.toleranceMs < 0) {
+        throw new Error('Packet verification measurement bounds are invalid');
+    }
+    if (input.conditions.traffic.capturesUnrelatedTraffic !== false)
+        throw new Error('Packet verification must exclude unrelated traffic');
+    if (input.executionContext === 'ci' && input.conditions.traffic.kind !== 'synthetic') {
+        throw new Error('CI packet verification requires isolated synthetic traffic');
+    }
+}
+function analysisContext(evidence) {
+    const contexts = evidence.capture.analysis_contexts;
+    if (!Array.isArray(contexts) || contexts.length !== 1)
+        throw new Error('Packet verification requires one analysis context per bundle');
+    return contexts[0];
+}
+function recipeId(evidence) {
+    return required(evidence.provenance?.recipe_id, 'Recipe identity');
+}
+function traceSide(side, recipe) {
+    return { buildId: side.buildId, bundleId: side.evidence.bundle_id, captureDigest: String(side.evidence.capture.capture_digest), recipeId: recipe };
+}
+function attachment(sideName, side, recipe) {
+    return {
+        side: sideName,
+        bundleId: side.evidence.bundle_id,
+        captureDigest: String(side.evidence.capture.capture_digest),
+        recipeId: recipe,
+        artifactDigests: side.evidence.artifacts.map((artifact) => `${artifact.digest.algorithm}:${artifact.digest.value}`),
+        rawCaptureIncluded: false,
+    };
+}
+function summaryMetrics(evidence) {
+    const summary = evidence.evidence_items.find(item => String(item.evidence_id).includes('capture-summary'));
+    const fields = Array.isArray(summary?.observed_fields) ? summary.observed_fields : [];
+    const result = new Map();
+    for (const field of fields) {
+        if (typeof field.value === 'number' || typeof field.value === 'string')
+            result.set(field.name, field.value);
+    }
+    return result;
+}
+function compareProtocols(baseline, candidate) {
+    const left = protocolCounts(baseline.get('summary.protocol_hierarchy'));
+    const right = protocolCounts(candidate.get('summary.protocol_hierarchy'));
+    return [...new Set([...left.keys(), ...right.keys()])].sort().map(protocol => ({
+        protocol, baseline: left.get(protocol) ?? 0, candidate: right.get(protocol) ?? 0,
+        delta: (right.get(protocol) ?? 0) - (left.get(protocol) ?? 0),
+    }));
+}
+function protocolCounts(value) {
+    const result = new Map();
+    if (typeof value !== 'string')
+        return result;
+    for (const entry of value.split(',')) {
+        const [protocol, count] = entry.split(':');
+        if (protocol && Number.isFinite(Number(count)))
+            result.set(protocol, Number(count));
+    }
+    return result;
+}
+function required(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0'))
+        throw new Error(`${label} is required`);
+    return value;
+}
+function stringArray(value, label) {
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim()))
+        throw new Error(`${label} must contain non-empty strings`);
+    return [...value];
+}
+//# sourceMappingURL=verification.js.map

package/dist/src/output-modes/registry.js

@@ -5,6 +5,9 @@ import { createHash } from 'node:crypto';
 import { dirname, extname, join, resolve } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { z } from 'zod';
+import { getWritingChannelPack } from '../writing/channel-packs.js';
+import { WriterProfileStore } from '../writing/writer-profile-store.js';
+import { compileWriterProfile } from '../writing/writer-profile.js';
 import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
 const MODE_ID_PATTERN = /^[a-z0-9][a-z0-9.-]*$/;
 const PROTECTED = ['code', 'commands', 'citations', 'quoted-text', 'identifiers', 'machine-readable-blocks'];
@@ -41,6 +44,12 @@ const outputModeProfileSchema = z.object({
     }
 });
 const BUILTINS = [
+    ...['article', 'social', 'email', 'engineering', 'conversation'].map(channel => ({
+        id: `channel-${channel}`, version: '1.0.0', description: `Advisory ${channel} structure pack`,
+        kind: 'structure', stage: 'structure', order: 300,
+        instructions: getWritingChannelPack(channel).instructions, provenance: { source: 'AIWG channel packs', license: 'MIT' },
+        validation: { level: 'advisory' }, protectedContent: [...PROTECTED],
+    })),
     {
         id: 'unaltered', version: '1.0.0', description: 'No-op mode; preserves the provider output path unchanged.',
         kind: 'presentation', stage: 'presentation', order: -1000, instructions: '',
@@ -126,7 +135,18 @@ async function loadVoiceAdapters(frameworkRoot) {
     }
     return result;
 }
-export async function loadOutputModeRegistry(cwd, frameworkRoot) {
+async function loadWriterAdapters(cwd, scope, context) {
+    const store = new WriterProfileStore({ cwd, scope });
+    const result = [];
+    for (const id of await store.list()) {
+        const compiled = compileWriterProfile(await store.read(id), context);
+        result.push({ ...validateOutputModeProfile(compiled.profile), source: scope, sourcePath: join(store.directory, `${id}.json`) });
+    }
+    return result;
+}
+export async function loadOutputModeRegistry(cwd, frameworkRoot, context = {}) {
+    if (context.task !== undefined && (typeof context.task !== 'string' || !context.task.trim() || context.task.length > 120))
+        throw new Error('Invalid writer task context');
     const registry = new Map();
     for (const profile of BUILTINS)
         registry.set(profile.id, { ...profile, source: 'builtin' });
@@ -134,9 +154,16 @@ export async function loadOutputModeRegistry(cwd, frameworkRoot) {
         if (!registry.has(profile.id))
             registry.set(profile.id, profile);
     // User overrides built-ins; project overrides user.
-    for (const entry of [...profileDirs(cwd)].reverse())
-        for (const profile of await loadDirectory(entry.dir, entry.source))
+    for (const entry of [...profileDirs(cwd)].reverse()) {
+        const profiles = await loadDirectory(entry.dir, entry.source);
+        const writers = await loadWriterAdapters(cwd, entry.source, context);
+        const ids = new Set(profiles.map(profile => profile.id));
+        for (const writer of writers)
+            if (ids.has(writer.id))
+                throw new Error(`Duplicate output mode '${writer.id}' from a writer sidecar and a mode file in the same scope.`);
+        for (const profile of [...profiles, ...writers])
             registry.set(profile.id, profile);
+    }
     return registry;
 }
 function statePath(cwd, scope) {
@@ -162,8 +189,8 @@ export async function writeOutputModeState(cwd, scope, modes) {
     await writeFile(path, stringify({ version: 1, modes }), 'utf8');
     return path;
 }
-export async function resolveOutputModes(cwd, frameworkRoot, invocation = [], overrides = {}) {
-    const registry = await loadOutputModeRegistry(cwd, frameworkRoot);
+export async function resolveOutputModes(cwd, frameworkRoot, invocation = [], overrides = {}, context = {}) {
+    const registry = await loadOutputModeRegistry(cwd, frameworkRoot, context);
     const project = overrides.project ?? (await readOutputModeState(cwd, 'project')).modes;
     const session = overrides.session ?? (await readOutputModeState(cwd, 'session')).modes;
     for (const [scope, modes] of [['project', project], ['session', session], ['invocation', invocation]]) {
@@ -188,7 +215,11 @@ export async function resolveOutputModes(cwd, frameworkRoot, invocation = [], ov
                 throw new Error(`Output modes '${a.id}' and '${b.id}' conflict. Disable one or configure an explicit merge strategy.`);
             if (a.kind === b.kind && a.kind !== 'voice')
                 throw new Error(`Output modes '${a.id}' and '${b.id}' share kind '${a.kind}' without a merge strategy.`);
-            if (a.kind === 'voice' && b.kind === 'voice' && a.mergeStrategy !== 'weighted-voice' && b.mergeStrategy !== 'weighted-voice')
+            const writerSelected = a.id.startsWith('writer-') || b.id.startsWith('writer-');
+            const missingMerge = writerSelected
+                ? a.mergeStrategy !== 'weighted-voice' || b.mergeStrategy !== 'weighted-voice'
+                : a.mergeStrategy !== 'weighted-voice' && b.mergeStrategy !== 'weighted-voice';
+            if (a.kind === 'voice' && b.kind === 'voice' && missingMerge)
                 throw new Error(`Voice modes '${a.id}' and '${b.id}' require an explicit weighted-voice merge strategy.`);
         }
     for (const mode of modes)