@adhdev/daemon-core 0.9.82-rc.310 → 0.9.82-rc.312

package/dist/logging/log-redactor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Log redactor — mask secrets before a raw daemon log line leaves the machine.
+ *
+ * Daemon logs can incidentally contain credentials: ADHDev API keys (adk_*),
+ * machine secrets (adm_*), provider keys (adp_*), bearer tokens, JWTs, TURN
+ * `username:credential` pairs, and `SECRET=...` style env dumps. The mesh
+ * `get_mesh_node_logs` command ships a log tail over P2P to the coordinator, so
+ * every line MUST pass through redactLogLine() first — otherwise a secret in a
+ * remote daemon's log is exfiltrated to whoever is driving the coordinator.
+ *
+ * Patterns are intentionally conservative: each masks the secret material while
+ * preserving enough surrounding shape that the line stays useful for debugging
+ * (e.g. `adk_••••1234`, `Bearer ••••redacted`). When in doubt, mask.
+ */
+/**
+ * Mask secrets in a single log line. Idempotent-ish: re-running over an
+ * already-masked line leaves the MASK token in place (it contains no secret
+ * shape). Never throws — a redaction failure must not crash the log path.
+ */
+export declare function redactLogLine(line: string): string;
+/** Redact an array of log lines in place-safe fashion (returns a new array). */
+export declare function redactLogLines(lines: string[]): string[];
+/** Exposed for tests/introspection: the rule names applied, in order. */
+export declare const LOG_REDACTION_RULE_NAMES: readonly string[];

package/dist/logging/log-tail-reader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Daemon log tail reader — read the last N bytes of a daemon log file, newest
+ * bytes first, bounded so the result is safe to ship over a mesh P2P channel.
+ *
+ * Used by the mesh `get_mesh_node_logs` command: the coordinator asks a (possibly
+ * remote) daemon for its recent log tail instead of having to open a session and
+ * grep the file by hand. Because the mesh RPC envelope is sent as a single
+ * datachannel message (~256KB SCTP ceiling, no chunking), the returned tail is
+ * HARD-bounded by `tailBytes` (default 64KB, capped at MAX_TAIL_BYTES=128KB) and
+ * flags `truncated:true` when the file was larger.
+ *
+ * Boundary-safe: lines are cut on the newline byte (0x0A) only, which never
+ * appears inside a multibyte UTF-8 sequence, so decoding each complete byte
+ * segment never splits a multibyte char.
+ */
+export declare const DEFAULT_TAIL_BYTES: number;
+export declare const MAX_TAIL_BYTES: number;
+export interface ReadDaemonLogTailArgs {
+    /** Date of the log file to read (defaults to today). YYYY-MM-DD string or Date. */
+    date?: string | Date;
+    /** Max bytes of tail to return. Clamped to (0, MAX_TAIL_BYTES]. Default 64KB. */
+    tailBytes?: number;
+    /** Optional regex source string; only lines matching (case-insensitive) are kept. */
+    grep?: string;
+    /** Optional epoch-ms floor; only lines whose leading [HH:MM:SS...] / ISO ts >= this are kept. */
+    sinceMs?: number;
+}
+export interface DaemonLogTailResult {
+    success: boolean;
+    error?: string;
+    lines: string[];
+    truncated: boolean;
+    logPath: string;
+    platform: NodeJS.Platform;
+    bytesReturned: number;
+    /** True when a grep/since filter dropped lines from the raw tail window. */
+    filtered: boolean;
+    /** The grep source actually applied (echoed back for clarity). */
+    grep?: string;
+}
+/**
+ * Read the daemon log tail for `date` (default today), bounded to `tailBytes`,
+ * with optional grep (regex source) and sinceMs filters. Falls back to the
+ * size-rotation backup (`*.1.log`) when the primary file does not exist.
+ */
+export declare function readDaemonLogTail(args?: ReadDaemonLogTailArgs): DaemonLogTailResult;

package/dist/mesh/mesh-events-coordinator.d.ts

@@ -1,4 +1,5 @@
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
 export declare function __resetIdleAutoFastForwardForTests(): void;
 export declare function __resetMeshWorkspaceCacheForTests(): void;
 export declare function tryAssignQueueTask(components: DaemonComponents, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
@@ -7,6 +8,35 @@ export declare function tryAssignQueueTask(components: DaemonComponents, meshId:
 export declare function activeWriteAssignedCount(meshId: string): number;
 /** Active read-only (live_debug_readonly) assignments, for the read-only safety cap. */
 export declare function activeReadonlyAssignedCount(meshId: string): number;
+/**
+ * Order eligible nodes for assignment per the mesh scheduling pipeline:
+ *   PRIORITY (schedulingPriority desc) → TIE-BREAK (strategy).
+ *
+ * The caller has already applied the TAG hard-filter and is responsible for the
+ * MAX-ALLOC capacity gate (the per-node launch/claim checks). This function only
+ * decides the *preference order* among nodes that are otherwise eligible.
+ *
+ * - 'first_eligible' (default): returns the input order verbatim and does NOT touch
+ *   the round-robin cursor — byte-for-byte the pre-feature behavior.
+ * - 'priority_only': schedulingPriority desc, then input order (load ignored).
+ * - 'least_loaded': schedulingPriority desc, then active load asc, then input order.
+ * - 'round_robin': same as least_loaded, but among nodes tied at (priority, load)
+ *   the input order is rotated by a per-mesh cursor that advances once per pass.
+ *
+ * `nodes` carries the original config/array index so the tie-break can fall back to
+ * deterministic input order. `bumpCursor` advances the round-robin cursor exactly
+ * once per scheduling pass (only consulted for 'round_robin').
+ */
+interface RankableNode {
+    nodeId: string;
+    node: any;
+    index: number;
+}
+/** Test-only: the pure node-ordering stage (PRIORITY → TIE-BREAK). Exposed so the
+ *  scheduling pipeline can be unit-tested without standing up live CLI sessions. */
+export declare function __orderEligibleNodesForTests(meshId: string, strategy: RepoMeshSchedulingStrategy, nodes: RankableNode[], opts?: {
+    bumpCursor?: boolean;
+}): RankableNode[];
 export interface MeshQueueTriggerResult {
     success: true;
     meshId: string;
@@ -136,3 +166,4 @@ export declare function handleMeshForwardEvent(components: DaemonComponents, pay
     error: string;
 };
 export declare function setupMeshEventForwarding(components: DaemonComponents): void;
+export {};

package/dist/mesh/mesh-runtime-store.d.ts

@@ -34,6 +34,24 @@ export declare class MeshRuntimeStore {
     private hasActiveSessionAssignment;
     /** A node may only execute one write task at a time (worktree isolation). */
     private hasActiveNodeAssignment;
+    /**
+     * Count active (status='assigned') tasks on a node, regardless of provider or
+     * task mode. This is the load metric for least-loaded / round-robin ranking:
+     * the scheduler prefers the node with the fewest active assignments so
+     * untargeted work spreads instead of piling onto whichever node asks first.
+     */
+    nodeActiveAssignmentCount(meshId: string, nodeId: string): number;
+    /**
+     * Read the current per-mesh round-robin cursor (0 when unset). Used to rotate
+     * the tie-break winner among nodes tied at the least load.
+     */
+    getSchedulerCursor(meshId: string): number;
+    /**
+     * Atomically advance the per-mesh round-robin cursor by one and return the
+     * value that was current BEFORE the bump (the value the caller should rotate
+     * by for this pass). UPSERT keeps it lock-free across concurrent passes.
+     */
+    bumpSchedulerCursor(meshId: string): number;
     /**
      * Count active (status='assigned') tasks on a (node, provider) combination,
      * matched by the assignedProviderType stamped on the payload at claim time.

package/dist/mesh/mesh-work-queue.d.ts

@@ -85,6 +85,29 @@ export declare function buildMeshNodeCapabilityTags(node: {
     worktreeBranch?: unknown;
 } | undefined, providerType?: string): string[];
 export declare function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags: unknown): boolean;
+/**
+ * Convergence-aware required-tags resolution (load-balancing scheduler, opt-in).
+ *
+ * When the mesh enables policy.autoConvergeCodeChange, a `converge=refine` required
+ * tag is merged into a code_change task's required tags at enqueue time, so the
+ * scheduler hard-filters the task onto refine-capable worktree nodes only (on any
+ * machine — refine_mesh_node forwards to the owning daemon). Because the tag is
+ * persisted on the queue entry, BOTH the eligibility scan (maybeAutoLaunchOneQueueSession)
+ * and the claim transaction (claimNextQueueTask → nodeSatisfiesRequiredTags) enforce
+ * it consistently.
+ *
+ * Strict backward compatibility — the injection is skipped (returns the explicit tags
+ * unchanged) when ANY of:
+ *   - the mesh does not opt in (autoConvergeCodeChange !== true), or
+ *   - the task is not code_change (validation / live_debug_readonly / launch_app /
+ *     convergence carry no merge cost and may run anywhere), or
+ *   - the task is explicitly targeted (targetNodeId): the operator chose the node, so
+ *     we do not second-guess it by filtering on convergence capability.
+ * Idempotent: normalizeMeshCapabilityTags dedupes, so re-injection is a no-op.
+ */
+export declare function resolveConvergeRequiredTags(meshId: string, taskMode: MeshTaskMode | undefined, explicitRequiredTags: string[], opts?: {
+    targetNodeId?: string;
+}): string[];
 /**
  * M1: detect dependency cycles before enqueue. Walks the dependency graph of
  * existing queue entries plus the new task's edges. Fail-closed: a cycle

package/dist/providers/spec/cli-adapter.d.ts

@@ -91,9 +91,15 @@ export declare class SpecCliAdapter implements CliAdapter {
      * drives the dispatch:
      *
      *   send_keys     → click_control                   (e.g. stop)
-     *   open_picker   → click_control then resolve when extract_choices
-     *                   surface; choice index comes from args.choiceIndex
-     *                   or args.choice (string label match), defaulting to 0
+     *   open_picker   → two roles, driven by the screen, not a hardcoded list:
+     *                   - LIST  (no choice arg): open the picker, wait for it
+     *                     to render, parse the on-screen options via
+     *                     `extract_choices`, and return them as
+     *                     `controlResult.options` (+ `currentValue`). This is
+     *                     how the dashboard's Model/Mode controls learn what is
+     *                     actually selectable in this CLI right now.
+     *                   - SELECT (args.choiceIndex / args.choiceLabel): drive
+     *                     the picker to that option using `submit_key`.
      *   attach_image  → attach_image dispatch; expects args.blob (data url
      *                   or base64) and args.mime
      *
@@ -101,6 +107,31 @@ export declare class SpecCliAdapter implements CliAdapter {
      * No control matched, no driver call — keeps the surface honest.
      */
     invokeScript(scriptName: string, args?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Open an `open_picker` control and return the options the CLI is showing,
+     * parsed live from the screen via `extract_choices`. Nothing is selected —
+     * the picker is left open so a follow-up SELECT invoke can commit a choice.
+     */
+    private openPickerAndListChoices;
+    /**
+     * Drive an already-listable picker to a specific option. The option can be
+     * named (choiceLabel — matched against the parsed on-screen labels) or
+     * positional (choiceIndex — the on-screen number). The actual keystrokes
+     * come from the spec's `submit_key` with `{index}` substituted, so the spec
+     * — not this code — decides how a selection is keyed for each CLI.
+     */
+    private selectPickerChoice;
+    /** Poll the live screen until the picker's `wait_for` condition matches,
+     *  up to a short budget. Returns true if it rendered, false on timeout. */
+    private waitForPickerRendered;
+    /** Parse the picker's `extract_choices` pattern against the live screen.
+     *  Each match yields { index, label, current }. `current` is true for the
+     *  line the CLI marks with its cursor glyph (❯ ›). Purely screen-driven —
+     *  no model/mode names are baked in. */
+    private extractPickerChoices;
+    /** Live text of a named screen section (or the whole screen when no
+     *  section is named), resolved from the driver's current sections. */
+    private readScreenSectionText;
     getDebugSnapshot(): unknown;
     getRuntimeMetadata(): unknown;
     updateRuntimeMeta(meta?: Record<string, unknown>): void;

package/dist/providers/spec/types.d.ts

@@ -74,6 +74,42 @@ export interface NativeHistoryMessageMap {
     content_unwrap?: string[];
     timestamp_ms?: string;
     kind?: string;
+    /**
+     * Declarative tool-bubble extraction. Without it the executor only emits
+     * the text-bearing parts of each record, so a turn that is purely a tool
+     * call or tool result (no prose) is dropped — the restored transcript
+     * loses every tool interaction. When present, the executor walks each
+     * record's content blocks and emits an extra `kind:'tool'` message for
+     * any block whose `$.type` matches a tool shape.
+     *
+     * Defaults target the Anthropic-style content-block shape that claude-cli
+     * and codex-cli persist (blocks of `{ type: 'tool_use' | 'tool_result',
+     * name, input, content }`); a provider with a different on-disk shape
+     * overrides the field paths. Set `tools: {}` to opt in with the defaults.
+     */
+    tools?: NativeHistoryToolMap;
+}
+/**
+ * How to surface tool-call / tool-result blocks as `kind:'tool'` bubbles.
+ * Every field is optional — the defaults read the Anthropic block shape.
+ * Paths are jsonpath-lite evaluated against a single content block (the
+ * element of `$.message.content[]`), not the whole record.
+ */
+export interface NativeHistoryToolMap {
+    /** Path to a block's discriminator. Default `$.type`. */
+    block_type?: string;
+    /** Block-type values that mean "a tool was invoked". Default
+     *  `['tool_use', 'function_call', 'custom_tool_call']`. */
+    call_types?: string[];
+    /** Block-type values that mean "a tool returned". Default
+     *  `['tool_result', 'function_call_output', 'custom_tool_call_output']`. */
+    result_types?: string[];
+    /** Path to the tool name on a call block. Default `$.name`. */
+    call_name?: string;
+    /** Path to the tool arguments on a call block. Default `$.input`. */
+    call_args?: string;
+    /** Path to the result payload on a result block. Default `$.content`. */
+    result_content?: string;
 }
 export interface AnchorContext {
     prev?: string;

package/dist/repo-mesh-types.d.ts

@@ -71,6 +71,62 @@ export interface RepoMeshNode {
 export type RepoMeshNodeHealth = 'online' | 'offline' | 'degraded' | 'dirty' | 'wrong_branch' | 'unknown';
 export type RepoMeshSessionCleanupMode = 'preserve' | 'stop' | 'delete_stopped' | 'stop_and_delete';
 export type RepoMeshSpawnedSessionVisibility = 'visible' | 'hidden';
+/**
+ * Mesh-wide tie-break strategy for distributing untargeted queue work across
+ * eligible nodes. This ONLY governs the final tie-break stage of the scheduler
+ * pipeline (TAG hard-filter → MAX-ALLOC capacity gate → PRIORITY soft score →
+ * TIE-BREAK); eligibility/capacity/priority are evaluated identically for every
+ * strategy.
+ *
+ * - 'first_eligible' (DEFAULT): preserve today's behavior exactly. Nodes are
+ *   visited in config/array order and the first that can launch wins. No
+ *   load-spreading. This is the strict no-change default — a mesh that never
+ *   sets schedulingStrategy behaves identically to before this feature.
+ * - 'least_loaded': prefer the eligible node with the fewest active assignments,
+ *   so untargeted work spreads instead of piling onto whichever node asks first.
+ * - 'round_robin': among nodes tied at the least load, rotate the winner using a
+ *   per-mesh cursor so distribution stays fair across passes.
+ * - 'priority_only': rank purely by schedulingPriority (then config order),
+ *   ignoring load — always send to the highest-priority eligible node.
+ *
+ * Distribution is explicit opt-in: a strategy other than 'first_eligible' must be
+ * configured for any load-spreading to occur.
+ */
+export type RepoMeshSchedulingStrategy = 'first_eligible' | 'least_loaded' | 'round_robin' | 'priority_only';
+export declare const MESH_SCHEDULING_STRATEGIES: RepoMeshSchedulingStrategy[];
+export declare const DEFAULT_MESH_SCHEDULING_STRATEGY: RepoMeshSchedulingStrategy;
+/**
+ * Normalize an unknown scheduling-strategy value to a valid strategy, defaulting
+ * to 'first_eligible' (strict no-change) for anything missing/blank/unrecognized.
+ */
+export declare function normalizeMeshSchedulingStrategy(value: unknown): RepoMeshSchedulingStrategy;
+/**
+ * Resolve a node's soft scheduling priority — a single scalar used as the PRIORITY
+ * stage rank key (higher = preferred). It is NOT an eligibility gate (the MAX-ALLOC
+ * capacity gate alone decides whether a node can take work). Missing/blank/NaN
+ * resolves to 0 so unconfigured nodes all share the same neutral priority.
+ */
+export declare function resolveNodeSchedulingPriority(nodePolicy: Pick<RepoMeshNodePolicy, 'schedulingPriority'> | null | undefined): number;
+/**
+ * Synthetic capability tag advertised by every mesh node describing how it can land
+ * its work onto the base branch:
+ *   - converge=refine: a local worktree node (on any machine — refine_mesh_node
+ *     forwards to the owning daemon) can run the Refinery merge → push → cleanup.
+ *   - converge=fast_forward: a non-worktree node (the machine itself) can only
+ *     fast-forward/push an already-converged branch.
+ * Emitted by buildMeshNodeCapabilityTags and matched through the ordinary
+ * required-tags filter.
+ */
+export declare const MESH_CONVERGE_REFINE_TAG = "converge=refine";
+export declare const MESH_CONVERGE_FAST_FORWARD_TAG = "converge=fast_forward";
+/**
+ * Resolve whether the load-balancing scheduler should auto-inject a
+ * `converge=refine` required tag onto code_change tasks so they hard-filter onto
+ * refine-capable (worktree) nodes only. Strict opt-in: defaults to false, so a mesh
+ * that does not set it behaves exactly as before (code_change routes to any eligible
+ * node, including a non-worktree machine node when no worktree exists).
+ */
+export declare function resolveAutoConvergeCodeChange(policy: Pick<RepoMeshPolicy, 'autoConvergeCodeChange'> | null | undefined): boolean;
 export interface RepoMeshAutoFastForwardPolicy {
     /** Defaults to true. Set false to disable daemon-initiated idle fast-forwards. */
     enabled: boolean;
@@ -94,6 +150,24 @@ export interface RepoMeshPolicy {
     dirtyWorkspaceBehavior: 'block' | 'warn' | 'checkpoint_then_continue';
     maxParallelTasks: number;
     allowedProviders?: string[];
+    /**
+     * Mesh-wide tie-break strategy for distributing untargeted queue work across
+     * eligible nodes. Defaults to 'first_eligible' (today's exact behavior — no
+     * load-spreading). Set to 'least_loaded' / 'round_robin' / 'priority_only' to
+     * opt into distribution. Only governs the final tie-break stage; eligibility,
+     * capacity, and priority are evaluated identically regardless of strategy.
+     */
+    schedulingStrategy?: RepoMeshSchedulingStrategy;
+    /**
+     * Convergence routing opt-in: when true, the scheduler auto-injects a
+     * `converge=refine` required tag onto every code_change task at enqueue time, so
+     * code_change work hard-filters onto refine-capable worktree nodes (on any
+     * machine — refine_mesh_node forwards to the owning daemon) and never lands on a
+     * non-worktree machine node. Explicit target_node_id routing and any
+     * caller-supplied required_tags are preserved (the tag is merged, not replaced).
+     * Defaults to false: code_change routing is unchanged unless opted in.
+     */
+    autoConvergeCodeChange?: boolean;
     /**
      * Whether sessions spawned by mesh/coordinator policy should auto-open as visible
      * dashboard tabs or start hidden. Defaults to 'visible' to preserve existing
@@ -140,12 +214,17 @@ export interface RepoMeshRelatedRepo {
  *
  * `role` is a free-form resource-pool label (recommended values:
  * 'investigation' | 'coding' | 'orchestration') describing what this
- * (node, provider) combination is *for*. It is a label/hint only — it is
- * surfaced to the coordinator and dashboards but the daemon does NOT route
- * tasks by role (task routing stays driven by taskMode + requiredTags +
- * targetNode/targetSession). role is intentionally orthogonal to taskMode:
- * taskMode classifies the *work* (code_change vs live_debug_readonly), role
- * classifies the *resource pool*.
+ * (node, provider) combination is *for*. As of the load-balancing scheduler it
+ * is ALSO routable: each declared role is advertised as a synthetic `role=<x>`
+ * capability tag (see buildMeshNodeCapabilityTags), so a task enqueued with
+ * requiredTags: ["role=validation"] is hard-filtered to nodes/providers that
+ * declare that role — through the same nodeSatisfiesRequiredTags path as any
+ * other tag. There is intentionally no separate "advertisedRoles" field: the
+ * label and the routing tag are one mechanism. A task that does not require a
+ * `role=` tag ignores roles entirely (opt-in, fully backward compatible).
+ *
+ * role is intentionally orthogonal to taskMode: taskMode classifies the *work*
+ * (code_change vs live_debug_readonly), role classifies the *resource pool*.
  *
  * `maxParallel` is the only enforced field: the queue will not assign a task
  * to this (node, provider) once it already has `maxParallel` active
@@ -166,15 +245,24 @@ export interface RepoMeshNodePolicy {
     readOnly?: boolean;
     canPush?: boolean;
     maxConcurrentSessions?: number;
+    /**
+     * Soft scheduling priority used as the PRIORITY rank key (higher = preferred)
+     * when the mesh schedulingStrategy spreads work across nodes. Defaults to 0.
+     * This is NOT an eligibility gate — a node with a high priority that is at its
+     * capacity (MAX-ALLOC gate) is still skipped; priority only orders nodes that
+     * can actually take work. Ignored entirely under 'first_eligible'.
+     */
+    schedulingPriority?: number;
     /** Ordered provider preference used when mesh_launch_session omits an explicit type. */
     providerPriority?: string[];
     /**
      * Per-(node, provider) role + parallelism declarations. Each entry binds a
      * providerType on THIS node to an optional free-form role label and an
-     * optional maxParallel cap. Only maxParallel is enforced (as an additional,
+     * optional maxParallel cap. maxParallel is enforced (as an additional,
      * stricter-wins constraint on top of the global maxParallelTasks/taskMode
-     * caps); role is a label/hint surfaced to the coordinator. Missing/empty:
-     * the node behaves exactly as before (global caps only).
+     * caps); role is advertised as a routable `role=<x>` capability tag so tasks
+     * can hard-filter by required role. Missing/empty: the node behaves exactly
+     * as before (global caps only, no role tags).
      */
     providerRoles?: RepoMeshProviderRole[];
     /**
@@ -412,6 +500,12 @@ export interface RepoMeshPeerConnectionStatus {
     transport: RepoMeshPeerConnectionTransport;
     reported: boolean;
     reason?: string;
+    /**
+     * Round-trip time in ms for the selected candidate pair, as sampled by the
+     * coordinator daemon when connected. Optional — older daemons and not_reported
+     * fallbacks omit it; the dashboard must treat it as best-effort telemetry.
+     */
+    rttMs?: number;
     lastStateChangeAt?: string;
     lastConnectedAt?: string;
     lastCommandAt?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.310",
+  "version": "0.9.82-rc.312",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.310",
+    "@adhdev/mesh-shared": "0.9.82-rc.312",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/chat-commands.ts

@@ -29,7 +29,7 @@ import {
 } from '../chat/source-resolver.js';
 import type { ChatMessage } from '../types.js';
 import type { SessionTransport } from '../shared-types.js';
-import { filterUserFacingChatMessages, normalizeChatMessages } from '../providers/chat-message-normalization.js';
+import { filterUserFacingChatMessages, isActivityChatMessage, isUserFacingChatMessage, normalizeChatMessages } from '../providers/chat-message-normalization.js';
 
 const RECENT_SEND_WINDOW_MS = 1200;
 export const READ_CHAT_PROVIDER_EVAL_TIMEOUT_MS = 25_000;
@@ -1531,7 +1531,15 @@ function buildReadChatCommandResult(payload: Record<string, any>, args: any, h?:
     const filteredMessages = h
         ? maybeHideCoordinatorPromptMessage(h, providerHint, sessionIdHint, messages)
         : messages;
-    const visibleMessages = filterUserFacingChatMessages(filteredMessages);
+    // By default read_chat returns only user-facing prose turns. When the
+    // caller opts in with `includeActivity`, tool/terminal/thought activity
+    // bubbles (e.g. the native transcript's tool calls and results) are kept
+    // inline too, in chronological order, so a restored conversation can show
+    // what the agent actually did — not just the prose around it.
+    const includeActivity = args?.includeActivity === true || args?.includeActivity === 'true';
+    const visibleMessages = includeActivity
+        ? filteredMessages.filter((m) => isUserFacingChatMessage(m) || isActivityChatMessage(m))
+        : filterUserFacingChatMessages(filteredMessages);
     const sync = buildFullTail(visibleMessages, normalizeReadChatTailLimit(args));
     const hiddenMsgCount = Math.max(0, messages.length - visibleMessages.length);
     const preservedPayloadFields = Object.fromEntries(Object.entries(payload).filter(([key]) => shouldPreserveReadChatPayloadField(key)));