@adhdev/mesh-shared 1.0.60-rc.6 → 1.0.60-rc.60

package/dist/types.d.ts

@@ -136,4 +136,15 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null;
     lastActivityAt?: string | null;
     isCached?: boolean;
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: {
+        delivered: boolean;
+        reason?: string;
+    };
 }

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,50 +1,80 @@
 /**
- * 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.
+ * 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.
  */
-/** 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'
+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;
 /**
- * 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.
+ * 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.
  */
- | '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'
+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 const isDaemonToServerWsMsg: (value: unknown) => value is DaemonToServerWsMsg;
+export declare const isServerToDaemonWsMsg: (value: unknown) => value is ServerToDaemonWsMsg;
 /**
- * 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.
+ * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to
+ * the daemon for client-side enforcement.
+ *
+ * WHY THIS EXISTS: the wire spelling is `maxP2Pconnections` (lowercase `c`),
+ * inherited from `PlanLimits` in the proprietary server's plan-limits.ts. The
+ * daemon-cloud consumer independently declared the same field as
+ * `maxP2PConnections` (capital `C`) and assigned it from a `payload as any`
+ * cast — so the two spellings NEVER met under a type, TypeScript had nothing
+ * to compare, and the limit arrived as `undefined` at every comparison site.
+ * `undefined !== -1` passes the "is it unlimited?" guard, then every
+ * `count >= undefined` is false: enforcement silently degraded to unlimited on
+ * all plans, in production, for months.
+ *
+ * The lesson is NOT "pick a spelling" — it is that a cross-package wire
+ * contract asserted by hand on both ends with an `any` in between cannot fail
+ * loudly. Both producer (server) and consumer (daemon-cloud) must now import
+ * THIS symbol, so a rename breaks the build on both sides instead of silently
+ * disabling a paid-plan limit. Use `normalizeAuthOkLimits()` at the parse
+ * boundary; never re-spell these fields locally.
  */
- | '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';
+export interface AuthOkPlanLimits {
+    /** P2P concurrent connection count (-1 = unlimited). WIRE SPELLING — lowercase `c`. */
+    maxP2Pconnections: number;
+    /** Screenshot send interval floor (seconds). 0 = real-time. */
+    screenshotIntervalSeconds: number;
+    /** Daily screenshot usage budget (minutes). -1 = unlimited. */
+    dailyScreenshotMinutes: number;
+    /** Max connectable machines/daemons (-1 = unlimited). */
+    maxMachines: number;
+}
 /**
- * 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).
+ * Parse-boundary normalizer for `auth_ok.payload.limits`.
+ *
+ * Returns `null` when the payload carries no usable limits object, so callers
+ * keep their existing "no limits known yet" branch. Individual non-numeric or
+ * missing fields fall back to the UNLIMITED sentinel (-1) for count-style
+ * limits and 0 for the interval floor, matching how each consumer already
+ * treats "no constraint" — a malformed field must never be coerced to a
+ * MORE restrictive value than the server intended, or a server-side schema
+ * change would start throttling paying users.
+ *
+ * Accepts the capital-`C` misspelling as an input alias ONLY so a daemon
+ * talking to a mixed-version fleet cannot regress; output is always the
+ * canonical wire spelling.
  */
-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 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 function normalizeAuthOkLimits(raw: unknown): AuthOkPlanLimits | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.6",
+  "version": "1.0.60-rc.60",
   "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/brain-routing.ts

@@ -66,7 +66,7 @@ export function isMeshTaskDifficulty(value: unknown): value is MeshTaskDifficult
  *      a value that should never have been stamped provider-blind.
  *
  *   2. IT FOUGHT THE SLOTS. Operators express model choice per node via
- *      capability slots (`mesh_node_slots_set`), which know the provider. A
+ *      capability slots (`mesh_node_slots` action "set"), which know the provider. A
  *      mesh-wide preset that also picks a model duplicated that decision from a
  *      position with strictly less information, and needed the modelSource
  *      ('explicit' vs 'preset') precedence machinery plus a fail-closed
@@ -112,7 +112,7 @@ export function normalizeDifficultyBrainMap(raw: unknown): DifficultyBrainMap {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Node capability slots (ORCHESTRATION_NODE_SLOTS.md)
+// Node capability slots (node capability slots design, 2026-07-09)
 //
 // A node's "Preferred AI tools" list is redefined as an ordered array of
 // capability slots. Each slot bundles what used to be scattered across
@@ -252,7 +252,7 @@ export function deriveSlotsFromLegacy(input: {
  * The reverse direction of deriveSlotsFromLegacy: derive the legacy
  * `providerPriority` order from capability slots — each slot's provider, in
  * first-appearance order, de-duplicated. Slot order = preference is the settled
- * slots semantics (ORCHESTRATION_NODE_SLOTS.md), so this is what readers of the
+ * slots semantics (node capability slots design, 2026-07-09), so this is what readers of the
  * legacy `policy.providerPriority` field must fall back to when a node declares
  * slots but no explicit providerPriority (otherwise such a node reads as
  * unlaunchable even though its slots fully determine the preference order).

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/magi.ts

@@ -59,7 +59,7 @@
  * already pinned the (node, provider) target, so any difficulty would be inert at best
  * and would fight the panel's own slot selection at worst. To change how hard a
  * replica thinks or how much parallelism a node grants, edit that NODE's capability
- * slots (`mesh_node_slots_set`); it is a different axis, on purpose.
+ * slots (`mesh_node_slots` action "set"); it is a different axis, on purpose.
  *
  * Unknown keys are dropped rather than rejected, so slots written by another version
  * stay readable. Write paths pair the normalizer with

package/src/mesh-tool-names.ts

@@ -28,9 +28,7 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_view_queue',
     // GRAPH-ORCHESTRATION Phase E — the coordinator gate + graph view surface.
     'mesh_graph_view',
-    'mesh_graph_gate_claim',
-    'mesh_graph_gate_release',
-    'mesh_graph_gate_abandon',
+    'mesh_graph_gate',
     'mesh_graph_node_patch',
     'mesh_queue_cancel',
     'mesh_queue_requeue',
@@ -48,7 +46,6 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_approve',
     'mesh_answer_question',
     'mesh_list_pending_approvals',
-    'mesh_plan_onboarding',
     'mesh_create',
     'mesh_add_node',
     'mesh_clone_node',
@@ -56,35 +53,84 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_cleanup_worktree_nodes',
     'mesh_refine_node',
     'mesh_refine_batch',
-    'mesh_refine_config',
-    'mesh_change_impact_config',
+    'mesh_config',
     'mesh_init',
-    'mesh_reinit',
-    'mesh_write_mesh_json_config',
     'mesh_refine_plan',
     'mesh_cleanup_sessions',
-    'mesh_prune_stale_direct',
     'mesh_task_history',
     'mesh_ledger_query',
-    'mesh_record_note',
-    'mesh_forget_note',
+    'mesh_note',
     'mesh_reconcile_ledger',
-    'mesh_requeue_held_events',
     'mesh_mission_upsert',
     'mesh_mission_list',
     'mesh_review_inbox',
     'mesh_magi_review',
     'mesh_magi_collect',
-    'mesh_magi_kind_panel_set',
-    'mesh_magi_kind_panel_list',
-    'mesh_node_slots_set',
-    'mesh_node_slots_list',
-    'mesh_node_slots_propose',
-    'mesh_coordinator_prompt_append_get',
-    'mesh_coordinator_prompt_append_set',
+    'mesh_magi_kind_panel',
+    'mesh_node_slots',
+    'mesh_coordinator_prompt_append',
 ] as const;
 
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];
 
 /** The count the `NN tools` barrel doc comments and consistency test assert against. */
 export const CANONICAL_MESH_TOOL_COUNT = CANONICAL_MESH_TOOL_NAMES.length;
+
+/**
+ * Tool names retired by the 2026-09-26 tool-surface consolidation (60 → 48).
+ * Every capability behind them is still reachable: each retired name maps to the
+ * merged tool plus the discriminator argument that selects the same behaviour.
+ *
+ * mcp-server answers a call to a retired name with an error naming the
+ * replacement (it does NOT forward silently — a coordinator running an old
+ * prompt must learn the new spelling), and the daemon-core coordinator prompt
+ * test asserts none of these names is advertised anywhere in the prompt.
+ *
+ * `args` is the discriminator to add; every other argument keeps its name.
+ * `note` covers the one rename where an argument moved (the old
+ * `mesh_graph_gate_claim({ extend_seconds })` extend-only mode).
+ */
+export const RETIRED_MESH_TOOLS: Readonly<Record<string, {
+    readonly tool: CanonicalMeshToolName;
+    readonly args: Readonly<Record<string, string>>;
+    readonly note?: string;
+}>> = {
+    mesh_graph_gate_claim: {
+        tool: 'mesh_graph_gate',
+        args: { action: 'claim' },
+        note: 'The extend-only form (claim with extend_seconds) is now action: "extend" with the same extend_seconds.',
+    },
+    mesh_graph_gate_release: { tool: 'mesh_graph_gate', args: { action: 'release' } },
+    mesh_graph_gate_abandon: { tool: 'mesh_graph_gate', args: { action: 'abandon' } },
+    // Never a published tool (it is the daemon command behind the extend verb),
+    // but an older gate-expiry notice told coordinators to call it by this name.
+    mesh_graph_gate_extend: { tool: 'mesh_graph_gate', args: { action: 'extend' } },
+    mesh_node_slots_set: { tool: 'mesh_node_slots', args: { action: 'set' } },
+    mesh_node_slots_list: { tool: 'mesh_node_slots', args: { action: 'list' } },
+    mesh_node_slots_propose: { tool: 'mesh_node_slots', args: { action: 'propose' } },
+    mesh_magi_kind_panel_set: { tool: 'mesh_magi_kind_panel', args: { action: 'set' } },
+    mesh_magi_kind_panel_list: { tool: 'mesh_magi_kind_panel', args: { action: 'list' } },
+    mesh_coordinator_prompt_append_get: { tool: 'mesh_coordinator_prompt_append', args: { action: 'get' } },
+    mesh_coordinator_prompt_append_set: { tool: 'mesh_coordinator_prompt_append', args: { action: 'set' } },
+    mesh_record_note: { tool: 'mesh_note', args: { action: 'record' } },
+    mesh_forget_note: { tool: 'mesh_note', args: { action: 'forget' } },
+    mesh_reinit: { tool: 'mesh_init', args: { mode: 'reinit' } },
+    mesh_refine_config: { tool: 'mesh_config', args: { kind: 'refine' } },
+    mesh_change_impact_config: { tool: 'mesh_config', args: { kind: 'change_impact' } },
+    mesh_write_mesh_json_config: { tool: 'mesh_config', args: { kind: 'mesh_json' } },
+    mesh_plan_onboarding: { tool: 'mesh_create', args: { mode: 'plan' } },
+    mesh_prune_stale_direct: { tool: 'mesh_cleanup_sessions', args: { mode: 'prune_stale_direct' } },
+};
+
+/**
+ * The error text for a call to a retired tool name, or null when `name` is not
+ * retired. One wording shared by every MCP mode so the redirect reads the same
+ * wherever an old prompt calls it.
+ */
+export function retiredMeshToolError(name: string): string | null {
+    const entry = Object.prototype.hasOwnProperty.call(RETIRED_MESH_TOOLS, name) ? RETIRED_MESH_TOOLS[name] : undefined;
+    if (!entry) return null;
+    const discriminator = Object.entries(entry.args).map(([k, v]) => `${k}: "${v}"`).join(', ');
+    return `Tool "${name}" was retired (merged into ${entry.tool}). Call ${entry.tool} with ${discriminator} and the same other arguments.`
+        + (entry.note ? ` ${entry.note}` : '');
+}

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}`
+}