@adhdev/mesh-shared 1.0.60-rc.7 → 1.0.60-rc.70

package/src/keyed-status-delta.ts

@@ -0,0 +1,239 @@
+/**
+ * Keyed status delta — the diff/fold pair behind the `daemon.metadata` lane
+ * (the ONE daemon→dashboard state lane; data-path audit 2026-09-29 P0-3).
+ *
+ * The daemon digests every body it would have sent, diffs it against the
+ * digest of the last body DELIVERED to a subscription, and sends only the
+ * difference: changed top-level fields, changed daemon-level `status` fields,
+ * and per-session changed fields keyed by session id, with removals explicit.
+ * An unchanged state diffs to `null` — zero bytes on the wire. The dashboard
+ * folds each delta into its held snapshot; the fold of every delta since a
+ * snapshot equals the latest snapshot (pinned by keyed-status-delta.test.ts).
+ *
+ * Pure leaf: plain objects in, plain objects out; no transport, no clock.
+ */
+
+/** A session row: identified by `id`, everything else is a field. */
+export interface KeyedStatusSession {
+    id: string
+    [field: string]: unknown
+}
+
+/** The snapshot body being diffed: top-level fields plus a `status` with a keyed session list. */
+export interface KeyedStatusBody {
+    status: { sessions: KeyedStatusSession[]; [field: string]: unknown }
+    [field: string]: unknown
+}
+
+export interface KeyedStatusDigestOptions {
+    /** Top-level keys that are never diffed (envelope identity: daemonId, …). */
+    ignoreTopLevel?: readonly string[]
+    /** `status` keys that are never diffed (in addition to `sessions`). */
+    ignoreStatus?: readonly string[]
+    /**
+     * Session fields that change on every build without meaning anything
+     * (a build-time `lastUpdated` stamp). A change to ONLY these fields is not
+     * a change; when something else changed they ride along.
+     */
+    volatileSessionFields?: readonly string[]
+}
+
+interface SessionDigest {
+    readonly value: KeyedStatusSession
+    /** Signature of every non-volatile field (fast unchanged check). */
+    readonly sig: string
+    /** Per-field signatures, computed lazily — only for sessions that changed. */
+    fieldSigs?: Map<string, string>
+}
+
+export interface KeyedStatusDigest {
+    readonly top: ReadonlyMap<string, string>
+    readonly topValues: Readonly<Record<string, unknown>>
+    readonly status: ReadonlyMap<string, string>
+    readonly statusValues: Readonly<Record<string, unknown>>
+    readonly sessions: ReadonlyMap<string, SessionDigest>
+    readonly order: readonly string[]
+    readonly volatile: ReadonlySet<string>
+}
+
+export interface KeyedStatusDelta {
+    set?: Record<string, unknown>
+    unset?: string[]
+    statusSet?: Record<string, unknown>
+    statusUnset?: string[]
+    sessions?: KeyedStatusSession[]
+    sessionUnset?: Record<string, string[]>
+    removedSessionIds?: string[]
+    sessionOrder?: string[]
+}
+
+function sig(value: unknown): string | undefined {
+    if (value === undefined) return undefined
+    try {
+        return JSON.stringify(value)
+    } catch {
+        return undefined
+    }
+}
+
+function digestFields(
+    source: Record<string, unknown>,
+    ignore: ReadonlySet<string>,
+): { sigs: Map<string, string>; values: Record<string, unknown> } {
+    const sigs = new Map<string, string>()
+    const values: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(source)) {
+        if (ignore.has(key)) continue
+        const s = sig(value)
+        if (s === undefined) continue
+        sigs.set(key, s)
+        values[key] = value
+    }
+    return { sigs, values }
+}
+
+function sessionSignature(session: KeyedStatusSession, volatile: ReadonlySet<string>): string {
+    if (volatile.size === 0) return sig(session) ?? ''
+    const stable: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(session)) {
+        if (!volatile.has(key)) stable[key] = value
+    }
+    return sig(stable) ?? ''
+}
+
+function fieldSigsOf(digest: SessionDigest): Map<string, string> {
+    if (!digest.fieldSigs) {
+        const sigs = new Map<string, string>()
+        for (const [key, value] of Object.entries(digest.value)) {
+            const s = sig(value)
+            if (s !== undefined) sigs.set(key, s)
+        }
+        digest.fieldSigs = sigs
+    }
+    return digest.fieldSigs
+}
+
+/** Digest one body. Cheap to hold: values are referenced, not copied. */
+export function digestKeyedStatus(body: KeyedStatusBody, options: KeyedStatusDigestOptions = {}): KeyedStatusDigest {
+    const volatile = new Set(options.volatileSessionFields ?? [])
+    const top = digestFields(body as Record<string, unknown>, new Set(['status', ...(options.ignoreTopLevel ?? [])]))
+    const status = digestFields(body.status, new Set(['sessions', ...(options.ignoreStatus ?? [])]))
+    const sessions = new Map<string, SessionDigest>()
+    const order: string[] = []
+    for (const session of Array.isArray(body.status?.sessions) ? body.status.sessions : []) {
+        if (!session || typeof session.id !== 'string' || !session.id) continue
+        if (sessions.has(session.id)) continue
+        sessions.set(session.id, { value: session, sig: sessionSignature(session, volatile) })
+        order.push(session.id)
+    }
+    return { top: top.sigs, topValues: top.values, status: status.sigs, statusValues: status.values, sessions, order, volatile }
+}
+
+function diffFieldMaps(
+    prev: ReadonlyMap<string, string>,
+    next: ReadonlyMap<string, string>,
+    nextValues: Readonly<Record<string, unknown>>,
+): { set?: Record<string, unknown>; unset?: string[] } {
+    let set: Record<string, unknown> | undefined
+    let unset: string[] | undefined
+    for (const [key, s] of next) {
+        if (prev.get(key) === s) continue
+        ;(set ??= {})[key] = nextValues[key]
+    }
+    for (const key of prev.keys()) {
+        if (!next.has(key)) (unset ??= []).push(key)
+    }
+    return { ...(set ? { set } : {}), ...(unset ? { unset } : {}) }
+}
+
+function sameOrder(a: readonly string[], b: readonly string[]): boolean {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false
+    return true
+}
+
+/**
+ * The difference `prev → next`, or `null` when nothing a consumer can observe
+ * changed. `prev === null` is not accepted here — a subscription with no
+ * delivered baseline gets a snapshot, not a delta.
+ */
+export function diffKeyedStatus(prev: KeyedStatusDigest, next: KeyedStatusDigest): KeyedStatusDelta | null {
+    const delta: KeyedStatusDelta = {}
+    const top = diffFieldMaps(prev.top, next.top, next.topValues)
+    if (top.set) delta.set = top.set
+    if (top.unset) delta.unset = top.unset
+    const status = diffFieldMaps(prev.status, next.status, next.statusValues)
+    if (status.set) delta.statusSet = status.set
+    if (status.unset) delta.statusUnset = status.unset
+
+    for (const [id, nextSession] of next.sessions) {
+        const prevSession = prev.sessions.get(id)
+        if (!prevSession) {
+            ;(delta.sessions ??= []).push(nextSession.value)
+            continue
+        }
+        if (prevSession.sig === nextSession.sig) continue
+        const prevSigs = fieldSigsOf(prevSession)
+        const nextSigs = fieldSigsOf(nextSession)
+        const change: KeyedStatusSession = { id }
+        let changed = false
+        for (const [key, s] of nextSigs) {
+            if (key === 'id' || prevSigs.get(key) === s) continue
+            change[key] = nextSession.value[key]
+            changed = true
+        }
+        const gone: string[] = []
+        for (const key of prevSigs.keys()) {
+            if (!nextSigs.has(key)) gone.push(key)
+        }
+        if (changed) (delta.sessions ??= []).push(change)
+        if (gone.length > 0) (delta.sessionUnset ??= {})[id] = gone
+    }
+    for (const id of prev.sessions.keys()) {
+        if (!next.sessions.has(id)) (delta.removedSessionIds ??= []).push(id)
+    }
+    if (!sameOrder(prev.order, next.order)) delta.sessionOrder = [...next.order]
+
+    return Object.keys(delta).length > 0 ? delta : null
+}
+
+/** Rebuild the full body from a held one plus a delta. Never mutates `held`. */
+export function foldKeyedStatus<T extends KeyedStatusBody>(held: T, delta: KeyedStatusDelta): T {
+    const next: Record<string, unknown> = { ...held }
+    for (const key of delta.unset ?? []) delete next[key]
+    Object.assign(next, delta.set ?? {})
+
+    const status: Record<string, unknown> = { ...held.status }
+    for (const key of delta.statusUnset ?? []) delete status[key]
+    Object.assign(status, delta.statusSet ?? {})
+
+    const byId = new Map<string, KeyedStatusSession>()
+    for (const session of held.status.sessions ?? []) byId.set(session.id, session)
+    for (const id of delta.removedSessionIds ?? []) byId.delete(id)
+    for (const change of delta.sessions ?? []) {
+        const base = byId.get(change.id)
+        byId.set(change.id, base ? { ...base, ...change } : { ...change })
+    }
+    for (const [id, keys] of Object.entries(delta.sessionUnset ?? {})) {
+        const base = byId.get(id)
+        if (!base) continue
+        const trimmed = { ...base }
+        for (const key of keys) delete trimmed[key]
+        byId.set(id, trimmed)
+    }
+    const order = delta.sessionOrder ?? (held.status.sessions ?? []).map((session) => session.id)
+    const sessions: KeyedStatusSession[] = []
+    const placed = new Set<string>()
+    for (const id of order) {
+        const session = byId.get(id)
+        if (!session || placed.has(id)) continue
+        sessions.push(session)
+        placed.add(id)
+    }
+    for (const [id, session] of byId) {
+        if (!placed.has(id)) sessions.push(session)
+    }
+    status.sessions = sessions
+    next.status = status
+    return next as T
+}

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