@adhdev/mesh-shared 1.0.82-rc.34 → 1.0.82-rc.35

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

package/src/protocol/daemon-server.ts

@@ -52,6 +52,9 @@ export const DAEMON_STATUS_EVENT_NAMES = [
     'agent:generating_completed',
     'agent:stopped',
     'monitor:no_progress',
+    // An owner decision (structured missions) needs the owner. Server-bound for the push only;
+    // the dashboard learns about decisions over P2P (`mission_decisions_list`).
+    'agent:decision_needed',
 ] as const
 export type DaemonStatusEventName = typeof DAEMON_STATUS_EVENT_NAMES[number]
 export const isDaemonStatusEventName = makeTypeGuard(DAEMON_STATUS_EVENT_NAMES)
@@ -62,6 +65,27 @@ export const isDaemonStatusEventName = makeTypeGuard(DAEMON_STATUS_EVENT_NAMES)
  * (`modalMessage`/`modalButtons`, CLAUDE.md "Push notification exception").
  * Mirror of daemon-core `DaemonStatusEventPayload`.
  */
+/**
+ * Owner-decision push payload (design §9, owner decision D1 2026-10-28). The ONLY mission text that
+ * reaches the server: the question (<=80 chars) and up to 3 option labels (<=24 chars). Never
+ * `context`, free-text answers, mission goal/summary or chat content.
+ */
+export type DecisionPushWire = {
+    meshId: string
+    missionId: string
+    itemId: string
+    question: string
+    options: Array<{ id: string; label: string }>
+    recommended?: string
+    urgency: 'normal' | 'blocking'
+    dueAt?: string
+    /** `new` = freshly asked; `remind` = a blocking decision crossed its due time. */
+    reason: 'new' | 'remind'
+}
+export const DECISION_PUSH_QUESTION_MAX = 80
+export const DECISION_PUSH_OPTION_LABEL_MAX = 24
+export const DECISION_PUSH_OPTIONS_MAX = 3
+
 export type DaemonStatusEventWirePayload = {
     event: DaemonStatusEventName
     timestamp: number
@@ -78,6 +102,8 @@ export type DaemonStatusEventWirePayload = {
     waitKind?: 'external'
     surfaceHidden?: boolean
     muted?: boolean
+    /** Present only on `agent:decision_needed`. */
+    decision?: DecisionPushWire
 }
 
 // ─── Status report (mirror of daemon-core `CloudStatusReportPayload`) ──────

package/src/turn-ipc-mission.ts

@@ -85,9 +85,43 @@ export interface MissionUpsertRequest {
      * this wire guard only checks SHAPE, not that decision.
      */
     brief?: MissionBriefWire | null
-}
-
-export interface MeshMissionRecordWire {
+    /**
+     * Structured-missions bundle A (design 2026-10-28 §5.1). Every key below is optional
+     * and ABSENT on a legacy call. `structured: true` is the caller's capability flag: the
+     * daemon only puts the new keys on the response (mission summary/outcome/version,
+     * `result`) when it is set, so an older mcp-server that never sends it keeps decoding
+     * byte-identical responses (mixed-version fleets, design §13.1).
+     */
+    structured?: boolean
+    summary?: string
+    outcome?: string
+    outcomeReason?: string
+    /** Mission id open items move to when this call closes the mission (default: the carry-over mission). */
+    carryOverTo?: string
+    /** Route to the mesh's auto-created carry-over mission instead of `id`/`title` (decision requests without a mission). `title` may then be empty. */
+    toCarryOver?: boolean
+    itemsAdd?: readonly Record<string, unknown>[]
+    itemsUpdate?: readonly Record<string, unknown>[]
+}
+
+export interface MeshMissionOpenItemCountsWire {
+    remaining: number
+    live_check: number
+    decision: number
+    evidence: number
+}
+
+/** Structured-missions fields (only with `structured: true` on the request). */
+export interface MeshMissionStructuredWire {
+    summary?: string
+    outcome?: string
+    outcomeReason?: string
+    version?: number
+    carryOver?: boolean
+    openItems?: MeshMissionOpenItemCountsWire
+}
+
+export interface MeshMissionRecordWire extends MeshMissionStructuredWire {
     id: string
     meshId: string
     title: string
@@ -99,10 +133,30 @@ export interface MeshMissionRecordWire {
 
 export interface MissionUpsertResponse {
     mission: MeshMissionRecordWire
+    /** Structured calls only: per-item results, movedItems/movedTo, restoredItems, ownerConfirmationItemId, warnings. */
+    result?: Record<string, unknown>
+}
+
+const STRUCTURED_MISSION_KEYS = ['summary', 'outcome', 'outcomeReason', 'version', 'carryOver', 'openItems'] as const
+
+function isOpenItemCountsWire(value: unknown): value is MeshMissionOpenItemCountsWire {
+    if (!isRecord(value) || !hasOnlyKeys(value, ['remaining', 'live_check', 'decision', 'evidence'])) return false
+    return (['remaining', 'live_check', 'decision', 'evidence'] as const).every((k) => isNonNegativeInt(value[k]))
+}
+
+function isStructuredMissionFields(value: Record<string, unknown>): boolean {
+    for (const k of ['summary', 'outcome', 'outcomeReason'] as const) {
+        if (value[k] !== undefined && typeof value[k] !== 'string') return false
+    }
+    if (value.version !== undefined && !isNonNegativeInt(value.version)) return false
+    if (value.carryOver !== undefined && typeof value.carryOver !== 'boolean') return false
+    if (value.openItems !== undefined && !isOpenItemCountsWire(value.openItems)) return false
+    return true
 }
 
 function isMeshMissionRecordWire(value: unknown): value is MeshMissionRecordWire {
-    if (!isRecord(value) || !hasOnlyKeys(value, ['id', 'meshId', 'title', 'goal', 'status', 'brief'])) return false
+    if (!isRecord(value) || !hasOnlyKeys(value, ['id', 'meshId', 'title', 'goal', 'status', 'brief', ...STRUCTURED_MISSION_KEYS])) return false
+    if (!isStructuredMissionFields(value)) return false
     if (!isEvidenceIdentifier(value.id) || !isEvidenceIdentifier(value.meshId)) return false
     if (typeof value.title !== 'string' || typeof value.goal !== 'string') return false
     if (!isMeshMissionStatusValue(value.status)) return false
@@ -111,11 +165,24 @@ function isMeshMissionRecordWire(value: unknown): value is MeshMissionRecordWire
 }
 
 function isMissionUpsertRequest(value: unknown): value is MissionUpsertRequest {
-    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'id', 'title', 'goal', 'status', 'brief'])) return false
+    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'id', 'title', 'goal', 'status', 'brief', 'structured', 'summary', 'outcome', 'outcomeReason', 'carryOverTo', 'toCarryOver', 'itemsAdd', 'itemsUpdate'])) return false
     if (value.v !== TURN_IPC_PROTOCOL_VERSION) return false
     if (!isEvidenceIdentifier(value.meshId)) return false
     if (value.id !== undefined && !isEvidenceIdentifier(value.id)) return false
-    if (typeof value.title !== 'string' || value.title.trim().length === 0) return false
+    if (typeof value.title !== 'string') return false
+    // An empty title is allowed only when the daemon can supply one: an existing mission (id) or the carry-over mission.
+    if (value.title.trim().length === 0 && value.toCarryOver !== true && value.id === undefined) return false
+    if (value.structured !== undefined && typeof value.structured !== 'boolean') return false
+    if (value.toCarryOver !== undefined && typeof value.toCarryOver !== 'boolean') return false
+    for (const k of ['summary', 'outcome', 'outcomeReason'] as const) {
+        if (value[k] !== undefined && typeof value[k] !== 'string') return false
+    }
+    if (value.carryOverTo !== undefined && !isEvidenceIdentifier(value.carryOverTo)) return false
+    for (const k of ['itemsAdd', 'itemsUpdate'] as const) {
+        const list = value[k]
+        // Bounded only to keep the IPC message sane; per-entry shape/size is clamped (never rejected) by the daemon.
+        if (list !== undefined && (!Array.isArray(list) || list.length > 500 || !list.every(isRecord))) return false
+    }
     if (value.goal !== undefined && typeof value.goal !== 'string') return false
     if (value.status !== undefined && !isMeshMissionStatusValue(value.status)) return false
     if (value.brief !== undefined && value.brief !== null && !isMissionBriefWire(value.brief)) return false
@@ -127,7 +194,8 @@ export function decodeMissionUpsertRequest(value: unknown): MissionUpsertRequest
 }
 
 export function isMissionUpsertResponse(value: unknown): value is MissionUpsertResponse {
-    return isRecord(value) && hasOnlyKeys(value, ['mission']) && isMeshMissionRecordWire(value.mission)
+    return isRecord(value) && hasOnlyKeys(value, ['mission', 'result']) && isMeshMissionRecordWire(value.mission)
+        && (value.result === undefined || isRecord(value.result))
 }
 
 export function decodeMissionUpsertResponse(value: unknown): MissionUpsertResponse | null {
@@ -207,6 +275,12 @@ export interface MissionListQueryRequest {
      * option except `historyIdLimit` is ignored. An older daemon rejects the key.
      */
     meshStatusView?: 'compact' | 'verbose'
+    /** Structured-missions capability flag (see MissionUpsertRequest.structured): rows then carry summary/outcome/openItems/carryOver/version. */
+    structured?: boolean
+    /** Structured only: attach each mission's items. */
+    items?: boolean
+    /** Structured only: attach each mission's change history (bounded tail). */
+    history?: boolean
 }
 
 export interface MeshMissionTaskAggregateWire {
@@ -248,6 +322,15 @@ export interface MissionListSummaryVerboseWire {
     createdAt?: string
     updatedAt?: string
     closeCandidateEmittedAt?: string | null
+    /** Structured lists only. */
+    summary?: string
+    outcome?: string
+    outcomeReason?: string
+    version?: number
+    carryOver?: boolean
+    openItems?: MeshMissionOpenItemCountsWire
+    items?: readonly Record<string, unknown>[]
+    history?: readonly Record<string, unknown>[]
 }
 
 /** Compact (default) mission row. `goalPreview`/`goalTruncated` present, `goal` absent. */
@@ -266,6 +349,15 @@ export interface MissionListSummarySlimWire {
     createdAt?: string
     updatedAt?: string
     closeCandidateEmittedAt?: string | null
+    /** Structured lists only. */
+    summary?: string
+    outcome?: string
+    outcomeReason?: string
+    version?: number
+    carryOver?: boolean
+    openItems?: MeshMissionOpenItemCountsWire
+    items?: readonly Record<string, unknown>[]
+    history?: readonly Record<string, unknown>[]
 }
 
 export type MissionListSummaryWire = MissionListSummaryVerboseWire | MissionListSummarySlimWire
@@ -286,7 +378,10 @@ export interface MissionListQueryResponse {
 }
 
 function isMissionListQueryRequest(value: unknown): value is MissionListQueryRequest {
-    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'statuses', 'verbose', 'withStats', 'limit', 'historyIdLimit', 'meshStatusView'])) return false
+    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'statuses', 'verbose', 'withStats', 'limit', 'historyIdLimit', 'meshStatusView', 'structured', 'items', 'history'])) return false
+    for (const k of ['structured', 'items', 'history'] as const) {
+        if (value[k] !== undefined && typeof value[k] !== 'boolean') return false
+    }
     if (value.meshStatusView !== undefined && value.meshStatusView !== 'compact' && value.meshStatusView !== 'verbose') return false
     if (value.v !== TURN_IPC_PROTOCOL_VERSION) return false
     if (!isEvidenceIdentifier(value.meshId)) return false
@@ -332,7 +427,7 @@ function isMissionListSummaryWire(value: unknown): value is MissionListSummaryWi
     const hasGoal = 'goal' in value
     const hasPreview = 'goalPreview' in value && 'goalTruncated' in value
     if (hasGoal === hasPreview) return false // exactly one of the two shapes
-    const baseKeys = ['id', 'meshId', 'title', 'status', 'tasks', 'stats', 'brief', 'createdAt', 'updatedAt', 'closeCandidateEmittedAt'] as const
+    const baseKeys = ['id', 'meshId', 'title', 'status', 'tasks', 'stats', 'brief', 'createdAt', 'updatedAt', 'closeCandidateEmittedAt', ...STRUCTURED_MISSION_KEYS, 'items', 'history'] as const
     const allowed = hasGoal ? [...baseKeys, 'goal'] : [...baseKeys, 'goalPreview', 'goalTruncated']
     if (!hasOnlyKeys(value, allowed)) return false
     if (!isEvidenceIdentifier(value.id) || !isEvidenceIdentifier(value.meshId)) return false
@@ -346,6 +441,10 @@ function isMissionListSummaryWire(value: unknown): value is MissionListSummaryWi
     if (value.createdAt !== undefined && typeof value.createdAt !== 'string') return false
     if (value.updatedAt !== undefined && typeof value.updatedAt !== 'string') return false
     if (value.closeCandidateEmittedAt !== undefined && value.closeCandidateEmittedAt !== null && typeof value.closeCandidateEmittedAt !== 'string') return false
+    if (!isStructuredMissionFields(value)) return false
+    for (const k of ['items', 'history'] as const) {
+        if (value[k] !== undefined && (!Array.isArray(value[k]) || !(value[k] as unknown[]).every(isRecord))) return false
+    }
     return true
 }
 

package/src/worker-protocol.ts

@@ -43,6 +43,10 @@ export const WORKER_TOOLS = [
     'driver_list',
     'driver_describe',
     'driver_invoke',
+    'driver_scaffold',
+    'driver_validate',
+    'driver_export',
+    'driver_install',
     'artifact_register',
     'artifact_list',
     'artifact_read',