@lumenflow/cli 5.3.2 → 5.4.0

package/dist/signal-hook.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { A2ASignalV1Schema } from '@lumenflow/control-plane-sdk/a2a';
+import { CLAUDE_HOOKS, ENV_VARS, LUMENFLOW_PATHS } from '@lumenflow/core/wu-constants';
+import { runCLI } from './cli-entry-point.js';
+import { collectActiveSessionRecords } from './session-cross-link.js';
+export const SIGNAL_HOOK_EVENT_NAME = 'signal:received';
+export const SIGNAL_HOOK_QUEUE_DIR = path.join(LUMENFLOW_PATHS.STATE_DIR, 'signal-hooks');
+export const SIGNAL_RECEIVED_HOOK_SCRIPT = CLAUDE_HOOKS.SCRIPTS.SIGNAL_RECEIVED;
+const SESSION_CURRENT_FILE = LUMENFLOW_PATHS.SESSION_CURRENT;
+const INTERRUPT_RANK = {
+    urgent: 3,
+    immediate: 3,
+    priority: 2,
+    soon: 2,
+    advisory: 1,
+};
+function sanitizeQueueName(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9_.:-]/g, '_');
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function sessionIdentities(session) {
+    return [session.session_id, session.agent_identity, session.display_name].filter((value) => typeof value === 'string' && value.length > 0);
+}
+function identityForReceipt(session) {
+    return session.agent_identity ?? session.session_id ?? session.wu_id;
+}
+function normalizeOrigin(origin) {
+    return origin === 'remote' ? 'remote' : 'local';
+}
+function normalizeRecipients(signal) {
+    if (signal.recipients && signal.recipients.length > 0) {
+        return Array.from(new Set(signal.recipients.map((recipient) => recipient.trim()).filter(Boolean)));
+    }
+    return signal.target_agent ? [signal.target_agent] : [];
+}
+function matchesRecipient(session, recipients) {
+    const identitySet = new Set(sessionIdentities(session));
+    return recipients.some((recipient) => identitySet.has(recipient));
+}
+function eventSortRank(event) {
+    return INTERRUPT_RANK[event.signal.interrupt_class ?? 'advisory'] ?? 0;
+}
+function parseEvent(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (parsed.event !== SIGNAL_HOOK_EVENT_NAME ||
+            parsed.schema_version !== 'A2A.V1' ||
+            typeof parsed.signal_id !== 'string' ||
+            typeof parsed.recipient_session_id !== 'string' ||
+            typeof parsed.recipient_identity !== 'string' ||
+            typeof parsed.dedupe_key !== 'string') {
+            return null;
+        }
+        A2ASignalV1Schema.parse(parsed.signal);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function buildDedupeKey(signal, session) {
+    const sessionId = session.session_id ?? identityForReceipt(session);
+    return `${sessionId}:${signal.idempotency_key ?? signal.signal_id}`;
+}
+function buildDeliveryId(dedupeKey) {
+    return `sigdel-${Buffer.from(dedupeKey).toString('base64url').slice(0, 16)}`;
+}
+function buildNextAction(signal) {
+    if (signal.requires_ack !== true) {
+        return undefined;
+    }
+    const scope = signal.wu_id ? ` --wu ${signal.wu_id}` : '';
+    return {
+        requires_ack: true,
+        reply_to: signal.signal_id,
+        ack_command: `pnpm mem:signal 'Agreed'${scope} --reply-to ${signal.signal_id} --intent AGREE`,
+        reject_command: `pnpm mem:signal 'Rejected: <reason>'${scope} --reply-to ${signal.signal_id} --intent REJECT`,
+        prep_gate: 'wu:prep blocks until this signal is answered with AGREE or REJECT.',
+    };
+}
+function buildEvent(signal, session, deliveredAt) {
+    const sessionId = session.session_id;
+    if (!sessionId) {
+        return null;
+    }
+    const dedupeKey = buildDedupeKey(signal, session);
+    const nextAction = buildNextAction(signal);
+    return {
+        event: SIGNAL_HOOK_EVENT_NAME,
+        schema_version: 'A2A.V1',
+        signal,
+        signal_id: signal.signal_id,
+        recipient_session_id: sessionId,
+        recipient_identity: identityForReceipt(session),
+        ...(session.display_name ? { recipient_display_name: session.display_name } : {}),
+        delivered_at: deliveredAt,
+        delivery_id: buildDeliveryId(dedupeKey),
+        dedupe_key: dedupeKey,
+        ...(nextAction ? { next_action: nextAction } : {}),
+    };
+}
+export function getSignalHookQueuePath(baseDir, sessionId) {
+    return path.join(baseDir, SIGNAL_HOOK_QUEUE_DIR, `${sanitizeQueueName(sessionId)}.jsonl`);
+}
+export function buildA2ASignalForHook(signal) {
+    const payload = {
+        schema_version: 'A2A.V1',
+        signal_id: signal.signal_id ?? signal.id,
+        sender_identity: signal.sender_identity ?? signal.sender ?? 'system',
+        recipients: normalizeRecipients(signal),
+        message: signal.message,
+        created_at: signal.created_at,
+        origin: normalizeOrigin(signal.origin),
+    };
+    if (signal.workspace_id)
+        payload.workspace_id = signal.workspace_id;
+    if (signal.thread_id)
+        payload.thread_id = signal.thread_id;
+    if (signal.reply_to)
+        payload.reply_to = signal.reply_to;
+    if (signal.intent)
+        payload.intent = signal.intent;
+    if (signal.interrupt_class)
+        payload.interrupt_class = signal.interrupt_class;
+    if (signal.requires_ack !== undefined)
+        payload.requires_ack = signal.requires_ack;
+    if (signal.idempotency_key)
+        payload.idempotency_key = signal.idempotency_key;
+    if (signal.wu_id)
+        payload.wu_id = signal.wu_id;
+    if (signal.initiative)
+        payload.initiative = signal.initiative;
+    if (signal.lane)
+        payload.lane = signal.lane;
+    if (signal.role)
+        payload.role = signal.role;
+    if (signal.target_role)
+        payload.target_role = signal.target_role;
+    if (signal.delegation_id)
+        payload.delegation_id = signal.delegation_id;
+    if (signal.target_agent)
+        payload.target_agent = signal.target_agent;
+    return A2ASignalV1Schema.parse(payload);
+}
+export async function readPendingSignalReceivedEvents(baseDir, sessionId) {
+    const queuePath = getSignalHookQueuePath(baseDir, sessionId);
+    try {
+        const content = await fs.readFile(queuePath, 'utf-8');
+        return content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map(parseEvent)
+            .filter((event) => event !== null)
+            .sort((left, right) => {
+            const rankDelta = eventSortRank(right) - eventSortRank(left);
+            if (rankDelta !== 0)
+                return rankDelta;
+            return left.delivered_at.localeCompare(right.delivered_at);
+        });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+async function appendEventIfMissing(baseDir, event) {
+    const queuePath = getSignalHookQueuePath(baseDir, event.recipient_session_id);
+    const existing = await readPendingSignalReceivedEvents(baseDir, event.recipient_session_id);
+    if (existing.some((candidate) => candidate.dedupe_key === event.dedupe_key)) {
+        return false;
+    }
+    await fs.mkdir(path.dirname(queuePath), { recursive: true });
+    await fs.appendFile(queuePath, `${JSON.stringify(event)}\n`, 'utf-8');
+    return true;
+}
+export async function dispatchSignalReceivedEvents(baseDir, options) {
+    const parsedSignal = A2ASignalV1Schema.parse(options.signal);
+    const recipients = parsedSignal.recipients ?? [];
+    if (recipients.length === 0) {
+        return { emittedCount: 0, skippedDuplicateCount: 0, inactiveRecipientCount: 0 };
+    }
+    const deliveredAt = options.deliveredAt ?? new Date().toISOString();
+    const activeSessions = collectActiveSessionRecords(baseDir);
+    const allRecipientMatches = activeSessions.filter((session) => matchesRecipient(session, recipients));
+    const recipientMatches = options.recipientSessionId
+        ? allRecipientMatches.filter((session) => sessionIdentities(session).includes(options.recipientSessionId ?? ''))
+        : allRecipientMatches;
+    let emittedCount = 0;
+    let skippedDuplicateCount = 0;
+    for (const session of recipientMatches) {
+        const event = buildEvent(parsedSignal, session, deliveredAt);
+        if (!event) {
+            continue;
+        }
+        if (await appendEventIfMissing(baseDir, event)) {
+            emittedCount += 1;
+        }
+        else {
+            skippedDuplicateCount += 1;
+        }
+    }
+    const activeRecipientIds = new Set(allRecipientMatches.flatMap((session) => sessionIdentities(session)));
+    const inactiveRecipientCount = recipients.filter((recipient) => !activeRecipientIds.has(recipient)).length;
+    return { emittedCount, skippedDuplicateCount, inactiveRecipientCount };
+}
+async function resolveCurrentSessionId(baseDir) {
+    const envSessionId = nonEmptyString(process.env[ENV_VARS.AGENT_SESSION]);
+    if (envSessionId) {
+        return envSessionId;
+    }
+    try {
+        const content = await fs.readFile(path.join(baseDir, SESSION_CURRENT_FILE), 'utf-8');
+        const parsed = JSON.parse(content);
+        return nonEmptyString(parsed.session_id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function drainSignalReceivedEvents(baseDir, sessionId) {
+    const resolvedSessionId = sessionId ?? (await resolveCurrentSessionId(baseDir));
+    if (!resolvedSessionId) {
+        return [];
+    }
+    const events = await readPendingSignalReceivedEvents(baseDir, resolvedSessionId);
+    if (events.length > 0) {
+        await fs.rm(getSignalHookQueuePath(baseDir, resolvedSessionId), { force: true });
+    }
+    return events;
+}
+export function formatClaudeSignalReceivedPrompt(events) {
+    if (events.length === 0) {
+        return '';
+    }
+    const lines = [
+        '<lumenflow-signal-events>',
+        'Unread A2A signal:received events arrived for this session. Treat each directed signal as a decision point before continuing.',
+    ];
+    for (const event of events) {
+        const signal = event.signal;
+        lines.push('');
+        lines.push(`- signal_id: ${signal.signal_id}`);
+        lines.push(`  sender: ${signal.sender_identity}`);
+        lines.push(`  intent: ${signal.intent ?? 'INFO'}`);
+        lines.push(`  interrupt_class: ${signal.interrupt_class ?? 'advisory'}`);
+        lines.push(`  requires_ack: ${signal.requires_ack === true ? 'true' : 'false'}`);
+        if (signal.wu_id)
+            lines.push(`  wu: ${signal.wu_id}`);
+        if (signal.thread_id)
+            lines.push(`  thread: ${signal.thread_id}`);
+        lines.push(`  message: ${signal.message}`);
+        if (event.next_action) {
+            lines.push('  next_action:');
+            lines.push(`    ack: ${event.next_action.ack_command}`);
+            lines.push(`    reject: ${event.next_action.reject_command}`);
+            lines.push(`    gate: ${event.next_action.prep_gate}`);
+        }
+    }
+    lines.push('</lumenflow-signal-events>');
+    return lines.join('\n');
+}
+export function generateSignalReceivedHookScript() {
+    const agentSessionEnvVar = ENV_VARS.AGENT_SESSION;
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# signal-received.sh (WU-2921)
+#
+# Claude Code PostToolUse hook for A2A signal:received delivery.
+# Drains pending events for the current session and prints a structured
+# prompt prefix for Claude at the next safe tool boundary.
+#
+# Exit codes:
+#   0 = Always (signal delivery is fail-open)
+#
+
+set +e
+
+HOOK_EVENT="\${hook_event_name:-PostToolUse}"
+if [[ "$HOOK_EVENT" != "PostToolUse" ]]; then
+  exit 0
+fi
+
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  exit 0
+fi
+
+REPO_PATH="$CLAUDE_PROJECT_DIR"
+HOOK_ENTRY="$REPO_PATH/node_modules/@lumenflow/cli/dist/signal-hook.js"
+
+if [[ ! -f "$HOOK_ENTRY" && -f "$REPO_PATH/packages/@lumenflow/cli/dist/signal-hook.js" ]]; then
+  HOOK_ENTRY="$REPO_PATH/packages/@lumenflow/cli/dist/signal-hook.js"
+fi
+
+if [[ ! -f "$HOOK_ENTRY" ]]; then
+  exit 0
+fi
+
+SESSION_ARGS=()
+if [[ -n "\${${agentSessionEnvVar}:-}" ]]; then
+  SESSION_ARGS=(--session "$${agentSessionEnvVar}")
+fi
+
+node "$HOOK_ENTRY" drain --project "$REPO_PATH" "\${SESSION_ARGS[@]}" 2>/dev/null || true
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}
+function parseDrainArgs(argv) {
+    const [, , command, ...rest] = argv;
+    const result = {
+        command,
+        project: process.cwd(),
+    };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === '--project' && rest[index + 1]) {
+            result.project = rest[index + 1];
+            index += 1;
+        }
+        else if (arg === '--session' && rest[index + 1]) {
+            result.session = rest[index + 1];
+            index += 1;
+        }
+    }
+    return result;
+}
+export async function main() {
+    const args = parseDrainArgs(process.argv);
+    if (args.command !== 'drain') {
+        return;
+    }
+    const events = await drainSignalReceivedEvents(args.project, args.session);
+    const prompt = formatClaudeSignalReceivedPrompt(events);
+    if (prompt) {
+        console.log(prompt);
+    }
+}
+if (import.meta.main) {
+    void runCLI(main, { commandName: 'signal-hook' });
+}
+//# sourceMappingURL=signal-hook.js.map

package/dist/signal-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-hook.js","sourceRoot":"","sources":["../src/signal-hook.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,4DAA4D;AAE5D,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAoB,MAAM,kCAAkC,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,2BAA2B,EAA+B,MAAM,yBAAyB,CAAC;AAEnG,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAA0B,CAAC;AACjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAC1F,MAAM,CAAC,MAAM,2BAA2B,GAAG,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC;AAEhF,MAAM,oBAAoB,GAAG,eAAe,CAAC,eAAe,CAAC;AAC7D,MAAM,cAAc,GAA2B;IAC7C,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;CACZ,CAAC;AA4DF,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,OAAO,SAAS,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC;AAED,SAAS,iBAAiB,CAAC,OAA+B;IACxD,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CAC9E,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAC1E,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,OAA+B;IACzD,OAAO,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;AACvE,CAAC;AAED,SAAS,eAAe,CAAC,MAA0B;IACjD,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AAClD,CAAC;AAED,SAAS,mBAAmB,CAC1B,MAAgE;IAEhE,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC,IAAI,CACf,IAAI,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,gBAAgB,CAAC,OAA+B,EAAE,UAA6B;IACtF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,aAAa,CAAC,KAA8B;IACnD,OAAO,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QAC3D,IACE,MAAM,CAAC,KAAK,KAAK,sBAAsB;YACvC,MAAM,CAAC,cAAc,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YACpC,OAAO,MAAM,CAAC,oBAAoB,KAAK,QAAQ;YAC/C,OAAO,MAAM,CAAC,kBAAkB,KAAK,QAAQ;YAC7C,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,EACrC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,MAAmB,EAAE,OAA+B;IAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpE,OAAO,GAAG,SAAS,IAAI,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB;IACxC,OAAO,UAAU,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AAC/E,CAAC;AAED,SAAS,eAAe,CAAC,MAAmB;IAC1C,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,OAAO;QACL,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,MAAM,CAAC,SAAS;QAC1B,WAAW,EAAE,2BAA2B,KAAK,eAAe,MAAM,CAAC,SAAS,iBAAiB;QAC7F,cAAc,EAAE,uCAAuC,KAAK,eAAe,MAAM,CAAC,SAAS,kBAAkB;QAC7G,SAAS,EAAE,oEAAoE;KAChF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,MAAmB,EACnB,OAA+B,EAC/B,WAAmB;IAEnB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IACrC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO;QACL,KAAK,EAAE,sBAAsB;QAC7B,cAAc,EAAE,QAAQ;QACxB,MAAM;QACN,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,oBAAoB,EAAE,SAAS;QAC/B,kBAAkB,EAAE,kBAAkB,CAAC,OAAO,CAAC;QAC/C,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,sBAAsB,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,eAAe,CAAC,SAAS,CAAC;QACvC,UAAU,EAAE,SAAS;QACrB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,SAAiB;IACvE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,qBAAqB,EAAE,GAAG,iBAAiB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAA2B;IAC/D,MAAM,OAAO,GAA4C;QACvD,cAAc,EAAE,QAAQ;QACxB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,EAAE;QACxC,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,MAAM,IAAI,QAAQ;QACpE,UAAU,EAAE,mBAAmB,CAAC,MAAM,CAAC;QACvC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;KACvC,CAAC;IAEF,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IACpE,IAAI,MAAM,CAAC,SAAS;QAAE,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAC3D,IAAI,MAAM,CAAC,QAAQ;QAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACxD,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC7E,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAClF,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC7E,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC/C,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5C,IAAI,MAAM,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5C,IAAI,MAAM,CAAC,WAAW;QAAE,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACjE,IAAI,MAAM,CAAC,aAAa;QAAE,OAAO,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IACvE,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAEpE,OAAO,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAAe,EACf,SAAiB;IAEjB,MAAM,SAAS,GAAG,sBAAsB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,OAAO;aACX,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;aACjC,GAAG,CAAC,UAAU,CAAC;aACf,MAAM,CAAC,CAAC,KAAK,EAAoC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC;aACnE,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAC7D,IAAI,SAAS,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YACtC,OAAO,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;IACP,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,OAAe,EACf,KAA8B;IAE9B,MAAM,SAAS,GAAG,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC9E,MAAM,QAAQ,GAAG,MAAM,+BAA+B,CAAC,OAAO,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC5F,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAAe,EACf,OAA4C;IAE5C,MAAM,YAAY,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC;IACjD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,qBAAqB,EAAE,CAAC,EAAE,sBAAsB,EAAE,CAAC,EAAE,CAAC;IAClF,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpE,MAAM,cAAc,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,mBAAmB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5D,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,CACtC,CAAC;IACF,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB;QACjD,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CACrC,iBAAiB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC,CACtE;QACH,CAAC,CAAC,mBAAmB,CAAC;IACxB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,qBAAqB,GAAG,CAAC,CAAC;IAE9B,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC7D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,IAAI,MAAM,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;YAC/C,YAAY,IAAI,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,qBAAqB,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CACrE,CAAC;IACF,MAAM,sBAAsB,GAAG,UAAU,CAAC,MAAM,CAC9C,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAClD,CAAC,MAAM,CAAC;IAET,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,CAAC;AACzE,CAAC;AAED,KAAK,UAAU,uBAAuB,CAAC,OAAe;IACpD,MAAM,YAAY,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;IACzE,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC,CAAC;QACrF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA6B,CAAC;QAC/D,OAAO,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAe,EACf,SAAkB;IAElB,MAAM,iBAAiB,GAAG,SAAS,IAAI,CAAC,MAAM,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;IAChF,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,+BAA+B,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,EAAE,CAAC,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,MAA0C;IAE1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG;QACZ,2BAA2B;QAC3B,+HAA+H;KAChI,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;QACnD,KAAK,CAAC,IAAI,CAAC,sBAAsB,MAAM,CAAC,eAAe,IAAI,UAAU,EAAE,CAAC,CAAC;QACzE,KAAK,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACjF,IAAI,MAAM,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;YACxD,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,WAAW,CAAC,cAAc,EAAE,CAAC,CAAC;YAC9D,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,MAAM,kBAAkB,GAAG,QAAQ,CAAC,aAAa,CAAC;IAClD,sCAAsC;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAmCM,kBAAkB;8BACH,kBAAkB;;;;;CAK/C,CAAC;IACA,qCAAqC;AACvC,CAAC;AAED,SAAS,cAAc,CAAC,IAAc;IACpC,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,MAAM,MAAM,GAA4D;QACtE,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE;KACvB,CAAC;IAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,WAAW,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACjC,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACjC,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/wu-prep.js

@@ -46,10 +46,12 @@ import { createGitForPath } from '@lumenflow/core/git-adapter';
 import { TEST_FILE_PATTERNS } from '@lumenflow/core';
 import { resolveChangedFiles, isCodePathCoveredByChangedFiles, resolveBaseRef, } from '@lumenflow/core/wu-rules-engine';
 import { validatePreflight, formatPreflightResult, formatPreflightWarnings, } from '@lumenflow/core/wu-preflight-validators';
-import { CONTEXT_VALIDATION, PATTERNS, EXIT_CODES, WU_STATUS, EMOJI, CLAIMED_MODES, } from '@lumenflow/core/wu-constants';
+import { CONTEXT_VALIDATION, PATTERNS, EXIT_CODES, WU_STATUS, EMOJI, CLAIMED_MODES, LUMENFLOW_PATHS, } from '@lumenflow/core/wu-constants';
+import { WUStateStore } from '@lumenflow/core/wu-state-store';
 import { defaultBranchFrom } from '@lumenflow/core/wu-done-paths';
 import { getCurrentBranch } from '@lumenflow/core/wu-helpers';
 import { createPreGatesCheckpoint } from '@lumenflow/core/wu-checkpoint';
+import { isSignalAddressedToAny, loadSignals, resolveReaderIdentities, } from '@lumenflow/memory/signal';
 import { resolveTddDiffEvidencePolicy, resolveTddOrderingPolicy, resolveScopedUnitTestExecutionPlan, formatScopedUnitTestFallbackMessage, } from '@lumenflow/packs-software-delivery/policy/gates-config';
 import { runGates } from './gates.js';
 import { evaluateMainDirtyMutationGuard } from './hooks/dirty-guard.js';
@@ -95,6 +97,11 @@ const PREP_OPTIONS = {
     },
     force: WU_OPTIONS.force,
     reason: WU_OPTIONS.reason,
+    allowUnreadSignals: {
+        name: 'allowUnreadSignals',
+        flags: '--allow-unread-signals',
+        description: 'Allow prep to continue with unread directed mem:signal entries; requires --reason',
+    },
 };
 export const resolveScopedUnitTestsForPrep = resolveScopedUnitTestsForLifecycle;
 export function buildRunGatesOptionsForPrep(options) {
@@ -868,6 +875,65 @@ export function evaluatePrepMainMutationGuard(options) {
         isBranchPrMode: options.isBranchPr,
     });
 }
+function dedupeSignals(signals) {
+    const seen = new Set();
+    const deduped = [];
+    for (const signal of signals) {
+        if (seen.has(signal.id)) {
+            continue;
+        }
+        seen.add(signal.id);
+        deduped.push(signal);
+    }
+    return deduped;
+}
+export async function findUnreadDirectedSignalsForPrep(options) {
+    const readerIds = await resolveReaderIdentities(options.baseDir);
+    const readerId = readerIds[0] ?? 'local-session';
+    const wuSignals = await loadSignals(options.baseDir, {
+        wuId: options.wuId,
+        unreadOnly: true,
+        readerId,
+        compatibilityMode: 'skip-legacy',
+    });
+    const initiativeSignals = options.initiative
+        ? await loadSignals(options.baseDir, {
+            initiative: options.initiative,
+            unreadOnly: true,
+            readerId,
+            compatibilityMode: 'skip-legacy',
+        })
+        : [];
+    const signals = dedupeSignals([...wuSignals, ...initiativeSignals]).filter((signal) => isSignalAddressedToAny(signal, readerIds));
+    return { readerId, readerIds, signals };
+}
+export function formatUnreadDirectedSignalsFailure(options) {
+    const lines = options.signals
+        .map((signal) => {
+        const sender = signal.sender_identity ?? signal.sender ?? 'unknown';
+        const metadata = [
+            signal.intent ? `intent=${signal.intent}` : null,
+            signal.requires_ack !== undefined ? `requires_ack=${signal.requires_ack}` : null,
+        ].filter(Boolean);
+        const metadataText = metadata.length > 0 ? ` (${metadata.join(', ')})` : '';
+        return `  - ${signal.id} from ${sender}${metadataText}: ${signal.message}`;
+    })
+        .join('\n');
+    return (`${EMOJI.FAILURE} Unread directed signals block wu:prep for ${options.wuId}.\n\n` +
+        `Current reader identity: ${options.readerId}\n\n` +
+        `Read, ACK, or explicitly dismiss these signals before continuing:\n` +
+        `${lines}\n\n` +
+        `Override only when the handoff was handled elsewhere:\n` +
+        `  pnpm wu:prep --id ${options.wuId} --allow-unread-signals --reason '<audit reason>'`);
+}
+export async function recordUnreadSignalOverrideForPrep(options) {
+    const stateDir = path.join(options.baseDir, LUMENFLOW_PATHS.STATE_DIR);
+    const store = new WUStateStore(stateDir);
+    await store.checkpoint(options.wuId, '[wu:prep] unread directed signals override', {
+        progress: `reader=${options.readerId};signals=${options.signalIds.join(',')}`,
+        nextSteps: `reason=${options.reason}`,
+    });
+}
 /**
  * Print success message with copy-paste instruction.
  */
@@ -912,6 +978,7 @@ export async function main() {
             PREP_OPTIONS.fullTests,
             PREP_OPTIONS.force,
             PREP_OPTIONS.reason,
+            PREP_OPTIONS.allowUnreadSignals,
         ],
         required: ['id'],
         allowPositionalId: true,
@@ -999,6 +1066,32 @@ export async function main() {
             die(mainMutationGuard.message ?? `${EMOJI.FAILURE} wu:prep blocked by dirty-main guard.`);
         }
     }
+    const unreadDirectedSignals = await findUnreadDirectedSignalsForPrep({
+        baseDir: location.cwd,
+        wuId: id,
+        initiative: typeof doc.initiative === 'string' ? doc.initiative : undefined,
+    });
+    if (unreadDirectedSignals.signals.length > 0) {
+        const overrideReason = typeof args.reason === 'string' ? args.reason.trim() : '';
+        if (!args.allowUnreadSignals) {
+            die(formatUnreadDirectedSignalsFailure({
+                wuId: id,
+                readerId: unreadDirectedSignals.readerId,
+                signals: unreadDirectedSignals.signals,
+            }));
+        }
+        if (!overrideReason) {
+            die(`${EMOJI.FAILURE} --allow-unread-signals requires --reason '<audit reason>' for ${id}.`);
+        }
+        await recordUnreadSignalOverrideForPrep({
+            baseDir: location.cwd,
+            wuId: id,
+            readerId: unreadDirectedSignals.readerId,
+            signalIds: unreadDirectedSignals.signals.map((signal) => signal.id),
+            reason: overrideReason,
+        });
+        console.log(`${PREP_PREFIX} ${EMOJI.WARNING} Continuing after unread directed signal override: ${overrideReason}`);
+    }
     console.log(`${PREP_PREFIX} Preparing ${id} for completion...`);
     console.log(`${PREP_PREFIX} Location: ${location.cwd}`);
     console.log(`${PREP_PREFIX} Main checkout: ${location.mainCheckout}`);