@adhdev/mesh-shared 1.0.57 → 1.0.58-rc.10

package/dist/magi.d.ts

@@ -24,6 +24,38 @@
  * launch; `capabilityTags` route by tag when no nodeId is given; `n` is an optional
  * per-slot replica count. This is the SOLE panel-member shape — the fan-out planner
  * (buildMagiFanoutPlan) resolves a `MagiSlot[]` directly.
+ *
+ * ─── DELIBERATELY REDUCED SCHEMA — not a missing feature ─────────────────────
+ *
+ * A MagiSlot is a strict subset of a node's `NodeCapabilitySlot`. It accepts
+ * `provider` + optional `model` / `nodeId` / `capabilityTags` / `n`, and it
+ * deliberately does NOT accept the node-capability routing axes — `thinkingLevel`,
+ * `difficulty`, `maxParallel`. That asymmetry is the design, not an oversight:
+ *
+ *   - A node capability slot answers **"which work goes where"** — routing FITNESS.
+ *     Difficulty and thinking level exist there to match a task against the slot best
+ *     suited to run it.
+ *   - A MAGI panel slot answers **"who answers independently"** — cross-verification
+ *     DIVERSITY. Its whole value is that the replicas are NOT selected for fitness.
+ *
+ * Reviving the difficulty/thinking axes here would couple panel membership to routing
+ * optimization, and the best-fitting provider would win every slot. The panel would
+ * collapse toward one provider — which is precisely the failure MAGI exists to
+ * prevent, since agreement among coupled agents carries no information (see the
+ * `source_coupled` weighting in synthesis). A reduced schema is what keeps the two
+ * axes orthogonal.
+ *
+ * Consistent with that, `mesh_magi_review` enqueues every replica with a fixed
+ * `difficulty: 'freeform'` sentinel rather than a caller-chosen grade — the panel has
+ * already pinned the (node, provider) target, so any difficulty would be inert at best
+ * and would fight the panel's own slot selection at worst. To change how hard a
+ * replica thinks or how much parallelism a node grants, edit that NODE's capability
+ * slots (`mesh_node_slots_set`); it is a different axis, on purpose.
+ *
+ * Unknown keys are dropped rather than rejected, so slots written by another version
+ * stay readable. Write paths pair the normalizer with
+ * `collectIgnoredMagiSlotFields()` and report the drops as `ignoredFields`, so the
+ * reduction is visible instead of silent.
  */
 export interface MagiSlot {
     /** Optional — pin to a specific mesh node id. Absent → route by capabilityTags + provider. */

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

@@ -18,7 +18,7 @@
  * 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_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_queue_cancel", "mesh_queue_requeue", "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_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_requeue_held_events", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
+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_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_queue_cancel", "mesh_queue_requeue", "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_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_requeue_held_events", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
 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: 59;
+export declare const CANONICAL_MESH_TOOL_COUNT: 60;

package/dist/node-facts.d.ts

@@ -51,6 +51,25 @@ export interface MeshNodeFactsProviderQuota {
     status: string;
     session: MeshNodeFactsQuotaWindow | null;
     weekly: MeshNodeFactsQuotaWindow | null;
+    /** 30-day billing-style window, only for providers that report one
+     *  (cursor-cli). Promoted from the index signature 2026-08-24 so readers
+     *  can render it typed — an 'ok' cursor snapshot often carries ONLY this
+     *  axis, and a reader that looks at session/weekly alone misreads a
+     *  healthy reading as a failure. */
+    monthly?: MeshNodeFactsQuotaWindow | null;
+    /** Per-pool quota buckets, only for providers whose plan has more than one
+     *  pool (antigravity-cli: Gemini vs Claude/GPT groups, each with a 5h and
+     *  a weekly bucket). `session`/`weekly` above collapse these to the WORST
+     *  bucket per window (the routing-safe headline); the buckets carry the
+     *  per-pool detail a reader should surface. Promoted from the index
+     *  signature 2026-08-24, same reasoning as `monthly`. */
+    buckets?: Array<{
+        name?: string;
+        usedPercent?: number;
+        windowMinutes?: number;
+        resetsAt?: number | null;
+        [extra: string]: unknown;
+    }> | null;
     /** Unix ms of the snapshot itself — older than the bundle's reportedAt. */
     updatedAt: number;
     error: string | null;
@@ -136,7 +155,7 @@ export interface MeshNodeFacts {
     machineNickname?: string;
     /**
      * Per-provider quota snapshots, keyed by QuotaProvider id ('claude-cli',
-     * 'codex-cli', 'kimi'). Consumed by ROUTING as well as observation: the
+     * 'codex-cli', 'cursor-cli', 'kimi'). Consumed by ROUTING as well as observation: the
      * coordinator's quota gate / spread bonus (daemon-core mesh-quota-routing.ts,
      * thresholds in RepoMeshPolicy.quotaRouting) reads exactly this shape, so
      * field renames here are a routing-contract change, not a cosmetic one.

package/dist/semver-compare.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Semver precedence comparison — the single version-ordering primitive for the
+ * daemon's upgrade paths.
+ *
+ * Why this exists: the upgrade path used to decide "is this a no-op?" with a
+ * raw string equality check (`currentInstalled === latest`) and nothing else.
+ * Equality answers "is it the same version?" but never "which one is newer?",
+ * so any target that merely differed from the running build was installed —
+ * including one that is OLDER. That is how a node running `1.0.49-rc.2`
+ * silently got rolled back to `1.0.48`.
+ *
+ * String comparison cannot fix it either: `'1.0.49-rc.2' < '1.0.48'` is TRUE
+ * lexicographically (the '4' in "-rc.2"'s prefix never gets that far — '9' vs
+ * '8' at index 4 decides it, and even where it works `rc.10` sorts below
+ * `rc.9`). Only field-wise numeric comparison with semver §11 prerelease rules
+ * gives the right answer.
+ *
+ * This module is a PURE LEAF: zero imports, no I/O. It lives in mesh-shared
+ * (fragmentation audit) so BOTH the OSS daemon and the proprietary Workers
+ * server (`packages/server/src/utils/version-policy.ts`, previously a
+ * byte-identical independent copy) can consume ONE implementation — the two
+ * gate the same auto-update decision from opposite ends, and a drift between
+ * them can produce an unbreakable update-nag loop (server says behind, daemon
+ * gate refuses the "upgrade" as a rollback). daemon-core re-exports this from
+ * its original `version-compare.ts` path, so existing imports keep working.
+ *
+ * NOTE ON PRERELEASE SEMANTICS: this is STRICT semver §11 — `1.0.49-rc.2` is
+ * BELOW `1.0.49`, because a prerelease precedes its own release. That is the
+ * correct rule for "would installing this move me backwards?", which is the
+ * only question this module is used to answer. It deliberately differs from
+ * `oss/packages/web-core/src/utils/version-update.ts`, whose
+ * `isDaemonBehindTarget` treats an rc as up-to-date against its own base
+ * release so the dashboard does not nag preview users with an update banner.
+ * Those are two different questions; do not collapse them into one helper.
+ */
+/** Parsed semver fields. Build metadata (`+…`) is discarded: it never affects precedence (§10). */
+export interface ParsedSemver {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** Dot-separated prerelease identifiers; empty for a release build. */
+    readonly prerelease: readonly string[];
+}
+/**
+ * Parse a semver string, tolerating a leading `v` (npm/CLI output carries it
+ * inconsistently). Returns null for anything unparsable so callers can fail
+ * closed rather than guess.
+ */
+export declare function parseSemver(version: unknown): ParsedSemver | null;
+/**
+ * Compare two versions by semver precedence.
+ *
+ * @returns -1 when `a` precedes `b`, 0 when equal, 1 when `a` succeeds `b`, and
+ *   **null when either side is unparsable** — callers MUST treat null as
+ *   "direction unknown" and fail closed rather than coercing it to a number
+ *   (`null` compares as `0` in JS numeric contexts, which would read as "equal").
+ */
+export declare function compareSemver(a: unknown, b: unknown): number | null;
+/**
+ * Would installing `target` move a daemon currently on `current` BACKWARDS?
+ *
+ * Returns false when the direction cannot be established (either version
+ * unparsable) — an unknown direction must never block an upgrade, because the
+ * cost of a false block (the whole fleet can no longer be upgraded) is far
+ * higher than the cost of a missed downgrade guard. Equal versions are NOT a
+ * downgrade, so a same-version reinstall stays allowed.
+ */
+export declare function isDowngrade(current: unknown, target: unknown): boolean;

package/dist/ws-protocol.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ws-protocol — shared string-literal unions for the daemon↔server WS surface
+ * and the daemon↔dashboard P2P DataChannel surface.
+ *
+ * Fragmentation audit: these message types existed as a TypeScript union in
+ * exactly ONE package (the proprietary daemon-cloud's server-connection.ts),
+ * which is a leaf CONSUMER — the other two participants (the Workers server
+ * and OSS daemon-core, which is the primary `status_report` producer) matched
+ * bare string literals by hand. Renaming `auth_ok` server-side would compile
+ * everywhere and leave the daemon reconnecting forever. Pure literals, zero
+ * runtime deps — the textbook mesh-shared leaf.
+ *
+ * SCOPE HONESTY: this file declares the OSS-visible protocol surface. The
+ * proprietary repo's server-connection.ts remains the authority for the full
+ * ServerToDaemon command set; it should adopt these unions and extend them
+ * (`ServerToDaemonMsg | <proprietary extras>`) rather than re-declaring the
+ * shared members. Members here are the ones OSS daemon-core itself produces
+ * or matches.
+ */
+/** Messages the daemon sends UP to the Workers server over the WS bridge. */
+export type DaemonToServerWsMsg = 'auth' | 'status_report' | 'status_heartbeat' | 'status_event' | 'command_result' | 'error' | 'agent_event' | 'log';
+/** Server→daemon control messages the OSS engine reacts to. */
+export type ServerToDaemonWsMsg = 'auth_ok' | 'auth_error' | 'machine_evicted' | 'force_disconnect' | 'token_revoked' | 'version_mismatch' | 'force_update_required' | 'command' | 'agent_command' | 'resolve_action';
+/** P2P signaling relayed through the server WS. */
+export type P2PSignalingWsMsg = 'p2p_ready' | 'offer' | 'answer' | 'ice' | 'mesh_p2p_ready' | 'mesh_p2p_offer' | 'mesh_p2p_answer' | 'mesh_p2p_ice';
+/**
+ * Dashboard↔daemon P2P DataChannel JSON message kinds. Previously matched as
+ * hand-synced literals on both ends with NO shared symbol anywhere —
+ * `p2p_evicted` had exactly two occurrences repo-wide (emit + handle).
+ */
+export type DashboardP2PMessageKind = 'ping' | 'pong' | 'status_report' | 'status_event' | 'p2p_evicted' | 'command' | 'command_result' | 'command_result_chunk' | 'screenshot_start' | 'screenshot_stop' | 'pty_input' | 'pty_resize';
+export declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
+export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
+export declare function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg;
+export declare function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.57",
+  "version": "1.0.58-rc.10",
   "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/index.ts

@@ -26,3 +26,5 @@ export * from './interpolation'
 export * from './mesh-tool-names'
 export * from './mesh-status-probe'
 export * from './rpc-chunking'
+export * from './semver-compare'
+export * from './ws-protocol'

package/src/magi.ts

@@ -33,6 +33,38 @@
  * launch; `capabilityTags` route by tag when no nodeId is given; `n` is an optional
  * per-slot replica count. This is the SOLE panel-member shape — the fan-out planner
  * (buildMagiFanoutPlan) resolves a `MagiSlot[]` directly.
+ *
+ * ─── DELIBERATELY REDUCED SCHEMA — not a missing feature ─────────────────────
+ *
+ * A MagiSlot is a strict subset of a node's `NodeCapabilitySlot`. It accepts
+ * `provider` + optional `model` / `nodeId` / `capabilityTags` / `n`, and it
+ * deliberately does NOT accept the node-capability routing axes — `thinkingLevel`,
+ * `difficulty`, `maxParallel`. That asymmetry is the design, not an oversight:
+ *
+ *   - A node capability slot answers **"which work goes where"** — routing FITNESS.
+ *     Difficulty and thinking level exist there to match a task against the slot best
+ *     suited to run it.
+ *   - A MAGI panel slot answers **"who answers independently"** — cross-verification
+ *     DIVERSITY. Its whole value is that the replicas are NOT selected for fitness.
+ *
+ * Reviving the difficulty/thinking axes here would couple panel membership to routing
+ * optimization, and the best-fitting provider would win every slot. The panel would
+ * collapse toward one provider — which is precisely the failure MAGI exists to
+ * prevent, since agreement among coupled agents carries no information (see the
+ * `source_coupled` weighting in synthesis). A reduced schema is what keeps the two
+ * axes orthogonal.
+ *
+ * Consistent with that, `mesh_magi_review` enqueues every replica with a fixed
+ * `difficulty: 'freeform'` sentinel rather than a caller-chosen grade — the panel has
+ * already pinned the (node, provider) target, so any difficulty would be inert at best
+ * and would fight the panel's own slot selection at worst. To change how hard a
+ * replica thinks or how much parallelism a node grants, edit that NODE's capability
+ * slots (`mesh_node_slots_set`); it is a different axis, on purpose.
+ *
+ * Unknown keys are dropped rather than rejected, so slots written by another version
+ * stay readable. Write paths pair the normalizer with
+ * `collectIgnoredMagiSlotFields()` and report the drops as `ignoredFields`, so the
+ * reduction is visible instead of silent.
  */
 export interface MagiSlot {
     /** Optional — pin to a specific mesh node id. Absent → route by capabilityTags + provider. */

package/src/mesh-tool-names.ts

@@ -20,6 +20,7 @@
  */
 export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_status',
+    'mesh_route_preview',
     'mesh_list_nodes',
     // GRAPH-ORCHESTRATION Phase F — batch before task, mirroring ALL_MESH_TOOLS.
     'mesh_enqueue_batch',

package/src/node-facts.ts

@@ -54,6 +54,25 @@ export interface MeshNodeFactsProviderQuota {
     status: string
     session: MeshNodeFactsQuotaWindow | null
     weekly: MeshNodeFactsQuotaWindow | null
+    /** 30-day billing-style window, only for providers that report one
+     *  (cursor-cli). Promoted from the index signature 2026-08-24 so readers
+     *  can render it typed — an 'ok' cursor snapshot often carries ONLY this
+     *  axis, and a reader that looks at session/weekly alone misreads a
+     *  healthy reading as a failure. */
+    monthly?: MeshNodeFactsQuotaWindow | null
+    /** Per-pool quota buckets, only for providers whose plan has more than one
+     *  pool (antigravity-cli: Gemini vs Claude/GPT groups, each with a 5h and
+     *  a weekly bucket). `session`/`weekly` above collapse these to the WORST
+     *  bucket per window (the routing-safe headline); the buckets carry the
+     *  per-pool detail a reader should surface. Promoted from the index
+     *  signature 2026-08-24, same reasoning as `monthly`. */
+    buckets?: Array<{
+        name?: string
+        usedPercent?: number
+        windowMinutes?: number
+        resetsAt?: number | null
+        [extra: string]: unknown
+    }> | null
     /** Unix ms of the snapshot itself — older than the bundle's reportedAt. */
     updatedAt: number
     error: string | null
@@ -141,7 +160,7 @@ export interface MeshNodeFacts {
     machineNickname?: string
     /**
      * Per-provider quota snapshots, keyed by QuotaProvider id ('claude-cli',
-     * 'codex-cli', 'kimi'). Consumed by ROUTING as well as observation: the
+     * 'codex-cli', 'cursor-cli', 'kimi'). Consumed by ROUTING as well as observation: the
      * coordinator's quota gate / spread bonus (daemon-core mesh-quota-routing.ts,
      * thresholds in RepoMeshPolicy.quotaRouting) reads exactly this shape, so
      * field renames here are a routing-contract change, not a cosmetic one.
@@ -246,6 +265,7 @@ export const QUOTA_SUPPORTED_PROVIDERS: readonly string[] = [
     'antigravity-cli',
     'claude-cli',
     'codex-cli',
+    'cursor-cli',
     'grok-cli',
     'kimi',
     'opencode',

package/src/semver-compare.ts

@@ -0,0 +1,122 @@
+/**
+ * Semver precedence comparison — the single version-ordering primitive for the
+ * daemon's upgrade paths.
+ *
+ * Why this exists: the upgrade path used to decide "is this a no-op?" with a
+ * raw string equality check (`currentInstalled === latest`) and nothing else.
+ * Equality answers "is it the same version?" but never "which one is newer?",
+ * so any target that merely differed from the running build was installed —
+ * including one that is OLDER. That is how a node running `1.0.49-rc.2`
+ * silently got rolled back to `1.0.48`.
+ *
+ * String comparison cannot fix it either: `'1.0.49-rc.2' < '1.0.48'` is TRUE
+ * lexicographically (the '4' in "-rc.2"'s prefix never gets that far — '9' vs
+ * '8' at index 4 decides it, and even where it works `rc.10` sorts below
+ * `rc.9`). Only field-wise numeric comparison with semver §11 prerelease rules
+ * gives the right answer.
+ *
+ * This module is a PURE LEAF: zero imports, no I/O. It lives in mesh-shared
+ * (fragmentation audit) so BOTH the OSS daemon and the proprietary Workers
+ * server (`packages/server/src/utils/version-policy.ts`, previously a
+ * byte-identical independent copy) can consume ONE implementation — the two
+ * gate the same auto-update decision from opposite ends, and a drift between
+ * them can produce an unbreakable update-nag loop (server says behind, daemon
+ * gate refuses the "upgrade" as a rollback). daemon-core re-exports this from
+ * its original `version-compare.ts` path, so existing imports keep working.
+ *
+ * NOTE ON PRERELEASE SEMANTICS: this is STRICT semver §11 — `1.0.49-rc.2` is
+ * BELOW `1.0.49`, because a prerelease precedes its own release. That is the
+ * correct rule for "would installing this move me backwards?", which is the
+ * only question this module is used to answer. It deliberately differs from
+ * `oss/packages/web-core/src/utils/version-update.ts`, whose
+ * `isDaemonBehindTarget` treats an rc as up-to-date against its own base
+ * release so the dashboard does not nag preview users with an update banner.
+ * Those are two different questions; do not collapse them into one helper.
+ */
+
+/** Parsed semver fields. Build metadata (`+…`) is discarded: it never affects precedence (§10). */
+export interface ParsedSemver {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** Dot-separated prerelease identifiers; empty for a release build. */
+    readonly prerelease: readonly string[];
+}
+
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const NUMERIC_IDENTIFIER = /^\d+$/;
+
+/**
+ * Parse a semver string, tolerating a leading `v` (npm/CLI output carries it
+ * inconsistently). Returns null for anything unparsable so callers can fail
+ * closed rather than guess.
+ */
+export function parseSemver(version: unknown): ParsedSemver | null {
+    if (typeof version !== 'string') return null;
+    const match = version.trim().replace(/^v/, '').match(SEMVER_PATTERN);
+    if (!match) return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ? match[4].split('.') : [],
+    };
+}
+
+/**
+ * Semver §11 prerelease precedence: a release outranks its own prereleases;
+ * numeric identifiers compare numerically (so rc.10 > rc.9) and rank below
+ * alphanumeric ones; alphanumerics compare lexically; a shorter identifier
+ * list ranks below an otherwise-equal longer one.
+ */
+function comparePrerelease(a: readonly string[], b: readonly string[]): number {
+    if (a.length === 0 && b.length === 0) return 0;
+    // An empty prerelease list means "release build", which outranks any prerelease.
+    if (a.length === 0) return 1;
+    if (b.length === 0) return -1;
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === idB) continue;
+        const numA = NUMERIC_IDENTIFIER.test(idA);
+        const numB = NUMERIC_IDENTIFIER.test(idB);
+        if (numA && numB) return Number(idA) < Number(idB) ? -1 : 1;
+        if (numA) return -1;
+        if (numB) return 1;
+        return idA < idB ? -1 : 1;
+    }
+    return a.length === b.length ? 0 : (a.length < b.length ? -1 : 1);
+}
+
+/**
+ * Compare two versions by semver precedence.
+ *
+ * @returns -1 when `a` precedes `b`, 0 when equal, 1 when `a` succeeds `b`, and
+ *   **null when either side is unparsable** — callers MUST treat null as
+ *   "direction unknown" and fail closed rather than coercing it to a number
+ *   (`null` compares as `0` in JS numeric contexts, which would read as "equal").
+ */
+export function compareSemver(a: unknown, b: unknown): number | null {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb) return null;
+    if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+    if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+    if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+    return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+
+/**
+ * Would installing `target` move a daemon currently on `current` BACKWARDS?
+ *
+ * Returns false when the direction cannot be established (either version
+ * unparsable) — an unknown direction must never block an upgrade, because the
+ * cost of a false block (the whole fleet can no longer be upgraded) is far
+ * higher than the cost of a missed downgrade guard. Equal versions are NOT a
+ * downgrade, so a same-version reinstall stays allowed.
+ */
+export function isDowngrade(current: unknown, target: unknown): boolean {
+    const direction = compareSemver(target, current);
+    if (direction === null) return false;
+    return direction < 0;
+}

package/src/ws-protocol.ts

@@ -0,0 +1,90 @@
+/**
+ * ws-protocol — shared string-literal unions for the daemon↔server WS surface
+ * and the daemon↔dashboard P2P DataChannel surface.
+ *
+ * Fragmentation audit: these message types existed as a TypeScript union in
+ * exactly ONE package (the proprietary daemon-cloud's server-connection.ts),
+ * which is a leaf CONSUMER — the other two participants (the Workers server
+ * and OSS daemon-core, which is the primary `status_report` producer) matched
+ * bare string literals by hand. Renaming `auth_ok` server-side would compile
+ * everywhere and leave the daemon reconnecting forever. Pure literals, zero
+ * runtime deps — the textbook mesh-shared leaf.
+ *
+ * SCOPE HONESTY: this file declares the OSS-visible protocol surface. The
+ * proprietary repo's server-connection.ts remains the authority for the full
+ * ServerToDaemon command set; it should adopt these unions and extend them
+ * (`ServerToDaemonMsg | <proprietary extras>`) rather than re-declaring the
+ * shared members. Members here are the ones OSS daemon-core itself produces
+ * or matches.
+ */
+
+/** Messages the daemon sends UP to the Workers server over the WS bridge. */
+export type DaemonToServerWsMsg =
+    | 'auth'
+    | 'status_report'
+    | 'status_heartbeat'
+    | 'status_event'
+    | 'command_result'
+    | 'error'
+    | 'agent_event'
+    | 'log';
+
+/** Server→daemon control messages the OSS engine reacts to. */
+export type ServerToDaemonWsMsg =
+    | 'auth_ok'
+    | 'auth_error'
+    | 'machine_evicted'
+    | 'force_disconnect'
+    | 'token_revoked'
+    | 'version_mismatch'
+    | 'force_update_required'
+    | 'command'
+    | 'agent_command'
+    | 'resolve_action';
+
+/** P2P signaling relayed through the server WS. */
+export type P2PSignalingWsMsg =
+    | 'p2p_ready'
+    | 'offer'
+    | 'answer'
+    | 'ice'
+    | 'mesh_p2p_ready'
+    | 'mesh_p2p_offer'
+    | 'mesh_p2p_answer'
+    | 'mesh_p2p_ice';
+
+/**
+ * Dashboard↔daemon P2P DataChannel JSON message kinds. Previously matched as
+ * hand-synced literals on both ends with NO shared symbol anywhere —
+ * `p2p_evicted` had exactly two occurrences repo-wide (emit + handle).
+ */
+export type DashboardP2PMessageKind =
+    | 'ping'
+    | 'pong'
+    | 'status_report'
+    | 'status_event'
+    | 'p2p_evicted'
+    | 'command'
+    | 'command_result'
+    | 'command_result_chunk'
+    | 'screenshot_start'
+    | 'screenshot_stop'
+    | 'pty_input'
+    | 'pty_resize';
+
+export const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = [
+    'auth', 'status_report', 'status_heartbeat', 'status_event', 'command_result', 'error', 'agent_event', 'log',
+];
+
+export const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[] = [
+    'auth_ok', 'auth_error', 'machine_evicted', 'force_disconnect', 'token_revoked',
+    'version_mismatch', 'force_update_required', 'command', 'agent_command', 'resolve_action',
+];
+
+export function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg {
+    return typeof value === 'string' && (DAEMON_TO_SERVER_WS_MSGS as readonly string[]).includes(value);
+}
+
+export function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg {
+    return typeof value === 'string' && (SERVER_TO_DAEMON_WS_MSGS as readonly string[]).includes(value);
+}