@adhdev/daemon-core 0.9.76-rc.5 → 0.9.76-rc.51

package/src/config/mesh-config.ts

@@ -74,6 +74,21 @@ export function normalizeRepoIdentity(remoteUrl: string): string {
 
 // ─── CRUD Operations ────────────────────────────
 
+const SESSION_CLEANUP_MODES = new Set(['preserve', 'stop', 'delete_stopped', 'stop_and_delete']);
+
+function mergeMeshPolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMeshPolicy> | undefined): RepoMeshPolicy {
+    const policy: RepoMeshPolicy = { ...DEFAULT_MESH_POLICY, ...(base || {}), ...(patch || {}) };
+    if (!['block', 'warn', 'checkpoint_then_continue'].includes(policy.dirtyWorkspaceBehavior)) {
+        policy.dirtyWorkspaceBehavior = 'warn';
+    }
+    const maxParallelTasks = Number(policy.maxParallelTasks);
+    policy.maxParallelTasks = Number.isFinite(maxParallelTasks) ? Math.max(1, Math.min(8, Math.floor(maxParallelTasks))) : 2;
+    if (!SESSION_CLEANUP_MODES.has(String(policy.sessionCleanupOnNodeRemove))) {
+        policy.sessionCleanupOnNodeRemove = 'preserve';
+    }
+    return policy;
+}
+
 export function listMeshes(): LocalMeshEntry[] {
     return loadMeshConfig().meshes;
 }
@@ -112,7 +127,7 @@ export function createMesh(opts: CreateMeshOptions): LocalMeshEntry {
         repoIdentity,
         repoRemoteUrl: opts.repoRemoteUrl,
         defaultBranch: opts.defaultBranch,
-        policy: { ...DEFAULT_MESH_POLICY, ...opts.policy },
+        policy: mergeMeshPolicy(undefined, opts.policy),
         coordinator: opts.coordinator || {},
         nodes: [],
         createdAt: now,
@@ -138,7 +153,7 @@ export function updateMesh(meshId: string, opts: UpdateMeshOptions): LocalMeshEn
 
     if (opts.name !== undefined) mesh.name = opts.name.trim().slice(0, 100);
     if (opts.defaultBranch !== undefined) mesh.defaultBranch = opts.defaultBranch;
-    if (opts.policy) mesh.policy = { ...mesh.policy, ...opts.policy };
+    if (opts.policy) mesh.policy = mergeMeshPolicy(mesh.policy, opts.policy);
     if (opts.coordinator) mesh.coordinator = opts.coordinator;
     mesh.updatedAt = new Date().toISOString();
 
@@ -160,9 +175,12 @@ export function deleteMesh(meshId: string): boolean {
 export interface AddNodeOptions {
     workspace: string;
     repoRoot?: string;
+    daemonId?: string;
     userOverrides?: Partial<RepoMeshNodeCapabilities>;
     policy?: RepoMeshNodePolicy;
     isLocalWorktree?: boolean;
+    worktreeBranch?: string;
+    clonedFromNodeId?: string;
 }
 
 export function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntry | undefined {
@@ -183,9 +201,12 @@ export function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntr
         id: `node_${randomUUID().replace(/-/g, '')}`,
         workspace: opts.workspace.trim(),
         repoRoot: opts.repoRoot,
+        daemonId: opts.daemonId,
         userOverrides: opts.userOverrides || {},
         policy: opts.policy || {},
         isLocalWorktree: opts.isLocalWorktree,
+        worktreeBranch: opts.worktreeBranch,
+        clonedFromNodeId: opts.clonedFromNodeId,
     };
 
     mesh.nodes.push(node);

package/src/git/git-commands.ts

@@ -152,6 +152,7 @@ const FAILURE_REASONS = new Set<GitFailureReason>([
   'dirty_index_required',
   'conflict',
   'invalid_args',
+  'nothing_to_commit',
   'git_command_failed',
 ]);
 
@@ -454,7 +455,10 @@ async function gitCheckpoint(
   } catch (err: any) {
     const output = (err?.stdout || '') + (err?.stderr || '');
     if (/nothing to commit/i.test(output)) {
-      throw new GitCommandError('git_command_failed', 'Nothing to commit');
+      throw new GitCommandError('nothing_to_commit', 'Nothing to commit — working tree is clean.', {
+        stdout: err?.stdout,
+        stderr: err?.stderr,
+      });
     }
     throw err;
   }

package/src/git/git-types.ts

@@ -14,6 +14,7 @@ export type GitFailureReason =
   | 'dirty_index_required'
   | 'conflict'
   | 'invalid_args'
+  | 'nothing_to_commit'
   | 'git_command_failed';
 
 export interface GitRepoIdentity {

package/src/git/git-worktree.ts

@@ -0,0 +1,214 @@
+/**
+ * Git Worktree — Create/remove/list worktrees for Repo Mesh node cloning
+ *
+ * Used by the `clone_mesh_node` daemon command to create isolated
+ * worktree-based nodes for parallel branch work within a mesh.
+ *
+ * Worktrees are placed outside the source repo to avoid .gitignore
+ * pollution and submodule conflicts:
+ *   <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
+ */
+
+import * as path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const WORKTREE_DIR_NAME = '.adhdev-worktrees';
+const GIT_TIMEOUT_MS = 30_000;
+const GIT_MAX_BUFFER = 4 * 1024 * 1024;
+
+// ─── Types ──────────────────────────────────────
+
+export interface WorktreeCreateOptions {
+    /** Absolute path to the source repo's git root */
+    repoRoot: string;
+    /** Branch name for the new worktree */
+    branch: string;
+    /** Starting point for the branch (default: HEAD) */
+    baseBranch?: string;
+    /** Mesh name, used for organizing worktree directories */
+    meshName: string;
+    /** Override the auto-resolved target directory */
+    targetDir?: string;
+}
+
+export interface WorktreeCreateResult {
+    success: true;
+    worktreePath: string;
+    branch: string;
+}
+
+export interface WorktreeEntry {
+    path: string;
+    head: string;
+    branch: string | null;
+    bare: boolean;
+}
+
+export interface WorktreeRemoveResult {
+    success: true;
+    removedPath: string;
+}
+
+// ─── Path Resolution ────────────────────────────
+
+/**
+ * Resolve the target directory for a new worktree.
+ * Places worktrees at: <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
+ */
+export function resolveWorktreePath(repoRoot: string, meshName: string, branch: string): string {
+    // Sanitize branch name for filesystem (e.g. feat/auth → feat-auth)
+    const safeBranch = branch.replace(/[/\\:*?"<>|]/g, '-').replace(/^\.+|\.+$/g, '');
+    const safeMeshName = meshName.replace(/[/\\:*?"<>|]/g, '-').replace(/^\.+|\.+$/g, '');
+    const parentDir = path.dirname(repoRoot);
+    return path.join(parentDir, WORKTREE_DIR_NAME, safeMeshName, safeBranch);
+}
+
+// ─── Create ─────────────────────────────────────
+
+/**
+ * Create a new git worktree with a fresh branch.
+ *
+ * Runs: git worktree add <targetDir> -b <branch> [baseBranch]
+ */
+export async function createWorktree(opts: WorktreeCreateOptions): Promise<WorktreeCreateResult> {
+    const { repoRoot, branch, baseBranch, meshName } = opts;
+    const targetDir = opts.targetDir || resolveWorktreePath(repoRoot, meshName, branch);
+
+    if (existsSync(targetDir)) {
+        throw new Error(`Worktree target directory already exists: ${targetDir}`);
+    }
+
+    // Ensure parent directory exists
+    await mkdir(path.dirname(targetDir), { recursive: true });
+
+    const args = ['worktree', 'add', targetDir, '-b', branch];
+    if (baseBranch) {
+        args.push(baseBranch);
+    }
+
+    try {
+        await execFileAsync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+        });
+    } catch (error: any) {
+        const stderr = typeof error.stderr === 'string' ? error.stderr : '';
+        // Clean error messages for common failures
+        if (/already exists/i.test(stderr)) {
+            throw new Error(`Branch '${branch}' already exists or is checked out in another worktree`);
+        }
+        throw new Error(`git worktree add failed: ${stderr.trim() || error.message}`);
+    }
+
+    return {
+        success: true,
+        worktreePath: targetDir,
+        branch,
+    };
+}
+
+// ─── Remove ─────────────────────────────────────
+
+/**
+ * Remove a git worktree and clean up the directory.
+ *
+ * Runs: git worktree remove <worktreePath> --force
+ */
+export async function removeWorktree(repoRoot: string, worktreePath: string): Promise<WorktreeRemoveResult> {
+    if (!existsSync(worktreePath)) {
+        // Already gone — just prune
+        await pruneWorktrees(repoRoot);
+        return { success: true, removedPath: worktreePath };
+    }
+
+    try {
+        await execFileAsync('git', ['worktree', 'remove', worktreePath, '--force'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+        });
+    } catch (error: any) {
+        const stderr = typeof error.stderr === 'string' ? error.stderr : '';
+        throw new Error(`git worktree remove failed: ${stderr.trim() || error.message}`);
+    }
+
+    return { success: true, removedPath: worktreePath };
+}
+
+// ─── List ───────────────────────────────────────
+
+/**
+ * List all worktrees for a repository.
+ *
+ * Runs: git worktree list --porcelain
+ */
+export async function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]> {
+    const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER,
+        windowsHide: true,
+    });
+
+    return parseWorktreeListOutput(stdout);
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ */
+export function parseWorktreeListOutput(output: string): WorktreeEntry[] {
+    const entries: WorktreeEntry[] = [];
+    const blocks = output.trim().split(/\n\n+/);
+
+    for (const block of blocks) {
+        if (!block.trim()) continue;
+        const lines = block.trim().split('\n');
+        const entry: WorktreeEntry = { path: '', head: '', branch: null, bare: false };
+
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                entry.path = line.slice('worktree '.length).trim();
+            } else if (line.startsWith('HEAD ')) {
+                entry.head = line.slice('HEAD '.length).trim();
+            } else if (line.startsWith('branch ')) {
+                const ref = line.slice('branch '.length).trim();
+                // refs/heads/feat/auth → feat/auth
+                entry.branch = ref.replace(/^refs\/heads\//, '');
+            } else if (line === 'bare') {
+                entry.bare = true;
+            }
+        }
+
+        if (entry.path) {
+            entries.push(entry);
+        }
+    }
+
+    return entries;
+}
+
+// ─── Prune ──────────────────────────────────────
+
+async function pruneWorktrees(repoRoot: string): Promise<void> {
+    try {
+        await execFileAsync('git', ['worktree', 'prune'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        });
+    } catch {
+        // Prune is best-effort
+    }
+}

package/src/git/index.ts

@@ -73,3 +73,17 @@ export type {
 
 export { TurnSnapshotTracker } from './turn-snapshot-tracker.js';
 export type { TurnCompletedCallback } from './turn-snapshot-tracker.js';
+
+export {
+  createWorktree,
+  listWorktrees,
+  parseWorktreeListOutput,
+  removeWorktree,
+  resolveWorktreePath,
+} from './git-worktree.js';
+export type {
+  WorktreeCreateOptions,
+  WorktreeCreateResult,
+  WorktreeEntry,
+  WorktreeRemoveResult,
+} from './git-worktree.js';

package/src/mesh/coordinator-prompt.ts

@@ -16,6 +16,7 @@ import type {
     RepoMeshStatus,
     RepoMeshNodeStatus,
 } from '../repo-mesh-types.js';
+import { DEFAULT_MESH_POLICY } from '../repo-mesh-types.js';
 
 // ─── Prompt Builder ─────────────────────────────
 
@@ -23,10 +24,11 @@ export interface CoordinatorPromptContext {
     mesh: LocalMeshEntry;
     status?: RepoMeshStatus;
     userInstruction?: string;
+    coordinatorCliType?: string;
 }
 
 export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string {
-    const { mesh, status, userInstruction } = ctx;
+    const { mesh, status, userInstruction, coordinatorCliType } = ctx;
     const sections: string[] = [];
 
     // ── Identity ──
@@ -45,7 +47,7 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
     }
 
     // ── Policy ──
-    sections.push(buildPolicySection(mesh.policy));
+    sections.push(buildPolicySection({ ...DEFAULT_MESH_POLICY, ...(mesh.policy || {}) }));
 
     // ── Tools ──
     sections.push(TOOLS_SECTION);
@@ -54,14 +56,14 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
     sections.push(WORKFLOW_SECTION);
 
     // ── Rules ──
-    sections.push(RULES_SECTION);
+    sections.push(buildRulesSection(coordinatorCliType));
 
     // ── User instruction ──
     if (userInstruction) {
         sections.push(`## Additional Context\n${userInstruction}`);
     }
 
-    if (mesh.coordinator.systemPromptSuffix) {
+    if (mesh.coordinator?.systemPromptSuffix) {
         sections.push(mesh.coordinator.systemPromptSuffix);
     }
 
@@ -130,7 +132,9 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_read_chat\` | Read an agent's recent messages to check progress |
 | \`mesh_git_status\` | Check git status on a specific node |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
-| \`mesh_approve\` | Approve/reject a pending agent action |`;
+| \`mesh_approve\` | Approve/reject a pending agent action |
+| \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
+| \`mesh_remove_node\` | Remove a node (cleans up worktree if applicable) |`;
 
 const WORKFLOW_SECTION = `## Orchestration Workflow
 
@@ -138,21 +142,32 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
 2. **Plan** — Decompose the user's request into independent tasks for parallel execution, or sequential tasks when dependencies exist.
 3. **Delegate** — For each task:
    a. Pick the best node (consider: health, dirty state, current workload).
-   b. If no session exists, call \`mesh_launch_session\` to start one.
-   c. Call \`mesh_send_task\` with a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
+   b. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
+   c. If no session exists, call \`mesh_launch_session\` to start one.
+   d. Call \`mesh_send_task\` with a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
 4. **Monitor** — Periodically call \`mesh_read_chat\` to check progress. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
-7. **Report** — Summarize what was done, what changed, and any issues.`;
+7. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
+8. **Report** — Summarize what was done, what changed, and any issues.`;
 
-const RULES_SECTION = `## Rules
+function buildRulesSection(coordinatorCliType?: string): string {
+    const coordinatorNote = coordinatorCliType
+        ? `\n- **Coordinator runtime is not a delegation default.** This coordinator is running as \`${coordinatorCliType}\`, but delegated node sessions must follow the user's requested provider, not the coordinator's own runtime.`
+        : '';
+
+    return `## Rules
 
 - **Minimize coordinator context.** The coordinator's job is routing, not implementing. Do not read source files, run commands, or analyze code directly — delegate all of that to node agents. Your context should stay lean.
 - **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to a node. Do not do it yourself.
+- **Respect explicit provider requests.** If the user names an agent/provider, pass the matching provider type to \`mesh_launch_session\`: Hermes → \`hermes-cli\`, Claude Code/Claude → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`. Never substitute \`claude-cli\` just because the coordinator itself is Claude Code.
 - **Front-load the task message.** When calling \`mesh_send_task\`, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
 - **Don't inspect code.** Trust the agent's output. Verify via \`mesh_git_status\`, not by reading source files.
 - **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed.
 - **Handle failures gracefully.** If a task fails, read the chat to understand why, then retry or reassign.
 - **Keep the user informed.** Report progress after each delegation round — one or two sentences, not a narration.
 - **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
-- **Never fabricate tool results.** Always call the actual tool; never pretend you did.`;
+- **Never fabricate tool results.** Always call the actual tool; never pretend you did.
+- **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
+- **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
+}

package/src/mesh/mesh-events.ts

@@ -1,61 +1,127 @@
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
-import { getMeshByRepo } from '../config/mesh-config.js';
+import { getMesh, getMeshByRepo } from '../config/mesh-config.js';
 import { LOG } from '../logging/logger.js';
 
+function readNonEmptyString(value: unknown): string {
+    return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function formatCompletionMetadata(event: Record<string, unknown>): string {
+    const parts = [
+        readNonEmptyString(event.targetSessionId) ? `session_id=${readNonEmptyString(event.targetSessionId)}` : '',
+        readNonEmptyString(event.providerType) ? `provider=${readNonEmptyString(event.providerType)}` : '',
+        readNonEmptyString(event.providerSessionId) ? `provider_session_id=${readNonEmptyString(event.providerSessionId)}` : '',
+    ].filter(Boolean);
+    return parts.length > 0 ? ` (${parts.join('; ')})` : '';
+}
+
+function buildMeshSystemMessage(args: {
+    event: string;
+    nodeLabel: string;
+    metadataEvent: Record<string, unknown>;
+}): string {
+    const metadata = formatCompletionMetadata(args.metadataEvent);
+    if (args.event === 'agent:generating_completed') {
+        return `[System] ${args.nodeLabel} has completed its task and is now idle${metadata}. This completion came from the agent status event path; use mesh_read_chat once to review its final progress, but do not poll repeatedly.`;
+    }
+    if (args.event === 'agent:waiting_approval') {
+        return `[System] ${args.nodeLabel} is waiting for approval to proceed${metadata}. You may use mesh_read_chat and mesh_approve to handle it.`;
+    }
+    return '';
+}
+
+function injectMeshSystemMessage(components: DaemonComponents, args: {
+    meshId: string;
+    sourceInstanceId?: string;
+    nodeLabel: string;
+    event: string;
+    metadataEvent: Record<string, unknown>;
+}) {
+    const coordinatorInstances = components.instanceManager.getByCategory('cli').filter((inst) => {
+        const instState = inst.getState();
+        if (instState.settings?.meshCoordinatorFor !== args.meshId) return false;
+        if (args.sourceInstanceId && instState.instanceId === args.sourceInstanceId) return false;
+        return true;
+    });
+
+    if (coordinatorInstances.length === 0) return { success: true, forwarded: 0 };
+
+    const messageText = buildMeshSystemMessage({
+        event: args.event,
+        nodeLabel: args.nodeLabel,
+        metadataEvent: args.metadataEvent,
+    });
+    if (!messageText) return { success: false, error: 'unsupported mesh event' };
+
+    for (const coord of coordinatorInstances) {
+        const coordState = coord.getState();
+        LOG.info('MeshEvents', `Forwarding mesh event to coordinator ${coordState.instanceId}`);
+        coord.onEvent('send_message', { input: { text: messageText, textFallback: messageText } });
+    }
+    return { success: true, forwarded: coordinatorInstances.length };
+}
+
+export function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>) {
+    const eventName = readNonEmptyString(payload.event);
+    if (eventName !== 'agent:generating_completed' && eventName !== 'agent:waiting_approval') {
+        return { success: false, error: 'unsupported mesh event' };
+    }
+    const meshId = readNonEmptyString(payload.meshId);
+    if (!meshId) return { success: false, error: 'meshId required' };
+
+    const nodeId = readNonEmptyString(payload.nodeId);
+    const workspace = readNonEmptyString(payload.workspace);
+    const nodeLabel = nodeId ? `Node '${nodeId}'` : workspace ? `Agent at ${workspace}` : 'Remote agent';
+    return injectMeshSystemMessage(components, {
+        meshId,
+        nodeLabel,
+        event: eventName,
+        metadataEvent: {
+            targetSessionId: readNonEmptyString(payload.targetSessionId) || readNonEmptyString(payload.sessionId),
+            providerType: readNonEmptyString(payload.providerType),
+            providerSessionId: readNonEmptyString(payload.providerSessionId),
+        },
+    });
+}
+
 export function setupMeshEventForwarding(components: DaemonComponents) {
     components.instanceManager.onEvent((event) => {
         // We only care about agent sub-session completion or waiting approval
         if (event.event !== 'agent:generating_completed' && event.event !== 'agent:waiting_approval') return;
-        
-        const instanceId = event.instanceId as string;
+
+        const instanceId = readNonEmptyString(event.instanceId);
         if (!instanceId) return;
 
-        // Try to find the workspace of the sub-agent
+        // Try to find the workspace and mesh metadata of the sub-agent.
         const sourceInstance = components.instanceManager.getInstance(instanceId);
         if (!sourceInstance || sourceInstance.category !== 'cli') return;
         const state = sourceInstance.getState();
-        const workspace = state.workspace;
+        const workspace = readNonEmptyString(state.workspace);
         if (!workspace) return;
+        const settings = state.settings && typeof state.settings === 'object' ? state.settings as Record<string, unknown> : {};
+        const meshIdFromRuntime = readNonEmptyString(settings.meshNodeFor);
 
-        // Find the mesh that this workspace belongs to
-        const mesh = getMeshByRepo(workspace);
-        if (!mesh) return;
-
-        // Find the coordinator session(s)
-        const allInstances = components.instanceManager.getByCategory('cli');
-        const coordinatorInstances = allInstances.filter((inst) => {
-            const instState = inst.getState();
-            
-            // The coordinator session was launched with meshCoordinatorFor setting
-            if (instState.settings?.meshCoordinatorFor !== mesh.id) return false;
-            
-            // Exclude the source instance itself (just in case)
-            if (instState.instanceId === instanceId) return false;
-            
-            return true;
-        });
-
-        if (coordinatorInstances.length === 0) return;
-
-        // Determine node label
-        const targetNode = mesh.nodes.find((n) => n.workspace === workspace);
-        const nodeLabel = targetNode ? `Node '${targetNode.id}'` : `Agent at ${workspace}`;
+        // Prefer runtime mesh metadata: delegated mesh-node agents can come from inline/cloud meshes
+        // that are not present in local meshes.json. Fall back to persisted mesh lookup for legacy sessions.
+        const mesh = meshIdFromRuntime ? getMesh(meshIdFromRuntime) : getMeshByRepo(workspace);
+        const meshId = meshIdFromRuntime || readNonEmptyString(mesh?.id);
+        if (!meshId) return;
 
-        // Construct a system message in English
-        let messageText = '';
-        if (event.event === 'agent:generating_completed') {
-            messageText = `[System] ${nodeLabel} has completed its task and is now idle. You may use mesh_read_chat to review its progress.`;
-        } else if (event.event === 'agent:waiting_approval') {
-            messageText = `[System] ${nodeLabel} is waiting for approval to proceed. You may use mesh_read_chat and mesh_approve to handle it.`;
-        }
+        // Determine node label. Inline/cloud meshes may be unavailable here, so preserve runtime node id.
+        const targetNode = mesh?.nodes?.find((n: any) => n.workspace === workspace);
+        const runtimeNodeId = readNonEmptyString(settings.meshNodeId);
+        const nodeLabel = targetNode
+            ? `Node '${targetNode.id}'`
+            : runtimeNodeId
+                ? `Node '${runtimeNodeId}'`
+                : `Agent at ${workspace}`;
 
-        if (!messageText) return;
-
-        // Inject the message into the coordinator sessions
-        for (const coord of coordinatorInstances) {
-            const coordState = coord.getState();
-            LOG.info('MeshEvents', `Forwarding event from ${workspace} to coordinator ${coordState.instanceId}`);
-            coord.onEvent('send_message', { input: { text: messageText, textFallback: messageText } });
-        }
+        injectMeshSystemMessage(components, {
+            meshId,
+            sourceInstanceId: instanceId,
+            nodeLabel,
+            event: event.event,
+            metadataEvent: event,
+        });
     });
 }

package/src/providers/chat-message-normalization.ts

@@ -171,3 +171,57 @@ export function normalizeChatMessage<T extends ChatMessage>(message: T): T {
 export function normalizeChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
   return (Array.isArray(messages) ? messages : []).map((message) => normalizeChatMessage(message));
 }
+
+function readMessageMeta(message: ChatMessage): Record<string, unknown> | null {
+  const meta = message?.meta;
+  return meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? meta as Record<string, unknown>
+    : null;
+}
+
+function isExplicitlyHiddenFromTranscript(meta: Record<string, unknown> | null): boolean {
+  if (!meta) return false;
+  const visibility = typeof meta.transcriptVisibility === 'string'
+    ? meta.transcriptVisibility.trim().toLowerCase()
+    : '';
+  return visibility === 'hidden'
+    || visibility === 'debug'
+    || meta.internal === true
+    || meta.debug === true
+    || meta.statusOnly === true
+    || meta.controlOnly === true;
+}
+
+function isExplicitlyVisibleInTranscript(meta: Record<string, unknown> | null): boolean {
+  if (!meta) return false;
+  const visibility = typeof meta.transcriptVisibility === 'string'
+    ? meta.transcriptVisibility.trim().toLowerCase()
+    : '';
+  return visibility === 'visible' || meta.userFacing === true;
+}
+
+/**
+ * Product chat transcript visibility contract.
+ *
+ * read_chat/debug paths may preserve every normalized message, including tool,
+ * terminal, thought, status, and control rows. The default user-facing chat UX
+ * should only render meaningful conversation turns unless a producer explicitly
+ * marks a non-standard row as user-facing. This keeps internal tool/status/control
+ * plumbing out of the ordinary transcript without matching provider-specific text.
+ */
+export function isUserFacingChatMessage(message: ChatMessage | null | undefined): boolean {
+  if (!message) return false;
+  const meta = readMessageMeta(message);
+  if (isExplicitlyHiddenFromTranscript(meta)) return false;
+  if (isExplicitlyVisibleInTranscript(meta)) return true;
+
+  const role = typeof message.role === 'string' ? message.role.trim().toLowerCase() : '';
+  const kind = resolveChatMessageKind(message);
+  if (role === 'user' || role === 'human') return kind === 'standard' || kind === '';
+  if (role === 'assistant') return kind === 'standard' || kind === '';
+  return false;
+}
+
+export function filterUserFacingChatMessages<T extends ChatMessage>(messages: T[] | null | undefined): T[] {
+  return (Array.isArray(messages) ? messages : []).filter((message) => isUserFacingChatMessage(message));
+}

package/src/providers/cli-provider-instance.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext } from './provider-instance.js';
+import type { ChatMessage } from '../types.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 export declare class CliProviderInstance implements ProviderInstance {
@@ -77,6 +78,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private formatMarkerTimestamp;
     private maybeAppendRuntimeRecoveryMessage;
     private appendRuntimeSystemMessage;
+    mergeRuntimeChatMessages(parsedMessages: ChatMessage[]): ChatMessage[];
     private mergeConversationMessages;
     private formatApprovalRequestMessage;
     private promoteProviderSessionId;