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

package/src/turn-ipc-mission.ts

@@ -85,9 +85,46 @@ 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
+    /** One user/operator-visible sentence for the release CHANGELOG draft (design 2026-11-01-release-objects L5). `''` clears. */
+    releaseNote?: 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
+    releaseNote?: string
+    outcome?: string
+    outcomeReason?: string
+    version?: number
+    carryOver?: boolean
+    openItems?: MeshMissionOpenItemCountsWire
+}
+
+export interface MeshMissionRecordWire extends MeshMissionStructuredWire {
     id: string
     meshId: string
     title: string
@@ -99,10 +136,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', 'releaseNote', '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', 'releaseNote', '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 +168,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', 'releaseNote', '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', 'releaseNote', '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 +197,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 +278,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 {
@@ -221,6 +298,8 @@ export interface MeshMissionTaskAggregateWire {
 }
 
 export interface MeshMissionStatsWire {
+    /** Present on peers that project proven blocked outcomes separately. */
+    blocked?: number
     missionId: string
     taskCount: number
     completed: number
@@ -246,6 +325,16 @@ export interface MissionListSummaryVerboseWire {
     createdAt?: string
     updatedAt?: string
     closeCandidateEmittedAt?: string | null
+    /** Structured lists only. */
+    summary?: string
+    releaseNote?: 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. */
@@ -264,6 +353,16 @@ export interface MissionListSummarySlimWire {
     createdAt?: string
     updatedAt?: string
     closeCandidateEmittedAt?: string | null
+    /** Structured lists only. */
+    summary?: string
+    releaseNote?: 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
@@ -284,7 +383,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
@@ -313,12 +415,13 @@ function isMeshMissionTaskAggregateWire(value: unknown): value is MeshMissionTas
 }
 
 function isMeshMissionStatsWire(value: unknown): value is MeshMissionStatsWire {
-    const keys = ['missionId', 'taskCount', 'completed', 'failed', 'totalDurationMs', 'wallClockMs', 'retries', 'incompleteTaskIds'] as const
+    const keys = ['missionId', 'taskCount', 'completed', 'failed', 'blocked', 'totalDurationMs', 'wallClockMs', 'retries', 'incompleteTaskIds'] as const
     if (!isRecord(value) || !hasOnlyKeys(value, keys)) return false
     if (!isEvidenceIdentifier(value.missionId)) return false
     for (const k of ['taskCount', 'completed', 'failed', 'totalDurationMs', 'retries'] as const) {
         if (!isNonNegativeInt(value[k])) return false
     }
+    if (value.blocked !== undefined && !isNonNegativeInt(value.blocked)) return false
     if (value.wallClockMs !== null && !isNonNegativeInt(value.wallClockMs)) return false
     if (!Array.isArray(value.incompleteTaskIds) || !value.incompleteTaskIds.every(isEvidenceIdentifier)) return false
     return true
@@ -329,7 +432,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
@@ -343,6 +446,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
 }
 
@@ -580,6 +687,8 @@ export interface LedgerQueryEntryWire {
 }
 
 export interface LedgerQuerySummaryWire {
+    /** Absent on older peers; never folded into failed by the decoder. */
+    taskBlocked?: number
     meshId: string
     totalEntries: number
     taskDispatched: number
@@ -625,12 +734,13 @@ function isLedgerQueryEntryWire(value: unknown): value is LedgerQueryEntryWire {
 }
 
 function isLedgerQuerySummaryWire(value: unknown): value is LedgerQuerySummaryWire {
-    const keys = ['meshId', 'totalEntries', 'taskDispatched', 'taskCompleted', 'taskFailed', 'taskStalled', 'sessionLaunched', 'checkpointCreated', 'lastActivityAt', 'recentFailures'] as const
+    const keys = ['meshId', 'totalEntries', 'taskDispatched', 'taskCompleted', 'taskFailed', 'taskBlocked', 'taskStalled', 'sessionLaunched', 'checkpointCreated', 'lastActivityAt', 'recentFailures'] as const
     if (!isRecord(value) || !hasOnlyKeys(value, keys)) return false
     if (!isEvidenceIdentifier(value.meshId)) return false
     for (const k of ['totalEntries', 'taskDispatched', 'taskCompleted', 'taskFailed', 'taskStalled', 'sessionLaunched', 'checkpointCreated', 'recentFailures'] as const) {
         if (!isNonNegativeInt(value[k])) return false
     }
+    if (value.taskBlocked !== undefined && !isNonNegativeInt(value.taskBlocked)) return false
     if (value.lastActivityAt !== null && typeof value.lastActivityAt !== 'string') return false
     return true
 }

package/src/turn-ipc-queue.ts

@@ -135,6 +135,8 @@ export interface QueueQueryResponse {
     counts?: Record<string, number>
     /** `withCounts` + `historicalOlderThanMs`: terminal rows older than that age. */
     oldHistoricalCount?: number
+    /** Included in counts.blocked, derived from proven worker reports; stored failed rows stay unchanged. */
+    legacyReportedBlockedCount?: number
     /** `withDependencyHeads`. */
     dependencyHeads?: readonly QueueDependencyHeadWire[]
 }
@@ -159,9 +161,10 @@ function isQueueDependencyHeadWire(value: unknown): value is QueueDependencyHead
 }
 
 function isQueueQueryResponse(value: unknown): value is QueueQueryResponse {
-    if (!isRecord(value) || !hasOnlyKeys(value, ['entries', 'counts', 'oldHistoricalCount', 'dependencyHeads'])) return false
+    if (!isRecord(value) || !hasOnlyKeys(value, ['entries', 'counts', 'oldHistoricalCount', 'legacyReportedBlockedCount', 'dependencyHeads'])) return false
     if (!Array.isArray(value.entries) || !value.entries.every(isQueueEntryWire)) return false
     if (value.counts !== undefined && (!isRecord(value.counts) || !Object.values(value.counts).every(isNonNegativeInt))) return false
+    if (value.legacyReportedBlockedCount !== undefined && !isNonNegativeInt(value.legacyReportedBlockedCount)) return false
     if (value.oldHistoricalCount !== undefined && !isNonNegativeInt(value.oldHistoricalCount)) return false
     if (value.dependencyHeads !== undefined && (!Array.isArray(value.dependencyHeads) || !value.dependencyHeads.every(isQueueDependencyHeadWire))) return false
     return true
@@ -491,3 +494,28 @@ function isRecoveryContextQueryResponse(value: unknown): value is RecoveryContex
 export function decodeRecoveryContextQueryResponse(value: unknown): RecoveryContextQueryResponse | null {
     return isRecoveryContextQueryResponse(value) ? value : null
 }
+
+// ── queue_revise: host-authenticated pending CAS, never a force requeue ──
+export interface QueueReviseRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION
+    meshId: string
+    taskId: string
+    expectedRevision: number
+    patch: { message?: string; ownedPaths?: string[]; phase?: 'source' | 'integration'; dependsOn?: string[]; routingPreferences?: import('./task-source-phase').MeshRoutingPreferences; review?: import('./task-source-phase').MeshReviewConstraint }
+}
+export type QueueReviseResponse = QueueRequeueResponse
+export function decodeQueueReviseRequest(value: unknown): QueueReviseRequest | null {
+    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'taskId', 'expectedRevision', 'patch'])
+        || value.v !== TURN_IPC_PROTOCOL_VERSION || !isEvidenceIdentifier(value.meshId) || !isEvidenceIdentifier(value.taskId)
+        || !Number.isSafeInteger(value.expectedRevision) || (value.expectedRevision as number) < 0
+        || !isRecord(value.patch) || !Object.keys(value.patch).length
+        || !hasOnlyKeys(value.patch, ['message', 'ownedPaths', 'phase', 'dependsOn', 'routingPreferences', 'review'])) return null
+    const p = value.patch
+    if (p.message !== undefined && (typeof p.message !== 'string' || !p.message.trim())) return null
+    if (p.phase !== undefined && p.phase !== 'source' && p.phase !== 'integration') return null
+    for (const key of ['ownedPaths', 'dependsOn']) {
+        if (p[key] !== undefined && (!Array.isArray(p[key]) || !(p[key] as unknown[]).every(x => typeof x === 'string' && !!x.trim()))) return null
+    }
+    return value as unknown as QueueReviseRequest
+}
+export const decodeQueueReviseResponse = decodeQueueRequeueResponse

package/src/turn-ipc-turn.ts

@@ -66,7 +66,7 @@ function isTurnObserveResponse(value: unknown): value is TurnObserveResponse {
         && (value.outcome === undefined || isTurnOutcomeValue(value.outcome))
 }
 
-const TURN_OUTCOMES_LOCAL = ['completed', 'failed', 'cancelled'] as const
+const TURN_OUTCOMES_LOCAL = ['completed', 'blocked', 'failed', 'cancelled'] as const
 function isTurnOutcomeValue(value: unknown): value is TurnOutcome {
     return typeof value === 'string' && (TURN_OUTCOMES_LOCAL as readonly string[]).includes(value)
 }

package/src/turn-ipc.ts

@@ -132,6 +132,7 @@ export const TURN_IPC_COMMANDS = [
     'queue_enqueue_batch',
     'queue_cancel',
     'queue_requeue',
+    'queue_revise',
     'direct_dispatch_record',
     'active_work_query',
     'recovery_context_query',

package/src/types.ts

@@ -137,6 +137,7 @@ export interface MeshNodeIdentified {
 }
 
 export interface RepoMeshSessionStatus {
+    providerApproval?: import('./provider-approval').ProviderApproval | null;
     sessionId: string
     providerType?: string
     state?: string

package/src/worker-protocol.ts

@@ -40,6 +40,21 @@ export const WORKER_TOOLS = [
     'git_status',
     'git_log',
     'git_diff',
+    'driver_list',
+    'driver_describe',
+    'driver_invoke',
+    'driver_scaffold',
+    'driver_validate',
+    'driver_export',
+    'driver_install',
+    'artifact_register',
+    'artifact_list',
+    'artifact_read',
+    // Contract versioning (Cut A): exact pinned-unit reads (E2), the explicit
+    // read claim (C1) and the authoritative head/notice pull.
+    'contract_read',
+    'contract_observe',
+    'contract_current',
 ] as const
 
 export type WorkerTool = typeof WORKER_TOOLS[number]