@opencorelabs/lucidity 0.1.0

package/node_modules/@lucidity/shared/src/schemas/harness.ts

@@ -0,0 +1,779 @@
+import { z } from 'zod';
+import {
+  SENDER_KINDS,
+  HARNESS_REQUEST_KINDS,
+  APPROVAL_DECISIONS,
+  WORKSPACE_MODES,
+  WORKER_STATUSES,
+  EFFORT_LEVELS,
+  DELIVERY_CHANNELS,
+  AGENT_MODES,
+} from '../constants.js';
+
+/**
+ * The Lucid harness wire contract (M6). One shape that every transport speaks:
+ * phone → hosted room → local daemon (free) or hosted executor (Pro). The room
+ * is transport-only; it never inspects payloads. Both the buffered
+ * (request/response) and streaming (SSE) forms are defined here so the same
+ * envelope works regardless of how a reply is delivered.
+ */
+
+// ---- Requests (phone → room → engine) -------------------------------------
+
+// Fields shared by every request, whatever the kind. `id` correlates the reply
+// (or stream) back to the caller so one socket can multiplex concurrent turns;
+// `stream` opts into SSE token streaming instead of a single buffered reply.
+const HarnessRequestBase = z.object({
+  id: z.uuidv7(),
+  senderKind: z.enum(SENDER_KINDS).default('human'),
+  stream: z.boolean().optional(),
+});
+
+// A photo attached to an ask/code turn — a base64 vision input sent inline through
+// the (opaque) room, then handed to the model as a content block. Capped hard: the
+// room buffers each frame in memory for replay, so an unbounded payload is a memory
+// risk. The phone downscales well under these ceilings (≈1568px long edge, JPEG)
+// before sending; these are the safety ceiling, not the target. Media types are the
+// four Anthropic vision accepts.
+export const HarnessImageSchema = z.object({
+  mediaType: z.enum(['image/jpeg', 'image/png', 'image/gif', 'image/webp']),
+  /** Raw base64 (no `data:` prefix). ~5M chars ≈ 3.7MB decoded, above any downscaled photo. */
+  dataBase64: z.string().min(1).max(5_000_000),
+});
+
+// At most a handful per turn — keeps the worst-case replay-buffer footprint bounded.
+const harnessImagesField = z.array(HarnessImageSchema).max(6).optional();
+
+// One-shot question to Lucid ("Ask Lucid"). The only kind that carries free text.
+export const AskRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('ask'),
+  prompt: z.string().min(1).max(8000),
+  /** Photos attached to the question (vision). Optional; absent on a text-only ask. */
+  images: harnessImagesField,
+  /** Claude Code session id to continue (conversation continuity via --resume). */
+  resume: z.string().optional(),
+});
+
+// Today's briefing. The engine derives the content from the user's tasks, so no
+// input beyond the envelope is needed.
+export const BriefingRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('briefing'),
+});
+
+// Read Lucid's agent journal (past runs it logged). Cursor-paginated newest
+// first; `before` is an ISO timestamp echoed from a prior page's `nextBefore`.
+export const JournalRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('journal'),
+  limit: z.number().int().positive().max(100).optional(),
+  before: z.string().optional(),
+});
+
+// Drive Claude Code in a repo on the user's machine (M7). `repoId` is resolved
+// server-side through the daemon's allowlist to an absolute path — the phone
+// never sends a filesystem path.
+export const CodeRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('code'),
+  repoId: z.string().min(1),
+  prompt: z.string().min(1).max(8000),
+  /** Photos attached to the request (e.g. a screenshot of the bug). Optional. */
+  images: harnessImagesField,
+  /** Claude Code session id to continue — threads both the conversation (--resume)
+   *  and the files (re-attach the session's lucid/<repoId> branch) across turns. */
+  resume: z.string().optional(),
+  /** Conductor worker id (a fleet subtask's id). Present when the phone drills into one
+   *  worker of a fan-out and sends it a follow-up turn: the daemon runs it in that worker's
+   *  isolated `fleet/<repoId>/<workerId>` worktree, on its own lane. Absent → the bare repo
+   *  session, exactly as before. */
+  workerId: z.uuidv7().optional(),
+  /** Where to do the work (#121). Absent → 'worktree', so a daemon on this schema
+   *  still understands a phone that predates the mode picker. The daemon rejects
+   *  'in-place' when its config sets `allowInPlace: false`. */
+  mode: z.enum(WORKSPACE_MODES).optional(),
+  /** The branch the phone believes is checked out, for an `in-place` turn (#121). The phone's
+   *  repo list is a cache — the user can `git checkout` on the Mac between its last refresh
+   *  and this turn — so the daemon rejects the turn when reality disagrees, rather than
+   *  committing onto a branch nobody was shown. Absent → no check. */
+  expectedBranch: z.string().optional(),
+});
+
+// List the repos this daemon will code in (its allowlist ids) — powers the phone's repo picker.
+export const RepoListRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('repos'),
+});
+
+// List the open GitHub PRs for a repo (the Code tab's PR chip + repo-wide list). The daemon
+// resolves them via the `gh` CLI on the Mac (the phone can't) and reports the session's own
+// branch so the phone can pick out "this session's" PR. `mode` decides which branch that is.
+export const ListPrsRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('prs'),
+  repoId: z.string().min(1),
+  mode: z.enum(WORKSPACE_MODES).optional(),
+});
+
+// Clone a new repo from the phone (#78). The phone sends a git URL — never a path;
+// the daemon clones into its configured workspaceRoot and it becomes pickable.
+export const CloneRepoRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('clone'),
+  url: z.string().min(1).max(2000),
+});
+
+// ---- Conductor (a fleet of coding agents) ---------------------------------
+
+// One worker in a fan-out plan — a single coding lane. Its `workerId` is the fleet
+// subtask's uuid AND the stream id its code frames arrive under (both uuidv7), so a
+// worker reuses the whole existing code-turn pipeline: the phone routes any frame whose
+// `requestId` equals a known `workerId` into that worker's lane. `ownedPaths` is the
+// files/globs this worker may touch (the ownership map that prevents two lanes colliding);
+// `mergeOrder` (lower first) mirrors the subtask's priority and decides integration order.
+export const FleetWorkerSchema = z.object({
+  workerId: z.uuidv7(),
+  title: z.string().min(1).max(200),
+  brief: z.string().min(1).max(8000),
+  ownedPaths: z.array(z.string().max(400)).max(200),
+  mergeOrder: z.number().int(),
+});
+
+// The lead's decomposition of a goal — what the phone renders as the Fan-out card, and
+// what it sends back (possibly edited) to execute. `overlaps` are the ⚠ pairs whose owned
+// paths intersect, so the card can warn and the runner can force those two to serialize.
+export const FleetPlanSchema = z.object({
+  goal: z.string().min(1).max(500),
+  /** The parent Lucidity task (the goal); each worker is a subtask of it. Set once the
+   *  daemon has created the task graph (dogfood); absent on a freshly-proposed plan. */
+  parentTaskId: z.uuidv7().optional(),
+  workers: z.array(FleetWorkerSchema).min(1).max(16),
+  overlaps: z
+    .array(
+      z.object({
+        a: z.uuidv7(),
+        b: z.uuidv7(),
+        paths: z.array(z.string().max(400)).max(200),
+      }),
+    )
+    .max(120) // at most C(16,2) pairs for the 16-worker ceiling
+    .optional(),
+  /** How many workers may run at once (quota guard). Absent → the daemon's default cap. */
+  maxParallel: z.number().int().positive().max(16).optional(),
+});
+
+// Phone → daemon. Four phases over one request kind:
+//  - `plan`: decompose `prompt` (the goal) → one `fleet_plan` event. Nothing runs or is created,
+//    so the user edits or discards freely.
+//  - `setup`: materialize an approved plan for the DESIGN-FIRST flow — create the task graph and
+//    announce the workers (`worker_status: queued`), but write NO code. The user then chats each
+//    worker via a `code` turn carrying its `workerId`, and merges with `integrate` when ready.
+//  - `run`: the AUTO flow — create the graph, dispatch every worker to code in merge order, then
+//    integrate. One-tap "fan out & run".
+//  - `integrate`: merge the plan's worker branches onto lucid/<repo> in order → `worker_status`
+//    (merged) / `fleet_conflict` / `fleet_done`. Used by the design-first flow's "Merge fleet".
+// Splitting plan from the rest keeps fan-out a one-tap opt-in: no worker spawns until the phone
+// sends `setup`/`run` with a plan the user accepted.
+export const ConductRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('conduct'),
+  repoId: z.string().min(1),
+  phase: z.enum(['plan', 'run', 'setup', 'integrate']),
+  prompt: z.string().min(1).max(8000),
+  images: harnessImagesField,
+  /** The approved plan to execute — required on `run`, ignored on `plan`. */
+  plan: FleetPlanSchema.optional(),
+  /** Conductor (lead) session id to continue its planning conversation across turns. */
+  resume: z.string().optional(),
+  /** Skip the dogfood task graph (no parent/subtask on the board). Set for quick incremental
+   *  spawns so the board isn't spammed with a parent per task; the fleet UI tracks them anyway. */
+  ephemeral: z.boolean().optional(),
+});
+
+// Stop an in-flight request (the phone's stop button). `targetId` is the original
+// request's `id`; the daemon aborts its executor run and replies with a
+// `cancelled` stream event correlated to that same id.
+export const CancelRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('cancel'),
+  targetId: z.uuidv7(),
+});
+
+// Re-fetch an interrupted turn from the daemon's durable turn log (#…). `targetId` is
+// the ORIGINAL turn's id; the daemon replays every logged frame after `sinceSeq` UNDER
+// that same id (not this request's `id`), so the phone routes them to the existing turn
+// and de-dups by the frame's `seq`. A pull replays already-produced output — it never
+// re-runs the turn — so it is safe even for a `code` turn (no duplicate edits). The
+// daemon serves live frames past the log's end automatically when the turn is still
+// in-flight, and settles a dead turn (subprocess gone) with a synthesized terminal.
+export const PullRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('pull'),
+  targetId: z.uuidv7(),
+  /** Highest `seq` the phone already has for this turn; the daemon streams only frames
+   *  after it. 0 (or absent) → replay from the start. */
+  sinceSeq: z.number().int().nonnegative().default(0),
+});
+
+// ---- Connection incident (flight recorder #314) ---------------------------
+
+// One transition in a turn's phone-side lifeline. `state`/`detail` are free strings so a
+// newer phone's states parse on an older daemon without a schema bump.
+export const IncidentTransitionSchema = z.object({
+  at: z.number(),
+  state: z.string(),
+  detail: z.string().optional(),
+});
+
+// The phone's durable per-message record for one turn — the phone half of an incident
+// bundle. Keyed by `requestId`, which is what joins it to the daemon's turn log. Kept
+// deliberately permissive: the daemon reads only a handful of fields to classify the
+// failure and must tolerate a phone that's ahead of (or behind) its own schema.
+export const IncidentTurnSchema = z.object({
+  requestId: z.string(),
+  kind: z.string(),
+  startedAt: z.number(),
+  updatedAt: z.number().optional(),
+  endedAt: z.number().optional(),
+  state: z.string(),
+  /** How the first send left the phone; `outbox` (esp. with `staleSend`) is an
+   *  outbound-loss tell when the daemon's turn log has no record of the id. */
+  transport: z.enum(['socket', 'outbox']).optional(),
+  staleSend: z.boolean().optional(),
+  sessionReset: z.boolean().optional(),
+  retried: z.boolean().optional(),
+  pulled: z.boolean().optional(),
+  frames: z.number().optional(),
+  /** The phone's highest processed daemon `seq` — compared to the turn log's `maxSeq`. */
+  seq: z.number().optional(),
+  /** The Claude session id the phone sent as `resume`, and the one the reply came back on.
+   *  A mismatch is a SESSION_SWAP (the thread's memory silently changed). Present only once
+   *  the phone records them; the detector stays silent otherwise. */
+  resume: z.string().optional(),
+  sessionId: z.string().optional(),
+  transitions: z.array(IncidentTransitionSchema).max(64).optional(),
+});
+
+// A snapshot of the phone socket's internals at incident time — the subset the daemon's
+// invariant detectors read (a mirror of the mobile RoomSnapshot). All optional so a partial
+// or older phone still produces a usable bundle.
+export const IncidentSnapshotSchema = z.object({
+  status: z.string().optional(),
+  daemonConnected: z.boolean().optional(),
+  keepalivesSinceProof: z.number().optional(),
+  pongsSeen: z.number().optional(),
+  lastInboundAt: z.number().nullable().optional(),
+  longestInboundGapMs: z.number().optional(),
+  url: z.string().optional(),
+});
+
+// One connection-lifecycle event from the phone's diag ring (its `RoomDiagEvent`).
+export const IncidentDiagEventSchema = z.object({
+  at: z.number(),
+  kind: z.string(),
+  detail: z.string().optional(),
+  requestId: z.string().optional(),
+});
+
+// Phone → daemon: ship the flight recorder's ledger to the Mac so the daemon can join it
+// against its turn log and write a correlated incident bundle (#314). One-shot; the daemon
+// replies with an `incident` ack carrying the written bundle's path + the class it found.
+export const IncidentReportRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('incident'),
+  ledger: z.array(IncidentTurnSchema).max(200),
+  /** The turn the phone (or a detector) flagged, so the bundle's summary leads with it.
+   *  Absent → the daemon picks the most severe non-delivered turn. */
+  focusRequestId: z.string().optional(),
+  /** Why the incident was raised — a manual tap, or a named detector. */
+  reason: z.string().max(500).optional(),
+  /** The phone socket's live internals — feeds the session-wide invariant detectors
+   *  (WRONG_ROOM, STALE_LIVE_SOCKET, HALF_OPEN). */
+  snapshot: IncidentSnapshotSchema.optional(),
+  /** The tail of the phone's diag ring — feeds SUSPEND_GAP and enriches the timeline. */
+  diag: z.array(IncidentDiagEventSchema).max(400).optional(),
+});
+
+// ---- Voice diagnostics (Kokoro TTS drop/pause capture) --------------------
+
+// One sentence's trip through the pipeline: the text that was synthesized and how the synth went.
+// `synthOk` false = `forward()` failed (a silently-skipped sentence); a missing `durationMs` means
+// no audio was produced for it.
+export const VoiceDiagChunkSchema = z.object({
+  index: z.number().int(),
+  text: z.string(),
+  synthOk: z.boolean(),
+  synthMs: z.number().optional(),
+  durationMs: z.number().optional(),
+  retried: z.boolean().optional(),
+});
+
+// Phone → daemon: a per-utterance capture of the TTS pipeline so a Claude session can localize
+// where Kokoro loses words / collapses pauses (voice diagnostics). Carries every stage transform —
+// the raw markdown, the `toSpeakable()` output it actually spoke, the sentence split, per-chunk
+// synth outcome — plus the concatenated audio (written as a base64 WAV beside the JSON). Deliberate
+// and low-volume (a Speak & Diagnose tap), never automatic. One-shot; the daemon writes it under
+// `~/.lucidity/voice-diag` and acks with the path.
+export const VoiceDiagReportRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('voice-diag'),
+  /** Which path spoke it — the long-press "Speak" menu or an auto-spoken voice turn. */
+  path: z.enum(['long-press', 'auto-reply']),
+  voice: z.string(),
+  rate: z.number().optional(),
+  device: z.string().optional(),
+  raw: z.string().max(100_000),
+  speakable: z.string().max(100_000),
+  chunks: z.array(VoiceDiagChunkSchema).max(200),
+  /** 24kHz mono WAV of the concatenated synthesized audio, base64 (no `data:` prefix). Capped for
+   *  the room's replay buffer; a long reply is a few hundred KB. Absent if nothing synthesized. */
+  wavBase64: z.string().max(8_000_000).optional(),
+});
+
+// ---- Daemon config (Daemon Settings) --------------------------------------
+
+// 24h HH:MM. The daemon re-validates on write; this is the wire-level shape guard.
+const timeString = z
+  .string()
+  .regex(/^([01]?\d|2[0-3]):[0-5]\d$/, 'expected 24h HH:MM');
+
+// The capability dial the phone can flip (GitHub #98). `connected` is reserved and not
+// editable, so it's absent from the patch; the view reports it read-only.
+export const DaemonCapabilitiesPatchSchema = z
+  .object({ tasks: z.boolean(), memory: z.boolean() })
+  .partial();
+
+// The daemon's config as shown to the phone — every displayable field, with secrets
+// (`apiKey`, `oauthToken`) redacted to a presence boolean. Read-only fields (paths,
+// repo allowlist, apiUrl) are included so the screen can surface the whole config.
+export const DaemonConfigViewSchema = z.object({
+  // Editable, applied live. Two role-scoped model/effort pairs: `chat*` drives the
+  // real-time turns a human waits on (Ask Lucid + voice), tuned for latency; `code*`
+  // drives repo coding turns and the batch jobs (briefing/weekly/attention), tuned
+  // for depth. See the daemon's config for how each pair is routed.
+  chatModel: z.string(),
+  chatEffort: z.enum(EFFORT_LEVELS),
+  codeModel: z.string(),
+  codeEffort: z.enum(EFFORT_LEVELS),
+  reflect: z.boolean(),
+  allowInPlace: z.boolean(),
+  // Editable, applied on daemon restart
+  briefingTime: z.string(),
+  weeklyReview: z.boolean(),
+  weeklyReviewDay: z.number().int().min(0).max(6),
+  weeklyReviewTime: z.string(),
+  delivery: z.enum(DELIVERY_CHANNELS),
+  machineName: z.string(),
+  timezone: z.string().nullable(),
+  capabilities: z.object({
+    tasks: z.boolean(),
+    memory: z.boolean(),
+    connected: z.boolean(),
+  }),
+  // How much of the machine chat may touch (Puny God). Editable; restart-wired.
+  agentMode: z.enum(AGENT_MODES),
+  // Read-only display
+  apiUrl: z.string(),
+  chatPort: z.number().int(),
+  // Where Puny God's shell/edits run. Config-only for now (not phone-editable) so the
+  // location can be re-pointed later without a UI; surfaced read-only.
+  shellCwd: z.string(),
+  vaultPath: z.string(),
+  notesPath: z.string().nullable(),
+  workspaceRoot: z.string().nullable(),
+  repos: z.array(z.object({ id: z.string(), path: z.string() })),
+  repoRoots: z.array(z.string()),
+  hasOauthToken: z.boolean(),
+});
+
+// The editable subset the phone may write. Every field optional (a sparse patch); secrets
+// and read-only fields are intentionally excluded, so the daemon rejects anything else.
+export const DaemonConfigPatchSchema = z
+  .object({
+    chatModel: z.string().min(1),
+    chatEffort: z.enum(EFFORT_LEVELS),
+    codeModel: z.string().min(1),
+    codeEffort: z.enum(EFFORT_LEVELS),
+    reflect: z.boolean(),
+    allowInPlace: z.boolean(),
+    briefingTime: timeString,
+    weeklyReview: z.boolean(),
+    weeklyReviewDay: z.number().int().min(0).max(6),
+    weeklyReviewTime: timeString,
+    delivery: z.enum(DELIVERY_CHANNELS),
+    machineName: z.string().min(1),
+    timezone: z.string().min(1),
+    capabilities: DaemonCapabilitiesPatchSchema,
+    agentMode: z.enum(AGENT_MODES),
+  })
+  .partial();
+
+// Read the daemon's current config for the Daemon Settings screen.
+export const GetConfigRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('getConfig'),
+});
+
+// Write a config patch. `restart` asks the daemon to relaunch after persisting, so that
+// boot-wired fields (schedules/delivery/capabilities) actually take effect — the phone
+// sets it only when the patch touches one of those.
+export const SetConfigRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('setConfig'),
+  patch: DaemonConfigPatchSchema,
+  restart: z.boolean().optional(),
+});
+
+// Phone → daemon: give me the attention board for the Dashboard (#320). `refresh` forces a
+// recompose even when the daemon has a recent one cached — that's the pull-to-refresh gesture,
+// as opposed to the cheap fetch the screen does when it opens.
+export const AttentionRequestSchema = HarnessRequestBase.extend({
+  kind: z.literal('attention'),
+  refresh: z.boolean().optional(),
+});
+
+export const HarnessRequestSchema = z.discriminatedUnion('kind', [
+  AskRequestSchema,
+  BriefingRequestSchema,
+  JournalRequestSchema,
+  CodeRequestSchema,
+  ConductRequestSchema,
+  RepoListRequestSchema,
+  ListPrsRequestSchema,
+  CloneRepoRequestSchema,
+  CancelRequestSchema,
+  PullRequestSchema,
+  GetConfigRequestSchema,
+  SetConfigRequestSchema,
+  IncidentReportRequestSchema,
+  AttentionRequestSchema,
+  VoiceDiagReportRequestSchema,
+]);
+
+// ---- Approval control channel (M7 permission bridge) ----------------------
+
+// Engine → phone: a mutating/risky tool call that Claude Code's auto mode
+// escalated (via a PreToolUse hook). `id` correlates the response; `requestId`
+// ties it to the parent `code` turn.
+export const ApprovalRequestSchema = z.object({
+  type: z.literal('approval_request'),
+  id: z.uuidv7(),
+  requestId: z.uuidv7(),
+  toolName: z.string(),
+  toolInput: z.record(z.string(), z.unknown()).optional(),
+  cwd: z.string().optional(),
+});
+
+// Phone → engine: the human's decision, echoed back to the hook.
+export const ApprovalResponseSchema = z.object({
+  type: z.literal('approval_response'),
+  id: z.uuidv7(),
+  decision: z.enum(APPROVAL_DECISIONS),
+});
+
+// Server → phone presence: whether this user's daemon is connected to the room, and
+// its friendly machine name. Pushed when the phone joins and whenever the daemon
+// joins/leaves, so the phone can name the machine and distinguish "my socket is
+// down" from "the daemon is offline". Server-originated — not part of the opaque bridge.
+export const RoomPresenceSchema = z.object({
+  type: z.literal('presence'),
+  daemonConnected: z.boolean(),
+  machine: z.string().nullable(),
+});
+
+// Server → phone: another device signed in as this user wants the same room, and the relay
+// pairs exactly one phone per user. `rejected` means this socket lost — someone else was already
+// here and keeps the room; `evicted` means it was holding the room and a device that asked to
+// take over has replaced it. Either way the socket is closed immediately afterwards, and the
+// phone parks instead of redialling: two devices that both auto-reconnect evict each other about
+// once a second, forever (#221). Sent in-band rather than left to the close code because the
+// phone usually observes 1005 — the socket dies before the server's reason lands.
+export const DeviceConflictSchema = z.object({
+  type: z.literal('device_conflict'),
+  outcome: z.enum(['rejected', 'evicted']),
+});
+
+// Daemon → phone attention board (#320): the short piece of prose Lucid writes for the
+// Dashboard's top card. Unsolicited — it is not a reply to anything the phone asked for, so it
+// carries no `requestId` and is not part of a turn. That's deliberate on two counts: the relay
+// forwards a requestId-less frame verbatim without trying to buffer or seq-stamp it, and the
+// daemon must send it with the raw sender rather than the turn-aware one.
+//
+// The cost of having no `requestId` is that the relay won't hold it for a phone that's offline,
+// so a push can be missed. The phone caches the last board and the daemon recomposes on its next
+// trigger, so a miss heals rather than persisting.
+export const AttentionBoardEntrySchema = z.object({
+  /** Short all-caps eyebrow for the card ("WORK", "SHIPPING"). Absent → the card says ATTENTION. */
+  label: z.string().optional(),
+  text: z.string(),
+});
+
+export const AttentionBoardSchema = z.object({
+  type: z.literal('attention_board'),
+  /** One entry per card. Composed together and replaced together — boards are a derived view of
+   *  tasks + memory, never the durable record of anything, so there's no per-board lifetime to
+   *  preserve across a recompose. Capped by the composer, not here. */
+  boards: z.array(AttentionBoardEntrySchema),
+  /** When the daemon composed them (ISO). The phone renders age and drops stale ones, so this is
+   *  composition time — never send or receive time. */
+  writtenAt: z.string(),
+});
+
+// ---- Journal entries -------------------------------------------------------
+
+// One past run in Lucid's journal — a briefing, weekly review, or ask. Sourced
+// from the daemon's run log; `kind` is free-form so new job types need no schema
+// change.
+export const JournalEntrySchema = z.object({
+  id: z.string(),
+  kind: z.string(),
+  title: z.string(),
+  body: z.string(),
+  createdAt: z.string(),
+  costUsd: z.number().optional(),
+});
+
+// ---- Responses (buffered, non-streaming) ----------------------------------
+
+const HarnessResponseBase = z.object({
+  requestId: z.uuidv7(),
+});
+
+export const AskResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('ask'),
+  text: z.string(),
+  sessionId: z.string().optional(),
+  costUsd: z.number().optional(),
+});
+
+export const BriefingResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('briefing'),
+  text: z.string(),
+  costUsd: z.number().optional(),
+});
+
+export const JournalResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('journal'),
+  entries: z.array(JournalEntrySchema),
+  nextBefore: z.string().optional(),
+});
+
+export const RepoListResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('repos'),
+  repos: z.array(
+    z.object({
+      id: z.string(),
+      /** The branch currently checked out in the real repo (#121) — what an in-place
+       *  turn would commit onto. Omitted by daemons predating the mode picker, and
+       *  when HEAD is detached. */
+      branch: z.string().optional(),
+      /** Whether this daemon permits in-place turns at all. Absent → treat as false,
+       *  so an older daemon never has the option offered for it. */
+      allowInPlace: z.boolean().optional(),
+      /** The repo's GitHub web base (`https://github.com/owner/repo`), when `origin` is a
+       *  github.com remote — the phone's GitHub fab appends `/pulls`, `/issues`, `/projects`.
+       *  Absent for non-GitHub repos and for daemons predating this field. */
+      htmlUrl: z.string().optional(),
+    }),
+  ),
+});
+
+// One open PR, trimmed to what the Code tab renders. `headRefName` is the PR's source branch —
+// the phone matches it against the session branch to pick the "this session" chip.
+export const PrInfoSchema = z.object({
+  number: z.number().int(),
+  title: z.string(),
+  url: z.string(),
+  headRefName: z.string(),
+  isDraft: z.boolean(),
+});
+
+export const PrListResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('prs'),
+  /** The branch this coding session commits onto (its `lucid/<repoId>` worktree branch, or the
+   *  live checkout branch in-place), so the phone can highlight the PR whose head matches. */
+  branch: z.string().optional(),
+  prs: z.array(PrInfoSchema),
+  /** Set when the lookup couldn't run — `gh` missing/unauthed, or no GitHub remote — so the phone
+   *  can explain an empty list instead of showing a bare blank. */
+  error: z.string().optional(),
+});
+
+// Answer to a `getConfig`/`setConfig` request. Always carries the daemon's current
+// (redacted) config so the phone re-renders from truth. `needsRestart` is true when a
+// `setConfig` patch touched a boot-wired field; `restarting` is true when the daemon is
+// about to relaunch to apply it (the socket will drop and presence will blip).
+export const ConfigResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('config'),
+  config: DaemonConfigViewSchema,
+  needsRestart: z.boolean().optional(),
+  restarting: z.boolean().optional(),
+  error: z.string().optional(),
+});
+
+// Daemon → phone: the incident bundle was written (or couldn't be). `path` + `summary` let
+// the phone confirm and show the failure class the daemon found in the join (#314).
+export const IncidentAckResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('incident'),
+  written: z.boolean(),
+  path: z.string().optional(),
+  summary: z.string().optional(),
+});
+
+// Daemon → phone reply to an `attention` request. `board` is null when the daemon has nothing
+// and couldn't compose one (offline, or the model returned empty) — the phone keeps whatever it
+// had cached rather than clearing the card on a failed refresh.
+export const AttentionResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('attention'),
+  /** Null when the daemon has nothing and couldn't compose — the phone keeps what it cached
+   *  rather than clearing the Deck on a failed refresh. */
+  board: z
+    .object({
+      boards: z.array(AttentionBoardEntrySchema),
+      writtenAt: z.string(),
+    })
+    .nullable(),
+});
+
+// Daemon → phone: the voice-diag bundle was written (or couldn't be). `path` lets the phone
+// confirm and (later) surface where it landed.
+export const VoiceDiagAckResponseSchema = HarnessResponseBase.extend({
+  kind: z.literal('voice-diag'),
+  written: z.boolean(),
+  path: z.string().optional(),
+});
+
+export const HarnessResponseSchema = z.discriminatedUnion('kind', [
+  AskResponseSchema,
+  BriefingResponseSchema,
+  JournalResponseSchema,
+  RepoListResponseSchema,
+  PrListResponseSchema,
+  ConfigResponseSchema,
+  IncidentAckResponseSchema,
+  AttentionResponseSchema,
+  VoiceDiagAckResponseSchema,
+]);
+
+// ---- Streaming events (over SSE) ------------------------------------------
+
+// A token/tool/done/error event. `requestId` correlates each event to its
+// originating request so a single socket can multiplex concurrent streams. This
+// is the wire mirror of the runtime's ExecutorStreamEvent, plus correlation and
+// a `tool_call` event for surfacing agentic tool use on the phone.
+//
+// The daemon also stamps a top-level monotonic-per-`requestId` `seq` on every one of
+// these frames (starting at 1) as it writes them to its durable turn log — the phone
+// de-dups by it and a `pull` replays by it. `seq` is transport metadata, deliberately
+// kept OUT of this schema (the relay forwards frames verbatim and never validates them
+// through here), so it isn't a member below.
+export const HarnessStreamEventSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('delta'),
+    requestId: z.uuidv7(),
+    text: z.string(),
+  }),
+  z.object({
+    type: z.literal('tool_call'),
+    requestId: z.uuidv7(),
+    name: z.string(),
+    phase: z.enum(['start', 'end']),
+  }),
+  z.object({
+    type: z.literal('done'),
+    requestId: z.uuidv7(),
+    text: z.string(),
+    sessionId: z.string().optional(),
+    costUsd: z.number().optional(),
+    // True when the daemon had a `resume` handle but it produced nothing in time, so it
+    // silently restarted as a FRESH (memoryless) Claude session. The reply is real but
+    // has no memory of earlier turns — the phone surfaces/counts this so a silent
+    // conversation reset is never invisible again (the root cause behind the #107 wipe).
+    freshStart: z.boolean().optional(),
+  }),
+  z.object({
+    // The result of a `code` turn (M7): the diff the turn produced, ready for the
+    // phone to review (Apply/Discard). Sent after the model's `done`. `branch` is
+    // the session's `lucid/<repoId>` branch in worktree mode, or the repo's live
+    // branch in-place; `mode` says which, so the phone can trust its own subtitle.
+    type: z.literal('code_result'),
+    requestId: z.uuidv7(),
+    branch: z.string(),
+    diff: z.string(),
+    summary: z.string().optional(),
+    mode: z.enum(WORKSPACE_MODES).optional(),
+    // In-place only: the branch the phone expected this turn to land on, echoed back ONLY
+    // when the Mac's live branch had drifted from it (a stale phone cache). The turn still
+    // ran — on `branch` — so the phone shows a quiet "checkout moved" notice on the bubble
+    // instead of the old dead-end rejection that made the user re-send.
+    movedFrom: z.string().optional(),
+  }),
+  z.object({
+    // The result of a `clone` turn (#78): the new repo's id, once cloned into the
+    // workspace root, so the phone can refresh the picker and open it.
+    type: z.literal('clone_result'),
+    requestId: z.uuidv7(),
+    repoId: z.string(),
+  }),
+  // ---- Conductor fleet events (stream under the CONDUCT turn's requestId) ----
+  z.object({
+    // The lead's decomposition, produced by a `conduct` `plan` turn — the phone renders it
+    // as the Fan-out card. Nothing has run or been created yet; the user edits/accepts, then
+    // sends `conduct` `run` with this (possibly edited) plan.
+    type: z.literal('fleet_plan'),
+    requestId: z.uuidv7(),
+    plan: FleetPlanSchema,
+  }),
+  z.object({
+    // A worker crossed into a new lifecycle state. The phone updates that lane's card on the
+    // Fleet board. The worker's own delta/tool_call/code_result/done frames arrive separately,
+    // UNDER `requestId === workerId`, so they flow through the existing code-turn rendering.
+    type: z.literal('worker_status'),
+    requestId: z.uuidv7(),
+    workerId: z.uuidv7(),
+    status: z.enum(WORKER_STATUSES),
+    /** A short live line for the card ("editing serialTts.ts"). Optional. */
+    detail: z.string().optional(),
+    /** This worker's diff size once it has one, for the card's "+N −M". Optional. */
+    diffStat: z
+      .object({ added: z.number().int(), removed: z.number().int(), files: z.number().int() })
+      .optional(),
+  }),
+  z.object({
+    // Integration hit a conflict merging a worker onto the fleet branch. Surfaced in the
+    // conductor feed (never silently) so the user can hand it back to a worker as a fresh turn.
+    // (Legacy combined-integrate path; per-feature delivery opens independent PRs and never
+    // merges workers together, so this doesn't fire there.)
+    type: z.literal('fleet_conflict'),
+    requestId: z.uuidv7(),
+    workerId: z.uuidv7(),
+    paths: z.array(z.string()),
+    message: z.string(),
+  }),
+  z.object({
+    // One worker was delivered as its OWN pull request (per-feature delivery): its branch was
+    // pushed and a PR opened against the base. `url` is that worker's PR; `error` a short reason
+    // it couldn't open (no remote / no gh / no auth) — the worker's commits still exist on its
+    // branch. One of these fires per delivered worker.
+    type: z.literal('worker_pr'),
+    requestId: z.uuidv7(),
+    workerId: z.uuidv7(),
+    url: z.string().optional(),
+    error: z.string().optional(),
+  }),
+  z.object({
+    // The fan-out finished. Per-feature delivery: `delivered`/`total` count how many workers got
+    // their own PR (each worker's URL arrives in its `worker_pr`). No single integration branch.
+    type: z.literal('fleet_done'),
+    requestId: z.uuidv7(),
+    delivered: z.number().int(),
+    total: z.number().int(),
+  }),
+  z.object({
+    type: z.literal('error'),
+    requestId: z.uuidv7(),
+    message: z.string(),
+  }),
+  // A `cancel` request successfully stopped this in-flight turn.
+  z.object({ type: z.literal('cancelled'), requestId: z.uuidv7() }),
+]);
+
+// ---- Message (forward-compat: chat + M4 agent turns) ----------------------
+
+// A single conversational turn. Carries `senderKind` so an agent reply can later
+// be posted into an M4 DM thread next to human messages (same shape, one
+// `author_kind`). Interactive chat (#257) builds its request/stream on top of
+// this; it is intentionally minimal here.
+export const HarnessMessageSchema = z.object({
+  id: z.uuidv7(),
+  senderKind: z.enum(SENDER_KINDS),
+  text: z.string(),
+  createdAt: z.string(),
+});