oh-my-codex 0.11.13 → 0.12.1

package/dist/team/runtime.js

@@ -3,10 +3,11 @@ import { existsSync, appendFileSync, mkdirSync } from 'fs';
 import { mkdir, readdir, readFile, writeFile } from 'fs/promises';
 import { performance } from 'perf_hooks';
 import { spawn, spawnSync } from 'child_process';
-import { sanitizeTeamName, isTmuxAvailable, createTeamSession, buildWorkerProcessLaunchSpec, resolveTeamWorkerCli, resolveTeamWorkerCliPlan, resolveTeamWorkerLaunchMode, waitForWorkerReady, dismissTrustPromptIfPresent, sleepFractionalSeconds, sendToWorker, sendToWorkerStdin, isWorkerAlive, getWorkerPanePid, killWorkerByPaneIdAsync, restoreStandaloneHudPane, teardownWorkerPanes, unregisterResizeHook, destroyTeamSession, listTeamSessions, } from './tmux-session.js';
+import { sanitizeTeamName, isTmuxAvailable, hasCurrentTmuxClientContext, createTeamSession, buildWorkerProcessLaunchSpec, resolveTeamWorkerCli, resolveTeamWorkerCliPlan, resolveTeamWorkerLaunchMode, waitForWorkerReady, dismissTrustPromptIfPresent, sleepFractionalSeconds, sendToWorker, sendToWorkerStdin, isWorkerAlive, getWorkerPanePid, killWorkerByPaneIdAsync, restoreStandaloneHudPane, teardownWorkerPanes, unregisterResizeHook, destroyTeamSession, listPaneIds, listTeamSessions, } from './tmux-session.js';
 import { teamInit as initTeamState, DEFAULT_MAX_WORKERS, teamReadConfig as readTeamConfig, teamWriteWorkerIdentity as writeWorkerIdentity, teamReadWorkerHeartbeat as readWorkerHeartbeat, teamReadWorkerStatus as readWorkerStatus, teamWriteWorkerInbox as writeWorkerInbox, teamCreateTask as createStateTask, teamReadTask as readTask, teamListTasks as listTasks, teamReadManifest as readTeamManifestV2, teamNormalizeGovernance as normalizeTeamGovernance, teamNormalizePolicy as normalizeTeamPolicy, teamClaimTask as claimTask, teamReleaseTaskClaim as releaseTaskClaim, teamReclaimExpiredTaskClaim as reclaimExpiredTaskClaim, teamAppendEvent as appendTeamEvent, teamReadTaskApproval as readTaskApproval, teamListMailbox as listMailboxMessages, teamMarkMessageDelivered as markMessageDelivered, teamMarkMessageNotified as markMessageNotified, teamEnqueueDispatchRequest as enqueueDispatchRequest, teamMarkDispatchRequestNotified as markDispatchRequestNotified, teamTransitionDispatchRequest as transitionDispatchRequest, teamReadDispatchRequest as readDispatchRequest, teamCleanup as cleanupTeamState, teamSaveConfig as saveTeamConfig, teamWriteShutdownRequest as writeShutdownRequest, teamReadShutdownAck as readShutdownAck, teamReadMonitorSnapshot as readMonitorSnapshot, teamWriteMonitorSnapshot as writeMonitorSnapshot, teamReadPhase as readTeamPhaseState, teamWritePhase as writeTeamPhaseState, } from './team-ops.js';
 import { queueInboxInstruction, queueDirectMailboxMessage, queueBroadcastMailboxMessage, waitForDispatchReceipt, } from './mcp-comm.js';
-import { generateWorkerOverlay, writeTeamWorkerInstructionsFile, removeTeamWorkerInstructionsFile, writeWorkerWorktreeRootAgentsFile, removeWorkerWorktreeRootAgentsFile, generateInitialInbox, generateTaskAssignmentInbox, generateShutdownInbox, generateTriggerMessage, generateMailboxTriggerMessage, generateLeaderMailboxTriggerMessage, writeWorkerRoleInstructionsFile, } from './worker-bootstrap.js';
+import { appendTeamDeliveryLogForCwd } from './delivery-log.js';
+import { generateWorkerOverlay, writeTeamWorkerInstructionsFile, removeTeamWorkerInstructionsFile, writeWorkerWorktreeRootAgentsFile, removeWorkerWorktreeRootAgentsFile, generateInitialInbox, generateTaskAssignmentInbox, generateShutdownInbox, buildTriggerDirective, buildMailboxTriggerDirective, buildLeaderMailboxTriggerDirective, writeWorkerRoleInstructionsFile, } from './worker-bootstrap.js';
 import { loadRolePrompt } from './role-router.js';
 import { composeRoleInstructionsForRole } from '../agents/native-config.js';
 import { codexPromptsDir } from '../utils/paths.js';
@@ -49,6 +50,58 @@ async function syncRootTeamModeStateOnTerminalPhase(teamName, phase, cwd) {
         // Best-effort compatibility sync only.
     }
 }
+export function applyCreatedInteractiveSessionToConfig(config, createdSession, workerPaneIds) {
+    config.tmux_session = createdSession.name;
+    config.leader_pane_id = createdSession.leaderPaneId;
+    config.hud_pane_id = createdSession.hudPaneId;
+    config.resize_hook_name = createdSession.resizeHookName;
+    config.resize_hook_target = createdSession.resizeHookTarget;
+    for (let i = 0; i < createdSession.workerPaneIds.length; i++) {
+        const paneId = createdSession.workerPaneIds[i];
+        workerPaneIds[i] = paneId;
+        if (config.workers[i]) {
+            config.workers[i].pane_id = paneId;
+        }
+    }
+}
+function collectShutdownPaneIds(params) {
+    const { config, livePaneIds = [], restoredStandaloneHudPaneId = null } = params;
+    const excludedPaneIds = new Set([
+        config.leader_pane_id,
+        config.hud_pane_id,
+        restoredStandaloneHudPaneId,
+    ].filter((paneId) => typeof paneId === 'string' && paneId.trim().startsWith('%')));
+    const paneIds = new Set();
+    for (const paneId of [
+        ...config.workers.map((worker) => worker.pane_id),
+        ...livePaneIds,
+    ]) {
+        if (typeof paneId !== 'string')
+            continue;
+        const normalized = paneId.trim();
+        if (!normalized.startsWith('%'))
+            continue;
+        if (excludedPaneIds.has(normalized))
+            continue;
+        paneIds.add(normalized);
+    }
+    return [...paneIds];
+}
+async function logRuntimeDispatchOutcome(params) {
+    const { cwd, teamName, workerName, requestId, messageId, intent, outcome, source = 'team.runtime' } = params;
+    await appendTeamDeliveryLogForCwd(cwd, {
+        event: 'dispatch_result',
+        source,
+        team: teamName,
+        request_id: requestId,
+        message_id: messageId,
+        to_worker: workerName,
+        intent,
+        transport: outcome.transport,
+        result: outcome.ok ? 'confirmed' : 'failed',
+        reason: outcome.reason,
+    });
+}
 function collectProvisionedShutdownWorktrees(config) {
     const seenWorktreePaths = new Set();
     const worktrees = [];
@@ -147,6 +200,36 @@ async function appendIntegrationEvent(teamName, type, worker, metadata, cwd) {
 async function sendIntegrationMessageToLeader(teamName, worker, body, cwd) {
     await sendWorkerMessage(teamName, worker.name, 'leader-fixed', body, cwd).catch(() => { });
 }
+function leaderHeadAdvanced(before, after) {
+    return typeof after === 'string' && after.length > 0 && after !== before;
+}
+async function recordIntegrationFailure(teamName, worker, state, details, cwd) {
+    const leaderHeadAfter = details.leaderHeadAfter ?? details.leaderHeadBefore;
+    const sourceShort = details.sourceCommit.slice(0, 12);
+    const leaderShort = details.leaderHeadBefore.slice(0, 12);
+    state.last_leader_head = leaderHeadAfter;
+    state.status = 'integration_failed';
+    state.conflict_commit = details.sourceCommit;
+    state.conflict_files = undefined;
+    state.updated_at = new Date().toISOString();
+    await appendIntegrationEvent(teamName, 'worker_integration_failed', worker, {
+        worker_name: worker.name,
+        operation: details.operation,
+        source_commit: details.sourceCommit,
+        leader_head_before: details.leaderHeadBefore,
+        leader_head_after: leaderHeadAfter,
+        worktree_path: details.worktreePath,
+        summary: `${details.operation} for ${worker.name} reported success but leader HEAD did not advance`,
+    }, cwd);
+    appendIntegrationReport(teamName, {
+        workerName: worker.name,
+        operation: details.operation,
+        strategy: details.strategy,
+        files: [],
+        detail: `${details.operation} reported success for ${sourceShort}, but leader HEAD did not advance from ${leaderShort}; not marking worker as integrated.`,
+    }, cwd);
+    await sendIntegrationMessageToLeader(teamName, worker, `INTEGRATION FAILED: ${details.operation} for ${worker.name} reported success, but leader HEAD stayed at ${leaderShort}. Not emitting INTEGRATED; retry or inspect leader branch state before continuing.`, cwd);
+}
 function autoCommitDirtyWorktree(worker) {
     const worktreePath = resolve(worker.worktree_path);
     const repoRoot = resolve(worker.worktree_repo_root);
@@ -247,8 +330,17 @@ async function integrateWorkerCommitsIntoLeader(params) {
             if (merge.ok) {
                 const newLeaderHead = resolveLeaderHead(repoRoot, cwd) ?? leaderHead;
                 const workerIntegrated = leaderContainsCommit(repoRoot, cwd, workerHead);
-                const leaderAdvanced = newLeaderHead !== leaderHead;
-                if (workerIntegrated && leaderAdvanced) {
+                if (!leaderHeadAdvanced(leaderHead, newLeaderHead)) {
+                    await recordIntegrationFailure(teamName, worker, state, {
+                        operation: 'merge',
+                        sourceCommit: workerHead,
+                        leaderHeadBefore: leaderHead,
+                        leaderHeadAfter: newLeaderHead,
+                        worktreePath,
+                        strategy: '-X theirs',
+                    }, cwd);
+                }
+                else if (workerIntegrated) {
                     state.last_integrated_head = workerHead;
                     state.last_leader_head = newLeaderHead;
                     state.status = 'integrated';
@@ -383,6 +475,18 @@ async function integrateWorkerCommitsIntoLeader(params) {
                     break;
                 }
                 const newLeaderHead = resolveLeaderHead(repoRoot, cwd) ?? leaderHead;
+                if (!leaderHeadAdvanced(leaderHead, newLeaderHead)) {
+                    await recordIntegrationFailure(teamName, worker, state, {
+                        operation: 'cherry-pick',
+                        sourceCommit: commit,
+                        leaderHeadBefore: leaderHead,
+                        leaderHeadAfter: newLeaderHead,
+                        worktreePath,
+                        strategy: '-X theirs',
+                    }, cwd);
+                    allPicked = false;
+                    break;
+                }
                 state.last_integrated_head = commit;
                 state.last_leader_head = newLeaderHead;
                 state.status = 'integrated';
@@ -1172,7 +1276,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
         if (!isTmuxAvailable()) {
             throw new Error('Team mode requires tmux. Install with: apt install tmux / brew install tmux');
         }
-        if (!process.env.TMUX) {
+        if (!hasCurrentTmuxClientContext()) {
             throw new Error('Team mode requires running inside tmux current leader pane');
         }
     }
@@ -1305,7 +1409,8 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
                 rolePromptContent: rawRolePromptContent ?? undefined,
                 worktreeRootAgentsCanonical: Boolean(workerWorkspace.worktreePath),
             });
-            const trigger = generateTriggerMessage(workerName, sanitized, resolveInstructionStateRoot(workerWorkspace.worktreePath));
+            const triggerDirective = buildTriggerDirective(workerName, sanitized, resolveInstructionStateRoot(workerWorkspace.worktreePath));
+            const trigger = triggerDirective.text;
             const initialPrompt = workerCliPlan[i - 1] === 'gemini' ? trigger : undefined;
             if (initialPrompt) {
                 await writeWorkerInbox(sanitized, workerName, inbox, leaderCwd);
@@ -1319,6 +1424,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
                 instructionsFilePath,
                 inbox,
                 trigger,
+                triggerIntent: triggerDirective.intent,
                 initialPrompt,
                 workerLaunchArgs,
                 workerCli: workerCliPlan[i - 1],
@@ -1355,14 +1461,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
             sessionCreated = true;
             createdWorkerPaneIds.push(...createdSession.workerPaneIds);
             createdLeaderPaneId = createdSession.leaderPaneId;
-            config.tmux_session = sessionName;
-            config.leader_pane_id = createdSession.leaderPaneId;
-            config.hud_pane_id = createdSession.hudPaneId;
-            config.resize_hook_name = createdSession.resizeHookName;
-            config.resize_hook_target = createdSession.resizeHookTarget;
-            for (let i = 0; i < createdSession.workerPaneIds.length; i++) {
-                workerPaneIds[i] = createdSession.workerPaneIds[i];
-            }
+            applyCreatedInteractiveSessionToConfig(config, createdSession, workerPaneIds);
         }
         else {
             config.tmux_session = `prompt-${sanitized}`;
@@ -1388,13 +1487,14 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
             if (!bootstrapPlan) {
                 throw new Error(`missing bootstrap plan for worker-${i}`);
             }
-            const { workerName, paneId, workerTasks, workerRole, inbox, trigger, initialPrompt } = {
+            const { workerName, paneId, workerTasks, workerRole, inbox, trigger, triggerIntent, initialPrompt } = {
                 workerName: bootstrapPlan.workerName,
                 paneId: workerPaneIds[i - 1],
                 workerTasks: bootstrapPlan.workerTasks,
                 workerRole: bootstrapPlan.workerRole,
                 inbox: bootstrapPlan.inbox,
                 trigger: bootstrapPlan.trigger,
+                triggerIntent: bootstrapPlan.triggerIntent,
                 initialPrompt: bootstrapPlan.initialPrompt,
             };
             const workerWorkspace = bootstrapPlan.workerWorkspace;
@@ -1418,7 +1518,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
             };
             // Get pane PID and store it (interactive mode) or process PID (prompt mode)
             if (workerLaunchMode === 'interactive') {
-                const panePid = getWorkerPanePid(sessionName, i);
+                const panePid = getWorkerPanePid(sessionName, i, paneId);
                 if (panePid)
                     identity.pid = panePid;
             }
@@ -1428,6 +1528,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
             if (paneId)
                 identity.pane_id = paneId;
             if (config.workers[i - 1]) {
+                config.workers[i - 1].pid = identity.pid;
                 config.workers[i - 1].pane_id = paneId;
                 config.workers[i - 1].role = workerRole;
                 config.workers[i - 1].worker_cli = workerCliPlan[i - 1];
@@ -1466,6 +1567,7 @@ export async function startTeam(teamName, task, agentType, workerCount, tasks, c
                         workerCli: workerCliPlan[i - 1],
                         inbox,
                         triggerMessage: trigger,
+                        intent: triggerIntent,
                         cwd: leaderCwd,
                         dispatchPolicy,
                         inboxCorrelationKey: `startup:${workerName}`,
@@ -1874,6 +1976,7 @@ export async function assignTask(teamName, workerName, taskId, cwd) {
         const maxAssignRetries = 2;
         const assignRetryDelayS = 2;
         let outcome = { ok: false, transport: 'none', reason: 'not_attempted' };
+        const triggerDirective = buildTriggerDirective(workerName, sanitized, resolveInstructionStateRoot(workerInfo.worktree_path));
         for (let attempt = 1; attempt <= maxAssignRetries; attempt++) {
             outcome = await dispatchCriticalInboxInstruction({
                 teamName: sanitized,
@@ -1882,7 +1985,8 @@ export async function assignTask(teamName, workerName, taskId, cwd) {
                 workerIndex: workerInfo.index,
                 paneId: workerInfo.pane_id,
                 inbox,
-                triggerMessage: generateTriggerMessage(workerName, sanitized, resolveInstructionStateRoot(workerInfo.worktree_path)),
+                triggerMessage: triggerDirective.text,
+                intent: triggerDirective.intent,
                 cwd,
                 dispatchPolicy,
                 inboxCorrelationKey: `assign:${taskId}:${workerName}`,
@@ -1988,6 +2092,7 @@ export async function shutdownTeam(teamName, cwd, options = {}) {
             const requestedAt = new Date().toISOString();
             await writeShutdownRequest(sanitized, w.name, 'leader-fixed', cwd);
             shutdownRequestTimes.set(w.name, requestedAt);
+            const triggerDirective = buildTriggerDirective(w.name, sanitized, resolveInstructionStateRoot(w.worktree_path));
             await dispatchCriticalInboxInstruction({
                 teamName: sanitized,
                 config,
@@ -1995,7 +2100,8 @@ export async function shutdownTeam(teamName, cwd, options = {}) {
                 workerIndex: w.index,
                 paneId: w.pane_id,
                 inbox: generateShutdownInbox(sanitized, w.name),
-                triggerMessage: generateTriggerMessage(w.name, sanitized, resolveInstructionStateRoot(w.worktree_path)),
+                triggerMessage: triggerDirective.text,
+                intent: triggerDirective.intent,
                 cwd,
                 dispatchPolicy,
                 inboxCorrelationKey: `shutdown:${w.name}`,
@@ -2049,8 +2155,10 @@ export async function shutdownTeam(teamName, cwd, options = {}) {
     const leaderPaneId = config.leader_pane_id;
     const hudPaneId = config.hud_pane_id;
     if (config.worker_launch_mode === 'interactive') {
-        const workerPanePids = config.workers
-            .map((w) => getWorkerPanePid(sessionName, w.index, w.pane_id))
+        const livePaneIds = listPaneIds(sessionName);
+        let shutdownPaneIds = collectShutdownPaneIds({ config, livePaneIds });
+        const workerPanePids = shutdownPaneIds
+            .map((paneId) => getWorkerPanePid(sessionName, 1, paneId))
             .filter((pid) => typeof pid === 'number' && Number.isFinite(pid) && pid > 0);
         for (const panePid of workerPanePids) {
             await terminateTrackedProcessTree(panePid);
@@ -2073,22 +2181,25 @@ export async function shutdownTeam(teamName, cwd, options = {}) {
         if (resizeHookWarning) {
             console.warn(`[team shutdown] ${sanitized}: ${resizeHookWarning}; continuing teardown`);
         }
-        const workerPaneIds = config.workers
-            .map((w) => w.pane_id)
-            .filter((paneId) => typeof paneId === 'string' && paneId.trim().length > 0);
-        await teardownWorkerPanes(workerPaneIds, {
-            leaderPaneId,
-            hudPaneId,
-        });
+        let restoredHudPaneId = null;
         if (hudPaneId) {
             await killWorkerByPaneIdAsync(hudPaneId, leaderPaneId ?? undefined);
             if (sessionName.includes(':')) {
-                const restoredHudPaneId = restoreStandaloneHudPane(leaderPaneId, cwd);
+                restoredHudPaneId = restoreStandaloneHudPane(leaderPaneId, cwd);
                 if (!restoredHudPaneId) {
                     console.warn(`[team shutdown] ${sanitized}: failed to restore standalone HUD pane`);
                 }
             }
         }
+        shutdownPaneIds = collectShutdownPaneIds({
+            config,
+            livePaneIds: listPaneIds(sessionName),
+            restoredStandaloneHudPaneId: restoredHudPaneId,
+        });
+        await teardownWorkerPanes(shutdownPaneIds, {
+            leaderPaneId,
+            hudPaneId: restoredHudPaneId ?? hudPaneId,
+        });
         // 4. Destroy tmux session
         if (!sessionName.includes(':')) {
             try {
@@ -2416,7 +2527,7 @@ async function markDispatchRequestLeaderPaneMissingDeferred(params) {
     }, cwd).catch(() => { });
 }
 async function dispatchCriticalInboxInstruction(params) {
-    const { teamName, config, workerName, workerIndex, paneId, workerCli, inbox, triggerMessage, cwd, dispatchPolicy, inboxCorrelationKey, requireWorkerStartupEvidence, } = params;
+    const { teamName, config, workerName, workerIndex, paneId, workerCli, inbox, triggerMessage, intent, cwd, dispatchPolicy, inboxCorrelationKey, requireWorkerStartupEvidence, } = params;
     if (config.worker_launch_mode === 'prompt') {
         return await queueInboxInstruction({
             teamName,
@@ -2425,6 +2536,7 @@ async function dispatchCriticalInboxInstruction(params) {
             paneId,
             inbox,
             triggerMessage,
+            intent,
             cwd,
             transportPreference: 'prompt_stdin',
             fallbackAllowed: false,
@@ -2440,6 +2552,7 @@ async function dispatchCriticalInboxInstruction(params) {
             paneId,
             inbox,
             triggerMessage,
+            intent,
             cwd,
             transportPreference: 'transport_direct',
             fallbackAllowed: false,
@@ -2454,6 +2567,7 @@ async function dispatchCriticalInboxInstruction(params) {
         paneId,
         inbox,
         triggerMessage,
+        intent,
         cwd,
         transportPreference: 'hook_preferred_with_fallback',
         fallbackAllowed: true,
@@ -2494,7 +2608,7 @@ async function dispatchCriticalInboxInstruction(params) {
     if (receipt?.status === 'failed') {
         const fallback = await notifyWorkerOutcome(config, workerIndex, triggerMessage, paneId);
         if (fallback.ok) {
-            await markDispatchRequestNotified(teamName, queued.request_id, { last_reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}`, failed_at: undefined }, cwd).catch(() => null);
+            await transitionDispatchRequest(teamName, queued.request_id, 'failed', 'failed', { last_reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}` }, cwd).catch(() => { });
             return {
                 ok: true,
                 transport: fallback.transport,
@@ -2543,14 +2657,16 @@ async function dispatchCriticalInboxInstruction(params) {
     };
 }
 async function finalizeHookPreferredMailboxDispatch(params) {
-    const { teamName, requestId, workerName, workerIndex, paneId, messageId, triggerMessage, config, dispatchPolicy, cwd, fallbackNotify, } = params;
+    const { teamName, requestId, workerName, workerIndex, paneId, messageId, triggerMessage, intent, config, dispatchPolicy, cwd, fallbackNotify, } = params;
     const receipt = await waitForDispatchReceipt(teamName, requestId, cwd, {
         timeoutMs: dispatchPolicy.dispatch_ack_timeout_ms,
         pollMs: 50,
     });
     if (receipt && (receipt.status === 'notified' || receipt.status === 'delivered')) {
         await markMessageNotified(teamName, workerName, messageId, cwd).catch(() => false);
-        return { ok: true, transport: 'hook', reason: `hook_receipt_${receipt.status}`, request_id: requestId, message_id: messageId };
+        const outcome = { ok: true, transport: 'hook', reason: `hook_receipt_${receipt.status}`, request_id: requestId, message_id: messageId };
+        await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+        return outcome;
     }
     const fallback = fallbackNotify
         ? await fallbackNotify()
@@ -2560,23 +2676,27 @@ async function finalizeHookPreferredMailboxDispatch(params) {
     if (receipt?.status === 'failed') {
         if (fallback.ok) {
             await markMessageNotified(teamName, workerName, messageId, cwd).catch(() => false);
-            await markDispatchRequestNotified(teamName, requestId, { message_id: messageId, last_reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}`, failed_at: undefined }, cwd).catch(() => null);
-            return {
+            await transitionDispatchRequest(teamName, requestId, 'failed', 'failed', { message_id: messageId, last_reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}` }, cwd).catch(() => { });
+            const outcome = {
                 ok: true,
                 transport: fallback.transport,
                 reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}`,
                 request_id: requestId,
                 message_id: messageId,
             };
+            await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+            return outcome;
         }
         await transitionDispatchRequest(teamName, requestId, 'failed', 'failed', { message_id: messageId, last_reason: `fallback_attempted_but_unconfirmed:${fallback.reason}` }, cwd).catch(() => { });
-        return {
+        const outcome = {
             ok: false,
             transport: fallback.transport,
             reason: `fallback_attempted_but_unconfirmed:${fallback.reason}`,
             request_id: requestId,
             message_id: messageId,
         };
+        await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+        return outcome;
     }
     if (fallback.ok) {
         if (isLeaderPaneMissingMailboxPersistedOutcome({ workerName, paneId, outcome: fallback })) {
@@ -2586,38 +2706,44 @@ async function finalizeHookPreferredMailboxDispatch(params) {
                 messageId,
                 cwd,
             });
-            return {
+            const outcome = {
                 ok: true,
                 transport: fallback.transport,
                 reason: 'leader_pane_missing_mailbox_persisted',
                 request_id: requestId,
                 message_id: messageId,
             };
+            await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+            return outcome;
         }
         await markMessageNotified(teamName, workerName, messageId, cwd).catch(() => false);
         const marked = await markDispatchRequestNotified(teamName, requestId, { message_id: messageId, last_reason: `fallback_confirmed:${fallback.reason}` }, cwd);
         if (!marked) {
             await transitionDispatchRequest(teamName, requestId, 'failed', 'failed', { message_id: messageId, last_reason: `fallback_confirmed_after_failed_receipt:${fallback.reason}` }, cwd).catch(() => { });
         }
-        return {
+        const outcome = {
             ok: true,
             transport: fallback.transport,
             reason: `hook_timeout_fallback_confirmed:${fallback.reason}`,
             request_id: requestId,
             message_id: messageId,
         };
+        await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+        return outcome;
     }
     const current = await readDispatchRequest(teamName, requestId, cwd);
     if (current) {
         await transitionDispatchRequest(teamName, requestId, current.status, 'failed', { message_id: messageId, last_reason: `fallback_attempted_but_unconfirmed:${fallback.reason}` }, cwd).catch(() => { });
     }
-    return {
+    const outcome = {
         ok: false,
         transport: fallback.transport,
         reason: `fallback_attempted_but_unconfirmed:${fallback.reason}`,
         request_id: requestId,
         message_id: messageId,
     };
+    await logRuntimeDispatchOutcome({ cwd, teamName, workerName, requestId, messageId, intent, outcome });
+    return outcome;
 }
 async function notifyLeaderAsync(config, message, cwd) {
     // Canonical leader delivery is durable mailbox persistence plus HUD-owned
@@ -2663,44 +2789,15 @@ async function deliverPendingMailboxMessages(teamName, config, workers, previous
         if (!worker.alive)
             continue;
         for (const msg of unnotified) {
-            const triggerMessage = generateMailboxTriggerMessage(worker.name, teamName, 1, resolveInstructionStateRoot(workerInfo.worktree_path));
-            const transportPreference = config.worker_launch_mode === 'prompt'
-                ? 'prompt_stdin'
-                : (dispatchPolicy.dispatch_mode === 'transport_direct' ? 'transport_direct' : 'hook_preferred_with_fallback');
-            const fallbackAllowed = transportPreference === 'hook_preferred_with_fallback';
-            const queued = await enqueueDispatchRequest(teamName, {
-                kind: 'mailbox',
-                to_worker: worker.name,
-                worker_index: workerInfo.index,
-                pane_id: workerInfo.pane_id,
-                trigger_message: triggerMessage,
-                message_id: msg.message_id,
-                transport_preference: transportPreference,
-                fallback_allowed: fallbackAllowed,
-            }, cwd);
-            let outcome;
-            if (transportPreference === 'hook_preferred_with_fallback') {
-                outcome = await finalizeHookPreferredMailboxDispatch({
-                    teamName,
-                    requestId: queued.request.request_id,
-                    workerName: worker.name,
-                    workerIndex: workerInfo.index,
-                    paneId: workerInfo.pane_id,
-                    messageId: msg.message_id,
-                    triggerMessage,
-                    config,
-                    dispatchPolicy,
-                    cwd,
-                });
-            }
-            else {
-                const direct = await notifyWorkerOutcome(config, workerInfo.index, triggerMessage, workerInfo.pane_id);
-                outcome = { ...direct, request_id: queued.request.request_id, message_id: msg.message_id };
-                if (outcome.ok) {
-                    await markMessageNotified(teamName, worker.name, msg.message_id, cwd).catch(() => false);
-                    await markDispatchRequestNotified(teamName, queued.request.request_id, { message_id: msg.message_id, last_reason: outcome.reason }, cwd).catch(() => null);
-                }
-            }
+            const outcome = await dispatchPendingMailboxMessage({
+                teamName,
+                workerName: worker.name,
+                workerInfo,
+                messageId: msg.message_id,
+                config,
+                dispatchPolicy,
+                cwd,
+            });
             if (outcome.ok) {
                 nextNotifications[msg.message_id] = new Date().toISOString();
             }
@@ -2713,87 +2810,175 @@ async function deliverPendingMailboxMessages(teamName, config, workers, previous
     }
     return pruned;
 }
-export async function sendWorkerMessage(teamName, fromWorker, toWorker, body, cwd) {
-    const sanitized = sanitizeTeamName(teamName);
-    const config = await readTeamConfig(sanitized, cwd);
-    if (!config)
-        throw new Error(`Team ${sanitized} not found`);
-    const manifest = await readTeamManifestV2(sanitized, cwd);
-    const dispatchPolicy = resolveDispatchPolicy(manifest?.policy, config.worker_launch_mode);
-    if (toWorker === 'leader-fixed') {
-        const leaderTriggerMessage = generateLeaderMailboxTriggerMessage(sanitized, fromWorker);
-        const leaderTransportPreference = dispatchPolicy.dispatch_mode === 'transport_direct'
-            ? 'transport_direct'
-            : 'hook_preferred_with_fallback';
-        const outcome = await queueDirectMailboxMessage({
-            teamName: sanitized,
-            fromWorker,
-            toWorker,
-            toPaneId: config.leader_pane_id ?? undefined,
-            body,
-            triggerMessage: leaderTriggerMessage,
+function resolveWorkerMailboxTransportPreference(config, dispatchPolicy) {
+    return config.worker_launch_mode === 'prompt'
+        ? 'prompt_stdin'
+        : (dispatchPolicy.dispatch_mode === 'transport_direct' ? 'transport_direct' : 'hook_preferred_with_fallback');
+}
+function resolveLeaderMailboxTransportPreference(dispatchPolicy) {
+    return dispatchPolicy.dispatch_mode === 'transport_direct' ? 'transport_direct' : 'hook_preferred_with_fallback';
+}
+function isExistingMailboxNotificationOutcome(outcome) {
+    return outcome.ok && outcome.reason === 'existing_message_already_notified';
+}
+async function dispatchPendingMailboxMessage(params) {
+    const { teamName, workerName, workerInfo, messageId, config, dispatchPolicy, cwd } = params;
+    const triggerDirective = buildMailboxTriggerDirective(workerName, teamName, 1, resolveInstructionStateRoot(workerInfo.worktree_path));
+    const transportPreference = resolveWorkerMailboxTransportPreference(config, dispatchPolicy);
+    const queued = await enqueueDispatchRequest(teamName, {
+        kind: 'mailbox',
+        to_worker: workerName,
+        worker_index: workerInfo.index,
+        pane_id: workerInfo.pane_id,
+        trigger_message: triggerDirective.text,
+        intent: triggerDirective.intent,
+        message_id: messageId,
+        transport_preference: transportPreference,
+        fallback_allowed: transportPreference === 'hook_preferred_with_fallback',
+    }, cwd);
+    if (transportPreference === 'hook_preferred_with_fallback') {
+        return await finalizeQueuedMailboxDispatch({
+            queuedOutcome: {
+                ok: true,
+                transport: 'hook',
+                reason: 'queued_for_hook_dispatch',
+                request_id: queued.request.request_id,
+                message_id: messageId,
+            },
+            transportPreference,
+            teamName,
+            workerName,
+            workerIndex: workerInfo.index,
+            paneId: workerInfo.pane_id,
+            messageId,
+            triggerMessage: triggerDirective.text,
+            intent: triggerDirective.intent,
+            config,
+            dispatchPolicy,
             cwd,
-            transportPreference: leaderTransportPreference,
-            fallbackAllowed: leaderTransportPreference === 'hook_preferred_with_fallback',
-            notify: async (_target, message) => (leaderTransportPreference === 'hook_preferred_with_fallback'
-                ? { ok: true, transport: 'hook', reason: 'queued_for_hook_dispatch' }
-                : await notifyLeaderAsync(config, message, cwd)),
         });
-        let finalOutcome = outcome;
-        const mailboxAlreadyNotified = outcome.ok && outcome.reason === 'existing_message_already_notified';
-        if (!mailboxAlreadyNotified && leaderTransportPreference === 'hook_preferred_with_fallback' && !config.leader_pane_id) {
-            if (outcome.request_id) {
-                await markDispatchRequestLeaderPaneMissingDeferred({
-                    teamName: sanitized,
-                    requestId: outcome.request_id,
-                    messageId: outcome.message_id,
-                    cwd,
-                });
-            }
-            finalOutcome = {
-                ...outcome,
-                ok: true,
-                transport: 'mailbox',
-                reason: 'leader_pane_missing_mailbox_persisted',
-            };
-        }
-        const canLeaderFallbackDirectly = Boolean(config.leader_pane_id) && isTmuxAvailable();
-        if (!mailboxAlreadyNotified && leaderTransportPreference === 'hook_preferred_with_fallback' && canLeaderFallbackDirectly) {
-            if (!outcome.request_id || !outcome.message_id) {
-                throw new Error('mailbox_notify_failed:dispatch_request_missing_id');
-            }
-            finalOutcome = await finalizeHookPreferredMailboxDispatch({
-                teamName: sanitized,
-                requestId: outcome.request_id,
-                workerName: 'leader-fixed',
-                paneId: config.leader_pane_id ?? undefined,
-                messageId: outcome.message_id,
-                triggerMessage: leaderTriggerMessage,
-                config,
-                dispatchPolicy,
+    }
+    const direct = await notifyWorkerOutcome(config, workerInfo.index, triggerDirective.text, workerInfo.pane_id);
+    const outcome = { ...direct, request_id: queued.request.request_id, message_id: messageId };
+    if (outcome.ok) {
+        await markMessageNotified(teamName, workerName, messageId, cwd).catch(() => false);
+        await markDispatchRequestNotified(teamName, queued.request.request_id, { message_id: messageId, last_reason: outcome.reason }, cwd).catch(() => null);
+    }
+    await logRuntimeDispatchOutcome({
+        cwd,
+        teamName,
+        workerName,
+        requestId: queued.request.request_id,
+        messageId,
+        outcome,
+    });
+    return outcome;
+}
+async function finalizeQueuedMailboxDispatch(params) {
+    const { queuedOutcome, transportPreference, teamName, workerName, workerIndex, paneId, messageId, triggerMessage, intent, config, dispatchPolicy, cwd, fallbackNotify, } = params;
+    if (transportPreference !== 'hook_preferred_with_fallback') {
+        return queuedOutcome;
+    }
+    if (isExistingMailboxNotificationOutcome(queuedOutcome)) {
+        return queuedOutcome;
+    }
+    if (!queuedOutcome.request_id || !messageId) {
+        return { ...queuedOutcome, ok: false, reason: 'dispatch_request_missing_id' };
+    }
+    return await finalizeHookPreferredMailboxDispatch({
+        teamName,
+        requestId: queuedOutcome.request_id,
+        workerName,
+        workerIndex,
+        paneId,
+        messageId,
+        triggerMessage,
+        intent,
+        config,
+        dispatchPolicy,
+        cwd,
+        fallbackNotify,
+    });
+}
+async function sendLeaderMailboxMessage(params) {
+    const { teamName, fromWorker, body, config, dispatchPolicy, cwd } = params;
+    const triggerDirective = buildLeaderMailboxTriggerDirective(teamName, fromWorker, config.team_state_root || undefined);
+    const transportPreference = resolveLeaderMailboxTransportPreference(dispatchPolicy);
+    const queuedOutcome = await queueDirectMailboxMessage({
+        teamName,
+        fromWorker,
+        toWorker: 'leader-fixed',
+        toPaneId: config.leader_pane_id ?? undefined,
+        body,
+        triggerMessage: triggerDirective.text,
+        intent: triggerDirective.intent,
+        cwd,
+        transportPreference,
+        fallbackAllowed: transportPreference === 'hook_preferred_with_fallback',
+        notify: async (_target, message) => (transportPreference === 'hook_preferred_with_fallback'
+            ? { ok: true, transport: 'hook', reason: 'queued_for_hook_dispatch' }
+            : await notifyLeaderAsync(config, message, cwd)),
+    });
+    if (!isExistingMailboxNotificationOutcome(queuedOutcome)
+        && transportPreference === 'hook_preferred_with_fallback'
+        && !config.leader_pane_id) {
+        if (queuedOutcome.request_id) {
+            await markDispatchRequestLeaderPaneMissingDeferred({
+                teamName,
+                requestId: queuedOutcome.request_id,
+                messageId: queuedOutcome.message_id,
                 cwd,
-                fallbackNotify: async () => await notifyLeaderAsync(config, leaderTriggerMessage, cwd),
             });
         }
-        if (!finalOutcome.ok)
-            throw new Error(`mailbox_notify_failed:${finalOutcome.reason}`);
-        return finalOutcome;
+        const deferredOutcome = {
+            ...queuedOutcome,
+            ok: true,
+            transport: 'mailbox',
+            reason: 'leader_pane_missing_mailbox_persisted',
+        };
+        await logRuntimeDispatchOutcome({
+            cwd,
+            teamName,
+            workerName: 'leader-fixed',
+            requestId: deferredOutcome.request_id,
+            messageId: deferredOutcome.message_id,
+            intent: triggerDirective.intent,
+            outcome: deferredOutcome,
+        });
+        return deferredOutcome;
     }
-    const recipient = config.workers.find((w) => w.name === toWorker);
+    const canLeaderFallbackDirectly = Boolean(config.leader_pane_id) && isTmuxAvailable();
+    return await finalizeQueuedMailboxDispatch({
+        queuedOutcome,
+        transportPreference: canLeaderFallbackDirectly ? transportPreference : 'transport_direct',
+        teamName,
+        workerName: 'leader-fixed',
+        paneId: config.leader_pane_id ?? undefined,
+        messageId: queuedOutcome.message_id,
+        triggerMessage: triggerDirective.text,
+        intent: triggerDirective.intent,
+        config,
+        dispatchPolicy,
+        cwd,
+        fallbackNotify: async () => await notifyLeaderAsync(config, triggerDirective.text, cwd),
+    });
+}
+async function sendRecipientMailboxMessage(params) {
+    const { teamName, fromWorker, toWorker, body, config, dispatchPolicy, cwd } = params;
+    const recipient = config.workers.find((worker) => worker.name === toWorker);
     if (!recipient)
         throw new Error(`Worker ${toWorker} not found in team`);
-    const triggerMessage = generateMailboxTriggerMessage(toWorker, sanitized, 1, resolveInstructionStateRoot(recipient.worktree_path));
-    const transportPreference = config.worker_launch_mode === 'prompt'
-        ? 'prompt_stdin'
-        : (dispatchPolicy.dispatch_mode === 'transport_direct' ? 'transport_direct' : 'hook_preferred_with_fallback');
-    const outcome = await queueDirectMailboxMessage({
-        teamName: sanitized,
+    const triggerDirective = buildMailboxTriggerDirective(toWorker, teamName, 1, resolveInstructionStateRoot(recipient.worktree_path));
+    const transportPreference = resolveWorkerMailboxTransportPreference(config, dispatchPolicy);
+    const queuedOutcome = await queueDirectMailboxMessage({
+        teamName,
         fromWorker,
         toWorker,
         toWorkerIndex: recipient.index,
         toPaneId: recipient.pane_id,
         body,
-        triggerMessage,
+        triggerMessage: triggerDirective.text,
+        intent: triggerDirective.intent,
         cwd,
         transportPreference,
         fallbackAllowed: transportPreference === 'hook_preferred_with_fallback',
@@ -2801,25 +2986,82 @@ export async function sendWorkerMessage(teamName, fromWorker, toWorker, body, cw
             ? { ok: true, transport: 'hook', reason: 'queued_for_hook_dispatch' }
             : await notifyWorkerOutcome(config, recipient.index, message, recipient.pane_id)),
     });
-    let finalOutcome = outcome;
-    const mailboxAlreadyNotified = outcome.ok && outcome.reason === 'existing_message_already_notified';
-    if (!mailboxAlreadyNotified && transportPreference === 'hook_preferred_with_fallback') {
-        if (!outcome.request_id || !outcome.message_id) {
-            throw new Error('mailbox_notify_failed:dispatch_request_missing_id');
+    return await finalizeQueuedMailboxDispatch({
+        queuedOutcome,
+        transportPreference,
+        teamName,
+        workerName: recipient.name,
+        workerIndex: recipient.index,
+        paneId: recipient.pane_id,
+        messageId: queuedOutcome.message_id,
+        triggerMessage: triggerDirective.text,
+        intent: triggerDirective.intent,
+        config,
+        dispatchPolicy,
+        cwd,
+    });
+}
+async function finalizeBroadcastMailboxOutcomes(params) {
+    const { teamName, outcomes, transportPreference, config, dispatchPolicy, cwd } = params;
+    if (transportPreference !== 'hook_preferred_with_fallback') {
+        return outcomes;
+    }
+    const finalizedOutcomes = [];
+    for (const outcome of outcomes) {
+        const target = outcome.to_worker
+            ? (config.workers.find((worker) => worker.name === outcome.to_worker) ?? null)
+            : null;
+        if (!target) {
+            finalizedOutcomes.push({ ...outcome, ok: false, reason: 'missing_worker_index' });
+            continue;
         }
-        finalOutcome = await finalizeHookPreferredMailboxDispatch({
-            teamName: sanitized,
-            requestId: outcome.request_id,
-            workerName: recipient.name,
-            workerIndex: recipient.index,
-            paneId: recipient.pane_id,
+        const triggerDirective = buildMailboxTriggerDirective(target.name, teamName, 1, resolveInstructionStateRoot(target.worktree_path));
+        finalizedOutcomes.push(await finalizeQueuedMailboxDispatch({
+            queuedOutcome: outcome,
+            transportPreference,
+            teamName,
+            workerName: target.name,
+            workerIndex: target.index,
+            paneId: target.pane_id,
             messageId: outcome.message_id,
-            triggerMessage,
+            triggerMessage: triggerDirective.text,
+            intent: triggerDirective.intent,
+            config,
+            dispatchPolicy,
+            cwd,
+        }));
+    }
+    return finalizedOutcomes;
+}
+export async function sendWorkerMessage(teamName, fromWorker, toWorker, body, cwd) {
+    const sanitized = sanitizeTeamName(teamName);
+    const config = await readTeamConfig(sanitized, cwd);
+    if (!config)
+        throw new Error(`Team ${sanitized} not found`);
+    const manifest = await readTeamManifestV2(sanitized, cwd);
+    const dispatchPolicy = resolveDispatchPolicy(manifest?.policy, config.worker_launch_mode);
+    if (toWorker === 'leader-fixed') {
+        const finalOutcome = await sendLeaderMailboxMessage({
+            teamName: sanitized,
+            fromWorker,
+            body,
             config,
             dispatchPolicy,
             cwd,
         });
+        if (!finalOutcome.ok)
+            throw new Error(`mailbox_notify_failed:${finalOutcome.reason}`);
+        return finalOutcome;
     }
+    const finalOutcome = await sendRecipientMailboxMessage({
+        teamName: sanitized,
+        fromWorker,
+        toWorker,
+        body,
+        config,
+        dispatchPolicy,
+        cwd,
+    });
     if (!finalOutcome.ok)
         throw new Error(`mailbox_notify_failed:${finalOutcome.reason}`);
     return finalOutcome;
@@ -2831,16 +3073,15 @@ export async function broadcastWorkerMessage(teamName, fromWorker, body, cwd) {
         throw new Error(`Team ${sanitized} not found`);
     const manifest = await readTeamManifestV2(sanitized, cwd);
     const dispatchPolicy = resolveDispatchPolicy(manifest?.policy, config.worker_launch_mode);
-    const transportPreference = config.worker_launch_mode === 'prompt'
-        ? 'prompt_stdin'
-        : (dispatchPolicy.dispatch_mode === 'transport_direct' ? 'transport_direct' : 'hook_preferred_with_fallback');
+    const transportPreference = resolveWorkerMailboxTransportPreference(config, dispatchPolicy);
     const outcomes = await queueBroadcastMailboxMessage({
         teamName: sanitized,
         fromWorker,
         recipients: config.workers.map((w) => ({ workerName: w.name, workerIndex: w.index, paneId: w.pane_id })),
         body,
         cwd,
-        triggerFor: (workerName) => generateMailboxTriggerMessage(workerName, sanitized, 1, resolveInstructionStateRoot(config.workers.find((worker) => worker.name === workerName)?.worktree_path)),
+        triggerFor: (workerName) => buildMailboxTriggerDirective(workerName, sanitized, 1, resolveInstructionStateRoot(config.workers.find((worker) => worker.name === workerName)?.worktree_path)).text,
+        intentFor: () => 'pending-mailbox-review',
         transportPreference,
         fallbackAllowed: transportPreference === 'hook_preferred_with_fallback',
         notify: async (target, message) => transportPreference === 'hook_preferred_with_fallback'
@@ -2849,37 +3090,14 @@ export async function broadcastWorkerMessage(teamName, fromWorker, body, cwd) {
                 ? await notifyWorkerOutcome(config, target.workerIndex, message, target.paneId)
                 : { ok: false, transport: 'none', reason: 'missing_worker_index' }),
     });
-    const finalizedOutcomes = [];
-    for (const outcome of outcomes) {
-        if (transportPreference !== 'hook_preferred_with_fallback') {
-            finalizedOutcomes.push(outcome);
-            continue;
-        }
-        if (!outcome.request_id || !outcome.message_id) {
-            finalizedOutcomes.push({ ...outcome, ok: false, reason: 'dispatch_request_missing_id' });
-            continue;
-        }
-        const target = outcome.to_worker
-            ? (config.workers.find((w) => w.name === outcome.to_worker) ?? null)
-            : null;
-        if (!target) {
-            finalizedOutcomes.push({ ...outcome, ok: false, reason: 'missing_worker_index' });
-            continue;
-        }
-        finalizedOutcomes.push(await finalizeHookPreferredMailboxDispatch({
-            teamName: sanitized,
-            requestId: outcome.request_id,
-            workerName: target.name,
-            workerIndex: target.index,
-            paneId: target.pane_id,
-            messageId: outcome.message_id,
-            triggerMessage: generateMailboxTriggerMessage(target.name, sanitized, 1, resolveInstructionStateRoot(target.worktree_path)),
-            config,
-            dispatchPolicy,
-            cwd,
-        }));
-    }
-    const results = transportPreference === 'hook_preferred_with_fallback' ? finalizedOutcomes : outcomes;
+    const results = await finalizeBroadcastMailboxOutcomes({
+        teamName: sanitized,
+        outcomes,
+        transportPreference,
+        config,
+        dispatchPolicy,
+        cwd,
+    });
     if (results.some((result) => !result.ok)) {
         const firstFailure = results.find((result) => !result.ok);
         throw new Error(`mailbox_notify_failed:${firstFailure?.reason ?? 'unknown'}`);