@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.491

package/dist/installer.d.ts

@@ -28,10 +28,7 @@ export interface InstallResult {
     alreadyInstalled: boolean;
     error?: string;
 }
-/**
- * Check if an extension is already installed
- */
-export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): boolean;
+export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): Promise<boolean>;
 /**
  * Install a single extension
  */

package/dist/ipc/local-ipc-server.d.ts

@@ -0,0 +1,91 @@
+/**
+ * LocalIpcServer — generic HTTP + WebSocket IPC endpoint for daemon processes.
+ *
+ * Both daemon-cloud and daemon-standalone need a local IPC surface so
+ * external tools — the `adhdev mcp --mode ipc` MCP server and anything
+ * else that wants to issue commands without going through the cloud
+ * Worker — can connect over `ws://127.0.0.1:<port>/ipc`.
+ *
+ * Until now the implementation lived only in daemon-cloud. Standalone
+ * sessions therefore couldn't host MCP mesh tools — codex/claude config
+ * pointing at `--mode ipc` got `Cannot reach ipc daemon`. This module
+ * moves the transport into daemon-core so both daemons can mount it.
+ *
+ * The transport itself is daemon-agnostic. Cloud-specific behaviors
+ * (mesh relay, mandatory update gates) are injected via the caller's
+ * `handleCommand` hook; the IPC layer just frames/unframes JSON and
+ * routes messages.
+ */
+import { WebSocket } from 'ws';
+/** Parameters passed to `handleCommand` for each incoming ext:command frame. */
+export interface IpcCommandContext {
+    /** The raw `command` field from the message — caller decides routing. */
+    command: string;
+    /** Args provided by the client; may have been normalized by the caller. */
+    args: Record<string, unknown>;
+    /** Stable id correlating the request and the eventual ext:command_result. */
+    requestId: string;
+    /** The connected WebSocket — only needed if the caller wants to send extra events. */
+    ws: WebSocket;
+}
+/** Result reported back to the client. `result` is optional context for success. */
+export interface IpcCommandResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    /**
+     * Additional fields the caller wants merged into the response payload
+     * (e.g. the cloud daemon's mandatory-update-block fields). Reserved.
+     */
+    extra?: Record<string, unknown>;
+}
+/** Status payload returned from GET / on the IPC HTTP port. */
+export interface IpcStatusPayload {
+    ok: true;
+    pid: number;
+    wsPath: string;
+    port: number;
+    /** Arbitrary daemon-specific summary. Cloud daemon includes mesh state, etc. */
+    status: Record<string, unknown> | null;
+}
+export interface LocalIpcServerOptions {
+    /** TCP port to listen on. 19222 is the conventional default. */
+    port: number;
+    /** Build the GET / status payload. Called on every health probe. */
+    buildStatusPayload: () => Record<string, unknown> | null;
+    /** Build the welcome message sent to a freshly-connected client. */
+    buildWelcomePayload: () => Record<string, unknown>;
+    /** Handle a single ext:command frame. Caller decides routing and returns the result. */
+    handleCommand: (ctx: IpcCommandContext) => Promise<IpcCommandResult>;
+    /** Optional notification when a new client connects (lets daemon track them for broadcasts). */
+    onClientConnected?: (ws: WebSocket) => void;
+    /** Optional notification when a client disconnects. */
+    onClientDisconnected?: (ws: WebSocket) => void;
+    /** Optional logger label (defaults to "IPC"). */
+    logCategory?: string;
+}
+/**
+ * Returned controller for stopping the server and broadcasting to clients.
+ * Stored by the daemon and torn down at shutdown.
+ */
+export interface LocalIpcServerHandle {
+    /** True once `listen()` succeeded. */
+    isListening(): boolean;
+    /** Push a message to every connected client. */
+    broadcast(type: string, payload: unknown): void;
+    /** Close all client sockets + the HTTP server. */
+    close(): Promise<void>;
+}
+/**
+ * Build a JSON HTTP response describing the IPC endpoint. Exposed so caller
+ * code (and tests) can build the same shape without spinning a real server.
+ */
+export declare function buildIpcStatusHttpResponse(method: string | undefined, url: string | undefined, payload: IpcStatusPayload): {
+    statusCode: number;
+    body: Record<string, unknown>;
+};
+/**
+ * Start the local IPC server. Returns a handle the caller can use to broadcast
+ * events and tear down at shutdown.
+ */
+export declare function startLocalIpcServer(opts: LocalIpcServerOptions): Promise<LocalIpcServerHandle>;

package/dist/launch.d.ts

@@ -18,7 +18,7 @@
 /** Kill IDE process (graceful → force) */
 export declare function killIdeProcess(ideId: string): Promise<boolean>;
 /** Check if IDE process is running */
-export declare function isIdeRunning(ideId: string): boolean;
+export declare function isIdeRunning(ideId: string): Promise<boolean>;
 export interface LaunchOptions {
     ideId?: string;
     workspace?: string;

package/dist/logging/async-batch-writer.d.ts

@@ -0,0 +1,10 @@
+export declare class AsyncBatchWriter {
+    private static buffers;
+    private static writePromises;
+    private static flushTimer;
+    /**
+     * Queues data to be written to a file asynchronously in a batch.
+     */
+    static write(filePath: string, data: string): void;
+    private static flushAll;
+}

package/dist/logging/debug-config.d.ts

@@ -14,6 +14,22 @@ export interface DebugRuntimeConfig {
     traceBufferSize: number;
     traceCategories: string[];
 }
+/**
+ * ALWAYS-ON trace categories. These bypass the `collectDebugTrace` master switch
+ * (and category selection) so they are collected in production daemons where
+ * `--trace` is unset. They exist so mesh completion diagnostics — the FSM-transition
+ * and completion-gate snapshots that explain an early / missing agent:generating_completed
+ * notification — are retrievable via mesh_read_debug (chat_debug_bundle) without asking
+ * an operator to relaunch the daemon with tracing on.
+ *
+ * SAFETY: only add a category here after confirming every record() call site for it
+ * carries a content-free payload (statuses, epochs, timestamps, deltas, lengths, roles,
+ * enum-like reasons — never transcript / prompt / bubble text). Always-on collection makes
+ * such payloads unconditional, so a content-bearing field would leak into the ring buffer
+ * in production.
+ */
+export declare const ALWAYS_ON_TRACE_CATEGORIES: readonly string[];
+export declare function isAlwaysOnTraceCategory(category?: string | null): boolean;
 export declare function resolveDebugRuntimeConfig(options?: DebugRuntimeOptions): DebugRuntimeConfig;
 export declare function setDebugRuntimeConfig(config: DebugRuntimeConfig): void;
 export declare function getDebugRuntimeConfig(): DebugRuntimeConfig;

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,81 @@
+/**
+ * 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 more content existed than fit.
+ *
+ * Two read modes:
+ *  - No filter (no grep/sinceMs): byte-bounded tail of the active file — read the
+ *    last `tailBytes` bytes only. Cheap, backward-compatible.
+ *  - Filtered (grep and/or sinceMs given): FULL-FILE scan. The filter is applied
+ *    across the ENTIRE file (plus the size-rotation `.1.log` backup) BEFORE the
+ *    byte cap, then the last `tailBytes` worth of MATCHING lines are returned.
+ *    This is the fix for "matches hidden behind polling spam": when the recent
+ *    tail window is saturated with high-frequency lines (e.g. coordinator polling
+ *    `get_pending_mesh_events`/`read_chat` every few seconds), a grep for a rarer
+ *    earlier line (dispatch/inject/forward) previously matched 0 because the line
+ *    had already scrolled out of the tail window before the filter ran. Filtering
+ *    the whole file first surfaces those matches regardless of how much unrelated
+ *    spam followed them.
+ *
+ * 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[];
+    /**
+     * No-filter mode: true when the file was larger than the byte window.
+     * Filter mode: true when matching lines were dropped from the FRONT to fit
+     * the byte cap (i.e. there are older matches than the ones returned).
+     */
+    truncated: boolean;
+    logPath: string;
+    platform: NodeJS.Platform;
+    bytesReturned: number;
+    /** True when a grep/since filter dropped at least one line. */
+    filtered: boolean;
+    /** The grep source actually applied (echoed back for clarity). */
+    grep?: string;
+    /** True when the filtered full-file scan path ran (grep/sinceMs given). */
+    fullScan: boolean;
+    /** Total bytes read while scanning (filter mode scans the whole file + backup). */
+    scannedBytes: number;
+    /** Number of lines that matched the filter across the full scan (filter mode). */
+    matchedLineCount: number;
+    /** Number of scanned lines dropped by the filter ("N lines excluded by filter"). */
+    excludedByFilter: number;
+}
+/**
+ * Read the daemon log tail for `date` (default today), bounded to `tailBytes`.
+ *
+ * - No grep/sinceMs → byte-bounded tail of the active file (legacy behaviour).
+ * - grep and/or sinceMs given → FULL-FILE scan: the filter is applied across the
+ *   whole file (plus the `*.1.log` size-rotation backup) BEFORE the byte cap, so
+ *   matches that have scrolled out of the recent tail window (e.g. behind
+ *   coordinator polling spam) are still returned. Only the last `tailBytes` worth
+ *   of matching lines ship over P2P.
+ *
+ * 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/logging/logger.d.ts

@@ -7,7 +7,7 @@
  * 1. daemonLog(category, msg, level) — explicit per-category logging
  * 2. installGlobalInterceptor() — Auto-intercept console.log (once on daemon start)
  * 3. Recent log ring buffer — for remote transmission via P2P/WS
- * 4. File logging — ~/Library/Logs/adhdev/daemon.log (10MB rolling)
+ * 4. File logging — ~/.adhdev/logs/daemon-YYYY-MM-DD.log (date-based rolling)
  *
  * use:
  * import { daemonLog, LOG } from './daemon-logger';

package/dist/mesh/contracts.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Mesh contract v2 — first-class identity, scopes, and protocol version.
+ *
+ * Replaces the implicit conventions that grew across mesh-events.ts,
+ * mesh-work-queue.ts, mesh-ledger.ts, and mesh-tools.ts where the same
+ * concept (a coordinator, a session, a task status) appeared in different
+ * shapes per file. The audit found:
+ *
+ *   - PendingMeshCoordinatorEvent had no targetCoordinatorDaemonId. All
+ *     events were broadcast to every coordinator that drained them. Two
+ *     coordinators sharing a mesh would each receive every event,
+ *     leading to duplicate completion handling and missed targeting.
+ *   - drainPendingMeshCoordinatorEvents accepted only meshId. The caller's
+ *     coordinator identity was never available, so per-coordinator
+ *     routing was impossible by construction.
+ *   - Session identifier keys diverged across stores: targetSessionId /
+ *     assignedSessionId / instanceId / runtimeSessionId / providerSessionId.
+ *     resolveEventSessionId() tried four fallbacks per call.
+ *   - No protocol version on the JSONL ledger or MeshRuntimeStore. Schema
+ *     evolutions had no guard rail.
+ *   - mesh_reconcile_ledger existed as a routine recovery tool, not as
+ *     an incident-response escape hatch. That itself signals the routing
+ *     layer cannot be trusted.
+ *
+ * This module introduces the types; the actual wiring lands in B2 (data
+ * model + 3-way transactional store), B3 (MCP layer enforcement), and B4
+ * (frontend consumption). B1 is intentionally non-breaking — it adds the
+ * types and leaves runtime behaviour unchanged.
+ */
+/** Provider type identifier (e.g. 'claude-cli', 'codex-cli', 'roo-code').
+ *  Free-form string; no shared enum exists in daemon-core yet. */
+type ProviderType = string;
+export declare const MESH_PROTOCOL_VERSION_V1: "1.0";
+export declare const MESH_PROTOCOL_VERSION_V2: "2.0";
+export type MeshProtocolVersion = typeof MESH_PROTOCOL_VERSION_V1 | typeof MESH_PROTOCOL_VERSION_V2;
+export declare const SUPPORTED_MESH_PROTOCOL_VERSIONS: readonly MeshProtocolVersion[];
+export declare function isSupportedMeshProtocolVersion(value: unknown): value is MeshProtocolVersion;
+/**
+ * Identity of a mesh coordinator. Required (non-optional) on every dispatch
+ * and drain operation in v2 — opaque/missing identity is the audit's
+ * smoking gun for routing failures and is structurally banned by the v2
+ * types.
+ *
+ * - daemonId: the machineId of the daemon hosting the coordinator. Stable
+ *   across coordinator restarts on the same machine.
+ * - coordinatorRunId: a UUID generated when the coordinator process starts.
+ *   Stable for the coordinator's lifetime, fresh on restart. Required so
+ *   two coordinators on the same daemon (one CLI, one MCP) can be told
+ *   apart without conflating their drains.
+ * - sessionId: optional CLI coordinator session identifier (instanceId).
+ *   Present when the coordinator is itself a CLI session, absent for
+ *   pure MCP coordinators.
+ */
+export interface CoordinatorIdentity {
+    readonly daemonId: string;
+    readonly coordinatorRunId: string;
+    readonly sessionId?: string;
+}
+export declare function coordinatorIdentityEquals(a: CoordinatorIdentity, b: CoordinatorIdentity): boolean;
+export declare function coordinatorIdentityKey(identity: CoordinatorIdentity): string;
+/**
+ * Unified mesh session identifier. v1 referred to "the session" with five
+ * different field names depending on which store you were reading; v2
+ * collapses them into one explicit handle that carries every disambiguator
+ * a consumer might need.
+ *
+ * - nodeId: the mesh node this session belongs to (FK into mesh node table).
+ * - sessionId: provider-instance identifier (the runtime session id).
+ * - providerType: which provider category/type the session runs (e.g.
+ *   'claude-cli', 'codex-cli', 'roo-code').
+ * - coordinatorDaemonId: which coordinator dispatched the work that
+ *   spawned this session. Used for completion event routing.
+ * - assignedAt: ms epoch when the session was bound to its current task.
+ */
+export interface MeshSessionHandle {
+    readonly nodeId: string;
+    readonly sessionId: string;
+    readonly providerType: ProviderType;
+    readonly coordinatorDaemonId: string;
+    readonly assignedAt: number;
+}
+export declare function meshSessionHandleKey(handle: MeshSessionHandle): string;
+/**
+ * Single canonical task status enum. v1 had at least three overlapping
+ * sets (queue / ledger / direct-dispatch). v2 consumers import from here.
+ */
+export declare const MESH_TASK_STATUSES: readonly ["pending", "assigned", "in_progress", "completed", "failed", "cancelled"];
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+export declare function isMeshTaskStatus(value: unknown): value is MeshTaskStatus;
+/**
+ * Explicit scope for pending coordinator events. v1 had no scope: every
+ * event was broadcast to every drainer. v2 forces producers to declare
+ * intent.
+ *
+ * - 'unicast': delivered to exactly one coordinator (intendedFor). Other
+ *   coordinators' drains skip it.
+ * - 'broadcast': delivered to every coordinator on the mesh. Used for
+ *   system-wide signals (e.g. mesh-wide policy changes). The v1 default
+ *   becomes explicit here so audit tools can flag unintended broadcasts.
+ * - 'system': delivered to the daemon-level handler, not coordinators.
+ *   Reserved for infrastructure events that no coordinator should see
+ *   (e.g. ledger reconciliation outcomes).
+ */
+export declare const MESH_EVENT_SCOPES: readonly ["unicast", "broadcast", "system"];
+export type MeshEventScope = typeof MESH_EVENT_SCOPES[number];
+export declare function isMeshEventScope(value: unknown): value is MeshEventScope;
+/**
+ * v2 shape of a pending coordinator event. Strict supersets of the v1
+ * shape — every v1 field is preserved so existing readers do not break;
+ * v2 fields (scope, dispatchedBy, intendedFor, protocolVersion) are
+ * additive and consulted by v2-aware drainers only.
+ *
+ * Mixed v1/v2 events coexist during the rollout window. B2 fully cuts
+ * over once every coordinator drain is v2-aware.
+ */
+export interface PendingMeshCoordinatorEventV2 {
+    readonly event: string;
+    readonly meshId: string;
+    readonly nodeLabel: string;
+    readonly nodeId?: string;
+    readonly workspace?: string;
+    readonly metadataEvent: Record<string, unknown>;
+    readonly coordinatorMessage?: string;
+    readonly queuedAt: number;
+    readonly protocolVersion: MeshProtocolVersion;
+    /**
+     * Idempotency key. A UUID generated ONCE at emit time and preserved verbatim
+     * across every store (SQLite payload + column, JSONL) and the P2P relay
+     * boundary. The receiving drain uses eventId as the authoritative dedup key
+     * (B3): an event whose eventId was already drained is skipped even if its
+     * content fingerprint differs. Distinct from the content fingerprint, which
+     * stays the v1 dedup mechanism during rollout.
+     */
+    readonly eventId: string;
+    readonly scope: MeshEventScope;
+    readonly dispatchedBy: CoordinatorIdentity;
+    /**
+     * Required when scope === 'unicast', forbidden otherwise. Drainers MUST
+     * skip unicast events whose intendedFor does not equal their own identity.
+     */
+    readonly intendedFor?: CoordinatorIdentity;
+}
+/**
+ * v2 ledger entry additions. The originatingCoordinator field is the
+ * source of truth that lets completion events route back to the
+ * coordinator that dispatched the task. v1's "worker settings carried it
+ * if it happened to be set" approach is replaced.
+ */
+export interface MeshLedgerOriginatingCoordinatorV2 {
+    readonly originatingCoordinator: CoordinatorIdentity;
+    readonly protocolVersion: MeshProtocolVersion;
+}
+export declare class MeshContractViolationError extends Error {
+    readonly violationPath: string;
+    readonly protocolVersion: MeshProtocolVersion;
+    constructor(protocolVersion: MeshProtocolVersion, violationPath: string, detail: string);
+}
+export declare function assertCoordinatorIdentity(raw: unknown, path: string): CoordinatorIdentity;
+export declare function assertPendingMeshCoordinatorEventV2(raw: unknown, path?: string): PendingMeshCoordinatorEventV2;
+/**
+ * Decide whether a v2 pending event should be delivered to the given drainer.
+ * Centralised so every drain implementation uses the same rule.
+ *
+ *   - 'broadcast': always delivered. NOTE: a terminal task event that reached the
+ *     queue as broadcast is an ownership leak (it belongs to its dispatching
+ *     coordinator). This pure helper does not have the drain-window
+ *     daemon-form/session matching semantics, so the terminal+broadcast
+ *     dispatchedBy filter is applied one layer up in the drainer (see
+ *     mesh-events-pending routeV2EventsForDrainer) where those semantics live.
+ *   - 'system': never delivered to coordinators (system handler only).
+ *   - 'unicast': delivered iff intendedFor matches drainer identity.
+ *
+ * v1 events (no scope / no protocolVersion) are treated as broadcast for
+ * backward compatibility during rollout; B3 tightens this so v1 events
+ * are quarantined to a dedicated drain endpoint instead.
+ */
+export declare function shouldDeliverPendingEventToCoordinator(event: PendingMeshCoordinatorEventV2, drainer: CoordinatorIdentity): boolean;
+/**
+ * True for a terminal task event (completion / stop / refine outcome). A terminal
+ * event belongs to exactly the coordinator that dispatched the task, so it must
+ * never fan out to sibling coordinators that did not dispatch it. Used by the
+ * emit-side stamp (to avoid downgrading an unaddressed terminal event to full
+ * broadcast) and by the drain-side filter (defense-in-depth for any terminal
+ * event that already reached the queue as broadcast).
+ */
+export declare function isTerminalTaskEvent(eventName: string): boolean;
+/**
+ * Default the v2 scope for an event by its producer event name (design decision
+ * §3). Terminal task events and coordinator-addressed alerts → unicast (routed
+ * to the originating coordinator). Everything else — node lifecycle and
+ * progress signals — → broadcast, which also matches v1's implicit "deliver to
+ * any coordinator" behaviour, so an unstamped v1 event and a v2-stamped-as-
+ * broadcast event route identically during rollout. No event currently defaults
+ * to 'system'; the scope remains in MESH_EVENT_SCOPES for wire compatibility
+ * (an already-queued or version-skewed 'system' event still routes away from
+ * coordinators).
+ */
+export declare function defaultScopeForEvent(eventName: string): MeshEventScope;
+/**
+ * The v2 envelope stamp applied to a pending coordinator event at emit time.
+ * Additive over the v1 shape: every field is consulted by v2-aware drainers
+ * only, so a v1 reader that ignores them is unaffected.
+ */
+export interface PendingEventEmitStampV2 {
+    readonly protocolVersion: typeof MESH_PROTOCOL_VERSION_V2;
+    readonly eventId: string;
+    readonly scope: MeshEventScope;
+    readonly dispatchedBy: CoordinatorIdentity;
+    readonly intendedFor?: CoordinatorIdentity;
+}
+/**
+ * Build a coordinator identity from the loosely-typed fields the v1 emit call
+ * sites already carry (a daemonId, and — sometimes — a coordinator session id).
+ * Returns undefined when no usable daemonId is present; the caller then leaves
+ * the event unstamped (v1, broadcast-treated) rather than fabricating identity.
+ * coordinatorRunId is not known at every emit site yet (B2 wires the registry),
+ * so it falls back to the daemonId — a stable, non-empty value that keeps the
+ * identity well-formed for assertCoordinatorIdentity without inventing a UUID
+ * that would differ per emit and defeat equality.
+ */
+export declare function coordinatorIdentityFromEmitFields(fields: {
+    daemonId?: string | null;
+    coordinatorRunId?: string | null;
+    sessionId?: string | null;
+}): CoordinatorIdentity | undefined;
+/**
+ * Compute the v2 emit stamp for an event (B2a). `eventId` MUST be supplied by
+ * the caller (generated via crypto.randomUUID at the daemon-core boundary so
+ * this module stays dependency-free and deterministically testable). Scope
+ * defaults from the event name unless explicitly overridden.
+ *
+ * When `dispatchedBy` cannot be constructed (no coordinator daemon known),
+ * returns undefined: the event stays a v1 (unstamped) event and is broadcast-
+ * treated during rollout, exactly as before — no regression, no fabricated
+ * identity. When the resolved scope is 'unicast' but no `intendedFor` is
+ * available, the fallback depends on the event class:
+ *
+ *   - Terminal task events (completion / stop / refine outcome) MUST NOT be
+ *     broadcast to every coordinator — a completion belongs to the coordinator
+ *     that dispatched the task, and broadcasting it makes non-owner coordinators
+ *     (e.g. sibling MAGI coordinators that never dispatched this replica's task)
+ *     act on a completion that is not theirs (MAGI-REPLICA-COMPLETION-EVENT-LEAK).
+ *     For these we address the event to `dispatchedBy` (the dispatching
+ *     coordinator) and KEEP it unicast, so the stamp stays contract-valid and the
+ *     event reaches only its originating coordinator.
+ *   - Any other unicast event with no addressable target falls back to broadcast
+ *     (contract-valid, still delivered, never dropped) — unchanged.
+ */
+export declare function buildPendingEventEmitStamp(opts: {
+    eventName: string;
+    eventId: string;
+    dispatchedBy?: CoordinatorIdentity;
+    intendedFor?: CoordinatorIdentity;
+    scope?: MeshEventScope;
+}): PendingEventEmitStampV2 | undefined;
+export {};

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

@@ -8,12 +8,88 @@
  *   3. How to orchestrate work across nodes
  *
  * The prompt is generated dynamically from the current mesh state.
+ *
+ * User customization:
+ *   ~/.adhdev/coordinator-prompts/<cliType>.md         — full override
+ *   ~/.adhdev/coordinator-prompts/<cliType>.append.md  — appended to default
+ *   ~/.adhdev/coordinator-prompts/default.md           — full override (any CLI)
+ *   ~/.adhdev/coordinator-prompts/default.append.md    — appended to default (any CLI)
+ *
+ * CLI-specific files take precedence over default.* files. The override file
+ * still gets the node/policy facts substituted via the same {{placeholders}}
+ * the daemon understands; an override that doesn't reference them just gets
+ * a static prompt, which is also fine.
  */
 import type { LocalMeshEntry, RepoMeshStatus } from '../repo-mesh-types.js';
+/**
+ * Cheap, locally-derived "what just happened" snapshot for the coordinator
+ * prompt. Built at launch from the local ledger + work-queue stats — no remote
+ * peer probe. Surfaces the gap a fresh coordinator otherwise misses: it can't
+ * see recent failures / queue depth until it manually calls mesh_task_history.
+ *
+ * All fields are optional so callers that have nothing to report (or fail to
+ * read the ledger) simply omit the section — the prompt output stays identical
+ * to the pre-activity form in that case.
+ */
+export interface CoordinatorRecentActivity {
+    /** task_failed entries from the recent window, newest last. */
+    recentFailures?: Array<{
+        timestamp?: string;
+        nodeId?: string;
+        /** Short task title/message, already truncated by the caller. */
+        summary?: string;
+    }>;
+    /** Count of task_failed entries inside the recent window. */
+    recentFailureCount?: number;
+    /**
+     * Size of the "recent" window in minutes. Drives the "failed in the last
+     * N min" phrasing. Omitted → defaults to 30, matching the prior hardcoded
+     * wording so existing callers render identically.
+     */
+    windowMinutes?: number;
+    /** Pending (unclaimed) tasks in the work queue. */
+    pendingTasks?: number;
+    /** Assigned-but-not-yet-terminal tasks in the work queue. */
+    assignedTasks?: number;
+    /** Stalled tasks recorded in the ledger. */
+    stalledTasks?: number;
+    /** ISO timestamp of the most recent ledger activity, if any. */
+    lastActivityAt?: string | null;
+}
+/**
+ * One coordinator operating note — a runtime-accumulated lesson (provider
+ * quirk, pattern to avoid, recovery lesson) persisted in the ledger so it
+ * survives coordinator restarts and is provider-neutral (visible to codex /
+ * hermes / antigravity coordinators, not just Claude's memory).
+ */
+export interface CoordinatorOperatingNote {
+    text: string;
+    category?: 'provider_quirk' | 'pattern_to_avoid' | 'recovery_lesson';
+    createdAt?: string;
+    sourceCoordinator?: string;
+}
 export interface CoordinatorPromptContext {
     mesh: LocalMeshEntry;
     status?: RepoMeshStatus;
     userInstruction?: string;
     coordinatorCliType?: string;
+    /**
+     * M3: pre-rendered active mission section (from buildMissionPromptSection).
+     * Empty/undefined when the mesh has no active mission — the prompt output
+     * stays identical to the pre-M3 form in that case.
+     */
+    missionSection?: string;
+    /**
+     * Gap1: recent ledger/queue activity surfaced so a freshly-launched
+     * coordinator sees recent failures + queue depth without first calling
+     * mesh_task_history. Omitted → no "## Recent Activity" section.
+     */
+    recentActivity?: CoordinatorRecentActivity;
+    /**
+     * Gap2-A: runtime-accumulated operating notes (provider-neutral lessons)
+     * read from the ledger at launch. Omitted/empty → no "## Operating Notes"
+     * section.
+     */
+    operatingNotes?: CoordinatorOperatingNote[];
 }
 export declare function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string;