@adhdev/mesh-shared 1.0.60-rc.33 → 1.0.60-rc.35

package/dist/worker-protocol.d.ts

@@ -0,0 +1,69 @@
+/**
+ * worker-protocol — what a delegated worker is told, and what it may call.
+ *
+ * Wiring-unification Phase F1 (docs/design/2026-09-23-wiring-unification.md §7b).
+ *
+ * Measured 2026-09-23 on the live preview ledger: 635 worker attempts in 14
+ * days, 3 `report_completion` calls. The worker MCP was delivered to every
+ * provider and never used, because nothing ever told the worker it existed —
+ * the dispatched task body carried no instruction and the coordinator prompt
+ * did not mention the worker tools at all. The only text a worker saw about
+ * its tools was the tool description.
+ *
+ * This module is the single source for BOTH sides of that contract:
+ *   - `WORKER_TOOLS` — exactly what `adhdev mcp --mode worker` advertises
+ *     (a parity test in mcp-server pins ListTools to this tuple);
+ *   - `renderWorkerProtocolFooter()` — the block appended to EVERY dispatched
+ *     task body, so a worker learns the protocol from the task itself;
+ *   - `renderCoordinatorWorkerSection()` — the matching paragraph the
+ *     coordinator prompt carries, so the coordinator expects structured reports
+ *     and stops polling for them.
+ *
+ * Wiring-unification Phase H2 adds an optional mission-brief block: when a
+ * dispatched task belongs to a mission that carries a `MissionBrief`
+ * (`./mission-brief.ts`), `renderWorkerProtocolFooter` renders it ABOVE the
+ * `WORKER_PROTOCOL_FOOTER_MARKER` line. This is deliberate placement, not an
+ * accident of insertion order: `hasWorkerProtocolFooter` / `stripWorkerProtocolFooter`
+ * both key off the marker line alone, so a body with a brief block strips
+ * identically to one without — the brief is authored content from the
+ * coordinator's point of view (like the task message itself), never part of
+ * the protocol contract the marker demarcates.
+ */
+import { type MissionBrief } from './mission-brief';
+export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff"];
+export type WorkerTool = typeof WORKER_TOOLS[number];
+export declare function isWorkerTool(value: unknown): value is WorkerTool;
+/** Stable marker line so a body is never footered twice and tests can find it. */
+export declare const WORKER_PROTOCOL_FOOTER_MARKER = "--- adhdev worker protocol ---";
+export interface WorkerProtocolFooterInput {
+    taskId?: string;
+    taskMode?: string;
+    difficulty?: string;
+    readonly?: boolean;
+    /** Number of handoff notes enclosed above the footer, when any. */
+    enclosedHandoffNotes?: number;
+    /** H2: the owning mission's brief, when this task belongs to one. Rendered above the marker line — see module doc. */
+    missionBrief?: MissionBrief;
+}
+export declare function hasWorkerProtocolFooter(body: string): boolean;
+/**
+ * The protocol block appended to a dispatched task. Written for the model that
+ * receives it: imperative, short, and explicit about what is NOT available so
+ * the worker does not go looking for coordinator tools.
+ */
+export declare function renderWorkerProtocolFooter(input?: WorkerProtocolFooterInput): string;
+/**
+ * The authored text of a dispatched body: everything before the footer marker.
+ * Ledger descriptors, replay fixtures and tests compare authored text, never
+ * the protocol block.
+ */
+export declare function stripWorkerProtocolFooter(body: string): string;
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export declare function appendWorkerProtocolFooter(body: string, input?: WorkerProtocolFooterInput): string;
+/**
+ * The paragraph the COORDINATOR prompt carries about its workers. Kept next to
+ * the footer so the two halves of the protocol cannot drift apart.
+ */
+export declare function renderCoordinatorWorkerSection(): string;

package/dist/ws-protocol.d.ts

@@ -1,53 +1,36 @@
 /**
- * ws-protocol — shared string-literal unions for the daemon↔server WS surface
- * and the daemon↔dashboard P2P DataChannel surface.
+ * ws-protocol — name-only aliases for the daemon↔server WS surface and the
+ * daemon↔dashboard P2P DataChannel surface, plus the `auth_ok.payload.limits`
+ * contract.
  *
- * Fragmentation audit: these message types existed as a TypeScript union in
- * exactly ONE package (the proprietary daemon-cloud's server-connection.ts),
- * which is a leaf CONSUMER — the other two participants (the Workers server
- * and OSS daemon-core, which is the primary `status_report` producer) matched
- * bare string literals by hand. Renaming `auth_ok` server-side would compile
- * everywhere and leave the daemon reconnecting forever. Pure literals, zero
- * runtime deps — the textbook mesh-shared leaf.
- *
- * SCOPE HONESTY: this file declares the OSS-visible protocol surface. The
- * proprietary repo's server-connection.ts remains the authority for the full
- * ServerToDaemon command set; it should adopt these unions and extend them
- * (`ServerToDaemonMsg | <proprietary extras>`) rather than re-declaring the
- * shared members. Members here are the ones OSS daemon-core itself produces
- * or matches.
- */
-/** Messages the daemon sends UP to the Workers server over the WS bridge. */
-export type DaemonToServerWsMsg = 'auth' | 'status_report' | 'status_heartbeat' | 'status_event' | 'command_result' | 'error' | 'agent_event' | 'log'
-/**
- * seqscribe Beacon vectors (design §7.1). ONE daemon-initiated frame carries
- * both directions — `op: 'put'` stores this node's content-free vector
- * report, `op: 'get'` asks for the board — because the server has no way to
- * wake itself: `DaemonConnectionDO` has neither an alarm nor a timer, and
- * adding one would hit the most request-quota-pressured axis in the system.
- */
- | 'beacon_vectors';
-/** Server→daemon control messages the OSS engine reacts to. */
-export type ServerToDaemonWsMsg = 'auth_ok' | 'auth_error' | 'machine_evicted' | 'force_disconnect' | 'token_revoked' | 'version_mismatch' | 'force_update_required' | 'command' | 'agent_command' | 'resolve_action'
-/**
- * Reply to a `beacon_vectors` GET, correlated by `requestId`. A PUT is
- * fire-and-forget and gets no reply at all — the beacon is advisory, so a
- * lost report costs one debounce cycle of prediction accuracy and nothing
- * else, which is not worth an ack round trip.
+ * Wiring-unification Phase A2: the typed frame unions now live in ./protocol
+ * (one file per link, payloads included). This file keeps the symbols that
+ * pre-dated them — `DaemonToServerWsMsg`, `ServerToDaemonWsMsg`,
+ * `P2PSignalingWsMsg`, `DashboardP2PMessageKind` and the two name arrays —
+ * DERIVED from the protocol unions rather than re-declared, so they cannot
+ * drift again. Before this derivation the list here said `offer|answer|ice`
+ * while the wire said `p2p_offer|p2p_answer|p2p_ice`, declared a `log` frame
+ * nothing sent or handled, omitted `daemon_mesh_command` (sent by a raw
+ * `ws.send`), and listed 12 of the ~27 P2P kinds — and nothing imported the
+ * drifted members, so nothing noticed.
  */
- | 'beacon_vectors_result';
-/** P2P signaling relayed through the server WS. */
-export type P2PSignalingWsMsg = 'p2p_ready' | 'offer' | 'answer' | 'ice' | 'mesh_p2p_ready' | 'mesh_p2p_offer' | 'mesh_p2p_answer' | 'mesh_p2p_ice';
+import { type DaemonToServerType, type ServerToDaemonControlType, type P2PSignalType, type MeshP2PSignalType, type DashboardToDaemonP2PType, type DaemonToDashboardP2PType } from './protocol';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 /**
- * Dashboard↔daemon P2P DataChannel JSON message kinds. Previously matched as
- * hand-synced literals on both ends with NO shared symbol anywhere —
- * `p2p_evicted` had exactly two occurrences repo-wide (emit + handle).
+ * Server→daemon CONTROL messages (see protocol/daemon-server.ts). The server
+ * additionally relays an open command namespace as the frame `type`
+ * (`ServerDirectCommandMsg`), which is deliberately not a member here.
  */
-export type DashboardP2PMessageKind = 'ping' | 'pong' | 'status_report' | 'status_event' | 'p2p_evicted' | 'command' | 'command_result' | 'command_result_chunk' | 'screenshot_start' | 'screenshot_stop' | 'pty_input' | 'pty_resize';
+export type ServerToDaemonWsMsg = ServerToDaemonControlType;
+/** P2P signaling relayed through the server WS — the `p2p_`/`mesh_p2p_` spellings the wire actually uses. */
+export type P2PSignalingWsMsg = P2PSignalType | MeshP2PSignalType;
+/** Every dashboard↔daemon P2P DataChannel JSON kind, both directions (see protocol/dashboard-daemon-p2p.ts). */
+export type DashboardP2PMessageKind = DashboardToDaemonP2PType | DaemonToDashboardP2PType;
 export declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
 export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
-export declare function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg;
-export declare function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg;
+export declare const isDaemonToServerWsMsg: (value: unknown) => value is DaemonToServerWsMsg;
+export declare const isServerToDaemonWsMsg: (value: unknown) => value is ServerToDaemonWsMsg;
 /**
  * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to
  * the daemon for client-side enforcement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.33",
+  "version": "1.0.60-rc.35",
   "description": "ADHDev mesh-shared — pure mesh/git status normalizers shared by daemon-core and web-core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -29,3 +29,13 @@ export * from './rpc-chunking'
 export * from './semver-compare'
 export * from './ws-protocol'
 export * from './interactive-prompt-constants'
+export * from './session-status'
+export * from './mesh-vocabulary'
+export * from './outbound-message'
+export * from './worker-protocol'
+export * from './protocol'
+export * from './turn-evidence'
+export * from './session-launch'
+export * from './turn-ipc'
+export * from './path-ownership'
+export * from './mission-brief'

package/src/mesh-tool-names.ts

@@ -69,7 +69,6 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_record_note',
     'mesh_forget_note',
     'mesh_reconcile_ledger',
-    'mesh_requeue_held_events',
     'mesh_mission_upsert',
     'mesh_mission_list',
     'mesh_review_inbox',

package/src/mesh-vocabulary.ts

@@ -0,0 +1,98 @@
+/**
+ * mesh-vocabulary — the ONE declaration of every mesh enum.
+ *
+ * Wiring-unification Phase A3 (docs/design/2026-09-23-wiring-unification.md).
+ *
+ * Before this file `MeshTaskStatus` was declared twice in daemon-core with
+ * different members (one carried `in_progress`, which no task row ever held),
+ * a third time in `repo-mesh-types.ts`, and loosened to `| string` in web-core;
+ * the MCP tool schemas hand-copied the task-mode list six times. Every enum a
+ * mesh tool, ledger row, queue entry or dashboard view branches on is declared
+ * here once, as a `const` tuple, and the type is derived from it. JSON-schema
+ * producers use `enumOf()` so the published schema cannot drift from the code.
+ *
+ * `MeshTaskDifficulty` / `MESH_TASK_DIFFICULTIES` already live in
+ * ./brain-routing.ts and are re-exported here for one-stop discovery.
+ */
+
+export { MESH_TASK_DIFFICULTIES, type MeshTaskDifficulty } from './brain-routing'
+
+export const MESH_TASK_STATUSES = ['pending', 'assigned', 'completed', 'failed', 'cancelled'] as const
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number]
+
+export const MESH_TERMINAL_TASK_STATUSES = ['completed', 'failed', 'cancelled'] as const
+export type MeshTerminalTaskStatus = typeof MESH_TERMINAL_TASK_STATUSES[number]
+
+export const MESH_TASK_MODES = ['code_change', 'validation', 'live_debug_readonly', 'launch_app', 'convergence'] as const
+export type MeshTaskMode = typeof MESH_TASK_MODES[number]
+
+export const MESH_TASK_PRIORITIES = ['low', 'normal', 'high'] as const
+export type MeshTaskPriority = typeof MESH_TASK_PRIORITIES[number]
+
+export const MESH_THINKING_LEVELS = ['low', 'medium', 'high'] as const
+export type MeshThinkingLevel = typeof MESH_THINKING_LEVELS[number]
+
+/**
+ * How a message is delivered to a session that may be busy.
+ *
+ *   'when_idle'  — DEFAULT. Never disturbs a running turn; a busy session's task
+ *                  is queued and auto-delivered on its next idle transition.
+ *   'interrupt'  — Abort the in-flight turn (the provider's own stop control),
+ *                  then deliver once the session settles to idle. The name is
+ *                  deliberately blunt: the unfinished work is LOST. `immediate`
+ *                  was rejected as a name because it reads like a gentle overlay.
+ */
+export const MESH_DELIVERY_MODES = ['when_idle', 'interrupt'] as const
+export type MeshDeliveryMode = typeof MESH_DELIVERY_MODES[number]
+
+/**
+ * What to do with a node's sessions when the node is removed or a MAGI fan-out
+ * settles. Declared here so daemon-core (`RepoMeshSessionCleanupMode`), the
+ * web dashboard picker and the MCP schemas all read one list.
+ */
+export const MESH_SESSION_CLEANUP_MODES = ['preserve', 'stop', 'delete_stopped', 'stop_and_delete'] as const
+export type MeshSessionCleanupMode = typeof MESH_SESSION_CLEANUP_MODES[number]
+
+/** Outcome a delegated worker may report through `report_completion`. */
+export const WORKER_REPORT_OUTCOMES = ['completed', 'blocked', 'failed'] as const
+export type WorkerReportOutcome = typeof WORKER_REPORT_OUTCOMES[number]
+
+/** Final branch state a worker reports (see coordinator convergence rules). */
+export const WORKER_BRANCH_STATES = [
+    'merged_to_main',
+    'pushed_feature_branch_needs_merge',
+    'blocked_review',
+    'cleanup_candidate',
+    'not_mergeable',
+] as const
+export type WorkerBranchState = typeof WORKER_BRANCH_STATES[number]
+
+function makeGuard<T extends readonly string[]>(values: T): (value: unknown) => value is T[number] {
+    const set: ReadonlySet<string> = new Set(values)
+    return (value: unknown): value is T[number] => typeof value === 'string' && set.has(value)
+}
+
+export const isMeshTaskStatus = makeGuard(MESH_TASK_STATUSES)
+export const isMeshTerminalTaskStatus = makeGuard(MESH_TERMINAL_TASK_STATUSES)
+export const isMeshTaskMode = makeGuard(MESH_TASK_MODES)
+export const isMeshTaskPriority = makeGuard(MESH_TASK_PRIORITIES)
+export const isMeshThinkingLevel = makeGuard(MESH_THINKING_LEVELS)
+export const isMeshDeliveryMode = makeGuard(MESH_DELIVERY_MODES)
+export const isMeshSessionCleanupMode = makeGuard(MESH_SESSION_CLEANUP_MODES)
+export const isWorkerReportOutcome = makeGuard(WORKER_REPORT_OUTCOMES)
+export const isWorkerBranchState = makeGuard(WORKER_BRANCH_STATES)
+
+/**
+ * JSON-schema fragment for a string enum, derived from the tuple. Use this in
+ * every MCP tool schema instead of spelling the member list again.
+ */
+export function enumOf<T extends readonly string[]>(
+    values: T,
+    description?: string,
+): { type: 'string'; enum: T[number][]; description?: string } {
+    return {
+        type: 'string',
+        enum: [...values] as T[number][],
+        ...(description ? { description } : {}),
+    }
+}

package/src/mission-brief.ts

@@ -0,0 +1,153 @@
+/**
+ * mission-brief — the goal/constraints/done-criteria/handoff a coordinator
+ * attaches to a mission at `mesh_mission_upsert` time, and the deterministic
+ * rendering of that brief into a dispatched task's worker-protocol footer
+ * (wiring-unification Phase H2, `docs/design/2026-09-23-wiring-unification.md`
+ * §7c).
+ *
+ * `mesh_mission_upsert` today carries only a free-text `goal` string — no
+ * structured constraints, done-criteria or handoff notes, and nothing from a
+ * mission ever reaches a dispatched worker's task body. This module is the
+ * pure, dependency-free core: a normalized `MissionBrief` shape with length
+ * caps (mirrors `report_completion.summary`'s "prefer specifics" discipline —
+ * a brief is meant to be read by a worker mid-task, not skimmed by a human),
+ * and a deterministic Markdown renderer capped at 1,200 chars so a mission
+ * with many/long fields cannot blow a dispatched task's token budget.
+ *
+ * This module does NOT decide where the rendered block is inserted (that is
+ * `worker-protocol.ts`'s `renderWorkerProtocolFooter`, which places it above
+ * the marker line — see that file), and does NOT touch storage (H2's proposal
+ * keeps `mesh_missions` as the row source; this is the shape callers upsert
+ * into/read out of that row's `goal`/new `brief` columns).
+ */
+
+/** Per-field caps. Generous enough for real content, small enough that four
+ *  arrays of them cannot silently balloon a rendered block past the render cap. */
+const GOAL_MAX = 500
+const LIST_ITEM_MAX = 200
+const LIST_MAX_ITEMS = 12
+
+/** Total rendered-block cap (design doc H2 "bounded payload" discipline, mirrored from `listMeshMissionsForTool`). */
+export const MISSION_BRIEF_RENDER_MAX_CHARS = 1200
+
+export interface MissionBrief {
+    /** What this mission is trying to accomplish. Required — an empty brief is not meaningful. */
+    goal: string
+    /** Hard constraints a worker must respect (e.g. "do not touch daemon-core", "no npm install"). */
+    constraints?: string[]
+    /** How to know the mission is actually done. */
+    doneCriteria?: string[]
+    /** Standing notes for whoever picks up mission work next. */
+    handoffNotes?: string[]
+    /** Paths this mission's tasks collectively own (H1 integration point — surfaced, not enforced here). */
+    ownedPaths?: string[]
+}
+
+export interface NormalizeMissionBriefResult {
+    /** `null` when the input had no usable `goal` — callers should treat this as "no brief", not an empty one. */
+    readonly brief: MissionBrief | null
+    /** What was trimmed/dropped, for a caller that wants to warn (never thrown). */
+    readonly truncated: ReadonlyArray<{ field: string; reason: 'field_too_long' | 'list_too_long' | 'item_too_long' }>
+}
+
+function truncateString(value: string, max: number): string {
+    if (value.length <= max) return value
+    return `${value.slice(0, max - 1).trimEnd()}…`
+}
+
+function normalizeStringList(
+    value: unknown,
+    field: string,
+    truncated: Array<{ field: string; reason: 'field_too_long' | 'list_too_long' | 'item_too_long' }>,
+): string[] | undefined {
+    if (value === undefined || value === null) return undefined
+    if (!Array.isArray(value)) return undefined
+    const items: string[] = []
+    let itemTruncated = false
+    for (const raw of value) {
+        if (typeof raw !== 'string') continue
+        const trimmed = raw.trim()
+        if (!trimmed) continue
+        if (trimmed.length > LIST_ITEM_MAX) itemTruncated = true
+        items.push(truncateString(trimmed, LIST_ITEM_MAX))
+    }
+    if (itemTruncated) truncated.push({ field, reason: 'item_too_long' })
+    if (items.length > LIST_MAX_ITEMS) {
+        truncated.push({ field, reason: 'list_too_long' })
+        return items.slice(0, LIST_MAX_ITEMS)
+    }
+    return items.length > 0 ? items : undefined
+}
+
+/**
+ * Normalize a caller-supplied brief. Never throws. Returns `brief: null` when
+ * there is no non-empty `goal` — the caller (e.g. `mesh_mission_upsert`'s
+ * handler) decides whether that means "reject" or "no brief attached", this
+ * module only normalizes shape.
+ */
+export function normalizeMissionBrief(input: unknown): NormalizeMissionBriefResult {
+    const truncated: Array<{ field: string; reason: 'field_too_long' | 'list_too_long' | 'item_too_long' }> = []
+    if (!input || typeof input !== 'object') {
+        return { brief: null, truncated }
+    }
+    const raw = input as Record<string, unknown>
+
+    const rawGoal = typeof raw.goal === 'string' ? raw.goal.trim() : ''
+    if (!rawGoal) {
+        return { brief: null, truncated }
+    }
+    if (rawGoal.length > GOAL_MAX) truncated.push({ field: 'goal', reason: 'field_too_long' })
+    const goal = truncateString(rawGoal, GOAL_MAX)
+
+    const constraints = normalizeStringList(raw.constraints, 'constraints', truncated)
+    const doneCriteria = normalizeStringList(raw.doneCriteria ?? raw.done_criteria, 'doneCriteria', truncated)
+    const handoffNotes = normalizeStringList(raw.handoffNotes ?? raw.handoff_notes, 'handoffNotes', truncated)
+    const ownedPaths = normalizeStringList(raw.ownedPaths ?? raw.owned_paths, 'ownedPaths', truncated)
+
+    const brief: MissionBrief = { goal }
+    if (constraints) brief.constraints = constraints
+    if (doneCriteria) brief.doneCriteria = doneCriteria
+    if (handoffNotes) brief.handoffNotes = handoffNotes
+    if (ownedPaths) brief.ownedPaths = ownedPaths
+
+    return { brief, truncated }
+}
+
+function renderList(heading: string, items: readonly string[] | undefined): string[] {
+    if (!items || items.length === 0) return []
+    return [`${heading}:`, ...items.map(item => `- ${item}`)]
+}
+
+/**
+ * Deterministic Markdown rendering of a brief, capped at
+ * `MISSION_BRIEF_RENDER_MAX_CHARS`. Same field order every call (goal,
+ * constraints, done criteria, owned paths, handoff notes) so a snapshot test
+ * or a worker reading two renders of the same brief sees no drift. If the
+ * assembled text exceeds the cap, trailing sections are dropped whole (never
+ * mid-line) until it fits, and a final `(brief truncated)` marker is appended
+ * — a worker should never receive a block cut off mid-sentence.
+ */
+export function renderMissionBriefBlock(brief: MissionBrief): string {
+    const sections: string[] = [`Mission goal: ${brief.goal}`]
+    sections.push(...renderList('Constraints', brief.constraints))
+    sections.push(...renderList('Done when', brief.doneCriteria))
+    sections.push(...renderList('Owned paths', brief.ownedPaths))
+    sections.push(...renderList('Handoff notes', brief.handoffNotes))
+
+    const full = sections.join('\n')
+    if (full.length <= MISSION_BRIEF_RENDER_MAX_CHARS) return full
+
+    // Drop whole lines from the end until it fits, then append the marker
+    // (itself budgeted into the cap so the final string never exceeds it).
+    const marker = '\n(brief truncated)'
+    const budget = MISSION_BRIEF_RENDER_MAX_CHARS - marker.length
+    const lines = full.split('\n')
+    let acc = ''
+    for (const line of lines) {
+        const next = acc ? `${acc}\n${line}` : line
+        if (next.length > budget) break
+        acc = next
+    }
+    if (!acc) acc = truncateString(lines[0] ?? '', Math.max(budget, 0))
+    return `${acc}${marker}`
+}