@tarfa/cli 0.1.6 → 0.1.7

package/dist/{chunk-UPCCR4ZA.js → chunk-4M2ZRGQR.js}

@@ -5151,6 +5151,16 @@ async function loadOrCreateAgentKeys(path) {
     return parseKeys(await readFile4(path, "utf8"), path);
   }
 }
+async function readAgentPublicKey(path) {
+  let text;
+  try {
+    text = await readFile4(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") throw new Error(`no agent key at ${path}: run tarfa setup first`);
+    throw err;
+  }
+  return parseKeys(text, path).x25519.publicKey;
+}
 function parseKeys(text, path) {
   const keyPattern = /^[A-Za-z0-9_-]{43}$/;
   const parsed = JSON.parse(text);
@@ -5276,6 +5286,436 @@ var FileDeviceStore = class {
   }
 };
 
+// ../contracts/src/domain/workspace-link.ts
+var WORKSPACE_LINK_PREFIX = "#open?";
+var KEY = /^[A-Za-z0-9_-]{43}$/;
+var ID = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+var valid = (link) => KEY.test(link.agentKey) && ID.test(link.workspaceId);
+function workspaceLink(pwaOrigin, link) {
+  if (!valid(link)) throw new Error(`not a linkable workspace: ${link.workspaceId}`);
+  return `${new URL(pwaOrigin).origin}/${WORKSPACE_LINK_PREFIX}k=${link.agentKey}&w=${link.workspaceId}`;
+}
+
+// ../contracts/src/domain/workspace-status.ts
+var WORKSPACE_STATUSES = [
+  "needs-feedback",
+  "needs-hands",
+  "idle",
+  "finished",
+  "parked",
+  "blocked",
+  "review",
+  "working"
+];
+function isWorkspaceStatus(value) {
+  return typeof value === "string" && WORKSPACE_STATUSES.includes(value);
+}
+
+// ../contracts/src/domain/sort-by-status.ts
+var RANK = Object.fromEntries(WORKSPACE_STATUSES.map((s, i) => [s, i]));
+
+// ../contracts/src/domain/runs-claude.ts
+function runsClaude(command) {
+  return /(^|[\s/])claude(\s|$)/.test(command);
+}
+
+// ../contracts/src/domain/dictation-key-format.ts
+var SHAPES = {
+  elevenlabs: [/^sk_[A-Za-z0-9]{32,}$/, /^[0-9a-f]{32}$/],
+  openrouter: [/^sk-or-v\d+-[A-Za-z0-9]{32,}$/]
+};
+function dictationKeyProblem(provider, key2) {
+  if (SHAPES[provider].some((shape) => shape.test(key2))) return null;
+  const other = provider === "elevenlabs" ? "openrouter" : "elevenlabs";
+  return SHAPES[other].some((shape) => shape.test(key2)) ? "other-provider" : "format";
+}
+
+// ../contracts/src/domain/image-media-type.ts
+var BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  svg: "image/svg+xml"
+};
+function imageMediaType(path) {
+  const dot = path.lastIndexOf(".");
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  if (dot <= slash + 1) return "";
+  return BY_EXT[path.slice(dot + 1).toLowerCase()] ?? "";
+}
+
+// ../contracts/src/domain/pdf-media-type.ts
+function pdfMediaType(path) {
+  const dot = path.lastIndexOf(".");
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  if (dot <= slash + 1) return "";
+  return path.slice(dot + 1).toLowerCase() === "pdf" ? "application/pdf" : "";
+}
+
+// ../contracts/src/domain/audio-media-type.ts
+var BY_EXT2 = {
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  wav: "audio/wav",
+  flac: "audio/flac",
+  ogg: "audio/ogg",
+  oga: "audio/ogg",
+  opus: "audio/ogg"
+};
+function audioMediaType(path) {
+  const dot = path.lastIndexOf(".");
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  if (dot <= slash + 1) return "";
+  return BY_EXT2[path.slice(dot + 1).toLowerCase()] ?? "";
+}
+
+// ../contracts/src/protocol/messages.ts
+import { z as z5 } from "zod";
+
+// ../contracts/src/protocol/session-channels.ts
+import { z as z4 } from "zod";
+
+// ../contracts/src/protocol/client-log.ts
+import { z as z3 } from "zod";
+var clientLogEventSchema = z3.object({
+  sess: z3.string(),
+  // per-app-launch id
+  seq: z3.number().int().nonnegative(),
+  // monotonic within sess
+  t: z3.number(),
+  // epoch ms at emit
+  machineId: z3.string().optional(),
+  // absent for app-global events (visibility/online)
+  kind: z3.string(),
+  code: z3.number().int().optional(),
+  // WS close code, when reported
+  reason: z3.string().optional(),
+  // classified diagnostic message / close reason
+  online: z3.boolean(),
+  vis: z3.string()
+});
+var clientLogBatchSchema = z3.object({
+  ua: z3.string().optional(),
+  shell: z3.string().optional(),
+  events: z3.array(clientLogEventSchema).min(1).max(500)
+});
+
+// ../contracts/src/protocol/session-channels.ts
+var id = z4.string().min(1).max(64);
+var mediaResultSchema = z4.enum(["ok", "forbidden", "not-found", "too-large", "error"]);
+var sessionClientMessageSchemas = [
+  z4.object({ type: z4.literal("readMedia"), id, path: z4.string() }),
+  z4.object({ type: z4.literal("mediaAck"), id, seq: z4.number().int().nonnegative() }),
+  z4.object({ type: z4.literal("mediaCancel"), id }),
+  // A browser view: `data` is one message of the browser stream protocol (browser-messages.ts)
+  // as JSON text. Each `browser` the agent sends
+  // is acknowledged with a `browserAck`, which is what lets the agent drop stale frames for a
+  // slow phone (see BrowserStreamHandler).
+  z4.object({ type: z4.literal("browserOpen"), stream: id, session: z4.string() }),
+  z4.object({ type: z4.literal("browser"), stream: id, data: z4.string() }),
+  z4.object({ type: z4.literal("browserAck"), stream: id }),
+  z4.object({ type: z4.literal("browserClose"), stream: id }),
+  z4.object({ type: z4.literal("clientLog"), id, batch: clientLogBatchSchema })
+];
+var sessionAgentMessageSchemas = [
+  // The answer to `readMedia`. `size` and `mediaType` come with `ok`; `size` bytes then follow
+  // as chunks numbered from 0.
+  z4.object({
+    type: z4.literal("media"),
+    id,
+    result: mediaResultSchema,
+    mediaType: z4.string().optional(),
+    size: z4.number().int().nonnegative().optional()
+  }),
+  z4.object({ type: z4.literal("mediaChunk"), id, seq: z4.number().int().nonnegative(), data: z4.string() }),
+  z4.object({ type: z4.literal("browser"), stream: id, data: z4.string() }),
+  // The agent ended the stream (the session closed, was taken over, or never existed); the
+  // reason, when there is one, came just before as a browser-protocol `ended`.
+  z4.object({ type: z4.literal("browserClosed"), stream: id }),
+  z4.object({ type: z4.literal("clientLogAck"), id, ok: z4.boolean() })
+];
+
+// ../contracts/src/protocol/messages.ts
+var workspaceStatusSchema = z5.enum(
+  WORKSPACE_STATUSES
+);
+var workspaceSchema = z5.object({
+  machineId: z5.string(),
+  id: z5.string(),
+  name: z5.string(),
+  projectPath: z5.string(),
+  command: z5.string(),
+  createdAt: z5.number(),
+  lastActivityAt: z5.number(),
+  status: workspaceStatusSchema,
+  // Optional GitHub owner/repo (parsed from the origin remote by the agent). `.optional()`
+  // keeps a version-skewed rollout safe: an old agent omits it, a new one includes it.
+  github: z5.object({ owner: z5.string(), repo: z5.string(), ownerType: z5.enum(["user", "org"]).optional() }).optional(),
+  // Manual "pin to top of its status group" flag. `.optional()` keeps a version-skewed
+  // rollout safe: an old agent omits it and the PWA reads it as not-urgent.
+  urgent: z5.boolean().optional(),
+  // The name Claude Code's session registry gives the session running in this workspace.
+  // `.optional()` keeps a version-skewed rollout safe: an old agent omits it and the PWA
+  // simply shows no badge. It must be declared here or zod strips it off the wire.
+  agentAddress: z5.string().optional(),
+  parentId: z5.string().optional(),
+  waitingOn: z5.literal("parent").optional(),
+  asking: z5.boolean().optional()
+});
+var dim = z5.number().int().positive();
+var browserSessionSchema = z5.object({ name: z5.string() });
+var machineStatsSchema = z5.object({
+  cpuPercent: z5.number(),
+  memory: z5.object({ usedBytes: z5.number(), totalBytes: z5.number() }),
+  swapUsedBytes: z5.number(),
+  limit: z5.object({
+    usedBytes: z5.number(),
+    totalBytes: z5.number(),
+    stallPercent: z5.number().optional(),
+    // The kill line. `totalBytes` is min(high, max) — the throttle line the machine is
+    // normally pinned against — so headroom, which measures the distance to an OOM kill,
+    // needs `memory.max` separately. Absent when the cgroup sets no hard limit.
+    maxBytes: z5.number().optional(),
+    // Page cache plus reclaimable slab, less mapped file pages: memory the kernel can
+    // hand back without killing anything. This is what makes `usedBytes` sitting at the
+    // ceiling harmless, and what headroom adds to the distance-to-max.
+    reclaimableBytes: z5.number().optional(),
+    // Cumulative `memory.events` oom_kill for the cgroup. The client keeps the first
+    // value it sees per connection and colours on the delta, so the agent stays dumb.
+    oomKills: z5.number().optional()
+  }).optional()
+});
+var dictationProviderSchema = z5.enum(["elevenlabs", "openrouter"]);
+var clientMessageSchema = z5.discriminatedUnion("type", [
+  // `token` carries a `tarfa pair` code for a new phone, or nothing (an enrolled key needs none).
+  z5.object({ type: z5.literal("auth"), token: z5.string() }),
+  z5.object({ type: z5.literal("list") }),
+  z5.object({ type: z5.literal("getRecentPaths") }),
+  z5.object({ type: z5.literal("browseDir"), path: z5.string() }),
+  // Create a new directory named `name` inside the already-browsed `parent`. The agent
+  // authorizes it against the same allowed-roots set as browseDir, then replies with a
+  // `dirEntries` for the new (empty) folder so the picker browses into it.
+  z5.object({ type: z5.literal("makeDir"), parent: z5.string(), name: z5.string() }),
+  z5.object({ type: z5.literal("listRoots") }),
+  // No longer answered; kept so an agent does not refuse it from an older PWA.
+  z5.object({ type: z5.literal("listCommands") }),
+  z5.object({ type: z5.literal("listLaunchers") }),
+  z5.object({ type: z5.literal("forgetLauncher"), command: z5.string() }),
+  z5.object({ type: z5.literal("listKeyterms") }),
+  // Asked only of an agent whose authResult lists AGENT_FEATURES.dictationKeys.
+  z5.object({ type: z5.literal("getDictationKeys") }),
+  // Store (`key`) or remove (`null`) one of the machine's dictation keys, as `tarfa dictation-key`
+  // does. Sent only to an agent whose authResult lists AGENT_FEATURES.setDictationKey; the key is
+  // checked by the agent, which answers `dictationKeySet` with the same `id`, so a late answer to
+  // an earlier save is never taken for this one's.
+  z5.object({ type: z5.literal("setDictationKey"), id: z5.string(), provider: dictationProviderSchema, key: z5.string().nullable() }),
+  z5.object({ type: z5.literal("readFile"), path: z5.string() }),
+  z5.object({ type: z5.literal("attach"), workspaceId: z5.string(), cols: dim, rows: dim }),
+  z5.object({ type: z5.literal("detach"), workspaceId: z5.string() }),
+  z5.object({ type: z5.literal("input"), workspaceId: z5.string(), data: z5.string() }),
+  z5.object({ type: z5.literal("putFile"), workspaceId: z5.string(), name: z5.string(), data: z5.string() }),
+  // A dictation streamed as it is spoken: 16 kHz mono s16le PCM (base64) the agent plays into
+  // the machine's virtual mic while holding space in the workspace, so Claude Code's /voice
+  // transcribes it. `id` names the dictation, so a late reply to an older one is never taken for
+  // the current one's. Answered with one `voiceDone`; an older agent answers `bad_message`.
+  z5.object({ type: z5.literal("voiceStart"), workspaceId: z5.string(), id: z5.string() }),
+  z5.object({ type: z5.literal("voiceChunk"), id: z5.string(), data: z5.string() }),
+  z5.object({ type: z5.literal("voiceEnd"), id: z5.string() }),
+  // The text of Claude's last reply in a workspace, read aloud on the phone. Sent only to an agent
+  // whose authResult names the `lastReply` feature.
+  z5.object({ type: z5.literal("lastReply"), workspaceId: z5.string() }),
+  z5.object({ type: z5.literal("resize"), workspaceId: z5.string(), cols: dim, rows: dim }),
+  // `remember` is set only when the command came from the Custom field: the agent then adds it
+  // to the machine's launcher list. Additive, so an older agent just ignores it.
+  z5.object({ type: z5.literal("create"), projectPath: z5.string(), command: z5.string(), remember: z5.boolean().optional() }),
+  z5.object({ type: z5.literal("close"), workspaceId: z5.string() }),
+  z5.object({ type: z5.literal("setStatus"), workspaceId: z5.string(), status: workspaceStatusSchema }),
+  // Manually pin/unpin a workspace to the top of its status group. Orthogonal to setStatus;
+  // the agent's onChange broadcasts the refreshed workspace to every device.
+  z5.object({ type: z5.literal("setUrgent"), workspaceId: z5.string(), urgent: z5.boolean() }),
+  // Start an agent-browser session named after the workspace. Old agents answer with their
+  // generic unknown-message error; the PWA only offers this once the agent has proven
+  // support by sending `browserSessions`.
+  z5.object({ type: z5.literal("startBrowser"), workspaceId: z5.string() }),
+  // Liveness probe: the PWA pings periodically so it can detect a half-open socket that
+  // never fires a `close` event (common on mobile) and force a reconnect. The agent answers
+  // with `pong`.
+  z5.object({ type: z5.literal("ping") }),
+  ...sessionClientMessageSchemas
+]);
+var detachReasonSchema = z5.enum(["opened-elsewhere", "closed", "error"]);
+var PROTOCOL_VERSION = 1;
+var AGENT_FEATURES = {
+  lastReply: "lastReply",
+  dictationKeys: "dictationKeys",
+  setDictationKey: "setDictationKey",
+  addresses: "addresses"
+};
+var agentMessageSchema = z5.discriminatedUnion("type", [
+  // `credential` is what authenticated the session (`token` only from an agent from before token
+  // enrolment was removed); `enrolled` says the device key is enrolled (written), so the phone
+  // forgets its pairing secret. Both optional: an older agent sends neither.
+  // `pushed`: the agent served the phone at once (its hello asked) and has sent the opening replies
+  // (workspaces, keyterms) behind it, so the phone does not ask for them.
+  z5.object({
+    type: z5.literal("authResult"),
+    ok: z5.boolean(),
+    credential: z5.enum(["device", "pairing", "token"]).optional().catch(void 0),
+    enrolled: z5.boolean().optional().catch(void 0),
+    pushed: z5.literal(true).optional().catch(void 0),
+    // `features` names what this agent answers beyond the protocol, so the PWA offers a control
+    // only to an agent that supports it (a worktree agent shares a release's version number).
+    // `addresses`: where phones reach this agent now (its TARFA_PHONE_ADDRESSES), which a phone
+    // adopts only once it has connected through each one.
+    agent: z5.object({
+      protocol: z5.number().int(),
+      version: z5.string().optional(),
+      features: z5.array(z5.string()).optional().catch(void 0),
+      addresses: z5.array(z5.string()).optional().catch(void 0)
+    }).optional().catch(void 0)
+  }),
+  // `claudeVoice`: whether this machine can play a Claude voice dictation (see voiceStart).
+  // An older agent omits it, and the PWA then treats Claude voice as unavailable there.
+  z5.object({ type: z5.literal("workspaces"), workspaces: z5.array(workspaceSchema), claudeVoice: z5.boolean().optional() }),
+  z5.object({ type: z5.literal("workspaceUpdated"), workspace: workspaceSchema }),
+  z5.object({ type: z5.literal("recentPaths"), paths: z5.array(z5.string()) }),
+  // The agent's configured project roots — the folder picker's top-level browse points.
+  // `roots` is additive: older agents omit it, so it defaults to [] rather than letting the
+  // strict client parser drop the whole message during a version-skewed rollout.
+  z5.object({ type: z5.literal("roots"), roots: z5.array(z5.string()).default([]) }),
+  // What the Create Workspace command list offers on this machine: the known CLIs found
+  // installed (`claude`, `codex`) and the custom commands launched here before. Additive like
+  // `roots`: an older agent never sends it and the PWA keeps its fixed list.
+  z5.object({ type: z5.literal("launchers"), detected: z5.array(z5.string()).default([]), custom: z5.array(z5.string()).default([]) }),
+  // The agent machine's dictation vocabulary (~/.tarfa/keyterms.txt), passed to ElevenLabs as
+  // keyterms so jargon transcribes correctly. Additive like `roots`: older agents omit it,
+  // so it defaults to [] instead of letting the strict client parser drop the whole message.
+  z5.object({ type: z5.literal("keyterms"), keyterms: z5.array(z5.string()).default([]) }),
+  // The dictation provider keys the agent's operator stored (~/.tarfa/dictation-keys.json), sent
+  // only in reply to getDictationKeys. A key the agent does not hold is absent.
+  z5.object({
+    type: z5.literal("dictationKeys"),
+    elevenlabs: z5.string().optional().catch(void 0),
+    openrouter: z5.string().optional().catch(void 0)
+  }),
+  // The answer to setDictationKey. `error` is the agent's fixed wording of a refusal and never
+  // holds the key.
+  z5.object({ type: z5.literal("dictationKeySet"), id: z5.string(), provider: dictationProviderSchema, ok: z5.boolean(), error: z5.string().optional() }),
+  // `files` is additive: older agents that predate it omit the field, so it defaults to []
+  // (a strictly-required field would make the strict client parser silently drop their
+  // dirEntries during a version-skewed rollout, hanging the browser on "Loading…").
+  z5.object({ type: z5.literal("dirEntries"), path: z5.string(), subdirs: z5.array(z5.string()), files: z5.array(z5.string()).default([]) }),
+  // `truncated`/`binary` are additive: older agents omit them, so they default to false (a
+  // strictly-required field would make the strict client parser drop the whole message
+  // during a version-skewed rollout).
+  z5.object({
+    type: z5.literal("fileContents"),
+    path: z5.string(),
+    data: z5.string(),
+    truncated: z5.boolean().default(false),
+    binary: z5.boolean().default(false)
+  }),
+  z5.object({ type: z5.literal("attached"), workspaceId: z5.string() }),
+  z5.object({ type: z5.literal("output"), workspaceId: z5.string(), data: z5.string() }),
+  z5.object({ type: z5.literal("fileStored"), workspaceId: z5.string(), path: z5.string() }),
+  // `text` is null when the agent holds no reply for that workspace (none since it started, or not Claude).
+  z5.object({ type: z5.literal("lastReply"), workspaceId: z5.string(), text: z5.string().nullable() }),
+  z5.object({ type: z5.literal("voiceDone"), id: z5.string(), ok: z5.boolean(), error: z5.string().optional() }),
+  z5.object({ type: z5.literal("detached"), workspaceId: z5.string(), reason: detachReasonSchema }),
+  z5.object({ type: z5.literal("closed"), workspaceId: z5.string() }),
+  // A phone was just enrolled on this machine (a pairing code), told to every other
+  // phone connected to it: a device nobody meant to add must not go unnoticed. An older PWA drops
+  // the unknown type.
+  z5.object({ type: z5.literal("deviceEnrolled"), id: z5.string(), name: z5.string(), at: z5.string() }),
+  z5.object({ type: z5.literal("error"), code: z5.string(), message: z5.string() }),
+  // Live agent-browser sessions, sent after every `workspaces` reply. `sessions` defaults
+  // to [] so a skewed sender omitting it can't make the strict client parser drop the
+  // whole message.
+  z5.object({ type: z5.literal("browserSessions"), sessions: z5.array(browserSessionSchema).default([]) }),
+  // The agent machine's current CPU/memory load (see machineStatsSchema). Pushed on a
+  // timer while at least one client is connected; an agent that predates it simply never
+  // sends one and the PWA shows no load strip for that machine.
+  z5.object({ type: z5.literal("stats"), stats: machineStatsSchema }),
+  // Reply to the client's liveness `ping` (see clientMessageSchema).
+  z5.object({ type: z5.literal("pong") }),
+  ...sessionAgentMessageSchemas
+]);
+function parseClientMessage(raw) {
+  return clientMessageSchema.parse(raw);
+}
+
+// ../contracts/src/protocol/browser-messages.ts
+import { z as z6 } from "zod";
+var modifiers = z6.number().int().optional();
+var browserClientMessageSchema = z6.discriminatedUnion("type", [
+  z6.object({ type: z6.literal("auth"), token: z6.string() }),
+  // Liveness probe, same pattern as the main terminal socket.
+  z6.object({ type: z6.literal("ping") }),
+  z6.object({
+    type: z6.literal("input_mouse"),
+    eventType: z6.string(),
+    x: z6.number(),
+    y: z6.number(),
+    button: z6.string().optional(),
+    clickCount: z6.number().int().optional(),
+    deltaX: z6.number().optional(),
+    deltaY: z6.number().optional(),
+    modifiers
+  }),
+  z6.object({
+    type: z6.literal("input_keyboard"),
+    eventType: z6.string(),
+    key: z6.string().optional(),
+    code: z6.string().optional(),
+    text: z6.string().optional(),
+    windowsVirtualKeyCode: z6.number().int().optional(),
+    modifiers
+  }),
+  z6.object({
+    type: z6.literal("input_touch"),
+    eventType: z6.string(),
+    touchPoints: z6.array(z6.object({ x: z6.number(), y: z6.number() }).passthrough()),
+    modifiers
+  }),
+  // Handled by the agent (CLI navigation/session control), never forwarded upstream.
+  z6.object({ type: z6.literal("navigate"), url: z6.string() }),
+  z6.object({ type: z6.literal("back") }),
+  z6.object({ type: z6.literal("forward") }),
+  z6.object({ type: z6.literal("closeSession") }),
+  // Resize the remote browser viewport to the attached viewer's canvas (CSS pixels).
+  z6.object({
+    type: z6.literal("setViewport"),
+    width: z6.number().int().positive(),
+    height: z6.number().int().positive()
+  })
+]);
+var browserEndedReasonSchema = z6.enum(["closed", "not-found", "error", "opened-elsewhere"]);
+var browserAgentMessageSchema = z6.discriminatedUnion("type", [
+  z6.object({ type: z6.literal("authResult"), ok: z6.boolean() }),
+  z6.object({ type: z6.literal("pong") }),
+  z6.object({ type: z6.literal("ended"), reason: browserEndedReasonSchema }),
+  z6.object({
+    type: z6.literal("frame"),
+    data: z6.string(),
+    // base64 JPEG
+    metadata: z6.object({ deviceWidth: z6.number(), deviceHeight: z6.number() }).passthrough()
+  }).passthrough(),
+  z6.object({ type: z6.literal("tabs") }).passthrough(),
+  z6.object({ type: z6.literal("url"), url: z6.string() }).passthrough(),
+  z6.object({ type: z6.literal("status") }).passthrough()
+]);
+function parseBrowserClientMessage(raw) {
+  return browserClientMessageSchema.parse(raw);
+}
+function parseBrowserAgentMessage(raw) {
+  return browserAgentMessageSchema.parse(raw);
+}
+
 // src/application/dictation-keys.ts
 var DICTATION_PROVIDERS = ["elevenlabs", "openrouter"];
 var MAX_KEY_LENGTH = 512;
@@ -5289,6 +5729,16 @@ function checkKey(raw) {
   if (key2.length > MAX_KEY_LENGTH) return { ok: false, error: `a key is at most ${MAX_KEY_LENGTH} characters` };
   return { ok: true, key: key2 };
 }
+var SHAPE = {
+  elevenlabs: "an ElevenLabs key starts with sk_ followed by at least 32 letters and digits",
+  openrouter: "an OpenRouter key starts with sk-or-v1- followed by at least 32 letters and digits"
+};
+var OTHER = { elevenlabs: "OpenRouter", openrouter: "ElevenLabs" };
+function keyFormatError(provider, key2) {
+  const problem = dictationKeyProblem(provider, key2);
+  if (problem === null) return null;
+  return problem === "other-provider" ? `this looks like an ${OTHER[provider]} key; ${SHAPE[provider]}` : SHAPE[provider];
+}
 function parseDictationKeys(raw) {
   let value;
   try {
@@ -5318,6 +5768,8 @@ async function changeDictationKey(store, provider, raw) {
   if (raw !== null) {
     const checked = checkKey(raw);
     if (!checked.ok) return checked;
+    const formatError = keyFormatError(provider, checked.key);
+    if (formatError) return { ok: false, error: formatError };
     key2 = checked.key;
   }
   const result = await store.update((keys) => key2 === null ? withoutKey(keys, provider) : withKey(keys, provider, key2));
@@ -5409,8 +5861,8 @@ function pairingName(machineId, hostname) {
   return GENERIC_MACHINE_IDS.has(machineId) ? hostname.split(".")[0] : machineId;
 }
 function announcedAddresses(phoneAddresses2) {
-  const valid = phoneAddresses2.length > 0 && phoneAddresses2.length <= MAX_ADDRESSES && phoneAddresses2.every(isMachineUrl);
-  return valid ? phoneAddresses2 : void 0;
+  const valid2 = phoneAddresses2.length > 0 && phoneAddresses2.length <= MAX_ADDRESSES && phoneAddresses2.every(isMachineUrl);
+  return valid2 ? phoneAddresses2 : void 0;
 }
 async function mintPairing(deps, input) {
   if (deps.defaultPath !== void 0 && !isPairingPath(deps.defaultPath)) {
@@ -5429,8 +5881,8 @@ async function mintPairing(deps, input) {
 
 // src/infrastructure/file-pairing-store.ts
 import { readFile as readFile7 } from "node:fs/promises";
-import { z as z3 } from "zod";
-var schema = z3.array(z3.object({ secret: z3.string().regex(/^[A-Za-z0-9_-]{43}$/), expiresAt: z3.string(), usedAt: z3.string().optional(), usedBy: z3.string().optional() }));
+import { z as z7 } from "zod";
+var schema = z7.array(z7.object({ secret: z7.string().regex(/^[A-Za-z0-9_-]{43}$/), expiresAt: z7.string(), usedAt: z7.string().optional(), usedBy: z7.string().optional() }));
 var FilePairingStore = class {
   constructor(filePath, staleLockMs = 1e4) {
     this.filePath = filePath;
@@ -5453,489 +5905,78 @@ var FilePairingStore = class {
       if (JSON.stringify(next) !== JSON.stringify(current)) await writeFileAtomic(this.filePath, `${JSON.stringify(next, null, 2)}
 `);
       return next;
-    });
-  }
-};
-
-// src/infrastructure/agent-env-file.ts
-import { execFile as execFile3 } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
-import { chmod as chmod2, copyFile, mkdir as mkdir7, readFile as readFile8, writeFile as writeFile5 } from "node:fs/promises";
-import { dirname as dirname8, resolve as resolve5 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { promisify as promisify3 } from "node:util";
-
-// src/application/agent-env-location.ts
-import { join as join6 } from "node:path";
-function resolveAgentEnvPath(input) {
-  if (input.env.TARFA_AGENT_ENV) return input.env.TARFA_AGENT_ENV;
-  const stateFile = join6(input.home, ".tarfa", "agent.env");
-  if (input.exists(stateFile) || input.checkout === null) return stateFile;
-  return join6(input.checkout, "deploy", "agent.env");
-}
-
-// src/infrastructure/agent-env-file.ts
-var exec3 = promisify3(execFile3);
-function withoutGitVars(env) {
-  return Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith("GIT_")));
-}
-async function mainCheckout(kind2 = installKind()) {
-  if (kind2 === "package") return null;
-  const here = dirname8(fileURLToPath2(import.meta.url));
-  try {
-    const { stdout } = await exec3("git", ["-C", here, "rev-parse", "--path-format=absolute", "--git-common-dir"], { env: withoutGitVars(process.env) });
-    return dirname8(stdout.trim());
-  } catch {
-    return resolve5(here, "..", "..", "..", "..");
-  }
-}
-async function locateAgentEnv(env, home, kind2 = installKind()) {
-  return resolveAgentEnvPath({ env, home, checkout: await mainCheckout(kind2), exists: existsSync3 });
-}
-function agentEnvFile(path, now = () => /* @__PURE__ */ new Date()) {
-  return {
-    path,
-    read: async () => {
-      try {
-        return await readFile8(path, "utf8");
-      } catch (err) {
-        if (err.code === "ENOENT") {
-          throw new Error(`no agent config at ${path}: set the agent up first (docs/DEPLOY.md), or set TARFA_AGENT_ENV`);
-        }
-        throw err;
-      }
-    },
-    write: async (text) => {
-      let backup = `${path}.bak-${now().toISOString().replace(/[:.]/g, "-")}`;
-      try {
-        await copyFile(path, backup);
-        await chmod2(backup, 384);
-      } catch (err) {
-        if (err.code !== "ENOENT") throw err;
-        backup = null;
-      }
-      await mkdir7(dirname8(path), { recursive: true, mode: 448 });
-      await writeFile5(path, text, { mode: 384 });
-      await chmod2(path, 384);
-      return backup;
-    }
-  };
-}
-
-// src/infrastructure/file-status-store.ts
-import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "node:fs";
-import { dirname as dirname9 } from "node:path";
-
-// ../contracts/src/domain/workspace-status.ts
-var WORKSPACE_STATUSES = [
-  "needs-feedback",
-  "needs-hands",
-  "idle",
-  "finished",
-  "parked",
-  "blocked",
-  "review",
-  "working"
-];
-function isWorkspaceStatus(value) {
-  return typeof value === "string" && WORKSPACE_STATUSES.includes(value);
-}
-
-// ../contracts/src/domain/sort-by-status.ts
-var RANK = Object.fromEntries(WORKSPACE_STATUSES.map((s, i) => [s, i]));
-
-// ../contracts/src/domain/runs-claude.ts
-function runsClaude(command) {
-  return /(^|[\s/])claude(\s|$)/.test(command);
-}
-
-// ../contracts/src/domain/image-media-type.ts
-var BY_EXT = {
-  png: "image/png",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  gif: "image/gif",
-  webp: "image/webp",
-  avif: "image/avif",
-  bmp: "image/bmp",
-  svg: "image/svg+xml"
-};
-function imageMediaType(path) {
-  const dot = path.lastIndexOf(".");
-  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
-  if (dot <= slash + 1) return "";
-  return BY_EXT[path.slice(dot + 1).toLowerCase()] ?? "";
-}
-
-// ../contracts/src/domain/pdf-media-type.ts
-function pdfMediaType(path) {
-  const dot = path.lastIndexOf(".");
-  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
-  if (dot <= slash + 1) return "";
-  return path.slice(dot + 1).toLowerCase() === "pdf" ? "application/pdf" : "";
-}
-
-// ../contracts/src/domain/audio-media-type.ts
-var BY_EXT2 = {
-  mp3: "audio/mpeg",
-  m4a: "audio/mp4",
-  aac: "audio/aac",
-  wav: "audio/wav",
-  flac: "audio/flac",
-  ogg: "audio/ogg",
-  oga: "audio/ogg",
-  opus: "audio/ogg"
+    });
+  }
 };
-function audioMediaType(path) {
-  const dot = path.lastIndexOf(".");
-  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
-  if (dot <= slash + 1) return "";
-  return BY_EXT2[path.slice(dot + 1).toLowerCase()] ?? "";
-}
-
-// ../contracts/src/protocol/messages.ts
-import { z as z6 } from "zod";
-
-// ../contracts/src/protocol/session-channels.ts
-import { z as z5 } from "zod";
-
-// ../contracts/src/protocol/client-log.ts
-import { z as z4 } from "zod";
-var clientLogEventSchema = z4.object({
-  sess: z4.string(),
-  // per-app-launch id
-  seq: z4.number().int().nonnegative(),
-  // monotonic within sess
-  t: z4.number(),
-  // epoch ms at emit
-  machineId: z4.string().optional(),
-  // absent for app-global events (visibility/online)
-  kind: z4.string(),
-  code: z4.number().int().optional(),
-  // WS close code, when reported
-  reason: z4.string().optional(),
-  // classified diagnostic message / close reason
-  online: z4.boolean(),
-  vis: z4.string()
-});
-var clientLogBatchSchema = z4.object({
-  ua: z4.string().optional(),
-  shell: z4.string().optional(),
-  events: z4.array(clientLogEventSchema).min(1).max(500)
-});
 
-// ../contracts/src/protocol/session-channels.ts
-var id = z5.string().min(1).max(64);
-var mediaResultSchema = z5.enum(["ok", "forbidden", "not-found", "too-large", "error"]);
-var sessionClientMessageSchemas = [
-  z5.object({ type: z5.literal("readMedia"), id, path: z5.string() }),
-  z5.object({ type: z5.literal("mediaAck"), id, seq: z5.number().int().nonnegative() }),
-  z5.object({ type: z5.literal("mediaCancel"), id }),
-  // A browser view: `data` is one message of the browser stream protocol (browser-messages.ts)
-  // as JSON text. Each `browser` the agent sends
-  // is acknowledged with a `browserAck`, which is what lets the agent drop stale frames for a
-  // slow phone (see BrowserStreamHandler).
-  z5.object({ type: z5.literal("browserOpen"), stream: id, session: z5.string() }),
-  z5.object({ type: z5.literal("browser"), stream: id, data: z5.string() }),
-  z5.object({ type: z5.literal("browserAck"), stream: id }),
-  z5.object({ type: z5.literal("browserClose"), stream: id }),
-  z5.object({ type: z5.literal("clientLog"), id, batch: clientLogBatchSchema })
-];
-var sessionAgentMessageSchemas = [
-  // The answer to `readMedia`. `size` and `mediaType` come with `ok`; `size` bytes then follow
-  // as chunks numbered from 0.
-  z5.object({
-    type: z5.literal("media"),
-    id,
-    result: mediaResultSchema,
-    mediaType: z5.string().optional(),
-    size: z5.number().int().nonnegative().optional()
-  }),
-  z5.object({ type: z5.literal("mediaChunk"), id, seq: z5.number().int().nonnegative(), data: z5.string() }),
-  z5.object({ type: z5.literal("browser"), stream: id, data: z5.string() }),
-  // The agent ended the stream (the session closed, was taken over, or never existed); the
-  // reason, when there is one, came just before as a browser-protocol `ended`.
-  z5.object({ type: z5.literal("browserClosed"), stream: id }),
-  z5.object({ type: z5.literal("clientLogAck"), id, ok: z5.boolean() })
-];
+// src/infrastructure/agent-env-file.ts
+import { execFile as execFile3 } from "node:child_process";
+import { existsSync as existsSync3 } from "node:fs";
+import { chmod as chmod2, copyFile, mkdir as mkdir7, readFile as readFile8, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname8, resolve as resolve5 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { promisify as promisify3 } from "node:util";
 
-// ../contracts/src/protocol/messages.ts
-var workspaceStatusSchema = z6.enum(
-  WORKSPACE_STATUSES
-);
-var workspaceSchema = z6.object({
-  machineId: z6.string(),
-  id: z6.string(),
-  name: z6.string(),
-  projectPath: z6.string(),
-  command: z6.string(),
-  createdAt: z6.number(),
-  lastActivityAt: z6.number(),
-  status: workspaceStatusSchema,
-  // Optional GitHub owner/repo (parsed from the origin remote by the agent). `.optional()`
-  // keeps a version-skewed rollout safe: an old agent omits it, a new one includes it.
-  github: z6.object({ owner: z6.string(), repo: z6.string(), ownerType: z6.enum(["user", "org"]).optional() }).optional(),
-  // Manual "pin to top of its status group" flag. `.optional()` keeps a version-skewed
-  // rollout safe: an old agent omits it and the PWA reads it as not-urgent.
-  urgent: z6.boolean().optional(),
-  // The name Claude Code's session registry gives the session running in this workspace.
-  // `.optional()` keeps a version-skewed rollout safe: an old agent omits it and the PWA
-  // simply shows no badge. It must be declared here or zod strips it off the wire.
-  agentAddress: z6.string().optional(),
-  parentId: z6.string().optional(),
-  waitingOn: z6.literal("parent").optional(),
-  asking: z6.boolean().optional()
-});
-var dim = z6.number().int().positive();
-var browserSessionSchema = z6.object({ name: z6.string() });
-var machineStatsSchema = z6.object({
-  cpuPercent: z6.number(),
-  memory: z6.object({ usedBytes: z6.number(), totalBytes: z6.number() }),
-  swapUsedBytes: z6.number(),
-  limit: z6.object({
-    usedBytes: z6.number(),
-    totalBytes: z6.number(),
-    stallPercent: z6.number().optional(),
-    // The kill line. `totalBytes` is min(high, max) — the throttle line the machine is
-    // normally pinned against — so headroom, which measures the distance to an OOM kill,
-    // needs `memory.max` separately. Absent when the cgroup sets no hard limit.
-    maxBytes: z6.number().optional(),
-    // Page cache plus reclaimable slab, less mapped file pages: memory the kernel can
-    // hand back without killing anything. This is what makes `usedBytes` sitting at the
-    // ceiling harmless, and what headroom adds to the distance-to-max.
-    reclaimableBytes: z6.number().optional(),
-    // Cumulative `memory.events` oom_kill for the cgroup. The client keeps the first
-    // value it sees per connection and colours on the delta, so the agent stays dumb.
-    oomKills: z6.number().optional()
-  }).optional()
-});
-var dictationProviderSchema = z6.enum(["elevenlabs", "openrouter"]);
-var clientMessageSchema = z6.discriminatedUnion("type", [
-  // `token` carries a `tarfa pair` code for a new phone, or nothing (an enrolled key needs none).
-  z6.object({ type: z6.literal("auth"), token: z6.string() }),
-  z6.object({ type: z6.literal("list") }),
-  z6.object({ type: z6.literal("getRecentPaths") }),
-  z6.object({ type: z6.literal("browseDir"), path: z6.string() }),
-  // Create a new directory named `name` inside the already-browsed `parent`. The agent
-  // authorizes it against the same allowed-roots set as browseDir, then replies with a
-  // `dirEntries` for the new (empty) folder so the picker browses into it.
-  z6.object({ type: z6.literal("makeDir"), parent: z6.string(), name: z6.string() }),
-  z6.object({ type: z6.literal("listRoots") }),
-  // No longer answered; kept so an agent does not refuse it from an older PWA.
-  z6.object({ type: z6.literal("listCommands") }),
-  z6.object({ type: z6.literal("listLaunchers") }),
-  z6.object({ type: z6.literal("forgetLauncher"), command: z6.string() }),
-  z6.object({ type: z6.literal("listKeyterms") }),
-  // Asked only of an agent whose authResult lists AGENT_FEATURES.dictationKeys.
-  z6.object({ type: z6.literal("getDictationKeys") }),
-  // Store (`key`) or remove (`null`) one of the machine's dictation keys, as `tarfa dictation-key`
-  // does. Sent only to an agent whose authResult lists AGENT_FEATURES.setDictationKey; the key is
-  // checked by the agent, which answers `dictationKeySet` with the same `id`, so a late answer to
-  // an earlier save is never taken for this one's.
-  z6.object({ type: z6.literal("setDictationKey"), id: z6.string(), provider: dictationProviderSchema, key: z6.string().nullable() }),
-  z6.object({ type: z6.literal("readFile"), path: z6.string() }),
-  z6.object({ type: z6.literal("attach"), workspaceId: z6.string(), cols: dim, rows: dim }),
-  z6.object({ type: z6.literal("detach"), workspaceId: z6.string() }),
-  z6.object({ type: z6.literal("input"), workspaceId: z6.string(), data: z6.string() }),
-  z6.object({ type: z6.literal("putFile"), workspaceId: z6.string(), name: z6.string(), data: z6.string() }),
-  // A dictation streamed as it is spoken: 16 kHz mono s16le PCM (base64) the agent plays into
-  // the machine's virtual mic while holding space in the workspace, so Claude Code's /voice
-  // transcribes it. `id` names the dictation, so a late reply to an older one is never taken for
-  // the current one's. Answered with one `voiceDone`; an older agent answers `bad_message`.
-  z6.object({ type: z6.literal("voiceStart"), workspaceId: z6.string(), id: z6.string() }),
-  z6.object({ type: z6.literal("voiceChunk"), id: z6.string(), data: z6.string() }),
-  z6.object({ type: z6.literal("voiceEnd"), id: z6.string() }),
-  // The text of Claude's last reply in a workspace, read aloud on the phone. Sent only to an agent
-  // whose authResult names the `lastReply` feature.
-  z6.object({ type: z6.literal("lastReply"), workspaceId: z6.string() }),
-  z6.object({ type: z6.literal("resize"), workspaceId: z6.string(), cols: dim, rows: dim }),
-  // `remember` is set only when the command came from the Custom field: the agent then adds it
-  // to the machine's launcher list. Additive, so an older agent just ignores it.
-  z6.object({ type: z6.literal("create"), projectPath: z6.string(), command: z6.string(), remember: z6.boolean().optional() }),
-  z6.object({ type: z6.literal("close"), workspaceId: z6.string() }),
-  z6.object({ type: z6.literal("setStatus"), workspaceId: z6.string(), status: workspaceStatusSchema }),
-  // Manually pin/unpin a workspace to the top of its status group. Orthogonal to setStatus;
-  // the agent's onChange broadcasts the refreshed workspace to every device.
-  z6.object({ type: z6.literal("setUrgent"), workspaceId: z6.string(), urgent: z6.boolean() }),
-  // Start an agent-browser session named after the workspace. Old agents answer with their
-  // generic unknown-message error; the PWA only offers this once the agent has proven
-  // support by sending `browserSessions`.
-  z6.object({ type: z6.literal("startBrowser"), workspaceId: z6.string() }),
-  // Liveness probe: the PWA pings periodically so it can detect a half-open socket that
-  // never fires a `close` event (common on mobile) and force a reconnect. The agent answers
-  // with `pong`.
-  z6.object({ type: z6.literal("ping") }),
-  ...sessionClientMessageSchemas
-]);
-var detachReasonSchema = z6.enum(["opened-elsewhere", "closed", "error"]);
-var PROTOCOL_VERSION = 1;
-var AGENT_FEATURES = {
-  lastReply: "lastReply",
-  dictationKeys: "dictationKeys",
-  setDictationKey: "setDictationKey",
-  addresses: "addresses"
-};
-var agentMessageSchema = z6.discriminatedUnion("type", [
-  // `credential` is what authenticated the session (`token` only from an agent from before token
-  // enrolment was removed); `enrolled` says the device key is enrolled (written), so the phone
-  // forgets its pairing secret. Both optional: an older agent sends neither.
-  // `pushed`: the agent served the phone at once (its hello asked) and has sent the opening replies
-  // (workspaces, keyterms) behind it, so the phone does not ask for them.
-  z6.object({
-    type: z6.literal("authResult"),
-    ok: z6.boolean(),
-    credential: z6.enum(["device", "pairing", "token"]).optional().catch(void 0),
-    enrolled: z6.boolean().optional().catch(void 0),
-    pushed: z6.literal(true).optional().catch(void 0),
-    // `features` names what this agent answers beyond the protocol, so the PWA offers a control
-    // only to an agent that supports it (a worktree agent shares a release's version number).
-    // `addresses`: where phones reach this agent now (its TARFA_PHONE_ADDRESSES), which a phone
-    // adopts only once it has connected through each one.
-    agent: z6.object({
-      protocol: z6.number().int(),
-      version: z6.string().optional(),
-      features: z6.array(z6.string()).optional().catch(void 0),
-      addresses: z6.array(z6.string()).optional().catch(void 0)
-    }).optional().catch(void 0)
-  }),
-  // `claudeVoice`: whether this machine can play a Claude voice dictation (see voiceStart).
-  // An older agent omits it, and the PWA then treats Claude voice as unavailable there.
-  z6.object({ type: z6.literal("workspaces"), workspaces: z6.array(workspaceSchema), claudeVoice: z6.boolean().optional() }),
-  z6.object({ type: z6.literal("workspaceUpdated"), workspace: workspaceSchema }),
-  z6.object({ type: z6.literal("recentPaths"), paths: z6.array(z6.string()) }),
-  // The agent's configured project roots — the folder picker's top-level browse points.
-  // `roots` is additive: older agents omit it, so it defaults to [] rather than letting the
-  // strict client parser drop the whole message during a version-skewed rollout.
-  z6.object({ type: z6.literal("roots"), roots: z6.array(z6.string()).default([]) }),
-  // What the Create Workspace command list offers on this machine: the known CLIs found
-  // installed (`claude`, `codex`) and the custom commands launched here before. Additive like
-  // `roots`: an older agent never sends it and the PWA keeps its fixed list.
-  z6.object({ type: z6.literal("launchers"), detected: z6.array(z6.string()).default([]), custom: z6.array(z6.string()).default([]) }),
-  // The agent machine's dictation vocabulary (~/.tarfa/keyterms.txt), passed to ElevenLabs as
-  // keyterms so jargon transcribes correctly. Additive like `roots`: older agents omit it,
-  // so it defaults to [] instead of letting the strict client parser drop the whole message.
-  z6.object({ type: z6.literal("keyterms"), keyterms: z6.array(z6.string()).default([]) }),
-  // The dictation provider keys the agent's operator stored (~/.tarfa/dictation-keys.json), sent
-  // only in reply to getDictationKeys. A key the agent does not hold is absent.
-  z6.object({
-    type: z6.literal("dictationKeys"),
-    elevenlabs: z6.string().optional().catch(void 0),
-    openrouter: z6.string().optional().catch(void 0)
-  }),
-  // The answer to setDictationKey. `error` is the agent's fixed wording of a refusal and never
-  // holds the key.
-  z6.object({ type: z6.literal("dictationKeySet"), id: z6.string(), provider: dictationProviderSchema, ok: z6.boolean(), error: z6.string().optional() }),
-  // `files` is additive: older agents that predate it omit the field, so it defaults to []
-  // (a strictly-required field would make the strict client parser silently drop their
-  // dirEntries during a version-skewed rollout, hanging the browser on "Loading…").
-  z6.object({ type: z6.literal("dirEntries"), path: z6.string(), subdirs: z6.array(z6.string()), files: z6.array(z6.string()).default([]) }),
-  // `truncated`/`binary` are additive: older agents omit them, so they default to false (a
-  // strictly-required field would make the strict client parser drop the whole message
-  // during a version-skewed rollout).
-  z6.object({
-    type: z6.literal("fileContents"),
-    path: z6.string(),
-    data: z6.string(),
-    truncated: z6.boolean().default(false),
-    binary: z6.boolean().default(false)
-  }),
-  z6.object({ type: z6.literal("attached"), workspaceId: z6.string() }),
-  z6.object({ type: z6.literal("output"), workspaceId: z6.string(), data: z6.string() }),
-  z6.object({ type: z6.literal("fileStored"), workspaceId: z6.string(), path: z6.string() }),
-  // `text` is null when the agent holds no reply for that workspace (none since it started, or not Claude).
-  z6.object({ type: z6.literal("lastReply"), workspaceId: z6.string(), text: z6.string().nullable() }),
-  z6.object({ type: z6.literal("voiceDone"), id: z6.string(), ok: z6.boolean(), error: z6.string().optional() }),
-  z6.object({ type: z6.literal("detached"), workspaceId: z6.string(), reason: detachReasonSchema }),
-  z6.object({ type: z6.literal("closed"), workspaceId: z6.string() }),
-  // A phone was just enrolled on this machine (a pairing code), told to every other
-  // phone connected to it: a device nobody meant to add must not go unnoticed. An older PWA drops
-  // the unknown type.
-  z6.object({ type: z6.literal("deviceEnrolled"), id: z6.string(), name: z6.string(), at: z6.string() }),
-  z6.object({ type: z6.literal("error"), code: z6.string(), message: z6.string() }),
-  // Live agent-browser sessions, sent after every `workspaces` reply. `sessions` defaults
-  // to [] so a skewed sender omitting it can't make the strict client parser drop the
-  // whole message.
-  z6.object({ type: z6.literal("browserSessions"), sessions: z6.array(browserSessionSchema).default([]) }),
-  // The agent machine's current CPU/memory load (see machineStatsSchema). Pushed on a
-  // timer while at least one client is connected; an agent that predates it simply never
-  // sends one and the PWA shows no load strip for that machine.
-  z6.object({ type: z6.literal("stats"), stats: machineStatsSchema }),
-  // Reply to the client's liveness `ping` (see clientMessageSchema).
-  z6.object({ type: z6.literal("pong") }),
-  ...sessionAgentMessageSchemas
-]);
-function parseClientMessage(raw) {
-  return clientMessageSchema.parse(raw);
+// src/application/agent-env-location.ts
+import { join as join6 } from "node:path";
+function resolveAgentEnvPath(input) {
+  if (input.env.TARFA_AGENT_ENV) return input.env.TARFA_AGENT_ENV;
+  const stateFile = join6(input.home, ".tarfa", "agent.env");
+  if (input.exists(stateFile) || input.checkout === null) return stateFile;
+  return join6(input.checkout, "deploy", "agent.env");
 }
 
-// ../contracts/src/protocol/browser-messages.ts
-import { z as z7 } from "zod";
-var modifiers = z7.number().int().optional();
-var browserClientMessageSchema = z7.discriminatedUnion("type", [
-  z7.object({ type: z7.literal("auth"), token: z7.string() }),
-  // Liveness probe, same pattern as the main terminal socket.
-  z7.object({ type: z7.literal("ping") }),
-  z7.object({
-    type: z7.literal("input_mouse"),
-    eventType: z7.string(),
-    x: z7.number(),
-    y: z7.number(),
-    button: z7.string().optional(),
-    clickCount: z7.number().int().optional(),
-    deltaX: z7.number().optional(),
-    deltaY: z7.number().optional(),
-    modifiers
-  }),
-  z7.object({
-    type: z7.literal("input_keyboard"),
-    eventType: z7.string(),
-    key: z7.string().optional(),
-    code: z7.string().optional(),
-    text: z7.string().optional(),
-    windowsVirtualKeyCode: z7.number().int().optional(),
-    modifiers
-  }),
-  z7.object({
-    type: z7.literal("input_touch"),
-    eventType: z7.string(),
-    touchPoints: z7.array(z7.object({ x: z7.number(), y: z7.number() }).passthrough()),
-    modifiers
-  }),
-  // Handled by the agent (CLI navigation/session control), never forwarded upstream.
-  z7.object({ type: z7.literal("navigate"), url: z7.string() }),
-  z7.object({ type: z7.literal("back") }),
-  z7.object({ type: z7.literal("forward") }),
-  z7.object({ type: z7.literal("closeSession") }),
-  // Resize the remote browser viewport to the attached viewer's canvas (CSS pixels).
-  z7.object({
-    type: z7.literal("setViewport"),
-    width: z7.number().int().positive(),
-    height: z7.number().int().positive()
-  })
-]);
-var browserEndedReasonSchema = z7.enum(["closed", "not-found", "error", "opened-elsewhere"]);
-var browserAgentMessageSchema = z7.discriminatedUnion("type", [
-  z7.object({ type: z7.literal("authResult"), ok: z7.boolean() }),
-  z7.object({ type: z7.literal("pong") }),
-  z7.object({ type: z7.literal("ended"), reason: browserEndedReasonSchema }),
-  z7.object({
-    type: z7.literal("frame"),
-    data: z7.string(),
-    // base64 JPEG
-    metadata: z7.object({ deviceWidth: z7.number(), deviceHeight: z7.number() }).passthrough()
-  }).passthrough(),
-  z7.object({ type: z7.literal("tabs") }).passthrough(),
-  z7.object({ type: z7.literal("url"), url: z7.string() }).passthrough(),
-  z7.object({ type: z7.literal("status") }).passthrough()
-]);
-function parseBrowserClientMessage(raw) {
-  return browserClientMessageSchema.parse(raw);
+// src/infrastructure/agent-env-file.ts
+var exec3 = promisify3(execFile3);
+function withoutGitVars(env) {
+  return Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith("GIT_")));
 }
-function parseBrowserAgentMessage(raw) {
-  return browserAgentMessageSchema.parse(raw);
+async function mainCheckout(kind2 = installKind()) {
+  if (kind2 === "package") return null;
+  const here = dirname8(fileURLToPath2(import.meta.url));
+  try {
+    const { stdout } = await exec3("git", ["-C", here, "rev-parse", "--path-format=absolute", "--git-common-dir"], { env: withoutGitVars(process.env) });
+    return dirname8(stdout.trim());
+  } catch {
+    return resolve5(here, "..", "..", "..", "..");
+  }
+}
+async function locateAgentEnv(env, home, kind2 = installKind()) {
+  return resolveAgentEnvPath({ env, home, checkout: await mainCheckout(kind2), exists: existsSync3 });
+}
+function agentEnvFile(path, now = () => /* @__PURE__ */ new Date()) {
+  return {
+    path,
+    read: async () => {
+      try {
+        return await readFile8(path, "utf8");
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          throw new Error(`no agent config at ${path}: set the agent up first (docs/DEPLOY.md), or set TARFA_AGENT_ENV`);
+        }
+        throw err;
+      }
+    },
+    write: async (text) => {
+      let backup = `${path}.bak-${now().toISOString().replace(/[:.]/g, "-")}`;
+      try {
+        await copyFile(path, backup);
+        await chmod2(backup, 384);
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+        backup = null;
+      }
+      await mkdir7(dirname8(path), { recursive: true, mode: 448 });
+      await writeFile5(path, text, { mode: 384 });
+      await chmod2(path, 384);
+      return backup;
+    }
+  };
 }
 
 // src/infrastructure/file-status-store.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "node:fs";
+import { dirname as dirname9 } from "node:path";
 var FileStatusStore = class {
   constructor(filePath, now = Date.now) {
     this.filePath = filePath;
@@ -6510,6 +6551,7 @@ export {
   browseDir,
   atomicWrite,
   loadOrCreateAgentKeys,
+  readAgentPublicKey,
   enrolmentMode,
   withEnrolmentMode,
   standingOf,
@@ -6517,6 +6559,17 @@ export {
   revokeDevice,
   forgetDevice,
   FileDeviceStore,
+  isWorkspaceStatus,
+  runsClaude,
+  imageMediaType,
+  pdfMediaType,
+  audioMediaType,
+  PROTOCOL_VERSION,
+  AGENT_FEATURES,
+  parseClientMessage,
+  parseBrowserClientMessage,
+  parseBrowserAgentMessage,
+  workspaceLink,
   DICTATION_PROVIDERS,
   providerOf,
   changeDictationKey,
@@ -6531,16 +6584,6 @@ export {
   mainCheckout,
   locateAgentEnv,
   agentEnvFile,
-  isWorkspaceStatus,
-  runsClaude,
-  imageMediaType,
-  pdfMediaType,
-  audioMediaType,
-  PROTOCOL_VERSION,
-  AGENT_FEATURES,
-  parseClientMessage,
-  parseBrowserClientMessage,
-  parseBrowserAgentMessage,
   FileStatusStore,
   FileParkedStore,
   FsFileWriter,

package/dist/cli.js

@@ -59,6 +59,7 @@ import {
   planCli,
   planSetup,
   providerOf,
+  readAgentPublicKey,
   renderService,
   resolveCodexHome,
   resolveStateDir,
@@ -70,8 +71,9 @@ import {
   systemPathResolver,
   unitRunsLauncher,
   withEnrolmentMode,
-  withLegacyEnv
-} from "./chunk-UPCCR4ZA.js";
+  withLegacyEnv,
+  workspaceLink
+} from "./chunk-4M2ZRGQR.js";
 
 // src/cli.ts
 import { randomBytes } from "node:crypto";
@@ -1196,7 +1198,7 @@ async function run3(argv, rawEnv, home, io = {}) {
     throw new UsageError(RELAYS_GONE);
   }
   if (argv[0] === "pair") return pair(argv.slice(1), env, home);
-  if (argv[0] === "ls" || argv[0] === "spawn" || argv[0] === "peek" || argv[0] === "unpark" || argv[0] === "rename" || argv[0] === "send" || argv[0] === "close" || argv[0] === "wait") {
+  if (argv[0] === "ls" || argv[0] === "spawn" || argv[0] === "peek" || argv[0] === "unpark" || argv[0] === "rename" || argv[0] === "link" || argv[0] === "send" || argv[0] === "close" || argv[0] === "wait") {
     return orchestration(argv[0], argv.slice(1), env, home, io);
   }
   const config = loadConfig({ ...env, ...await agentEnvValues(env, home) }, home);
@@ -1288,6 +1290,7 @@ Workspaces on this machine:
   send           send a message to another workspace
   unpark         reopen parked workspaces
   rename         rename a workspace (without an id: this one)
+  link           print a link that opens a workspace in the app (without an id: this one)
   close          close workspaces
   list, create, recent, browse   the agent's own views, as JSON
 
@@ -1307,6 +1310,7 @@ var COMMANDS = /* @__PURE__ */ new Set([
   "peek",
   "unpark",
   "rename",
+  "link",
   "send",
   "close",
   "wait",
@@ -1321,6 +1325,7 @@ var SPAWN_CLIS = ["claude", "codex", "pi"];
 var PEEK_USAGE = "usage: tarfa peek <workspace id> [-n <lines>]";
 var UNPARK_USAGE = "usage: tarfa unpark <workspace id>...";
 var RENAME_USAGE = "usage: tarfa rename [<workspace id>] <title>   (without an id: the workspace this runs in)";
+var LINK_USAGE = "usage: tarfa link [<workspace id>] [--pwa <PWA origin>]   (without an id: the workspace this runs in)";
 var SEND_USAGE = 'usage: tarfa send <workspace id> "<message>"   (or the message on stdin)';
 var CLOSE_USAGE = "usage: tarfa close <workspace id>...";
 var WAIT_USAGE = "usage: tarfa wait <workspace id>... [--timeout <seconds, at least 10>]";
@@ -1483,6 +1488,18 @@ async function orchestration(command, argv, env, home, io) {
       const done = `${id}: renamed to "${title.trim()}"`;
       return locked ? done : `${done} (this tmux cannot lock a title, so Claude may rename it again)`;
     }
+    case "link": {
+      const origin = pwaOrigin(takeOption(args, "--pwa", LINK_USAGE));
+      if (args.length > 1 || args.some((a) => a.startsWith("-"))) throw new Error(LINK_USAGE);
+      const id = args[0] ?? await callerWorkspace(env, tmux, config.sessionPrefix);
+      const workspace = (await listAll()).find((w) => w.id === id);
+      if (!workspace) throw new Error(`no workspace ${id} (see tarfa ls)`);
+      if (isHiddenPath(workspace.projectPath, await new FileHiddenFoldersStore(config.hiddenFoldersPath).list())) {
+        throw new Error(`${id} is in a hidden folder, which phones do not list`);
+      }
+      const agentKey = await readAgentPublicKey(config.agentKeyPath);
+      return workspaceLink(origin ?? pwaOrigin(config.pwaOrigin), { agentKey, workspaceId: id });
+    }
     case "close": {
       if (args.length === 0 || args.some((id) => id.startsWith("-"))) throw new UsageError(CLOSE_USAGE);
       const self = await callerWorkspace(env, tmux, config.sessionPrefix).catch(() => void 0);

package/dist/serve.js

@@ -78,7 +78,7 @@ import {
   systemPathResolver,
   withLegacyEnv,
   writeFileAtomic
-} from "./chunk-UPCCR4ZA.js";
+} from "./chunk-4M2ZRGQR.js";
 
 // src/serve.ts
 import { homedir as homedir2 } from "node:os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tarfa/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Tarfa agent and CLI: serves your Claude Code terminal sessions (tmux workspaces) to the Tarfa phone app.",
   "repository": {
     "type": "git",