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

package/dist/turn-ipc-turn.d.ts

@@ -0,0 +1,176 @@
+/**
+ * turn-ipc — the turn-ledger commands: turn_observe, mesh_record, turn_cancel,
+ * operator_status, turn_query, mesh_index_query. Part of the turn-ipc wire
+ * contract (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+import { type TurnEvidence, type TurnAttemptRef, type TurnOutcome, type ProjectedScalars, type TurnReason, type TurnEvidenceKind } from './turn-evidence';
+/** Reducer verdict, mirrored from the C1 reducer's `reduce()` return shape. */
+export declare const TURN_OBSERVE_VERDICTS: readonly ["applied", "recorded", "rejected"];
+export type TurnObserveVerdict = typeof TURN_OBSERVE_VERDICTS[number];
+export interface TurnObserveRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    evidence: TurnEvidence;
+}
+export interface TurnObserveResponse {
+    verdict: TurnObserveVerdict;
+    attemptRef: TurnAttemptRef;
+    /** Present only when the evidence committed the attempt (verdict 'applied' + a terminal-class kind). */
+    outcome?: TurnOutcome;
+}
+export declare function decodeTurnObserveRequest(value: unknown): TurnObserveRequest | null;
+export declare function decodeTurnObserveResponse(value: unknown): TurnObserveResponse | null;
+/**
+ * Structural pin of `seqscribe/mesh-event-projection.ts` `PROJECTED_PAYLOAD_KEYS`
+ * (daemon-core; this leaf cannot import it). A test in this package's test
+ * suite AND a daemon-core test each assert their list equals this one — see
+ * `mesh-shared/test/turn-ipc.test.ts` and the C-W6 report's break-once table.
+ * Adding a key here is the SAME assertion as adding it there: non-content
+ * (identifier, enum, boolean, or counter), never free text.
+ */
+export declare const MESH_RECORD_PAYLOAD_KEYS: readonly ["taskId", "deliveryId", "attemptId", "missionId", "checkpointId", "promptId", "providerSessionId", "targetNoteId", "nodeId", "sessionId", "providerType", "transport", "attemptedSessionId", "holderSessionId", "reason", "status", "outcome", "terminalKind", "event", "source", "intentionalStopReason", "retryable", "rebound", "forced", "fallback", "membershipRemoved", "requestedForce", "removedByRemoteDaemon", "completedViaReady", "intentional", "weak", "attempt", "attemptCount", "count"];
+/** Maximum length of any string value in a `mesh_record` payload (mirrors `MAX_PROJECTED_STRING`). */
+export declare const MAX_MESH_RECORD_STRING = 200;
+export interface MeshRecordRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** The original ledger `kind` string (daemon-core `MeshLedgerKind`; mesh-shared cannot import that union, so it is an identifier here). */
+    ledgerKind: string;
+    nodeId?: string;
+    sessionId?: string;
+    taskId?: string;
+    /** Restricted to `MESH_RECORD_PAYLOAD_KEYS` — an unknown key is a decode failure, not a silently dropped field. */
+    payload: ProjectedScalars;
+}
+export interface MeshRecordResponse {
+    /** `mesh.<id>.events` append coordinates, for callers that need to reference the entry (e.g. a `ref`'d handoff). */
+    eventId: string;
+    seq: number;
+}
+/** Every payload key must be a member of `MESH_RECORD_PAYLOAD_KEYS` — the allow-list boundary at the wire. */
+export declare function isMeshRecordPayload(value: unknown): value is ProjectedScalars;
+export declare function decodeMeshRecordRequest(value: unknown): MeshRecordRequest | null;
+export declare function decodeMeshRecordResponse(value: unknown): MeshRecordResponse | null;
+export interface TurnCancelRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    /** Exactly one of the two must be present — the decoder rejects both-or-neither. */
+    attemptId?: string;
+    taskId?: string;
+    reason: TurnReason;
+}
+export interface TurnCancelResponse {
+    attemptRef: TurnAttemptRef;
+    verdict: TurnObserveVerdict;
+}
+export declare function decodeTurnCancelRequest(value: unknown): TurnCancelRequest | null;
+export declare function decodeTurnCancelResponse(value: unknown): TurnCancelResponse | null;
+/**
+ * Fire-and-forget operator/tool-call status record — replaces
+ * `recordMeshCoordinatorToolCall` (10 sites, `mesh_tool_call_log`) and doubles
+ * as the `operator_status` evidence kind's wire shape.
+ *
+ * NAMING NOTE (flagged for the C-W6 implementer, see report §"mismatch"):
+ * the C-W6 brief's DELIVERABLES describes this request as
+ * `{taskId, status: MeshTaskStatus, reason}`, but C1's `operator_status`
+ * evidence kind (`turn-evidence.ts` `OPERATOR_STATUSES`) is the closed
+ * 2-value set `'completed' | 'failed'` — a verdict on an operator ACTION, not
+ * a `MeshTaskStatus` (5-value queue-row status: pending/assigned/completed/
+ * failed/cancelled). This contract follows `turn-evidence.ts` because that is
+ * what the C1 reducer actually consumes for this evidence kind; using the
+ * 5-value `MeshTaskStatus` here would let this request carry `pending` or
+ * `assigned`, which the reducer has no transition for.
+ */
+export declare const OPERATOR_STATUS_VALUES: readonly ["completed", "failed"];
+export type OperatorStatusValue = typeof OPERATOR_STATUS_VALUES[number];
+export declare const OPERATOR_STATUS_REASON_VALUES: readonly ["operator_update", "refine_terminal", "validation_terminal"];
+export type OperatorStatusReasonValue = typeof OPERATOR_STATUS_REASON_VALUES[number];
+export interface OperatorStatusRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    taskId: string;
+    status: OperatorStatusValue;
+    reason: OperatorStatusReasonValue;
+}
+/** Acknowledgement only — this command is fire-and-forget by design (the daemon owns rate-limiting the underlying log). */
+export interface OperatorStatusResponse {
+    accepted: true;
+}
+export declare function decodeOperatorStatusRequest(value: unknown): OperatorStatusRequest | null;
+export declare function decodeOperatorStatusResponse(value: unknown): OperatorStatusResponse | null;
+/** Row shape returned by `turn_query` — scalar projection of a `turn_attempts` row (C3 schema), never `data_json`/`payload_json` content. */
+export interface TurnQueryAttemptRow {
+    attemptId: string;
+    generation: number;
+    meshId?: string;
+    taskId?: string;
+    sessionId: string;
+    nodeId?: string;
+    providerType?: string;
+    state: string;
+    terminalOutcome?: TurnOutcome;
+    terminalReason?: TurnReason;
+    acceptedAt: number;
+    terminalAt?: number;
+}
+/** Row shape returned by `turn_query` for the event stream — scalar projection of a `turn_events` row, `payload_json` NEVER included. */
+export interface TurnQueryEventRow {
+    eventId: string;
+    attemptId?: string;
+    generation?: number;
+    sessionId: string;
+    kind: TurnEvidenceKind;
+    source: string;
+    verdict: TurnObserveVerdict | 'forwarded';
+    atMs: number;
+}
+export interface TurnQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId?: string;
+    attemptId?: string;
+    sessionId?: string;
+    state?: string;
+    since?: number;
+    tail?: number;
+}
+export interface TurnQueryResponse {
+    attempts: readonly TurnQueryAttemptRow[];
+    events: readonly TurnQueryEventRow[];
+    /** C7-5: set while `mesh.<id>.events` replication is behind for this mesh — the caller must not treat a fleet-scope answer as complete. */
+    replicationPending?: boolean;
+}
+export declare function decodeTurnQueryRequest(value: unknown): TurnQueryRequest | null;
+export declare function decodeTurnQueryResponse(value: unknown): TurnQueryResponse | null;
+export declare const MESH_INDEX_QUERY_WRITER_SCOPES: readonly ["own", "fleet"];
+export type MeshIndexQueryWriterScope = typeof MESH_INDEX_QUERY_WRITER_SCOPES[number];
+export interface MeshIndexQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    ledgerKind?: string;
+    sessionId?: string;
+    taskId?: string;
+    writer?: MeshIndexQueryWriterScope;
+    since?: number;
+    tail?: number;
+}
+/** Row shape returned by `mesh_index_query` — a `mesh_topic_index` row (C3 schema). */
+export interface MeshTopicIndexRow {
+    writer: string;
+    seq: number;
+    meshId: string;
+    eventId: string;
+    kind: string;
+    ledgerKind?: string;
+    taskId?: string;
+    sessionId?: string;
+    nodeId?: string;
+    atMs: number;
+    payload: ProjectedScalars;
+}
+export interface MeshIndexQueryResponse {
+    rows: readonly MeshTopicIndexRow[];
+    /** C7-5: true while `mesh.<id>.events` replication is behind for this mesh. */
+    replicationPending?: boolean;
+}
+export declare function decodeMeshIndexQueryRequest(value: unknown): MeshIndexQueryRequest | null;
+export declare function isMeshIndexQueryResponse(value: unknown): value is MeshIndexQueryResponse;
+export declare function decodeMeshIndexQueryResponse(value: unknown): MeshIndexQueryResponse | null;

package/dist/turn-ipc.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+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';
+/**
+ * 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 declare const TURN_IPC_ERROR_CODES: readonly ["daemon_required", "turn_ledger_unavailable", "ledger_not_owner"];
+export type TurnIpcErrorCode = typeof TURN_IPC_ERROR_CODES[number];
+export declare const isTurnIpcErrorCode: (value: unknown) => value is "daemon_required" | "turn_ledger_unavailable" | "ledger_not_owner";
+/** 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 declare function isTurnIpcError(value: unknown): value is TurnIpcError;
+/** The complete, closed set of IPC command names this contract defines. */
+export declare const TURN_IPC_COMMANDS: readonly ["turn_observe", "mesh_record", "turn_cancel", "operator_status", "turn_query", "mesh_index_query", "mission_upsert", "mission_query", "note_upsert", "note_forget", "tool_call_record", "ledger_query", "mission_list_query", "record_local", "queue_query", "queue_enqueue", "queue_enqueue_batch", "queue_cancel", "queue_requeue", "direct_dispatch_record", "active_work_query", "recovery_context_query", "task_stats_query", "prune_stale_direct", "orphaned_pin_notify"];
+export type TurnIpcCommand = typeof TURN_IPC_COMMANDS[number];
+export declare const isTurnIpcCommand: (value: unknown) => value is "prune_stale_direct" | "operator_status" | "turn_observe" | "mesh_record" | "turn_cancel" | "turn_query" | "mesh_index_query" | "mission_upsert" | "mission_query" | "note_upsert" | "note_forget" | "tool_call_record" | "ledger_query" | "mission_list_query" | "record_local" | "queue_query" | "queue_enqueue" | "queue_enqueue_batch" | "queue_cancel" | "queue_requeue" | "direct_dispatch_record" | "active_work_query" | "recovery_context_query" | "task_stats_query" | "orphaned_pin_notify";

package/dist/types.d.ts

@@ -136,4 +136,15 @@ 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/dist/worker-protocol.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { type MissionBrief } from './mission-brief';
+export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff"];
+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. */
+export declare 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 declare function hasWorkerProtocolFooter(body: string): boolean;
+/**
+ * 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 declare function renderWorkerProtocolFooter(input?: WorkerProtocolFooterInput): string;
+/**
+ * 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 declare function stripWorkerProtocolFooter(body: string): string;
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export declare function appendWorkerProtocolFooter(body: string, input?: WorkerProtocolFooterInput): string;
+/**
+ * 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 declare function renderCoordinatorWorkerSection(): string;

package/dist/ws-protocol.d.ts

@@ -1,50 +1,78 @@
 /**
- * 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'
+import { type DaemonToServerType, type ServerToDaemonControlType, type P2PSignalType, type MeshP2PSignalType, type DashboardToDaemonP2PType, type DaemonToDashboardP2PType } from './protocol';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 /**
- * 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.
+ * 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.
  */
- | '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'
+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 declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
+export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
 /**
- * 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.
+ * `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.
  */
- | 'beacon_vectors_result';
-/** 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';
+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;
+}
 /**
- * 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).
+ * 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 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;
+export declare function normalizeAuthOkLimits(raw: unknown): AuthOkPlanLimits | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.8",
+  "version": "1.0.60",
   "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/brain-routing.ts

@@ -5,10 +5,8 @@
  * per-difficulty "brain" preset resolves that into a concrete provider / model /
  * thinking-level for the launched session. The goal is token economy: an `easy`
  * task runs on a cheaper model at low reasoning effort; a `difficult` task gets a
- * stronger model at high effort. This is a separate axis from MAGI's review kinds
- * (rca/design/…) — MAGI fans out review replicas; this picks the single brain that
- * *executes* a task — but it reuses the same slot shape (provider/model) and the
- * same machine-local storage (`~/.adhdev/meshes.json`).
+ * stronger model at high effort. This picks the single brain that *executes* a
+ * task, stored machine-local (`~/.adhdev/meshes.json`).
  */
 
 /** The fixed difficulty axis the coordinator classifies a task into. */
@@ -33,8 +31,8 @@ export interface BrainSlot {
 
 /**
  * Per-difficulty brain bindings for ONE mesh, stored machine-local in
- * `~/.adhdev/meshes.json` under that mesh's entry (`meshes[].difficultyBrains`,
- * sibling of `magiKindPanels`). The scope is per mesh: two meshes on the same
+ * `~/.adhdev/meshes.json` under that mesh's entry (`meshes[].difficultyBrains`).
+ * The scope is per mesh: two meshes on the same
  * machine hold independent presets, so one can pin `difficult` to a cheaper model
  * without changing what any other mesh runs. (It formerly sat at the config root
  * keyed by difficulty alone — and since this map picks the MODEL a task runs on,
@@ -66,7 +64,7 @@ export function isMeshTaskDifficulty(value: unknown): value is MeshTaskDifficult
  *      a value that should never have been stamped provider-blind.
  *
  *   2. IT FOUGHT THE SLOTS. Operators express model choice per node via
- *      capability slots (`mesh_node_slots_set`), which know the provider. A
+ *      capability slots (`mesh_node_slots` action "set"), which know the provider. A
  *      mesh-wide preset that also picks a model duplicated that decision from a
  *      position with strictly less information, and needed the modelSource
  *      ('explicit' vs 'preset') precedence machinery plus a fail-closed
@@ -112,14 +110,14 @@ export function normalizeDifficultyBrainMap(raw: unknown): DifficultyBrainMap {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Node capability slots (ORCHESTRATION_NODE_SLOTS.md)
+// Node capability slots (node capability slots design, 2026-07-09)
 //
 // A node's "Preferred AI tools" list is redefined as an ordered array of
 // capability slots. Each slot bundles what used to be scattered across
 // providerPriority (order), a per-provider maxParallel cap, and the
 // the owning mesh's difficultyBrains (difficulty → model/thinking). Slot order =
-// preference. This single profile is the source of truth for task routing, MAGI
-// fan-out, and orchestrator-proposed edits.
+// preference. This single profile is the source of truth for task routing and
+// orchestrator-proposed edits.
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -252,7 +250,7 @@ export function deriveSlotsFromLegacy(input: {
  * The reverse direction of deriveSlotsFromLegacy: derive the legacy
  * `providerPriority` order from capability slots — each slot's provider, in
  * first-appearance order, de-duplicated. Slot order = preference is the settled
- * slots semantics (ORCHESTRATION_NODE_SLOTS.md), so this is what readers of the
+ * slots semantics (node capability slots design, 2026-07-09), so this is what readers of the
  * legacy `policy.providerPriority` field must fall back to when a node declares
  * slots but no explicit providerPriority (otherwise such a node reads as
  * unlaunchable even though its slots fully determine the preference order).

package/src/git-diff.ts

@@ -0,0 +1,48 @@
+/**
+ * Projection of a daemon `git_diff_file` answer into the per-file row the MCP
+ * `git_diff` tool and the cloud git-diff shortcut both return: the diff text
+ * capped at `maxLines` (with a visible truncation marker), plus the file's
+ * change metadata from the diff summary.
+ */
+
+import { readRecord } from './json'
+
+export interface GitFileDiffRow {
+    path: string
+    old_path?: string | null
+    status?: string
+    diff: string
+    truncated: boolean
+    binary: boolean
+    error?: string
+}
+
+/** Cap diff text at `maxLines`; a truncated diff ends with a `... (truncated)` marker line. */
+function truncateDiffText(text: string, maxLines: number): { diff: string; truncated: boolean } {
+    const lines = text.split('\n')
+    const truncated = lines.length > maxLines
+    return {
+        diff: truncated ? lines.slice(0, maxLines).join('\n') + '\n... (truncated)' : text,
+        truncated,
+    }
+}
+
+/** One changed file's row from its `git_diff_file` answer (either `{ diff: {...} }` or the bare diff record). */
+export function projectFileDiffRow(
+    file: { path: string; oldPath?: string | null; status?: string },
+    rawResult: unknown,
+    maxLines: number,
+): GitFileDiffRow {
+    const raw = readRecord(rawResult)
+    const d = readRecord(raw.diff ?? rawResult)
+    const text = typeof d.diff === 'string' ? d.diff : ''
+    const { diff, truncated } = truncateDiffText(text, maxLines)
+    return {
+        path: file.path,
+        old_path: file.oldPath ?? null,
+        status: file.status ?? 'M',
+        diff,
+        truncated,
+        binary: typeof d.binary === 'boolean' ? d.binary : false,
+    }
+}

package/src/index.ts

@@ -19,7 +19,7 @@ export * from './node-facts'
 export * from './workspace-normalize'
 export * from './daemon-normalize'
 export * from './git-summarize'
-export * from './magi'
+export * from './git-diff'
 export * from './brain-routing'
 export * from './slot-proposal'
 export * from './interpolation'
@@ -29,3 +29,14 @@ export * from './rpc-chunking'
 export * from './semver-compare'
 export * from './ws-protocol'
 export * from './interactive-prompt-constants'
+export * from './session-status'
+export * from './mesh-vocabulary'
+export * from './outbound-message'
+export * from './worker-protocol'
+export * from './protocol'
+export * from './turn-evidence'
+export * from './session-launch'
+export * from './turn-ipc'
+export * from './path-ownership'
+export * from './mission-brief'
+export * from './keyed-doc-delta'

package/src/interpolation.ts

@@ -1,21 +1,3 @@
-/**
- * Pure {{key}} template interpolation shared by the mesh command paths.
- *
- * Hoisted from packages/daemon-cloud/src/mesh/mesh-interpolation.ts — the
- * substitution is transport-agnostic (plain string/object work), so it belongs
- * in the dependency-free mesh-shared leaf where standalone can reuse it too.
- * The substitution semantics are byte-for-byte identical to the prior cloud copy.
- */
-export function interpolateArgs(
-  args: Record<string, unknown>,
-  context: Record<string, unknown>,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(args)) {
-    result[k] = typeof v === 'string' ? interpolateString(v, context) : v;
-  }
-  return result;
-}
 
 export function interpolateString(template: string, ctx: Record<string, unknown>): string {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {