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

package/src/index.ts

@@ -41,6 +41,8 @@ export * from './session-launch'
 export * from './turn-ipc'
 export * from './path-ownership'
 export * from './mission-brief'
+export * from './mission-items'
+export * from './decision-push-relay'
 export * from './keyed-doc-delta'
 export * from './provider-approval'
 export * from './provider-question'
@@ -48,3 +50,4 @@ export * from './launch-defaults'
 
 export * from './role-launch';
 export * from './task-source-phase';
+export * from './relay-reprobe'

package/src/mesh-tool-names.ts

@@ -45,6 +45,7 @@ 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',
@@ -69,6 +70,8 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'driver_list',
     'driver_describe',
     'artifact_list',
+    'artifact_read',
+    'artifact_register',
 ] as const;
 
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];

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`) ──────
@@ -263,8 +289,8 @@ export const DAEMON_P2P_SIGNAL_TYPES = ['p2p_offer', 'p2p_ice'] as const
 export type DaemonP2PSignalType = typeof DAEMON_P2P_SIGNAL_TYPES[number]
 export const isDaemonP2PSignalType = makeTypeGuard(DAEMON_P2P_SIGNAL_TYPES)
 
-export type P2POfferWirePayload = { sdp: string; type: string; peerId: string; attemptId?: number; attemptEpoch?: string }
-export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string; attemptId?: number; attemptEpoch?: string }
+export type P2POfferWirePayload = { sdp: string; type: string; peerId: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
+export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
 
 /**
  * A dashboard-originated signal as relayed to the daemon. `peerId` is stamped
@@ -278,6 +304,10 @@ export type RelayedP2PSignalWirePayload = {
     daemonId?: string
     attemptId?: number
     attemptEpoch?: string
+    /** p2p_ready only: the dashboard's stale-connect backoff index (see DashboardP2PReadyWirePayload). */
+    backoffStep?: number
+    /** Make-before-break relay->direct re-probe of an existing peer (see DashboardP2PReadyWirePayload). */
+    probe?: boolean
     sharePermission?: string
     shareTargetSessionId?: string
     sdp?: string

package/src/protocol/dashboard-server.ts

@@ -154,6 +154,7 @@ export type DashboardP2POfferWirePayload = {
     peerId?: string
     attemptId?: number
     attemptEpoch?: string
+    probe?: boolean
     sdp: string
     type: string
 }
@@ -163,6 +164,7 @@ export type DashboardP2PIceWirePayload = {
     peerId?: string
     attemptId?: number
     attemptEpoch?: string
+    probe?: boolean
     candidate: string
     mid?: string
     sdpMid?: string | null
@@ -238,13 +240,16 @@ export const DASHBOARD_P2P_SIGNAL_TYPES = ['p2p_ready', 'p2p_answer', 'p2p_ice']
 export type DashboardP2PSignalType = typeof DASHBOARD_P2P_SIGNAL_TYPES[number]
 export const isDashboardP2PSignalType = makeTypeGuard(DASHBOARD_P2P_SIGNAL_TYPES)
 
-export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string; attemptId?: number; attemptEpoch?: string }
-export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string; attemptId?: number; attemptEpoch?: string }
+/** `backoffStep`: the dashboard's stale-connect backoff index (0 = 15s, 1 = 30s, 2 = 60s), so the daemon holds the connecting slot for the same window. */
+/** `probe`: identifier-only flag — this signal belongs to a make-before-break relay->direct re-probe of the SAME logical peer (never a new peer for the connection cap). */
+export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string; attemptId?: number; attemptEpoch?: string; backoffStep?: number; probe?: boolean }
+export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
 export type DashboardP2PLocalIceWirePayload = {
     daemonId: string
     peerId: string
     attemptId?: number
     attemptEpoch?: string
+    probe?: boolean
     candidate: string
     sdpMid: string | null
     sdpMLineIndex: number | null

package/src/relay-reprobe.ts

@@ -0,0 +1,117 @@
+/**
+ * Relay -> direct re-probe scheduler (pure, dependency-free).
+ *
+ * A P2P connection that settled on a TURN relay never looks for a direct path
+ * again. The owning transport (dashboard `P2PConnection`, daemon peer manager)
+ * uses this scheduler to periodically attempt a make-before-break probe: a
+ * SECOND peer connection (STUN-only) is built next to the working relay one and
+ * only swapped in once it is verified direct. The scheduler owns nothing but
+ * timing: backoff 60s -> 5min (doubling), jitter, and the stop conditions. The
+ * transport supplies `shouldProbe` (open + idle + visible) and `probe`.
+ */
+
+export type RelayReprobeOutcome = 'direct' | 'relay' | 'failed' | 'skipped'
+
+export interface RelayReprobeTiming {
+    /** First delay and the unit of growth (default 60s). */
+    baseDelayMs?: number
+    /** Backoff ceiling before jitter (default 5min). */
+    maxDelayMs?: number
+    /** +/- fraction applied to every delay (default 0.2). */
+    jitterRatio?: number
+}
+
+export const RELAY_REPROBE_BASE_DELAY_MS = 60_000
+export const RELAY_REPROBE_MAX_DELAY_MS = 5 * 60_000
+export const RELAY_REPROBE_JITTER_RATIO = 0.2
+
+/** Delay before the next attempt after `failures` consecutive non-direct outcomes. */
+export function computeRelayReprobeDelay(
+    failures: number,
+    random: () => number,
+    timing: RelayReprobeTiming = {},
+): number {
+    const base = timing.baseDelayMs ?? RELAY_REPROBE_BASE_DELAY_MS
+    const max = timing.maxDelayMs ?? RELAY_REPROBE_MAX_DELAY_MS
+    const jitter = timing.jitterRatio ?? RELAY_REPROBE_JITTER_RATIO
+    const grown = Math.min(max, base * 2 ** Math.max(0, failures))
+    const factor = 1 + jitter * (Math.min(1, Math.max(0, random())) * 2 - 1)
+    return Math.round(grown * factor)
+}
+
+export interface RelayReprobeSchedulerOptions extends RelayReprobeTiming {
+    random: () => number
+    setTimer: (callback: () => void, ms: number) => unknown
+    clearTimer: (handle: unknown) => void
+    /** Connected over relay, idle, tab visible, auth epoch unchanged... Re-checked on every tick. */
+    shouldProbe: () => boolean
+    /** One make-before-break attempt. Must never throw into the scheduler; a rejection counts as 'failed'. */
+    probe: () => Promise<RelayReprobeOutcome>
+}
+
+export class RelayReprobeScheduler {
+    private handle: unknown = null
+    private running = false
+    private inFlight = false
+    private failureCount = 0
+    private generation = 0
+
+    constructor(private readonly options: RelayReprobeSchedulerOptions) {}
+
+    get isRunning(): boolean { return this.running }
+    get failures(): number { return this.failureCount }
+    get probing(): boolean { return this.inFlight }
+
+    /** Begin probing (idempotent). Call when a connection is selected as relay. */
+    start(): void {
+        if (this.running) return
+        this.running = true
+        this.failureCount = 0
+        this.generation++
+        this.schedule()
+    }
+
+    /** Stop for good (direct path found, connection closed, auth epoch changed). */
+    stop(): void {
+        this.running = false
+        this.generation++
+        if (this.handle !== null) {
+            this.options.clearTimer(this.handle)
+            this.handle = null
+        }
+    }
+
+    private schedule(): void {
+        if (!this.running) return
+        const generation = this.generation
+        const delay = computeRelayReprobeDelay(this.failureCount, this.options.random, this.options)
+        this.handle = this.options.setTimer(() => {
+            this.handle = null
+            void this.tick(generation)
+        }, delay)
+    }
+
+    private async tick(generation: number): Promise<void> {
+        if (!this.running || generation !== this.generation) return
+        if (this.inFlight || !this.options.shouldProbe()) {
+            this.schedule()
+            return
+        }
+        this.inFlight = true
+        let outcome: RelayReprobeOutcome
+        try {
+            outcome = await this.options.probe()
+        } catch {
+            outcome = 'failed'
+        }
+        this.inFlight = false
+        // stop()/restart while the probe was in flight: the verdict is stale.
+        if (!this.running || generation !== this.generation) return
+        if (outcome === 'direct') {
+            this.stop()
+            return
+        }
+        if (outcome !== 'skipped') this.failureCount++
+        this.schedule()
+    }
+}