@adhdev/mesh-shared 1.0.60-rc.8 → 1.0.60

package/src/turn-ipc.ts

@@ -0,0 +1,137 @@
+/**
+ * turn-ipc — typed IPC command contracts for the six commands that replace
+ * mcp-server's direct `mesh-runtime.db` access (design §5 C2 "MCP server").
+ *
+ * Wiring-unification Phase C, workstream C-W6
+ * (docs/design/2026-09-23-wiring-unification.md §5 C2/C3, C9 row C-W6).
+ *
+ * WHY THIS FILE EXISTS
+ * ---------------------
+ * mcp-server is a second, in-process writer of `mesh-runtime.db` (~45-69
+ * direct-mutation call sites, ~54 reads, per the C-W6 brief). C2 moves every
+ * one of those call sites behind IPC, executed in the daemon that owns the
+ * turn ledger and the seqscribe node, so mcp-server never opens the SQLite
+ * file itself. This file is the WIRE CONTRACT for that IPC surface — request/
+ * response shapes, closed enums, runtime decoders — shared by the daemon-core
+ * command handlers (added with C-W6 proper; NOT this file) and the mcp-server
+ * client (`mcp-server/src/ipc/turn-commands.ts`, this workstream).
+ *
+ * The six commands (§5 C2):
+ *   - turn_observe     — submit one TurnEvidence; returns the reducer verdict.
+ *   - mesh_record      — append a content-free scalar record (`mesh.record`
+ *                         topic entry), replacing `appendLedgerEntry`.
+ *   - turn_cancel       — cancel an attempt (`cancel` evidence, source `mcp_probe`
+ *                         or `operator`).
+ *   - operator_status   — record a fire-and-forget operator/tool-call status
+ *                         (`operator_status` evidence + the former
+ *                         `recordMeshCoordinatorToolCall` log write).
+ *   - turn_query        — read attempt/event rows (own or fleet scope).
+ *   - mesh_index_query  — read `mesh_topic_index` rows (fleet-wide, replacing
+ *                         the in-memory read model / parity reads).
+ *
+ * CONTENT BOUNDARY
+ * -----------------
+ * Every request/response field is an identifier, a closed enum, a boolean, a
+ * counter or a timestamp. `turn_observe` carries a `TurnEvidence`, which is
+ * content-free by construction (`turn-evidence.ts`). `mesh_record` carries a
+ * `ProjectedScalars` payload restricted to the SAME allow-list keys
+ * `seqscribe/mesh-event-projection.ts` already reviews and ships
+ * (`PROJECTED_PAYLOAD_KEYS`, 35 keys) — this file pins a STRUCTURAL COPY of
+ * that key list (`MESH_RECORD_PAYLOAD_KEYS`) so mesh-shared does not import
+ * daemon-core (leaf constraint), with a test asserting the two lists agree.
+ * Summaries, report bodies, progress notes and modal text never travel in any
+ * of these payloads — they go to the content-class `mesh.<id>.handoff` topic
+ * and are referenced by `SummaryRef {topic, writer, seq}` (already declared
+ * in `./turn-evidence.ts`).
+ *
+ * VERSIONING
+ * -----------
+ * Every request carries `v: 1` so a future incompatible change can be
+ * detected by the responder before it tries to interpret the args.
+ *
+ * LAYOUT
+ * -------
+ * This module holds the error codes and the command registry; the per-command
+ * contracts live in ./turn-ipc-{turn,mission,queue,stats}.ts (re-exported here)
+ * over the shared guard primitives in ./turn-ipc-guards.ts.
+ */
+
+import { isRecord } from './protocol/envelope'
+import { hasOnlyKeys, makeGuard } from './turn-ipc-guards';
+
+export { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+export * from './turn-ipc-turn';
+export * from './turn-ipc-mission';
+export * from './turn-ipc-queue';
+export * from './turn-ipc-stats';
+
+// ─── error codes ────────────────────────────────────────────────────────────
+
+/**
+ * Closed error-code union every command response may carry instead of (or in
+ * addition to, for the client-side wrapper) a result.
+ *
+ *   daemon_required      — no daemon reachable (no IPC/local transport
+ *                           connection could be established). Distinct from
+ *                           every other failure: it means "there is nobody to
+ *                           ask", not "the ask failed."
+ *   turn_ledger_unavailable — a daemon answered but its turn ledger is not
+ *                           armed yet (mid-boot, mid-migration).
+ *   ledger_not_owner     — the daemon that answered does not own the
+ *                           attempt/mesh addressed by the request (routing
+ *                           mistake, or the owner changed after a reclaim).
+ */
+export const TURN_IPC_ERROR_CODES = ['daemon_required', 'turn_ledger_unavailable', 'ledger_not_owner'] as const
+export type TurnIpcErrorCode = typeof TURN_IPC_ERROR_CODES[number]
+
+export const isTurnIpcErrorCode = makeGuard(TURN_IPC_ERROR_CODES)
+
+/** Structured failure shape a responder returns instead of a result. Never thrown across the wire — the client maps it to a typed error (see mcp-server/src/ipc/turn-commands.ts). */
+export interface TurnIpcError {
+    code: TurnIpcErrorCode
+    /** Short machine-oriented detail, e.g. which daemon was expected. Never free text describing content. */
+    detail?: string
+}
+
+export function isTurnIpcError(value: unknown): value is TurnIpcError {
+    return isRecord(value) && hasOnlyKeys(value, ['code', 'detail']) && isTurnIpcErrorCode(value.code)
+        && (value.detail === undefined || typeof value.detail === 'string')
+}
+
+// ─── command registry ───────────────────────────────────────────────────────
+
+/** The complete, closed set of IPC command names this contract defines. */
+export const TURN_IPC_COMMANDS = [
+    'turn_observe',
+    'mesh_record',
+    'turn_cancel',
+    'operator_status',
+    'turn_query',
+    'mesh_index_query',
+    'mission_upsert',
+    'mission_query',
+    'note_upsert',
+    'note_forget',
+    // C-W9b additions (2026-09-24 14:00 stamp "C-W9"):
+    'tool_call_record',
+    'ledger_query',
+    'mission_list_query',
+    // C-W9a additions (the event ledger retired; the queue behind IPC):
+    'record_local',
+    'queue_query',
+    'queue_enqueue',
+    'queue_enqueue_batch',
+    'queue_cancel',
+    'queue_requeue',
+    'direct_dispatch_record',
+    'active_work_query',
+    'recovery_context_query',
+    // C-W9c additions (2026-09-24 19:00 stamp — the last mcp-server in-process
+    // daemon-core paths: mission reads, task/mission stats, orphaned-pin
+    // helpers, one prune audit):
+    'task_stats_query',
+    'prune_stale_direct',
+    'orphaned_pin_notify',
+] as const
+export type TurnIpcCommand = typeof TURN_IPC_COMMANDS[number]
+export const isTurnIpcCommand = makeGuard(TURN_IPC_COMMANDS)

package/src/types.ts

@@ -153,4 +153,12 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null
     lastActivityAt?: string | null
     isCached?: boolean
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: { delivered: boolean; reason?: string }
 }

package/src/worker-protocol.ts

@@ -0,0 +1,164 @@
+/**
+ * worker-protocol — what a delegated worker is told, and what it may call.
+ *
+ * Wiring-unification Phase F1 (docs/design/2026-09-23-wiring-unification.md §7b).
+ *
+ * Measured 2026-09-23 on the live preview ledger: 635 worker attempts in 14
+ * days, 3 `report_completion` calls. The worker MCP was delivered to every
+ * provider and never used, because nothing ever told the worker it existed —
+ * the dispatched task body carried no instruction and the coordinator prompt
+ * did not mention the worker tools at all. The only text a worker saw about
+ * its tools was the tool description.
+ *
+ * This module is the single source for BOTH sides of that contract:
+ *   - `WORKER_TOOLS` — exactly what `adhdev mcp --mode worker` advertises
+ *     (a parity test in mcp-server pins ListTools to this tuple);
+ *   - `renderWorkerProtocolFooter()` — the block appended to EVERY dispatched
+ *     task body, so a worker learns the protocol from the task itself;
+ *   - `renderCoordinatorWorkerSection()` — the matching paragraph the
+ *     coordinator prompt carries, so the coordinator expects structured reports
+ *     and stops polling for them.
+ *
+ * Wiring-unification Phase H2 adds an optional mission-brief block: when a
+ * dispatched task belongs to a mission that carries a `MissionBrief`
+ * (`./mission-brief.ts`), `renderWorkerProtocolFooter` renders it ABOVE the
+ * `WORKER_PROTOCOL_FOOTER_MARKER` line. This is deliberate placement, not an
+ * accident of insertion order: `hasWorkerProtocolFooter` / `stripWorkerProtocolFooter`
+ * both key off the marker line alone, so a body with a brief block strips
+ * identically to one without — the brief is authored content from the
+ * coordinator's point of view (like the task message itself), never part of
+ * the protocol contract the marker demarcates.
+ */
+
+import { renderMissionBriefBlock, type MissionBrief } from './mission-brief'
+import { isMeshTaskDifficulty } from './brain-routing'
+
+export const WORKER_TOOLS = [
+    'report_completion',
+    'progress_update',
+    'peer_context_pull',
+    'git_status',
+    'git_log',
+    'git_diff',
+] as const
+
+export type WorkerTool = typeof WORKER_TOOLS[number]
+
+const WORKER_TOOL_SET: ReadonlySet<string> = new Set(WORKER_TOOLS)
+
+export function isWorkerTool(value: unknown): value is WorkerTool {
+    return typeof value === 'string' && WORKER_TOOL_SET.has(value)
+}
+
+/** Stable marker line so a body is never footered twice and tests can find it. */
+export const WORKER_PROTOCOL_FOOTER_MARKER = '--- adhdev worker protocol ---'
+
+export interface WorkerProtocolFooterInput {
+    taskId?: string
+    taskMode?: string
+    difficulty?: string
+    readonly?: boolean
+    /** Number of handoff notes enclosed above the footer, when any. */
+    enclosedHandoffNotes?: number
+    /** H2: the owning mission's brief, when this task belongs to one. Rendered above the marker line — see module doc. */
+    missionBrief?: MissionBrief
+}
+
+export function hasWorkerProtocolFooter(body: string): boolean {
+    return typeof body === 'string' && body.includes(WORKER_PROTOCOL_FOOTER_MARKER)
+}
+
+/**
+ * The protocol block appended to a dispatched task. Written for the model that
+ * receives it: imperative, short, and explicit about what is NOT available so
+ * the worker does not go looking for coordinator tools.
+ */
+export function renderWorkerProtocolFooter(input: WorkerProtocolFooterInput = {}): string {
+    const briefBlock = input.missionBrief ? renderMissionBriefBlock(input.missionBrief) : null
+    const lines: string[] = briefBlock ? [briefBlock, '', WORKER_PROTOCOL_FOOTER_MARKER] : [WORKER_PROTOCOL_FOOTER_MARKER]
+    const scope: string[] = []
+    if (input.taskId) scope.push(`task ${input.taskId}`)
+    if (input.taskMode) scope.push(`mode ${input.taskMode}`)
+    // MCP-usage-audit item 2: validate against the canonical difficulty set
+    // (this package's own brain-routing vocabulary — never duplicated here)
+    // rather than rendering an internal caller's typo or stale value verbatim.
+    // The MCP tool-schema enum already blocks a bad value AT THE TOOLS; this
+    // covers internal callers that can still construct a task with one.
+    if (input.difficulty) {
+        if (isMeshTaskDifficulty(input.difficulty)) {
+            scope.push(`difficulty ${input.difficulty}`)
+        } else {
+            // eslint-disable-next-line no-console -- mesh-shared is a dependency-free
+            // leaf with no logger abstraction; this is the one place that matters.
+            console.warn(
+                `[worker-protocol] task ${input.taskId ?? '(unknown)'}: dropping invalid difficulty '${input.difficulty}' `
+                    + `from the worker footer (expected one of easy, medium, difficult, freeform)`,
+            )
+        }
+    }
+    if (input.readonly) scope.push('read-only')
+    if (scope.length) lines.push(`You are a delegated worker (${scope.join(', ')}).`)
+    else lines.push('You are a delegated worker.')
+    lines.push(
+        'When your work is finished, blocked, or has failed, call `report_completion` exactly once. '
+            + 'Its `summary` is recorded verbatim as the authoritative record of this task — your terminal is not '
+            + 'scraped for it — so state what you did, what you found, and where you left the branch.',
+        'For work that runs longer than a few minutes, call `progress_update` at natural checkpoints so the '
+            + 'coordinator can see you are alive without polling.',
+        '`peer_context_pull` shows what sibling tasks in this mission have reported; `git_status` / `git_diff` / '
+            + '`git_log` inspect your own workspace — all three REQUIRE the absolute path to it as `workspace`.',
+        'You have no coordinator tools (no `mesh_*`) by design: do not enqueue, dispatch, or restart anything. '
+            + 'If you need a decision from the coordinator, finish with `report_completion` and outcome `blocked`, '
+            + 'listing what you need in `blockers`.',
+        'On a code-changing task, `report_completion` with outcome `completed` requires `touched_files` — send '
+            + '`[]` if you changed nothing, omitting the field is what gets refused. `blocked`/`failed` never need it, '
+            + 'and a read-only task should omit it or send `[]`.',
+        'If `report_completion` is refused, the response carries `validationErrors` (or a `hint`) naming exactly '
+            + 'what to fix — correct that field and call it again; a refusal records nothing.',
+    )
+    if (input.enclosedHandoffNotes && input.enclosedHandoffNotes > 0) {
+        lines.push(
+            `The ${input.enclosedHandoffNotes} handoff note(s) above were written by agents who touched this code before you; `
+                + 'honour their conflict guidance and add your own in `handoff_notes` when you report.',
+        )
+    }
+    return lines.join('\n')
+}
+
+/**
+ * The authored text of a dispatched body: everything before the footer marker.
+ * Ledger descriptors, replay fixtures and tests compare authored text, never
+ * the protocol block.
+ */
+export function stripWorkerProtocolFooter(body: string): string {
+    if (typeof body !== 'string') return body
+    const at = body.indexOf(WORKER_PROTOCOL_FOOTER_MARKER)
+    if (at < 0) return body
+    return body.slice(0, at).replace(/\s+$/, '')
+}
+
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export function appendWorkerProtocolFooter(body: string, input: WorkerProtocolFooterInput = {}): string {
+    if (hasWorkerProtocolFooter(body)) return body
+    const trimmed = body.replace(/\s+$/, '')
+    return `${trimmed}\n\n${renderWorkerProtocolFooter(input)}`
+}
+
+/**
+ * The paragraph the COORDINATOR prompt carries about its workers. Kept next to
+ * the footer so the two halves of the protocol cannot drift apart.
+ */
+export function renderCoordinatorWorkerSection(): string {
+    return [
+        '## Workers',
+        '',
+        `Every task you dispatch is delivered with a worker protocol footer. Workers hold exactly these tools: ${WORKER_TOOLS.map((tool) => `\`${tool}\``).join(', ')} — and no \`mesh_*\` tools.`,
+        '- A worker finishes by calling `report_completion`; its structured report (outcome, summary, touched files, branch state, handoff notes) is what reaches you as the completion event. Read that report — do not re-derive the outcome from `mesh_read_chat` or the terminal unless the report is missing.',
+        '- `progress_update` from a worker arrives as a lightweight progress note. Do NOT poll `mesh_status`, `mesh_view_queue` or `mesh_read_chat` to check on a running worker; completion, progress, blocked and failure all arrive as events.',
+        '- To reach a busy worker mid-task use `mesh_notify_worker`: the memo is delivered on the worker\'s next tool call (or when it becomes idle). A worker that reports `blocked` is asking you for a decision — answer it with `mesh_send_task` to the same session.',
+        '- `mesh_status` is for node health and capacity before delegating, never for progress.',
+        '- A `code_change` task\'s declared `owned_paths` (H1) is enforced at claim time: a second `code_change` task whose `owned_paths` overlaps an already-claimed task\'s is refused rather than silently racing it. A worker\'s `report_completion.touched_files` is compared against its own task\'s declaration afterward and any mismatch is surfaced back to you as evidence — it is never a validation failure, since a worker often cannot know its exact final file list at enqueue time.',
+    ].join('\n')
+}

package/src/ws-protocol.ts

@@ -1,107 +1,112 @@
 /**
- * ws-protocol — shared string-literal unions for the daemon↔server WS surface
- * and the daemon↔dashboard P2P DataChannel surface.
+ * ws-protocol — name-only aliases for the daemon↔server WS surface and the
+ * daemon↔dashboard P2P DataChannel surface, plus the `auth_ok.payload.limits`
+ * contract.
  *
- * 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.
+ * Wiring-unification Phase A2: the typed frame unions now live in ./protocol
+ * (one file per link, payloads included). This file keeps the symbols that
+ * pre-dated them — `DaemonToServerWsMsg`, `ServerToDaemonWsMsg`,
+ * `P2PSignalingWsMsg`, `DashboardP2PMessageKind` and the two name arrays —
+ * DERIVED from the protocol unions rather than re-declared, so they cannot
+ * drift again. Before this derivation the list here said `offer|answer|ice`
+ * while the wire said `p2p_offer|p2p_answer|p2p_ice`, declared a `log` frame
+ * nothing sent or handled, omitted `daemon_mesh_command` (sent by a raw
+ * `ws.send`), and listed 12 of the ~27 P2P kinds — and nothing imported the
+ * drifted members, so nothing noticed.
  */
 
-/** 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'
-    /**
-     * seqscribe Beacon vectors (design §7.1). ONE daemon-initiated frame carries
-     * both directions — `op: 'put'` stores this node's content-free vector
-     * report, `op: 'get'` asks for the board — because the server has no way to
-     * wake itself: `DaemonConnectionDO` has neither an alarm nor a timer, and
-     * adding one would hit the most request-quota-pressured axis in the system.
-     */
-    | 'beacon_vectors';
-
-/** 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'
-    /**
-     * Reply to a `beacon_vectors` GET, correlated by `requestId`. A PUT is
-     * fire-and-forget and gets no reply at all — the beacon is advisory, so a
-     * lost report costs one debounce cycle of prediction accuracy and nothing
-     * else, which is not worth an ack round trip.
-     */
-    | 'beacon_vectors_result';
+import {
+    DAEMON_TO_SERVER_TYPES,
+    SERVER_TO_DAEMON_CONTROL_TYPES,
+    type DaemonToServerType,
+    type ServerToDaemonControlType,
+    type P2PSignalType,
+    type MeshP2PSignalType,
+    type DashboardToDaemonP2PType,
+    type DaemonToDashboardP2PType,
+} from './protocol';
 
-/** 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';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 
 /**
- * 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).
+ * Server→daemon CONTROL messages (see protocol/daemon-server.ts). The server
+ * additionally relays an open command namespace as the frame `type`
+ * (`ServerDirectCommandMsg`), which is deliberately not a member here.
  */
-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 type ServerToDaemonWsMsg = ServerToDaemonControlType;
+
+/** P2P signaling relayed through the server WS — the `p2p_`/`mesh_p2p_` spellings the wire actually uses. */
+export type P2PSignalingWsMsg = P2PSignalType | MeshP2PSignalType;
+
+/** Every dashboard↔daemon P2P DataChannel JSON kind, both directions (see protocol/dashboard-daemon-p2p.ts). */
+export type DashboardP2PMessageKind = DashboardToDaemonP2PType | DaemonToDashboardP2PType;
 
-export const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = [
-    'auth', 'status_report', 'status_heartbeat', 'status_event', 'command_result', 'error', 'agent_event', 'log',
-    'beacon_vectors',
-];
+export const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[] = DAEMON_TO_SERVER_TYPES;
 
-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',
-    'beacon_vectors_result',
-];
+export const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[] = SERVER_TO_DAEMON_CONTROL_TYPES;
 
-export function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg {
-    return typeof value === 'string' && (DAEMON_TO_SERVER_WS_MSGS as readonly string[]).includes(value);
+
+
+/**
+ * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to
+ * the daemon for client-side enforcement.
+ *
+ * WHY THIS EXISTS: the wire spelling is `maxP2Pconnections` (lowercase `c`),
+ * inherited from `PlanLimits` in the proprietary server's plan-limits.ts. The
+ * daemon-cloud consumer independently declared the same field as
+ * `maxP2PConnections` (capital `C`) and assigned it from a `payload as any`
+ * cast — so the two spellings NEVER met under a type, TypeScript had nothing
+ * to compare, and the limit arrived as `undefined` at every comparison site.
+ * `undefined !== -1` passes the "is it unlimited?" guard, then every
+ * `count >= undefined` is false: enforcement silently degraded to unlimited on
+ * all plans, in production, for months.
+ *
+ * The lesson is NOT "pick a spelling" — it is that a cross-package wire
+ * contract asserted by hand on both ends with an `any` in between cannot fail
+ * loudly. Both producer (server) and consumer (daemon-cloud) must now import
+ * THIS symbol, so a rename breaks the build on both sides instead of silently
+ * disabling a paid-plan limit. Use `normalizeAuthOkLimits()` at the parse
+ * boundary; never re-spell these fields locally.
+ */
+export interface AuthOkPlanLimits {
+    /** P2P concurrent connection count (-1 = unlimited). WIRE SPELLING — lowercase `c`. */
+    maxP2Pconnections: number;
+    /** Screenshot send interval floor (seconds). 0 = real-time. */
+    screenshotIntervalSeconds: number;
+    /** Daily screenshot usage budget (minutes). -1 = unlimited. */
+    dailyScreenshotMinutes: number;
+    /** Max connectable machines/daemons (-1 = unlimited). */
+    maxMachines: number;
 }
 
-export function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg {
-    return typeof value === 'string' && (SERVER_TO_DAEMON_WS_MSGS as readonly string[]).includes(value);
+/**
+ * Parse-boundary normalizer for `auth_ok.payload.limits`.
+ *
+ * Returns `null` when the payload carries no usable limits object, so callers
+ * keep their existing "no limits known yet" branch. Individual non-numeric or
+ * missing fields fall back to the UNLIMITED sentinel (-1) for count-style
+ * limits and 0 for the interval floor, matching how each consumer already
+ * treats "no constraint" — a malformed field must never be coerced to a
+ * MORE restrictive value than the server intended, or a server-side schema
+ * change would start throttling paying users.
+ *
+ * Accepts the capital-`C` misspelling as an input alias ONLY so a daemon
+ * talking to a mixed-version fleet cannot regress; output is always the
+ * canonical wire spelling.
+ */
+export function normalizeAuthOkLimits(raw: unknown): AuthOkPlanLimits | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const src = raw as Record<string, unknown>;
+    const num = (value: unknown, fallback: number): number =>
+        typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    return {
+        maxP2Pconnections: num(
+            src.maxP2Pconnections !== undefined ? src.maxP2Pconnections : src.maxP2PConnections,
+            -1,
+        ),
+        screenshotIntervalSeconds: num(src.screenshotIntervalSeconds, 0),
+        dailyScreenshotMinutes: num(src.dailyScreenshotMinutes, -1),
+        maxMachines: num(src.maxMachines, -1),
+    };
 }