@adhdev/mesh-shared 1.0.82-rc.4 → 1.0.82-rc.41

package/src/mesh-tool-names.ts

@@ -27,7 +27,9 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_enqueue_task',
     'mesh_view_queue',
     'mesh_queue_cancel',
+    'mesh_direct_cancel',
     'mesh_queue_requeue',
+    'mesh_queue_revise',
     'mesh_send_task',
     'mesh_read_chat',
     'mesh_read_debug',
@@ -44,8 +46,11 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_list_pending_approvals',
     'mesh_create',
     'mesh_add_node',
+    'mesh_reattach_source_parent',
+    'mesh_attach_remote',
     'mesh_clone_node',
     'mesh_remove_node',
+    'mesh_retry_node_bootstrap',
     'mesh_cleanup_worktree_nodes',
     'mesh_refine_node',
     'mesh_refine_batch',
@@ -62,8 +67,19 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_reconcile_ledger',
     'mesh_mission_upsert',
     'mesh_mission_list',
+    'mesh_mission_git_eval',
+    'mesh_release_upsert',
+    'mesh_release_scope',
+    'mesh_release_list',
+    'mesh_release_record_deploy',
+    'mesh_release_changelog_draft',
     'mesh_review_inbox',
     'mesh_node_slots',
+    'driver_list',
+    'driver_describe',
+    'artifact_list',
+    'artifact_read',
+    'artifact_register',
 ] as const;
 
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];

package/src/mesh-vocabulary.ts

@@ -17,10 +17,12 @@
 
 export { MESH_TASK_DIFFICULTIES, type MeshTaskDifficulty } from './brain-routing'
 
-export const MESH_TASK_STATUSES = ['pending', 'assigned', 'completed', 'failed', 'cancelled'] as const
+/** `blocked` ends a worker attempt pending external follow-up; only completed satisfies dependencies.
+ * Branch convergence (including blocked_review) remains an independent axis. */
+export const MESH_TASK_STATUSES = ['pending', 'assigned', 'completed', 'blocked', 'failed', 'cancelled'] as const
 export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number]
 
-export const MESH_TERMINAL_TASK_STATUSES = ['completed', 'failed', 'cancelled'] as const
+export const MESH_TERMINAL_TASK_STATUSES = ['completed', 'blocked', '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
@@ -56,6 +58,14 @@ export type MeshSessionCleanupMode = typeof MESH_SESSION_CLEANUP_MODES[number]
 export const WORKER_REPORT_OUTCOMES = ['completed', 'blocked', 'failed'] as const
 export type WorkerReportOutcome = typeof WORKER_REPORT_OUTCOMES[number]
 
+/**
+ * Hard cap on a `report_completion` summary (characters, after trim). Over-limit
+ * summaries are REJECTED, never truncated. Declared once so the daemon validator
+ * and the mcp-server's pre-send check (which keeps an over-limit report out of the
+ * durable outbox) cannot drift apart.
+ */
+export const WORKER_REPORT_SUMMARY_MAX_CHARS = 8_000
+
 /** Final branch state a worker reports (see coordinator convergence rules). */
 export const WORKER_BRANCH_STATES = [
     'merged_to_main',

package/src/mission-git-state.ts

@@ -0,0 +1,112 @@
+/**
+ * mission-git-state — types and the pure aggregation for "did this mission's
+ * referenced commits/branches land on the default branch?"
+ * (docs/design/2026-11-01-mission-git-refs.md §3).
+ *
+ * The facts come from the daemon opening git objects itself (never from
+ * commit-message text, branch-name similarity or worker prose). `landed` means
+ * ONLY "the referenced changes are on the base"; it never implies live
+ * acceptance, mission completion or that remaining items are done, and it is
+ * never used to change a mission's status.
+ *
+ * Dependency-free leaf: plain data in, plain data out.
+ */
+
+/** Per-ref verdict. `unknown` is never folded into `not_contained` nor promoted to `contained_*`. */
+export const MISSION_REF_GIT_STATUSES = ['contained_ancestor', 'contained_patch_equivalent', 'not_contained', 'unknown'] as const
+export type MissionRefGitStatus = typeof MISSION_REF_GIT_STATUSES[number]
+
+/** How a contained verdict was reached. */
+export const MISSION_REF_GIT_METHODS = ['ancestry', 'cherry', 'residual_patch'] as const
+export type MissionRefGitMethod = typeof MISSION_REF_GIT_METHODS[number]
+
+/** Mission-level projection. */
+export const MISSION_GIT_STATES = ['no_refs', 'landed', 'partial', 'not_landed', 'unknown'] as const
+export type MissionGitStateValue = typeof MISSION_GIT_STATES[number]
+
+export function isMissionRefContained(status: MissionRefGitStatus): boolean {
+    return status === 'contained_ancestor' || status === 'contained_patch_equivalent'
+}
+
+/** Why a ref is `unknown` (detail.unknownReason). Free-form strings are tolerated on read. */
+export type MissionRefUnknownReason =
+    | 'object_missing'
+    | 'shallow'
+    | 'undeterminable'
+    | 'base_missing'
+    | 'branch_not_found'
+    | 'base_branch_ref'
+    | 'gitlink_undeterminable'
+    | 'merge_tree_failed'
+    | 'node_offline'
+    | 'no_repo'
+    | 'budget'
+    | 'not_a_git_ref'
+
+export interface MissionRefGitDetail {
+    reasonCode?: string
+    unknownReason?: MissionRefUnknownReason | string
+    /** `modified_since_landing_possible`: main later touched the same lines — shown as a hint, not a verdict. */
+    note?: string
+    nodeId?: string
+    residualPatchId?: string
+    ahead?: number
+    behind?: number
+}
+
+/** One stored per-ref evaluation (a row of `mesh_mission_ref_evals`). */
+export interface MissionRefGitEval {
+    itemId: string
+    /** `kind:repo:value` (normalized, lower-case SHA). */
+    refKey: string
+    kind: 'commit' | 'branch'
+    value: string
+    repo?: string
+    /** Branch refs: the SHA the name resolved to at first evaluation (re-evaluation keeps using it). */
+    pinnedSha?: string
+    baseRef: string
+    baseSha?: string
+    status: MissionRefGitStatus
+    method?: MissionRefGitMethod
+    detail?: MissionRefGitDetail
+    evaluatedAt: string
+}
+
+export interface MissionGitState {
+    missionId: string
+    state: MissionGitStateValue
+    /** `partial` only: some refs were `unknown` (not just `not_contained`). */
+    partialUnknown: boolean
+    counts: { total: number; contained: number; notContained: number; unknown: number }
+    /** Base the newest evaluation compared against. */
+    baseRef?: string
+    baseSha?: string
+    /** Oldest `evaluatedAt` among the refs (the freshness floor). */
+    evaluatedAt?: string
+    /** True when no row exists yet / the rows are older than the TTL — a refresh was (or can be) triggered. */
+    stale: boolean
+    refs: MissionRefGitEval[]
+}
+
+/**
+ * Aggregate per-ref statuses (design §3.3):
+ *  - none → `no_refs`; all contained → `landed`; some contained → `partial`
+ *    (`partialUnknown` when any of the rest is `unknown`);
+ *  - none contained: all `not_contained` → `not_landed`, otherwise `unknown`.
+ */
+export function aggregateMissionGitState(statuses: readonly MissionRefGitStatus[]): {
+    state: MissionGitStateValue
+    partialUnknown: boolean
+    counts: MissionGitState['counts']
+} {
+    const total = statuses.length
+    const contained = statuses.filter(isMissionRefContained).length
+    const notContained = statuses.filter(s => s === 'not_contained').length
+    const unknown = statuses.filter(s => s === 'unknown').length
+    const counts = { total, contained, notContained, unknown }
+    if (total === 0) return { state: 'no_refs', partialUnknown: false, counts }
+    if (contained === total) return { state: 'landed', partialUnknown: false, counts }
+    if (contained > 0) return { state: 'partial', partialUnknown: unknown > 0, counts }
+    if (notContained === total) return { state: 'not_landed', partialUnknown: false, counts }
+    return { state: 'unknown', partialUnknown: false, counts }
+}

package/src/mission-items.ts

@@ -0,0 +1,421 @@
+/**
+ * mission-items — structured mission records: the item kinds a mission carries
+ * (remaining work, live checks, owner decisions, evidence), their normalization
+ * and limits, dedupe-key derivation and the close outcome enum
+ * (docs/design/2026-10-28-structured-missions-and-owner-decisions.md §4, §5).
+ *
+ * Philosophy (owner 2026-10-28, design §0): NEVER reject for size or shape —
+ * over-long text is truncated, extra refs are dropped, unusable items are
+ * reported per-item. The only hard rule lives elsewhere (the daemon): a
+ * coordinator or worker can never ANSWER a decision, so `answer`/`delivery`
+ * are stripped from every caller-supplied `decision` here.
+ *
+ * Dependency-free leaf: pure functions over plain data, no storage.
+ */
+
+export const MISSION_ITEM_KINDS = ['remaining', 'live_check', 'decision', 'evidence'] as const
+export type MissionItemKind = typeof MISSION_ITEM_KINDS[number]
+
+export const MISSION_ITEM_STATES = ['open', 'done', 'failed', 'dropped', 'moved', 'answered', 'expired', 'withdrawn', 'superseded'] as const
+export type MissionItemState = typeof MISSION_ITEM_STATES[number]
+
+/** States a coordinator/worker may SET through items_update, per kind. `answered`/`expired`/`failed` (owner live-check verdict) are daemon-owned. */
+export const COORDINATOR_SETTABLE_ITEM_STATES: Readonly<Record<MissionItemKind, readonly MissionItemState[]>> = {
+    remaining: ['open', 'done', 'dropped'],
+    live_check: ['open', 'done', 'dropped'],
+    evidence: ['open', 'done', 'dropped'],
+    decision: ['open', 'withdrawn', 'superseded'],
+}
+
+export const MISSION_OUTCOMES = ['merged', 'verified_live', 'superseded', 'not_needed', 'owner_abandoned', 'unspecified'] as const
+export type MissionOutcome = typeof MISSION_OUTCOMES[number]
+export function isMissionOutcome(value: unknown): value is MissionOutcome {
+    return typeof value === 'string' && (MISSION_OUTCOMES as readonly string[]).includes(value)
+}
+
+export const MISSION_REF_KINDS = ['commit', 'branch', 'pr', 'task', 'artifact', 'mission', 'url'] as const
+export type MissionRefKind = typeof MISSION_REF_KINDS[number]
+
+export const MISSION_LIMITS = {
+    summary: 300,
+    outcomeReason: 500,
+    itemText: 300,
+    machine: 80,
+    refs: 8,
+    refValue: 300,
+    refRepo: 120,
+    refNote: 200,
+    dedupeKey: 400,
+    question: 300,
+    context: 600,
+    options: 5,
+    optionLabel: 60,
+    optionDetail: 200,
+    /** Open items per mission before the oldest `remaining` fold into a "N more" summary item. */
+    openItemsPerMission: 200,
+    /** One event payload (serialized). */
+    eventPayloadBytes: 16 * 1024,
+    /** items_add / items_update entries honoured per call (extra entries are reported, not applied). */
+    itemsPerCall: 50,
+} as const
+
+export const MISSION_DECISION_OPTION_IDS = ['a', 'b', 'c', 'd', 'e'] as const
+export const MISSION_DECISION_URGENCIES = ['normal', 'blocking'] as const
+export type MissionDecisionUrgency = typeof MISSION_DECISION_URGENCIES[number]
+export const MISSION_DECISION_ON_DUE = ['remind', 'apply_recommended'] as const
+export type MissionDecisionOnDue = typeof MISSION_DECISION_ON_DUE[number]
+
+export interface MissionItemRef {
+    kind: MissionRefKind
+    repo?: string
+    value: string
+    note?: string
+}
+
+export interface MissionDecisionOption {
+    id: string
+    label: string
+    detail?: string
+}
+
+/** Who/where an answer came from. Written only by the daemon's (owner-side) answer path — never from tool input. */
+export interface MissionDecisionAnswer {
+    optionId?: string
+    text?: string
+    by: 'owner' | 'auto_recommended'
+    via: 'dashboard' | 'assistant' | 'push' | 'cli' | 'auto'
+    interpretedFrom?: string
+    at: string
+    ingress?: string
+}
+
+export interface MissionDecisionDelivery {
+    messageId: string
+    /**
+     * `queued`: the coordinator's input queue accepted it but has not typed it yet — the daemon
+     * confirms it against the send receipt (a daemon restart drops that queue). Daemon-written.
+     */
+    state: 'pending' | 'queued' | 'sent' | 'acked'
+    lastAttemptAt?: string
+    /** Coordinator session + funnel messageId of a `queued` delivery (receipt lookup). Daemon-written. */
+    sessionId?: string
+    wireMessageId?: string
+    /** Failed send attempts of this revision (retry backoff). Daemon-written. */
+    attempts?: number
+    /** What the coordinator is told: a first answer, a changed answer, or an undone one. Daemon-written. */
+    kind?: 'answered' | 'changed' | 'undone'
+}
+
+export interface MissionDecision {
+    question: string
+    context?: string
+    options: MissionDecisionOption[]
+    recommended?: string
+    allowFreeText: boolean
+    dueAt?: string
+    onDue: MissionDecisionOnDue
+    urgency: MissionDecisionUrgency
+    answer?: MissionDecisionAnswer
+    delivery?: MissionDecisionDelivery
+    /**
+     * Coordinator-prompt watermark (bundle B): ISO time the coordinator last "saw" this item's
+     * answer. An answered decision is shown in the coordinator prompt while this is absent or
+     * older than `answer.at` (a changed answer re-surfaces). Written only by the daemon.
+     */
+    promptAckedAt?: string
+    /** Counts answer writes (answer / change / undo); delivery messageIds are `decision:<itemId>:r<n>`. Daemon-written. */
+    answerRevision?: number
+    /** ISO time an `onDue: remind` crossing was recorded (once per dueAt). Daemon-written. */
+    remindedAt?: string
+}
+
+export interface NormalizedMissionItem {
+    kind: MissionItemKind
+    text: string
+    machine?: string
+    refs: MissionItemRef[]
+    decision?: MissionDecision
+    dedupeKey: string
+    /** Fields that were truncated/dropped — informational, never an error. */
+    truncated: string[]
+}
+
+export function truncateMissionText(value: string, max: number): string {
+    if (value.length <= max) return value
+    return `${value.slice(0, max - 1).trimEnd()}…`
+}
+
+function str(value: unknown): string {
+    return typeof value === 'string' ? value.trim() : ''
+}
+
+function collapse(value: string): string {
+    return value.replace(/\s+/g, ' ').trim()
+}
+
+export function normalizeMissionSummary(value: unknown): { value: string; truncated: boolean } | null {
+    if (typeof value !== 'string') return null
+    const text = collapse(value)
+    return { value: truncateMissionText(text, MISSION_LIMITS.summary), truncated: text.length > MISSION_LIMITS.summary }
+}
+
+export function normalizeOutcomeReason(value: unknown): { value: string; truncated: boolean } | null {
+    if (typeof value !== 'string') return null
+    const text = value.trim()
+    return { value: truncateMissionText(text, MISSION_LIMITS.outcomeReason), truncated: text.length > MISSION_LIMITS.outcomeReason }
+}
+
+/** Refs: ≤8, `{kind, repo?, value, note?}`. Unusable entries are dropped; the 9th and later are dropped. */
+export function normalizeMissionRefs(value: unknown): { refs: MissionItemRef[]; truncated: boolean } {
+    if (!Array.isArray(value)) return { refs: [], truncated: false }
+    const refs: MissionItemRef[] = []
+    let truncated = false
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue
+        const r = raw as Record<string, unknown>
+        const kind = str(r.kind)
+        const refValue = str(r.value)
+        if (!(MISSION_REF_KINDS as readonly string[]).includes(kind) || !refValue) continue
+        if (refs.length >= MISSION_LIMITS.refs) { truncated = true; break }
+        const repo = str(r.repo)
+        const note = str(r.note)
+        refs.push({
+            kind: kind as MissionRefKind,
+            ...(repo ? { repo: truncateMissionText(repo, MISSION_LIMITS.refRepo) } : {}),
+            value: truncateMissionText(refValue, MISSION_LIMITS.refValue),
+            ...(note ? { note: truncateMissionText(note, MISSION_LIMITS.refNote) } : {}),
+        })
+    }
+    return { refs, truncated }
+}
+
+function normalizeOptions(value: unknown, truncated: string[]): MissionDecisionOption[] {
+    if (!Array.isArray(value)) return []
+    const out: MissionDecisionOption[] = []
+    for (const raw of value) {
+        if (typeof raw === 'string' && raw.trim()) {
+            if (out.length >= MISSION_LIMITS.options) { truncated.push('options'); break }
+            out.push({ id: MISSION_DECISION_OPTION_IDS[out.length], label: truncateMissionText(raw.trim(), MISSION_LIMITS.optionLabel) })
+            continue
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue
+        const o = raw as Record<string, unknown>
+        const label = collapse(str(o.label))
+        if (!label) continue
+        if (out.length >= MISSION_LIMITS.options) { truncated.push('options'); break }
+        const detail = str(o.detail)
+        // Ids are positional ('a'..'e') so a caller cannot collide or invent ids.
+        out.push({
+            id: MISSION_DECISION_OPTION_IDS[out.length],
+            label: truncateMissionText(label, MISSION_LIMITS.optionLabel),
+            ...(detail ? { detail: truncateMissionText(detail, MISSION_LIMITS.optionDetail) } : {}),
+        })
+    }
+    return out
+}
+
+function normalizeDueAt(value: unknown): string | undefined {
+    if (typeof value !== 'string' || !value.trim()) return undefined
+    const ms = Date.parse(value)
+    return Number.isNaN(ms) ? undefined : new Date(ms).toISOString()
+}
+
+/**
+ * Caller-supplied decision → stored shape. `answer`/`delivery` (and any other
+ * unknown key) are DROPPED: a coordinator/worker cannot pre-answer its own
+ * question. `recommended` must name one of the options, else it is dropped.
+ */
+export function normalizeDecisionInput(raw: Record<string, unknown>, truncated: string[]): MissionDecision | null {
+    const questionSource = collapse(str(raw.question) || str(raw.text))
+    if (!questionSource) return null
+    if (questionSource.length > MISSION_LIMITS.question) truncated.push('question')
+    const question = truncateMissionText(questionSource, MISSION_LIMITS.question)
+    const contextSource = str(raw.context)
+    if (contextSource.length > MISSION_LIMITS.context) truncated.push('context')
+    const options = normalizeOptions(raw.options, truncated)
+    const recommendedRaw = str(raw.recommended)
+    const recommended = recommendedRaw && options.some(o => o.id === recommendedRaw)
+        ? recommendedRaw
+        // Also accept the option label (coordinators naturally write "recommended: Option A").
+        : options.find(o => recommendedRaw && o.label.toLowerCase() === recommendedRaw.toLowerCase())?.id
+    const dueAt = normalizeDueAt(raw.dueAt ?? raw.due_at)
+    const onDueRaw = str(raw.onDue ?? raw.on_due)
+    const urgencyRaw = str(raw.urgency)
+    const allowFreeTextRaw = raw.allowFreeText ?? raw.allow_free_text
+    return {
+        question,
+        ...(contextSource ? { context: truncateMissionText(contextSource, MISSION_LIMITS.context) } : {}),
+        options,
+        ...(recommended ? { recommended } : {}),
+        allowFreeText: typeof allowFreeTextRaw === 'boolean' ? allowFreeTextRaw : true,
+        ...(dueAt ? { dueAt } : {}),
+        // apply_recommended without a recommended option has nothing to apply — fall back to remind.
+        onDue: onDueRaw === 'apply_recommended' && recommended ? 'apply_recommended' : 'remind',
+        urgency: urgencyRaw === 'blocking' ? 'blocking' : 'normal',
+    }
+}
+
+/** Normalized text for dedupe: lower-case, whitespace-collapsed, trailing punctuation trimmed. */
+export function normalizeForDedupe(text: string): string {
+    return collapse(text).toLowerCase().replace(/[\s.!?。]+$/u, '')
+}
+
+export function deriveItemDedupeKey(kind: MissionItemKind, parts: { text?: string; machine?: string; refs?: readonly MissionItemRef[]; question?: string; explicit?: string }): string {
+    const explicit = str(parts.explicit)
+    if (explicit) return truncateMissionText(`k:${explicit}`, MISSION_LIMITS.dedupeKey)
+    if (kind === 'decision') return truncateMissionText(`decision:${normalizeForDedupe(parts.question ?? parts.text ?? '')}`, MISSION_LIMITS.dedupeKey)
+    if (kind === 'evidence') {
+        const ref = parts.refs?.[0]
+        if (ref) return truncateMissionText(`evidence:${ref.kind}:${ref.repo ?? ''}:${ref.value}`, MISSION_LIMITS.dedupeKey)
+    }
+    const machine = parts.machine ? `@${normalizeForDedupe(parts.machine)}` : ''
+    return truncateMissionText(`${kind}${machine}:${normalizeForDedupe(parts.text ?? '')}`, MISSION_LIMITS.dedupeKey)
+}
+
+/**
+ * Normalize one caller-supplied `items_add[]` entry. Returns `null` + `error`
+ * only when nothing usable remains (no text/question) — everything else is
+ * clamped, never rejected.
+ */
+export function normalizeMissionItemInput(raw: unknown): { item: NormalizedMissionItem } | { error: string } {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'item must be an object' }
+    const r = raw as Record<string, unknown>
+    const kind = str(r.kind) || 'remaining'
+    if (!(MISSION_ITEM_KINDS as readonly string[]).includes(kind)) {
+        return { error: `invalid kind '${kind}' (valid: ${MISSION_ITEM_KINDS.join(', ')})` }
+    }
+    const truncated: string[] = []
+    const { refs, truncated: refsTruncated } = normalizeMissionRefs(r.refs)
+    if (refsTruncated) truncated.push('refs')
+    const machineRaw = collapse(str(r.machine))
+    const machine = machineRaw ? truncateMissionText(machineRaw, MISSION_LIMITS.machine) : undefined
+    const explicitKey = str(r.dedupe_key ?? r.dedupeKey)
+    if (kind === 'decision') {
+        const decisionRaw = (r.decision && typeof r.decision === 'object' && !Array.isArray(r.decision) ? r.decision : r) as Record<string, unknown>
+        const decision = normalizeDecisionInput({ ...decisionRaw, question: decisionRaw.question ?? r.question ?? r.text }, truncated)
+        if (!decision) return { error: 'decision item needs a question' }
+        return {
+            item: {
+                kind,
+                text: decision.question,
+                ...(machine ? { machine } : {}),
+                refs,
+                decision,
+                dedupeKey: deriveItemDedupeKey('decision', { question: decision.question, explicit: explicitKey }),
+                truncated,
+            },
+        }
+    }
+    const textSource = collapse(str(r.text))
+    if (!textSource && !(kind === 'evidence' && refs.length > 0)) return { error: `${kind} item needs text` }
+    if (textSource.length > MISSION_LIMITS.itemText) truncated.push('text')
+    const text = truncateMissionText(textSource || `${refs[0].kind}: ${refs[0].value}`, MISSION_LIMITS.itemText)
+    return {
+        item: {
+            kind: kind as MissionItemKind,
+            text,
+            ...(machine ? { machine } : {}),
+            refs,
+            dedupeKey: deriveItemDedupeKey(kind as MissionItemKind, { text, machine, refs, explicit: explicitKey }),
+            truncated,
+        },
+    }
+}
+
+export interface MissionItemUpdateInput {
+    id: string
+    state?: MissionItemState
+    text?: string
+    machine?: string | null
+    refs?: MissionItemRef[]
+}
+
+/** Normalize one `items_update[]` entry (id required). The kind-specific state rule is applied by the daemon, which knows the stored kind. */
+export function normalizeMissionItemUpdate(raw: unknown): { update: MissionItemUpdateInput; truncated: string[] } | { error: string } {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'update must be an object' }
+    const r = raw as Record<string, unknown>
+    const id = str(r.id ?? r.item_id ?? r.itemId)
+    if (!id) return { error: 'update needs an item id' }
+    const truncated: string[] = []
+    const update: MissionItemUpdateInput = { id }
+    if (r.state !== undefined) {
+        const state = str(r.state)
+        if (!(MISSION_ITEM_STATES as readonly string[]).includes(state)) return { error: `invalid state '${state}'` }
+        update.state = state as MissionItemState
+    }
+    if (typeof r.text === 'string') {
+        const text = collapse(r.text)
+        if (text.length > MISSION_LIMITS.itemText) truncated.push('text')
+        if (text) update.text = truncateMissionText(text, MISSION_LIMITS.itemText)
+    }
+    if (r.machine === null) update.machine = null
+    else if (typeof r.machine === 'string') {
+        const machine = collapse(r.machine)
+        update.machine = machine ? truncateMissionText(machine, MISSION_LIMITS.machine) : null
+    }
+    if (r.refs !== undefined) {
+        const { refs, truncated: t } = normalizeMissionRefs(r.refs)
+        if (t) truncated.push('refs')
+        update.refs = refs
+    }
+    return { update, truncated }
+}
+
+/** Cap a serialized event payload at {@link MISSION_LIMITS.eventPayloadBytes}; over-size payloads become a stub that says so. */
+export function boundEventPayload(payload: Record<string, unknown>): string {
+    let json = JSON.stringify(payload)
+    if (json.length <= MISSION_LIMITS.eventPayloadBytes) return json
+    // Shrink the largest string fields first (the previous goal text is the usual offender).
+    const shrunk: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(payload)) {
+        shrunk[k] = typeof v === 'string' && v.length > 4000 ? `${v.slice(0, 4000)}…` : v
+    }
+    shrunk.payloadTruncated = true
+    json = JSON.stringify(shrunk)
+    if (json.length <= MISSION_LIMITS.eventPayloadBytes) return json
+    return JSON.stringify({ payloadTruncated: true, keys: Object.keys(payload).slice(0, 20) })
+}
+
+/** The carry-over mission's fixed title (design §5.1). */
+export const CARRY_OVER_MISSION_TITLE = 'Carry-over — open items from closed missions'
+/** The title earlier builds stored; existing DBs still hold it, so it keeps matching (no rename). */
+export const LEGACY_CARRY_OVER_MISSION_TITLE = '이월 — 닫힌 미션에서 넘어온 항목'
+/** Canonical goal text of a newly created carry-over mission. */
+export const CARRY_OVER_MISSION_GOAL = 'Open items carried over from closed missions, and decisions requested without a mission. Managed automatically — do not close.'
+/**
+ * THE one predicate for "is this the auto carry-over mission". The daemon's `is_carry_over`
+ * column (`isCarryOver`) is the source of truth; wire views that cannot carry the flag (older
+ * strict decoders reject unknown keys) fall back to the fixed title. Use this everywhere.
+ */
+export function isCarryOverMissionRecord(m: { isCarryOver?: boolean; title?: unknown } | null | undefined): boolean {
+    return !!m && (m.isCarryOver === true || isCarryOverMissionTitle(m.title))
+}
+/** The carry-over mission's title is fixed (the daemon ignores renames), so a title match identifies it on wire views that carry no flag. */
+export function isCarryOverMissionTitle(title: unknown): boolean {
+    if (typeof title !== 'string') return false
+    const t = title.trim()
+    return t === CARRY_OVER_MISSION_TITLE || t === LEGACY_CARRY_OVER_MISSION_TITLE
+}
+
+/** Prefix of the owner-confirmation decision a coordinator's `owner_abandoned` close creates. */
+export const OWNER_ABANDON_CONFIRM_KEY_PREFIX = 'owner-abandon-confirm:'
+
+export const OWNER_ABANDON_CONFIRM_QUESTION = "The coordinator closed this as 'owner abandoned' — correct?"
+export const OWNER_ABANDON_CONFIRM_OPTIONS = ['Correct', 'Reopen'] as const
+
+/** worker `report_completion.decisions_needed` cap. */
+export const WORKER_DECISIONS_NEEDED_MAX = 3
+/** worker `report_completion.commits` cap and shape. */
+export const WORKER_COMMITS_MAX = 20
+const SHA_RE = /^[0-9a-f]{7,64}$/i
+export function normalizeReportCommits(value: unknown): string[] | null {
+    if (!Array.isArray(value)) return null
+    const out: string[] = []
+    for (const v of value) {
+        if (typeof v !== 'string') return null
+        const sha = v.trim()
+        if (!SHA_RE.test(sha)) return null
+        if (!out.includes(sha.toLowerCase())) out.push(sha.toLowerCase())
+    }
+    return out
+}