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

package/dist/mesh-tool-names.d.ts

@@ -18,10 +18,10 @@
  * Order mirrors mcp-server `ALL_MESH_TOOLS` for easy visual diffing, but the consistency
  * checks are set-based (order-insensitive).
  */
-export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_route_preview", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_queue_revise", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_create", "mesh_add_node", "mesh_attach_remote", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_config", "mesh_init", "mesh_cleanup_sessions", "mesh_task_history", "mesh_ledger_query", "mesh_note", "mesh_reconcile_ledger", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_node_slots", "driver_list", "driver_describe", "artifact_list"];
+export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_route_preview", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_queue_revise", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_create", "mesh_add_node", "mesh_reattach_source_parent", "mesh_attach_remote", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_config", "mesh_init", "mesh_cleanup_sessions", "mesh_task_history", "mesh_ledger_query", "mesh_note", "mesh_reconcile_ledger", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_node_slots", "driver_list", "driver_describe", "artifact_list", "artifact_read", "artifact_register"];
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];
 /** The count the `NN tools` barrel doc comments and consistency test assert against. */
-export declare const CANONICAL_MESH_TOOL_COUNT: 45;
+export declare const CANONICAL_MESH_TOOL_COUNT: 48;
 /**
  * Tool names retired by the 2026-09-26 tool-surface consolidation (60 → 48).
  * Every capability behind them is still reachable: each retired name maps to the

package/dist/protocol/daemon-server.d.ts

@@ -218,6 +218,7 @@ export type P2POfferWirePayload = {
     peerId: string;
     attemptId?: number;
     attemptEpoch?: string;
+    probe?: boolean;
 };
 export type P2PIceWirePayload = {
     candidate: string;
@@ -225,6 +226,7 @@ export type P2PIceWirePayload = {
     peerId: string;
     attemptId?: number;
     attemptEpoch?: string;
+    probe?: boolean;
 };
 /**
  * A dashboard-originated signal as relayed to the daemon. `peerId` is stamped
@@ -238,6 +240,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/dist/protocol/dashboard-server.d.ts

@@ -111,6 +111,7 @@ export type DashboardP2POfferWirePayload = {
     peerId?: string;
     attemptId?: number;
     attemptEpoch?: string;
+    probe?: boolean;
     sdp: string;
     type: string;
 };
@@ -119,6 +120,7 @@ export type DashboardP2PIceWirePayload = {
     peerId?: string;
     attemptId?: number;
     attemptEpoch?: string;
+    probe?: boolean;
     candidate: string;
     mid?: string;
     sdpMid?: string | null;
@@ -155,11 +157,15 @@ export declare const isDashboardToUserSessionType: (value: unknown) => value is
 export declare const DASHBOARD_P2P_SIGNAL_TYPES: readonly ["p2p_ready", "p2p_answer", "p2p_ice"];
 export type DashboardP2PSignalType = typeof DASHBOARD_P2P_SIGNAL_TYPES[number];
 export declare const isDashboardP2PSignalType: (value: unknown) => value is "p2p_ready" | "p2p_answer" | "p2p_ice";
+/** `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;
@@ -168,12 +174,14 @@ export type DashboardP2PAnswerWirePayload = {
     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/dist/relay-reprobe.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare const RELAY_REPROBE_BASE_DELAY_MS = 60000;
+export declare const RELAY_REPROBE_MAX_DELAY_MS: number;
+export declare const RELAY_REPROBE_JITTER_RATIO = 0.2;
+/** Delay before the next attempt after `failures` consecutive non-direct outcomes. */
+export declare function computeRelayReprobeDelay(failures: number, random: () => number, timing?: RelayReprobeTiming): number;
+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 declare class RelayReprobeScheduler {
+    private readonly options;
+    private handle;
+    private running;
+    private inFlight;
+    private failureCount;
+    private generation;
+    constructor(options: RelayReprobeSchedulerOptions);
+    get isRunning(): boolean;
+    get failures(): number;
+    get probing(): boolean;
+    /** Begin probing (idempotent). Call when a connection is selected as relay. */
+    start(): void;
+    /** Stop for good (direct path found, connection closed, auth epoch changed). */
+    stop(): void;
+    private schedule;
+    private tick;
+}

package/dist/worker-protocol.d.ts

@@ -30,7 +30,7 @@
  * the protocol contract the marker demarcates.
  */
 import { type MissionBrief } from './mission-brief';
-export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff", "driver_list", "driver_describe", "driver_invoke", "artifact_register"];
+export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff", "driver_list", "driver_describe", "driver_invoke", "artifact_register", "artifact_list", "artifact_read", "contract_read", "contract_observe", "contract_current"];
 export type WorkerTool = typeof WORKER_TOOLS[number];
 export declare function isWorkerTool(value: unknown): value is WorkerTool;
 /** Stable marker line so a body is never footered twice and tests can find it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.82-rc.32",
+  "version": "1.0.82-rc.34",
   "description": "ADHDev mesh-shared — pure mesh/git status normalizers shared by daemon-core and web-core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/assistant-protocol.ts

@@ -34,6 +34,8 @@ export const ASSISTANT_TOOLS = [
     'launch_defaults_set',
     'driver_list',
     'driver_describe',
+    'artifact_list',
+    'artifact_read',
 ] as const
 
 export type AssistantTool = typeof ASSISTANT_TOOLS[number]
@@ -67,6 +69,8 @@ export const ASSISTANT_VERB = {
     projectNote: 'assistant_project_note',
     launchDefaults: 'assistant_launch_defaults',
     launchDefaultsSet: 'assistant_launch_defaults_set',
+    artifactList: 'assistant_artifact_list',
+    artifactRead: 'assistant_artifact_read',
     // assistant-side daemon verbs without a tool of the same name
     launch: 'launch_assistant',
     pendingRelays: 'assistant_pending_relays',
@@ -101,6 +105,8 @@ export const ASSISTANT_TOOL_VERBS: Readonly<Record<AssistantTool, AssistantVerb>
     project_note: ASSISTANT_VERB.projectNote,
     launch_defaults: ASSISTANT_VERB.launchDefaults,
     launch_defaults_set: ASSISTANT_VERB.launchDefaultsSet,
+    artifact_list: ASSISTANT_VERB.artifactList,
+    artifact_read: ASSISTANT_VERB.artifactRead,
 }
 
 /**
@@ -164,7 +170,7 @@ export const ASSISTANT_REMOTE_FOLLOW_COMMAND = 'assistant_remote_follow' as cons
  * `assistant_remote_project` when the host's `assistantRemoteAccess` ACL is active.
  * `note`, `terminal`, and `inventory` remain strictly roster-member-only.
  */
-export const ASSISTANT_FOLLOWER_ALLOWED_OPS = ['status', 'read', 'poll', 'report', 'send'] as const
+export const ASSISTANT_FOLLOWER_ALLOWED_OPS = ['status', 'read', 'poll', 'report', 'send', 'artifact_list', 'artifact_read'] as const
 export type AssistantFollowerAllowedOp = typeof ASSISTANT_FOLLOWER_ALLOWED_OPS[number]
 
 const ASSISTANT_FOLLOWER_ALLOWED_OP_SET: ReadonlySet<string> = new Set(ASSISTANT_FOLLOWER_ALLOWED_OPS)
@@ -188,6 +194,7 @@ export interface AssistantRemoteAccessBinding {
     status: 'active' | 'revoked'
     allowedOps: readonly AssistantFollowerAllowedOp[]
     allowCoordinatorLaunch?: boolean
+    allowArtifactRead?: boolean
     grantedAt: number
     revokedAt?: number
 }
@@ -234,6 +241,7 @@ export interface FollowedRemoteProjectEntry {
     bindingRevision: number
     grantRevision: number
     allowCoordinatorLaunch?: boolean
+    allowArtifactRead?: boolean
     state: FollowedRemoteProjectState
     followedAt: number | string
     updatedAt: number | string
@@ -264,6 +272,7 @@ export interface RemoteProjectCatalogItem {
     sanitizedRepoIdentity: string | null
     coordinatorState?: 'none' | 'idle' | 'working' | 'waiting' | string
     allowCoordinatorLaunch?: boolean
+    allowArtifactRead?: boolean
     capabilities: {
         status: true
         read: true
@@ -272,6 +281,7 @@ export interface RemoteProjectCatalogItem {
         send: true
         coordinatorPresent?: boolean
         allowCoordinatorLaunch?: boolean
+        allowArtifactRead?: boolean
     }
     observedAt: number | string
 }

package/src/index.ts

@@ -48,3 +48,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/protocol/daemon-server.ts

@@ -263,8 +263,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 +278,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()
+    }
+}

package/src/worker-protocol.ts

@@ -44,6 +44,13 @@ export const WORKER_TOOLS = [
     'driver_describe',
     'driver_invoke',
     '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]