@adhdev/mesh-shared 1.0.82-rc.3 → 1.0.82-rc.31

package/src/quota-freshness.ts

@@ -0,0 +1,139 @@
+/**
+ * Quota snapshot freshness — the ONE decision every display surface shares.
+ *
+ * Why this lives in the leaf package: the dashboard chips (web-core
+ * `quotaWindowCue`), the `adhdev quota` CLI (daemon-core `quota/cli.ts`) and the
+ * coordinator-facing `mesh_status` fold (mcp-server `summarizeNodeQuota`) each
+ * carried a hand-copied version of this rule, and a fix to one left the other
+ * two telling a different story about the same snapshot. They all call
+ * `assessQuotaFreshness` now; only the WORDING stays per-surface.
+ *
+ * Pure: plain objects in, plain object out, no clock except the `now` argument.
+ */
+import type { MeshNodeFactsProviderQuota } from './node-facts'
+
+export type QuotaFreshnessCue = 'refreshing' | 'stale'
+
+export interface QuotaFreshness {
+    /** Undefined = nothing to say (a fresh reading, or no retained numbers). */
+    cue?: QuotaFreshnessCue
+    /**
+     * Only the USER can produce a new reading (aged-out Claude statusline;
+     * expired CLI access token — the daemon never redeems it). The surface
+     * should say what to run, not promise a self-heal.
+     */
+    userMustAct: boolean
+    /**
+     * Unix ms by which the daemon will have looked again, for a `stale` reading
+     * the daemon re-checks on its own. Absent when the user must act, when the
+     * reading is `refreshing` (a retry is already scheduled), or when the check
+     * is already due.
+     */
+    nextCheckAt?: number
+}
+
+/**
+ * How long past `metadata.retryAtMs` a retry still reads as "in flight". The
+ * retry timer fires at retryAtMs and the probe itself takes a few seconds; a
+ * retryAtMs well in the past with no newer attempt means no retry is coming.
+ */
+export const QUOTA_RETRY_INFLIGHT_GRACE_MS = 60_000
+
+/**
+ * The daemon's backfill horizon: a snapshot is re-probed once it is this old
+ * even on an idle machine. Mirrors daemon-core `QUOTA_ROUTABLE_MAX_AGE_MS`
+ * (quota/refresh.ts); daemon-core's quota-freshness test pins the two equal.
+ */
+export const QUOTA_BACKFILL_HORIZON_MS = 60 * 60 * 1000
+
+function hasUsableWindow(window: { usedPercent?: unknown } | null | undefined): boolean {
+    return !!window && typeof window.usedPercent === 'number' && Number.isFinite(window.usedPercent)
+}
+
+/**
+ * Does the snapshot carry any renderable number — session/weekly/monthly
+ * windows OR per-pool buckets? `monthly` counts on its own: cursor-cli reports
+ * ONLY that axis, and leaving it out made a retained cursor reading look
+ * numberless. A window without a finite `usedPercent` is unknown, not 0%.
+ */
+function hasReading(quota: MeshNodeFactsProviderQuota): boolean {
+    if (hasUsableWindow(quota.session) || hasUsableWindow(quota.weekly) || hasUsableWindow(quota.monthly)) return true
+    return Array.isArray(quota.buckets) && quota.buckets.some((b) => !!b && typeof b.usedPercent === 'number' && Number.isFinite(b.usedPercent))
+}
+
+function finiteMs(value: unknown): number | undefined {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+/**
+ * When the daemon will next look, from the snapshot alone — the same
+ * "both clocks" rule the refresh loop's backfill uses (data age AND attempt
+ * age must both pass the horizon). Undefined when that moment has passed.
+ */
+function backfillCheckAt(quota: MeshNodeFactsProviderQuota, now: number): number | undefined {
+    const dataDue = finiteMs(quota.updatedAt)
+    const attempted = finiteMs(quota.metadata?.fetchedAt)
+    const dueAt = Math.max(
+        dataDue === undefined ? Number.NEGATIVE_INFINITY : dataDue + QUOTA_BACKFILL_HORIZON_MS,
+        attempted === undefined ? Number.NEGATIVE_INFINITY : attempted + QUOTA_BACKFILL_HORIZON_MS,
+    )
+    return Number.isFinite(dueAt) && dueAt > now ? dueAt : undefined
+}
+
+/**
+ * Which freshness cue a snapshot's retained numbers should carry.
+ *
+ *  - `stale` + `userMustAct` — nothing will refresh it without the user:
+ *      · `no-data` on any provider EXCEPT codex (Claude's statusline aged out —
+ *        a session must run). Codex's `no-data` is the daemon re-reading the
+ *        rollout files itself (≈60s while a CLI is active, ≤60 min idle), so it
+ *        is `stale` WITHOUT userMustAct;
+ *      · `expired-token` on Grok/Kimi/antigravity — only the owning CLI
+ *        renews it on use. An idle CLI has no background renewal cadence.
+ *        A scheduled quota retry does not itself renew credentials.
+ *  - `refreshing` — retained numbers after a transient failure with a retry
+ *    actually pending. ★Honest about the end of the retry budget: once the
+ *    daemon has stopped retrying (`metadata.retryExhausted`, or `retryAtMs`
+ *    long past with no newer attempt) the numbers are `stale` with the next
+ *    scheduled check, not "refreshing" for the up-to-60 minutes until the
+ *    hourly backfill. A snapshot with NO retry bookkeeping at all (a daemon
+ *    predating the stamp) keeps the old `refreshing` reading.
+ */
+export function assessQuotaFreshness(quota: MeshNodeFactsProviderQuota, now: number = Date.now()): QuotaFreshness {
+    const meta = quota.metadata
+    const kind = meta?.failureKind
+    const userMustAct = kind === 'no-data' && quota.provider !== 'codex-cli'
+    const awaitsCliUse = kind === 'expired-token' && ['grok-cli', 'kimi', 'antigravity-cli'].includes(quota.provider)
+    // Order matters: the aged-out Claude shape and the retained expired-token
+    // shape both ALSO mark lastGoodWindows, so they must be classified before
+    // the generic branch. An expired short-lived access token that the CLI
+    // renews itself is NOT an auth failure requiring user action (userMustAct:
+    // false), while any retained lastGood numbers are marked stale.
+    if (userMustAct) return hasReading(quota) ? { cue: 'stale', userMustAct: true } : { userMustAct: true }
+    if (awaitsCliUse) return hasReading(quota) ? { cue: 'stale', userMustAct: false } : { userMustAct: false }
+    if (meta?.lastGoodWindows !== true) {
+        // A successful fetch is not a perpetual live reading. Use the DATA
+        // clock; a recent failed attempt must never rejuvenate old numbers.
+        const measuredAt = finiteMs(quota.updatedAt)
+        if (hasReading(quota) && (measuredAt === undefined || now - measuredAt >= QUOTA_BACKFILL_HORIZON_MS)) {
+            return { cue: 'stale', userMustAct }
+        }
+        return { userMustAct }
+    }
+
+    const retryAtMs = finiteMs(meta?.retryAtMs)
+    const retryStopped = meta?.retryExhausted === true
+        || (retryAtMs !== undefined && retryAtMs + QUOTA_RETRY_INFLIGHT_GRACE_MS < now)
+    // A `no-data` retained reading (codex) has no retry at all — it is a
+    // snapshot the daemon will simply look at again, never an in-flight refresh.
+    if (kind !== 'no-data' && !retryStopped) return { cue: 'refreshing', userMustAct: false }
+    const nextCheckAt = backfillCheckAt(quota, now)
+    return nextCheckAt === undefined
+        ? { cue: 'stale', userMustAct: false }
+        : { cue: 'stale', userMustAct: false, nextCheckAt }
+}
+
+/** Whole minutes (min 1) until `nextCheckAt`, for the "next check ~Nm" wording. */
+export function minutesUntilQuotaCheck(nextCheckAt: number, now: number = Date.now()): number {
+    return Math.max(1, Math.round((nextCheckAt - now) / 60_000))
+}

package/src/role-launch.ts

@@ -0,0 +1,51 @@
+/** Persisted role-launch intent. Restart replays this selection rather than
+ * consulting newer machine defaults; restore preserves its original provenance. */
+import { isLaunchDefaultRole, isLaunchDefaultSource, type LaunchDefaultRole,
+    type LaunchDefaultSelection, type LaunchDefaultAxis, type LaunchDefaultRef } from './launch-defaults';
+export interface RoleLaunchSelection {
+    role: LaunchDefaultRole;
+    selection: LaunchDefaultSelection;
+    applied: Record<keyof LaunchDefaultSelection, LaunchDefaultAxis>;
+    defaultRef?: LaunchDefaultRef;
+    documentRevision: number;
+}
+function record(value: unknown): Record<string, unknown> | undefined {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown> : undefined;
+}
+function ref(value: unknown): LaunchDefaultRef | undefined {
+    const r = record(value);
+    if (!r || !isLaunchDefaultRole(r.role) || (r.scope !== 'global' && r.scope !== 'project')
+        || !Number.isSafeInteger(r.revision) || (r.revision as number) < 1
+        || (r.scope === 'project' && (typeof r.projectId !== 'string' || !r.projectId))) return undefined;
+    return { role: r.role, scope: r.scope, revision: r.revision as number,
+        ...(r.scope === 'project' ? { projectId: r.projectId as string } : {}) };
+}
+function axis(value: unknown): LaunchDefaultAxis | undefined {
+    const a = record(value);
+    if (!a || !isLaunchDefaultSource(a.source) || (a.value !== null && typeof a.value !== 'string')) return undefined;
+    const defaultRef = ref(a.defaultRef);
+    if (a.source === 'stored_default' && defaultRef?.scope !== 'global'
+        || a.source === 'project_default' && defaultRef?.scope !== 'project'
+        || (a.source === 'user' || a.source === 'provider_default') && a.defaultRef !== undefined) return undefined;
+    return { value: a.value as string | null, source: a.source, ...(defaultRef ? { defaultRef } : {}) };
+}
+export function parseRoleLaunchSelection(value: unknown): RoleLaunchSelection | undefined {
+    const r = record(value), s = record(r?.selection), a = record(r?.applied);
+    if (!r || !isLaunchDefaultRole(r.role) || !s || typeof s.provider !== 'string' || !s.provider
+        || !Number.isSafeInteger(r.documentRevision) || (r.documentRevision as number) < 1
+        || (s.model !== undefined && typeof s.model !== 'string')
+        || (s.thinkingLevel !== undefined && typeof s.thinkingLevel !== 'string')) return undefined;
+    const provider = axis(a?.provider), model = axis(a?.model), thinkingLevel = axis(a?.thinkingLevel);
+    if (!provider || !model || !thinkingLevel
+        || [provider, model, thinkingLevel].some(axis => axis.defaultRef && (axis.defaultRef.role !== r.role
+            || axis.defaultRef.scope === 'global' && axis.defaultRef.revision > (r.documentRevision as number)))
+        || provider.value !== s.provider
+        || model.value !== (s.model ?? null) || thinkingLevel.value !== (s.thinkingLevel ?? null)) return undefined;
+    const defaultRef = ref(r.defaultRef);
+    return { role: r.role, selection: { provider: s.provider,
+        ...(typeof s.model === 'string' ? { model: s.model } : {}),
+        ...(typeof s.thinkingLevel === 'string' ? { thinkingLevel: s.thinkingLevel } : {}) },
+        applied: { provider, model, thinkingLevel }, ...(defaultRef ? { defaultRef } : {}),
+        documentRevision: r.documentRevision as number };
+}

package/src/session-launch.ts

@@ -1,3 +1,4 @@
+import { parseRoleLaunchSelection, type RoleLaunchSelection } from './role-launch'
 /**
  * session-launch — how a session was launched: provider, model and thinking
  * level, and WHERE each value came from.
@@ -35,11 +36,14 @@ export const MODEL_AXIS_SOURCES = [
     'user',
     /** The dashboard dialog restored it from the last launch (browser-local memory). */
     'remembered',
+    /** The authoritative daemon role default or host project override. */
+    'stored_default',
+    'project_default',
     /** A mesh capability slot supplied it (or a difficulty preset the slot outranked). */
     'mesh_slot',
     /** An explicit per-task model / thinking level on a mesh queue task. */
     'task_override',
-    /** Nothing was requested; the provider's default is known (discovery / manifest). */
+    /** Nothing requested: the provider chooses; resolvedDefault records it when known. */
     'provider_default',
     /** A value was requested without saying where it came from, or nothing is known. */
     'unspecified',
@@ -102,6 +106,7 @@ export interface ModelSelection {
 }
 
 export interface SessionLaunchRecord {
+    roleLaunch?: RoleLaunchSelection
     sessionId: string
     providerType: string
     providerVersion?: string
@@ -230,7 +235,9 @@ export function parseSessionLaunchRecord(raw: unknown): SessionLaunchRecord | un
     const providerVersion = readString(record.providerVersion)
     const workspace = readString(record.workspace)
     const autoApproveModeId = readString(record.autoApproveModeId)
+    const roleLaunch = parseRoleLaunchSelection(record.roleLaunch)
     return {
+        ...(roleLaunch ? { roleLaunch } : {}),
         sessionId,
         providerType,
         ...(providerVersion ? { providerVersion } : {}),

package/src/slot-proposal.ts

@@ -40,6 +40,13 @@ import {
 export interface CliSlotRecipe {
     /** Optional model to pin on the slot. Best-effort at launch. */
     model?: string
+    /**
+     * Optional ordered candidate models to prefer when the provider's live
+     * `modelOptions` (from model discovery) is present on `DetectedCliProvider`.
+     * The first candidate present in `modelOptions` wins; falls back to `model`
+     * when `modelOptions` is absent or contains none of the candidates.
+     */
+    modelCandidates?: readonly string[]
     /** Optional thinking level, in the provider's own vocabulary. */
     thinkingLevel?: string
     /** Difficulty range this slot handles. Empty = general-purpose. */
@@ -101,11 +108,26 @@ export const CLI_SLOT_RECIPES: Readonly<Record<string, readonly CliSlotRecipe[]>
     ],
     'antigravity-cli': [
         {
-            model: 'Gemini 3.1 Pro (High)',
+            model: 'Gemini 3.8 Flash (High)',
+            modelCandidates: ['Gemini 3.8 Flash (High)', 'Gemini 4 Argon (Low)', 'Gemini 3.7 Flash (High)', 'Gemini 3.1 Pro (High)'],
             difficulty: ['easy'],
             maxParallel: 2,
             rationale: 'Cheap capacity for easy tasks.',
         },
+        {
+            model: 'Gemini 4 Argon (Medium)',
+            modelCandidates: ['Gemini 4 Argon (Medium)', 'Gemini 3.8 Flash (High)', 'Gemini 3.7 Flash (High)', 'Gemini 3.1 Pro (High)'],
+            difficulty: ['medium'],
+            maxParallel: 2,
+            rationale: 'Balanced Argon tier for medium tasks.',
+        },
+        {
+            model: 'Gemini 4 Argon (High)',
+            modelCandidates: ['Gemini 4 Argon (High)', 'Gemini 3.8 Flash (High)', 'Gemini 3.1 Pro (High)'],
+            difficulty: ['difficult'],
+            maxParallel: 1,
+            rationale: 'Reserved for hard tasks; capped at 1 to bound cost.',
+        },
     ],
     'cursor-cli': [
         {
@@ -137,6 +159,13 @@ export interface DetectedCliProvider {
     displayName?: string
     /** Detected version, when known. Display only — never affects the mapping. */
     version?: string
+    /**
+     * Live discovered / resolved `modelOptions` for this provider on the node,
+     * when available on the status catalog. When present and non-empty, recipes
+     * prefer the first matching model from `[recipe.model, ...recipe.modelCandidates]`
+     * that exists in `modelOptions`.
+     */
+    modelOptions?: readonly string[]
 }
 
 /** One proposed slot plus why it was proposed. */
@@ -197,6 +226,36 @@ function dedupeDetected(detected: readonly DetectedCliProvider[]): DetectedCliPr
     return out
 }
 
+/**
+ * Resolve a recipe's pinned model against the provider's live `modelOptions`
+ * (populated from the daemon's model-discovery overlay when available). If
+ * `modelOptions` is absent or none of the recipe's candidates appear in it,
+ * falls back to `recipe.model`.
+ */
+function resolveRecipeModel(
+    recipe: CliSlotRecipe,
+    modelOptions: readonly string[] | undefined,
+): string | undefined {
+    if (!Array.isArray(modelOptions) || modelOptions.length === 0) {
+        return recipe.model
+    }
+    const available = new Set(
+        modelOptions
+            .filter((m): m is string => typeof m === 'string' && m.trim().length > 0)
+            .map(m => m.trim()),
+    )
+    if (available.size === 0) return recipe.model
+    const candidates = [
+        ...(recipe.model ? [recipe.model] : []),
+        ...(recipe.modelCandidates ?? []),
+    ]
+    for (const candidate of candidates) {
+        const trimmed = typeof candidate === 'string' ? candidate.trim() : ''
+        if (trimmed && available.has(trimmed)) return trimmed
+    }
+    return recipe.model
+}
+
 /**
  * Build a capability-slot proposal from a node's detected CLI providers.
  *
@@ -229,7 +288,7 @@ export function buildSlotProposal(
             // a proposal can never preview a shape the write would reshape.
             const slot = normalizeNodeCapabilitySlot({
                 provider: provider.type,
-                model: recipe.model,
+                model: resolveRecipeModel(recipe, provider.modelOptions),
                 thinkingLevel: recipe.thinkingLevel,
                 difficulty: recipe.difficulty,
                 maxParallel: recipe.maxParallel,

package/src/task-source-phase.ts

@@ -0,0 +1,61 @@
+import type { OwnedPathEntry } from './path-ownership'
+
+export type MeshTaskPhase = 'source' | 'integration'
+
+/** Host-produced evidence. Never accepted from MCP/peer-supplied paths or branch labels. */
+export interface PhysicalOwnershipScope {
+    version: 1
+    repoIdentity: string
+    machineId: string
+    nodeId: string
+    worktree: string
+    worktreeIdentity: string
+    gitDir: string
+    commonGitDir: string
+    phase: MeshTaskPhase
+    gitResources: { index: string; refs: string; hooks: string; config: string }
+    resources: Array<{ path: string; identity?: string; subtree: boolean }>
+    declaration: readonly OwnedPathEntry[]
+}
+
+/** A source packet is an input to integration, never release/feature acceptance. */
+export interface MeshSourceCandidate {
+    version: 1
+    readiness: 'uncommitted' | 'verified_source_candidate'
+    taskId: string
+    missionId: string
+    revision: number
+    repoIdentity: string
+    machineId: string
+    canonicalWorktree: string
+    rootBaseSha: string
+    ossBaseSha: string
+    rootCandidateSha?: string
+    ossCandidateSha?: string
+    patchSha256: string
+    manifestSha256: string
+    touchedPaths: string[]
+    tests: Array<{ command: string; exit: number; logSha256: string }>
+    settledCommands: boolean
+    integrationTaskId: string
+    logicalOverlapTaskIds: string[]
+}
+
+/** Product B consumes one frozen batch; normal hooks/parity/gates remain required. */
+export interface MeshIntegrationBatchContract {
+    version: 1
+    batchId: string
+    candidates: MeshSourceCandidate[]
+    integrationOrder: string[]
+    approvedRootSha: string
+    approvedOssSha: string
+    bundleInvocationCount: 1
+    requiredGates: string[]
+    normalHooksRequired: true
+    independentReviewRequired: true
+    ownerLandingApprovalRequired: true
+}
+
+/** These only rank legal targets; targetNodeId/SessionId and requiredTags remain hard. */
+export interface MeshRoutingPreferences { nodeIds?: string[]; providers?: string[] }
+export interface MeshReviewConstraint { sourceTaskId: string; differentProvider: true }

package/src/turn-evidence.ts

@@ -83,9 +83,9 @@ export type SessionReboundReason = typeof SESSION_REBOUND_REASONS[number]
 
 export const SUSPENSION_MODALS = ['approval', 'choice'] as const
 export type SuspensionModal = typeof SUSPENSION_MODALS[number]
-export const SUSPENSION_RESOLUTIONS = ['approved', 'rejected', 'answered'] as const
+export const SUSPENSION_RESOLUTIONS = ['approved', 'rejected', 'answered', 'dismissed'] as const
 export type SuspensionResolution = typeof SUSPENSION_RESOLUTIONS[number]
-export const SUSPENSION_RESOLUTION_VIAS = ['modal_button', 'auto_approve', 'prompt_answer'] as const
+export const SUSPENSION_RESOLUTION_VIAS = ['modal_button', 'auto_approve', 'prompt_answer', 'modal_disappeared'] as const
 export type SuspensionResolutionVia = typeof SUSPENSION_RESOLUTION_VIAS[number]
 
 export const TURN_END_STRENGTHS = ['genuine', 'weak'] as const
@@ -97,13 +97,13 @@ export const TURN_END_BLOCK_REASONS = [
 ] as const
 export type TurnEndBlockReason = typeof TURN_END_BLOCK_REASONS[number]
 
-export const NATIVE_TURN_OUTCOMES = ['completed', 'aborted'] as const
+export const NATIVE_TURN_OUTCOMES = ['completed', 'aborted', 'failed'] as const
 export type NativeTurnOutcome = typeof NATIVE_TURN_OUTCOMES[number]
 
 export const LIVENESS_RESULTS = ['alive', 'unknown', 'read_failed', 'dead'] as const
 export type LivenessResult = typeof LIVENESS_RESULTS[number]
 
-export const PROVIDER_FAILURES = ['auth_failed', 'billing_failed'] as const
+export const PROVIDER_FAILURES = ['auth_failed', 'billing_failed', 'usage_limit_exceeded', 'server_overloaded', 'provider_error'] as const
 export type ProviderFailure = typeof PROVIDER_FAILURES[number]
 
 /**
@@ -150,11 +150,11 @@ export const HOLD_REASONS = [
     // — a turn_end commits the report (R9t), expiry commits it anyway (R13t) so
     // a session whose FSM never shows the idle edge again does not wait for
     // liveness / hard_ceiling.
-    'await_end',
+    'await_end', 'report_correction',
 ] as const
 export type HoldReason = typeof HOLD_REASONS[number]
 
-export const TURN_OUTCOMES = ['completed', 'failed', 'cancelled'] as const
+export const TURN_OUTCOMES = ['completed', 'blocked', 'failed', 'cancelled'] as const
 export type TurnOutcome = typeof TURN_OUTCOMES[number]
 
 export const COMMIT_STRENGTHS = ['genuine', 'weak', 'tool_report', 'operator'] as const
@@ -164,7 +164,7 @@ export type CommitStrength = typeof COMMIT_STRENGTHS[number]
 export const TURN_REASONS = [
     // commits
     'turn_end', 'weak_end_confirmed', 'transcript_final', 'worker_reported',
-    'finalization_timeout_no_response', 'session_error', 'provider_auth_failed', 'provider_billing_failed',
+    'finalization_timeout_no_response', 'weak_end_liveness_unconfirmed', 'weak_end_probe_unobserved', 'report_correction_expired', 'session_error', 'provider_auth_failed', 'provider_billing_failed', 'provider_usage_limit_exceeded', 'provider_server_overloaded', 'provider_error',
     'operator_cancel', 'intentional_cleanup', 'task_removed', 'mission_abandoned', 'superseded',
     'operator_update', 'refine_terminal', 'validation_terminal',
     'hard_ceiling', 'reclaim_budget_exhausted', 'hollow_max_retries', 'migration_orphan',
@@ -186,7 +186,7 @@ export type TurnReason = typeof TURN_REASONS[number]
  * owner's local `turn_events.payload_json` and is rendered at deliver time.
  */
 export const NOTIFY_KINDS = [
-    'completed', 'failed', 'cancelled', 'stopped', 'approval', 'choice', 'approval_resolved',
+    'completed', 'blocked', 'failed', 'cancelled', 'stopped', 'approval', 'choice', 'approval_resolved',
     'candidate', 'no_progress', 'progress', 'late_completion', 'mesh_event',
 ] as const
 export type NotifyKind = typeof NOTIFY_KINDS[number]
@@ -207,7 +207,7 @@ export interface LiveTurnPending { modal: boolean; adapterPending: boolean; trai
 /** Structural copy of daemon-core's `CoordinatorIdentity` (this package cannot import daemon-core). */
 export interface EvidenceCoordinatorIdentity { daemonId: string; coordinatorRunId: string; sessionId?: string }
 
-export interface NativeTurnMarkerRef { outcome: NativeTurnOutcome; turnId?: string }
+export interface NativeTurnMarkerRef { outcome: NativeTurnOutcome; turnId?: string; receivedAt?: number; startedAt?: number; errorAt?: number }
 
 export interface EvidenceEnvelope {
     /** Stable id of this observation; dedupe key across republish/replication. */
@@ -250,10 +250,10 @@ export type TurnEvidenceBody =
     | { kind: 'session_rebound'; toSessionId: string; reason: SessionReboundReason }
     // ── worker turn lifecycle ──
     | { kind: 'turn_started'; retro: boolean }
-    | { kind: 'suspension'; modal: SuspensionModal; modalKey?: string }
-    | { kind: 'suspension_resolved'; resolution: SuspensionResolution; via: SuspensionResolutionVia }
+    | { kind: 'suspension'; modal: SuspensionModal; modalKey?: string; providerSetup?: boolean; clockUnknown?: boolean }
+    | { kind: 'suspension_resolved'; resolution: SuspensionResolution; via: SuspensionResolutionVia; modalKey?: string }
     | { kind: 'turn_end'; strength: TurnEndStrength; afterFinalizationTimeout?: boolean; hollow?: boolean; summary?: SummaryRef
-        blockReason?: TurnEndBlockReason; releasedByHardCap?: boolean; nativeOutcome?: NativeTurnOutcome; live?: LiveTurnPending
+        blockReason?: TurnEndBlockReason; releasedByHardCap?: boolean; nativeOutcome?: NativeTurnOutcome; nativeMarker?: NativeTurnMarkerRef; live?: LiveTurnPending
         /**
          * Stamped (true only) by the WORKER's daemon when the session holds a live
          * worker-MCP session bind, i.e. the worker can call report_completion. The
@@ -273,7 +273,7 @@ export type TurnEvidenceBody =
         live: LiveTurnPending; summary?: SummaryRef; messageAt?: number }
     | { kind: 'transcript_activity'; newestActivityAt: number }
     | { kind: 'no_progress'; stalledMs: number; observedStatus: NoProgressObservedStatus; finalAssistantPresent: boolean }
-    | { kind: 'liveness'; result: LivenessResult }
+    | { kind: 'liveness'; result: LivenessResult; probeStartedAtMs?: number }
     | { kind: 'process_exit'; exitCode: number | null; providerFailure?: ProviderFailure }
     | { kind: 'session_error'; reason: SessionErrorReason }
     // ── worker MCP (F2) ──
@@ -284,6 +284,7 @@ export type TurnEvidenceBody =
      */
     | { kind: 'worker_report'; outcome: WorkerReportOutcome; summary?: SummaryRef; hasHandoffNotes: boolean
         branchState?: WorkerBranchState; touchedFileCount?: number }
+    | { kind: 'worker_report_correction_requested'; deliveryId?: string }
     | { kind: 'worker_progress'; note?: SummaryRef }
     // ── coordinator / operator ──
     | { kind: 'git_side_effect'; dirty: boolean; commitsSinceDispatch: number; attributable: boolean }
@@ -352,13 +353,13 @@ export const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs = {
     duplicate_dispatch_refusal: { holderSessionId: id, holderAttemptId: idOpt },
     session_rebound: { toSessionId: id, reason: en(SESSION_REBOUND_REASONS) },
     turn_started: { retro: bool },
-    suspension: { modal: en(SUSPENSION_MODALS), modalKey: idOpt },
-    suspension_resolved: { resolution: en(SUSPENSION_RESOLUTIONS), via: en(SUSPENSION_RESOLUTION_VIAS) },
+    suspension: { modal: en(SUSPENSION_MODALS), modalKey: idOpt, providerSetup: boolOpt, clockUnknown: boolOpt },
+    suspension_resolved: { resolution: en(SUSPENSION_RESOLUTIONS), via: en(SUSPENSION_RESOLUTION_VIAS), modalKey: idOpt },
     turn_end: {
         strength: en(TURN_END_STRENGTHS), afterFinalizationTimeout: boolOpt, hollow: boolOpt,
         summary: { t: 'summary_ref', optional: true }, blockReason: enOpt(TURN_END_BLOCK_REASONS),
         releasedByHardCap: boolOpt, nativeOutcome: enOpt(NATIVE_TURN_OUTCOMES), live: { t: 'live', optional: true },
-        reportExpected: boolOpt, providerFailure: enOpt(PROVIDER_FAILURES),
+        nativeMarker: { t: 'native_marker', optional: true }, reportExpected: boolOpt, providerFailure: enOpt(PROVIDER_FAILURES),
     },
     transcript_final: {
         selfAttributing: bool, nativeRead: bool, nativeMarker: { t: 'native_marker', optional: true },
@@ -366,13 +367,14 @@ export const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs = {
     },
     transcript_activity: { newestActivityAt: ms },
     no_progress: { stalledMs: ms, observedStatus: en(NO_PROGRESS_OBSERVED_STATUSES), finalAssistantPresent: bool },
-    liveness: { result: en(LIVENESS_RESULTS) },
+    liveness: { result: en(LIVENESS_RESULTS), probeStartedAtMs: msOpt },
     process_exit: { exitCode: { t: 'int', nullable: true }, providerFailure: enOpt(PROVIDER_FAILURES) },
     session_error: { reason: en(SESSION_ERROR_REASONS) },
     worker_report: {
         outcome: en(WORKER_REPORT_OUTCOMES), summary: { t: 'summary_ref', optional: true }, hasHandoffNotes: bool,
         branchState: enOpt(WORKER_BRANCH_STATES), touchedFileCount: intOpt,
     },
+    worker_report_correction_requested: { deliveryId: { t: 'id', optional: true } },
     worker_progress: { note: { t: 'summary_ref', optional: true } },
     git_side_effect: { dirty: bool, commitsSinceDispatch: { t: 'int' }, attributable: bool },
     cancel: { reason: en(CANCEL_REASONS) },
@@ -440,11 +442,12 @@ function isLiveTurnPending(value: unknown): value is LiveTurnPending {
         && (value.newestActivityAt === undefined || isFiniteNumber(value.newestActivityAt))
 }
 
-function isNativeMarkerRef(value: unknown): value is NativeTurnMarkerRef {
+export function isNativeMarkerRef(value: unknown): value is NativeTurnMarkerRef {
     return isRecord(value)
-        && hasOnlyKeys(value, ['outcome', 'turnId'])
+        && hasOnlyKeys(value, ['outcome', 'turnId', 'receivedAt', 'startedAt', 'errorAt'])
         && (NATIVE_TURN_OUTCOMES as readonly string[]).includes(value.outcome as string)
         && (value.turnId === undefined || isEvidenceIdentifier(value.turnId))
+        && ['receivedAt', 'startedAt', 'errorAt'].every((key) => value[key] === undefined || isFiniteNumber(value[key]))
 }
 
 function isCoordinatorIdentity(value: unknown): value is EvidenceCoordinatorIdentity {

package/src/turn-ipc-mission.ts

@@ -221,6 +221,8 @@ export interface MeshMissionTaskAggregateWire {
 }
 
 export interface MeshMissionStatsWire {
+    /** Present on peers that project proven blocked outcomes separately. */
+    blocked?: number
     missionId: string
     taskCount: number
     completed: number
@@ -313,12 +315,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
@@ -580,6 +583,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 +630,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)
 }