@tarfa/cli 0.1.5 → 0.1.7

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

@@ -2463,8 +2463,6 @@ function deviceFingerprint(x25519PublicKey) {
 
 // ../secure-channel/src/pairing-link.ts
 var PREFIX = "#pair?";
-var KEY = /^[A-Za-z0-9_-]{43}$/;
-var MAX_NAME = 64;
 var MAX_ADDRESSES = 4;
 var MAX_PATH = 128;
 function isPairingPath(path) {
@@ -2485,19 +2483,6 @@ function pairingLink(pwaOrigin, pairing) {
   const query = fields.map(([name, value]) => `${name}=${encode(value)}`).join("&");
   return `${new URL(pwaOrigin).origin}/${PREFIX}${query}`;
 }
-function parsePairingLink(text) {
-  const trimmed = text.trim();
-  const hash = trimmed.startsWith("#") ? trimmed : trimmed.slice(Math.max(0, trimmed.indexOf("#")));
-  if (!trimmed.includes("#") || !hash.startsWith(PREFIX)) return null;
-  const query = new URLSearchParams(hash.slice(PREFIX.length));
-  const urls = query.getAll("u");
-  const [agentKey, secret] = ["k", "s"].map((name2) => query.get(name2) ?? "");
-  const name = (query.get("n") ?? "").trim() || "machine";
-  if (!KEY.test(agentKey) || !KEY.test(secret) || name.length > MAX_NAME) return null;
-  if (urls.length === 0 || urls.length > MAX_ADDRESSES || !urls.every(isMachineUrl)) return null;
-  const defaultPath = query.get("p") ?? "";
-  return { urls, agentKey, secret, name, ...isPairingPath(defaultPath) ? { defaultPath } : {} };
-}
 var LOOPBACK = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]"]);
 function isMachineUrl(text) {
   try {
@@ -2509,6 +2494,131 @@ function isMachineUrl(text) {
   }
 }
 
+// ../secure-channel/src/pairing-code.ts
+var PREFIX2 = "TARFA";
+var VERSION = 1;
+var MAX_PLAUSIBLE_VERSION = 15;
+var ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var KEY_BYTES = 32;
+var CHECKSUM_BYTES = 4;
+var MAX_NAME = 64;
+var SCHEMES = ["wss://", "ws://"];
+function pairingCode(pairing) {
+  const out = [VERSION, ...rawKey(pairing.agentKey), ...rawKey(pairing.secret)];
+  const text = (value) => {
+    const bytes = new TextEncoder().encode(value);
+    if (bytes.length > 65535) throw new Error("pairing code field too long");
+    out.push(bytes.length >> 8, bytes.length & 255, ...bytes);
+  };
+  text(pairing.name);
+  text(pairing.defaultPath ?? "");
+  out.push(pairing.urls.length);
+  for (const url of pairing.urls) {
+    const scheme = SCHEMES.findIndex((s) => url.toLowerCase().startsWith(s));
+    if (scheme < 0) throw new Error(`not a machine address: ${url}`);
+    out.push(scheme);
+    text(url.slice(SCHEMES[scheme].length));
+  }
+  const body = Uint8Array.from(out);
+  const code = PREFIX2 + encode32(Uint8Array.from([...body, ...sha256(body).slice(0, CHECKSUM_BYTES)]));
+  if (!parsePairingCode(code).ok) throw new Error("these pairing details do not make a valid pairing code");
+  return code;
+}
+function rawKey(key2) {
+  const bytes = /^[A-Za-z0-9_-]{43}$/.test(key2) ? b64url.decode(key2) : new Uint8Array();
+  if (bytes.length !== KEY_BYTES || b64url.encode(bytes) !== key2) throw new Error("a pairing key must be 32 bytes, canonically encoded");
+  return bytes;
+}
+function parsePairingCode(text) {
+  const invalid = { ok: false, reason: "invalid" };
+  const compact = text.replace(/\s+/g, "").toUpperCase();
+  if (!compact.startsWith(PREFIX2)) return invalid;
+  const bytes = decode32(compact.slice(PREFIX2.length));
+  if (!bytes || bytes.length < 1 + CHECKSUM_BYTES) return invalid;
+  if (bytes[0] > VERSION && bytes[0] <= MAX_PLAUSIBLE_VERSION) return { ok: false, reason: "newer" };
+  const body = bytes.slice(0, -CHECKSUM_BYTES);
+  const sum = sha256(body);
+  if (!bytes.slice(-CHECKSUM_BYTES).every((b, i) => b === sum[i])) return invalid;
+  if (body[0] !== VERSION) return invalid;
+  const pairing = readBody(body);
+  return pairing ? { ok: true, pairing } : invalid;
+}
+function readBody(body) {
+  let at = 1;
+  const take = (n) => {
+    if (at + n > body.length) return null;
+    at += n;
+    return body.slice(at - n, at);
+  };
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const text = () => {
+    const length = take(2);
+    const bytes = length && take(length[0] << 8 | length[1]);
+    if (!bytes) return null;
+    try {
+      return decoder.decode(bytes);
+    } catch {
+      return null;
+    }
+  };
+  const agentKey = take(KEY_BYTES);
+  const secret = take(KEY_BYTES);
+  const rawName = text();
+  const path = text();
+  const count = take(1)?.[0];
+  if (!agentKey || !secret || rawName === null || path === null || count === void 0) return null;
+  if (count === 0 || count > MAX_ADDRESSES) return null;
+  const urls = [];
+  for (let i = 0; i < count; i++) {
+    const scheme = SCHEMES[take(1)?.[0] ?? -1];
+    const rest = text();
+    if (!scheme || rest === null || !isMachineUrl(scheme + rest)) return null;
+    urls.push(scheme + rest);
+  }
+  if (at !== body.length) return null;
+  const name = rawName.trim() || "machine";
+  if (name.length > MAX_NAME) return null;
+  return {
+    urls,
+    agentKey: b64url.encode(agentKey),
+    secret: b64url.encode(secret),
+    name,
+    // A path the phone cannot use costs the path, not the pairing.
+    ...isPairingPath(path) ? { defaultPath: path } : {}
+  };
+}
+function encode32(bytes) {
+  let out = "";
+  let value = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    value = (value << 8 | byte) & 4095;
+    bits += 8;
+    while (bits >= 5) {
+      out += ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  return bits > 0 ? out + ALPHABET[value << 5 - bits & 31] : out;
+}
+function decode32(text) {
+  const out = [];
+  let value = 0;
+  let bits = 0;
+  for (const char of text) {
+    const digit = ALPHABET.indexOf(char);
+    if (digit < 0) return null;
+    value = (value << 5 | digit) & 4095;
+    bits += 5;
+    if (bits >= 8) {
+      out.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  if (bits >= 5 || (value & (1 << bits) - 1) !== 0) return null;
+  return Uint8Array.from(out);
+}
+
 // ../../node_modules/.pnpm/@noble+ciphers@2.4.0/node_modules/@noble/ciphers/utils.js
 function isBytes3(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array" && "BYTES_PER_ELEMENT" in a && a.BYTES_PER_ELEMENT === 1;
@@ -3740,10 +3850,10 @@ var SHELL_SAFE = /^[\w./@+-]+$/;
 var ADDRESS = /^wss:\/\/[A-Za-z0-9.-]+(:\d{1,5})?(\/[\w-]{0,64})?$/;
 var PWA_ORIGIN = /^https?:\/\/[A-Za-z0-9.-]+(:\d{1,5})?\/?$/;
 var FUNNEL_PORTS_CAP = "https://tailscale.com/cap/funnel-ports?ports=";
-function planSetup(flags, state) {
+function planSetup(given, state) {
   if (state.phonePortOwner === "other") {
     return {
-      error: `127.0.0.1:${flags.phonePort} is taken by another process (another user's agent?): pick a free one with --phone-port, e.g. ${flags.phonePort + 1}`
+      error: `127.0.0.1:${given.phonePort} is taken by another process (another user's agent?): pick a free one with --phone-port, e.g. ${given.phonePort + 1}`
     };
   }
   if (state.hooksPortOwner === "other") {
@@ -3757,21 +3867,27 @@ function planSetup(flags, state) {
   if (state.adoption?.agentLive.kind === "other") {
     return { error: `${state.adoption.agentLive.path} is not a link, and setup only ever removes a link there: move it away, then run tarfa setup again` };
   }
+  const reach = resolveReachability(given, state);
+  if ("error" in reach) return reach;
+  const flags = reach.flags;
+  const relayHint = (error) => reach.relayDefault ? { error: `${error.error} (this machine was reached through a public relay, so setup defaults to Funnel; pass --tailscale serve for tailnet only)` } : error;
   const target = `http://127.0.0.1:${flags.phonePort}`;
   const path = flags.slug ? `/${flags.slug}` : "/";
   const steps = [];
-  const checks = [];
+  const checks = [...reach.notes];
   let serveStep;
   let operatorStep;
   let derived;
+  let publicDerived = false;
   if (flags.tailscale !== "none") {
     const port = flags.tailscalePort ?? (flags.tailscale === "funnel" ? 1e4 : 443);
     const checked = checkTailscale(flags.tailscale, port, state.tailscale);
-    if ("error" in checked) return checked;
+    if ("error" in checked) return relayHint(checked);
     checks.push(...checked.checks);
     if (state.serve === null) return { error: "could not read `tailscale serve status --json`: setup will not add a handler it cannot check against the existing ones" };
     const served = serveNeeds(state.serve, `${checked.host}:${port}`, port, path, target, flags.tailscale === "funnel");
-    if ("error" in served) return served;
+    if ("error" in served) return relayHint(served);
+    publicDerived = flags.tailscale === "funnel" || served.public;
     if (served.public) checks.push(`tailscale: port ${port} is on Funnel, so this address is reachable from the internet`);
     if (served.needed) serveStep = { kind: "tailscale-serve", port, path, target, funnel: flags.tailscale === "funnel" || served.public };
     derived = `wss://${checked.host}:${port}${path === "/" ? "" : path}`;
@@ -3782,6 +3898,7 @@ function planSetup(flags, state) {
   }
   const addresses = [...derived ? [derived] : [], ...flags.addresses];
   if (addresses.length > MAX_ADDRESSES) return { error: `a machine takes at most ${MAX_ADDRESSES} addresses (got ${addresses.length})` };
+  checks.push(describeReachability(addresses.length > 0 ? addresses : reach.kept, state, derived !== void 0 ? { address: derived, public: publicDerived } : null));
   if (state.legacyService) steps.push({ kind: "stop-legacy-service" });
   if (state.stateDir === "legacy") steps.push({ kind: "move-state" });
   const adoption = state.adoption;
@@ -3820,6 +3937,65 @@ function planSetup(flags, state) {
   if (flags.pair) steps.push({ kind: "pair" });
   return { steps, checks };
 }
+var CHOOSE = "say whether phones must reach this machine without Tailscale: --tailscale funnel (with or without Tailscale, through Funnel) or --tailscale serve (only with Tailscale on); --tailscale none --address <wss-url> if you publish the phone port yourself";
+function resolveReachability(flags, state) {
+  const env = withLegacyEnv(parseEnvFile(state.envText ?? ""));
+  const relay = Boolean(env.TARFA_RELAY_URLS?.trim() || env.TARFA_RELAY_URL?.trim()) || state.legacyService;
+  const kept = (env.TARFA_PHONE_ADDRESSES ?? "").split(",").map((a) => a.trim()).filter(Boolean);
+  const settled = (tailscale, over = {}, notes = [], relayDefault = false) => ({
+    flags: { ...flags, ...over, tailscale },
+    kept,
+    notes,
+    relayDefault
+  });
+  if (flags.tailscale !== void 0) {
+    const lost = relay && flags.tailscale === "serve" ? ["this machine was reached through a public relay, so phones reached it without Tailscale; with --tailscale serve they reach it only with Tailscale on (--tailscale funnel keeps the old reach)"] : [];
+    return settled(flags.tailscale, {}, lost);
+  }
+  if (flags.addresses.length > 0 || kept.length > 0) return settled("none");
+  const handler = phonePortHandler(state.serve, `http://127.0.0.1:${flags.phonePort}`, flags.slug, flags.tailscalePort);
+  if (handler && relay && !handler.funnel) {
+    return {
+      error: `this machine was reached through a public relay, but its phone port is served on the tailnet only (port ${handler.port}): pass --tailscale funnel to keep it reachable without Tailscale, or --tailscale serve to make it tailnet-only`
+    };
+  }
+  if (handler) {
+    return settled(handler.funnel ? "funnel" : "serve", { tailscalePort: handler.port, ...handler.slug ? { slug: handler.slug } : {} });
+  }
+  if (relay) {
+    return settled("funnel", {}, ["this machine was reached through a public relay, so setup keeps it reachable without Tailscale: --tailscale funnel (pass --tailscale serve for tailnet only)"], true);
+  }
+  return { error: CHOOSE };
+}
+function phonePortHandler(serve, target, slug, port) {
+  const found = [];
+  for (const [hostPort, web] of Object.entries(serve?.Web ?? {})) {
+    for (const [path, handler] of Object.entries(web.Handlers ?? {})) {
+      if (handler.Proxy?.replace(/\/$/, "") !== target) continue;
+      if (slug !== void 0 && path !== `/${slug}`) continue;
+      const at = Number(hostPort.slice(hostPort.lastIndexOf(":") + 1));
+      if (port !== void 0 && at !== port) continue;
+      found.push({ port: at, ...path === "/" ? {} : { slug: path.slice(1) }, funnel: serve?.AllowFunnel?.[hostPort] === true });
+    }
+  }
+  return found.find((h) => h.funnel) ?? found[0] ?? null;
+}
+function describeReachability(addresses, state, derived) {
+  if (addresses.length === 0) {
+    return "reachability: phones cannot reach this machine yet: it has no phone address (--tailscale funnel or serve, or --address)";
+  }
+  const self = (state.tailscale?.Self?.DNSName ?? "").replace(/\.$/, "");
+  const kinds = addresses.map((address) => {
+    if (derived?.address === address) return derived.public ? "public" : "tailnet";
+    const url = new URL(address);
+    if (state.serve === null || !self || url.hostname !== self) return "unknown";
+    return state.serve.AllowFunnel?.[`${url.hostname}:${url.port || 443}`] === true ? "public" : "tailnet";
+  });
+  const list = addresses.join(", ");
+  if (kinds.includes("public")) return `reachability: phones reach this machine with or without Tailscale (${list})`;
+  if (kinds.every((k) => k === "tailnet")) return `reachability: phones reach this machine only with Tailscale on (${list})`;
+  return `reachability: phones reach this machine at ${list}; setup cannot tell whether that needs Tailscale`;
+}
 function planEnv(flags, state, addresses) {
   const legacy = renameLegacyEnvLines(state.envText ?? "");
   const before = legacy.text;
@@ -3971,8 +4147,8 @@ function parseSetupFlags(argv) {
   if (phonePort === null) return { error: "--phone-port must be a port number (1-65535)" };
   const slug = single.get("--slug");
   if (slug !== void 0 && !SLUG.test(slug)) return { error: "--slug takes letters, digits, _ and - (at most 64)" };
-  const tailscale = single.get("--tailscale") ?? "none";
-  if (tailscale !== "serve" && tailscale !== "funnel" && tailscale !== "none") return { error: "--tailscale takes serve, funnel or none" };
+  const tailscale = single.get("--tailscale");
+  if (tailscale !== void 0 && tailscale !== "serve" && tailscale !== "funnel" && tailscale !== "none") return { error: "--tailscale takes serve, funnel or none" };
   const tailscalePort = single.has("--tailscale-port") ? portNumber(single.get("--tailscale-port")) : void 0;
   if (tailscalePort === null) return { error: "--tailscale-port must be a port number" };
   const bad = addresses.find((a) => !isMachineUrl(a) || !ADDRESS.test(a));
@@ -3993,7 +4169,7 @@ function parseSetupFlags(argv) {
     ...defaultPath !== void 0 ? { defaultPath } : {},
     phonePort,
     ...slug !== void 0 ? { slug } : {},
-    tailscale,
+    ...tailscale !== void 0 ? { tailscale } : {},
     ...tailscalePort !== void 0 ? { tailscalePort } : {},
     addresses,
     ...pwa !== void 0 ? { pwa } : {},
@@ -4207,6 +4383,7 @@ function loadConfig(rawEnv, home) {
     // Usually a symlink to a vocabulary kept with the user's own dotfiles, so one list can
     // serve every machine; TARFA_KEYTERMS_PATH points at it directly instead.
     keytermsPath: env.TARFA_KEYTERMS_PATH ?? join3(stateDir, "keyterms.txt"),
+    dictationKeysPath: join3(stateDir, "dictation-keys.json"),
     clientLogPath: join3(stateDir, "client-log.jsonl"),
     hookEventLogPath: join3(stateDir, "hook-events.jsonl"),
     messageLogPath: join3(stateDir, "messages.jsonl"),
@@ -4938,9 +5115,25 @@ async function browseDir(deps, path, allowedRoots) {
   };
 }
 
-// src/infrastructure/agent-key-file.ts
-import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+// src/infrastructure/atomic-write.ts
+import { chmod, mkdir as mkdir4, rename as rename3, rm, writeFile as writeFile3 } from "node:fs/promises";
 import { dirname as dirname5 } from "node:path";
+async function atomicWrite(path, text, mode) {
+  await mkdir4(dirname5(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}`;
+  try {
+    await writeFile3(temp, text, { mode });
+    await chmod(temp, mode);
+    await rename3(temp, path);
+  } catch (err) {
+    await rm(temp, { force: true });
+    throw err;
+  }
+}
+
+// src/infrastructure/agent-key-file.ts
+import { mkdir as mkdir5, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname6 } from "node:path";
 async function loadOrCreateAgentKeys(path) {
   try {
     return parseKeys(await readFile4(path, "utf8"), path);
@@ -4948,9 +5141,9 @@ async function loadOrCreateAgentKeys(path) {
     if (err.code !== "ENOENT") throw err;
   }
   const keys = generateAgentKeys();
-  await mkdir4(dirname5(path), { recursive: true, mode: 448 });
+  await mkdir5(dirname6(path), { recursive: true, mode: 448 });
   try {
-    await writeFile3(path, `${JSON.stringify(keys, null, 2)}
+    await writeFile4(path, `${JSON.stringify(keys, null, 2)}
 `, { mode: 384, flag: "wx" });
     return keys;
   } catch (err) {
@@ -4958,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);
@@ -5021,8 +5224,8 @@ function forgetDevice(roster, id2) {
 }
 
 // src/infrastructure/file-device-store.ts
-import { mkdir as mkdir5, readFile as readFile5 } from "node:fs/promises";
-import { dirname as dirname6 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile5 } from "node:fs/promises";
+import { dirname as dirname7 } from "node:path";
 import { z as z2 } from "zod";
 var key = z2.string().regex(/^[A-Za-z0-9_-]{43}$/);
 var device = z2.object({ id: z2.string(), x25519: key, ed25519: key, name: z2.string(), enrolledAt: z2.string() });
@@ -5069,7 +5272,7 @@ var FileDeviceStore = class {
       }
       if (parsed?.tokenEnrolment === false) return false;
     }
-    await mkdir5(dirname6(this.filePath), { recursive: true, mode: 448 });
+    await mkdir6(dirname7(this.filePath), { recursive: true, mode: 448 });
     await this.update((roster) => roster);
     return true;
   }
@@ -5083,128 +5286,16 @@ var FileDeviceStore = class {
   }
 };
 
-// src/application/pairing.ts
-var PAIRING_TTL_MS = 10 * 6e4;
-var PAIRING_RETAIN_MS = 24 * 60 * 6e4;
-var retained = (list, now) => list.filter((p) => Date.parse(p.expiresAt) + PAIRING_RETAIN_MS > now.getTime());
-function stateOf(p, now) {
-  if (p.usedAt) return "used";
-  return now.getTime() < Date.parse(p.expiresAt) ? "live" : "expired";
-}
-function addPairing(list, secret, now, ttlMs = PAIRING_TTL_MS) {
-  return [...retained(list, now), { secret, expiresAt: new Date(now.getTime() + ttlMs).toISOString() }];
-}
-function redeemPairing(list, secret, now, device2) {
-  const kept = retained(list, now);
-  const match = secret ? kept.find((p) => constantTimeEqual(p.secret, secret)) : void 0;
-  if (!match) return { list: kept, outcome: "unknown" };
-  if (match.usedAt && match.usedBy === device2) return { list: kept, outcome: "mine" };
-  const state = stateOf(match, now);
-  if (state !== "live") return { list: kept, outcome: state };
-  const at = now.toISOString();
-  const spent = { secret: match.secret, expiresAt: at, usedAt: at, usedBy: device2 };
-  return { list: kept.map((p) => p === match ? spent : p), outcome: "redeemed" };
-}
-
-// src/infrastructure/file-pairing-store.ts
-import { readFile as readFile6 } 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() }));
-var FilePairingStore = class {
-  constructor(filePath, staleLockMs = 1e4) {
-    this.filePath = filePath;
-    this.staleLockMs = staleLockMs;
-  }
-  filePath;
-  staleLockMs;
-  async read() {
-    try {
-      const parsed = schema.safeParse(JSON.parse(await readFile6(this.filePath, "utf8")));
-      return parsed.success ? parsed.data : [];
-    } catch {
-      return [];
-    }
-  }
-  async update(change) {
-    return withFileLock(this.filePath, this.staleLockMs, async () => {
-      const current = await this.read();
-      const next = change(current);
-      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, copyFile, mkdir as mkdir6, readFile as readFile7, writeFile as writeFile4 } from "node:fs/promises";
-import { dirname as dirname7, 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 = dirname7(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 dirname7(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 readFile7(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 chmod(backup, 384);
-      } catch (err) {
-        if (err.code !== "ENOENT") throw err;
-        backup = null;
-      }
-      await mkdir6(dirname7(path), { recursive: true, mode: 448 });
-      await writeFile4(path, text, { mode: 384 });
-      await chmod(path, 384);
-      return backup;
-    }
-  };
+// ../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}`;
 }
 
-// src/infrastructure/file-status-store.ts
-import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "node:fs";
-import { dirname as dirname8 } from "node:path";
-
 // ../contracts/src/domain/workspace-status.ts
 var WORKSPACE_STATUSES = [
   "needs-feedback",
@@ -5228,6 +5319,17 @@ 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",
@@ -5273,244 +5375,274 @@ function audioMediaType(path) {
 }
 
 // ../contracts/src/protocol/messages.ts
-import { z as z6 } from "zod";
+import { z as z5 } from "zod";
 
 // ../contracts/src/protocol/session-channels.ts
-import { z as z5 } from "zod";
+import { z as z4 } from "zod";
 
 // ../contracts/src/protocol/client-log.ts
-import { z as z4 } from "zod";
-var clientLogEventSchema = z4.object({
-  sess: z4.string(),
+import { z as z3 } from "zod";
+var clientLogEventSchema = z3.object({
+  sess: z3.string(),
   // per-app-launch id
-  seq: z4.number().int().nonnegative(),
+  seq: z3.number().int().nonnegative(),
   // monotonic within sess
-  t: z4.number(),
+  t: z3.number(),
   // epoch ms at emit
-  machineId: z4.string().optional(),
+  machineId: z3.string().optional(),
   // absent for app-global events (visibility/online)
-  kind: z4.string(),
-  code: z4.number().int().optional(),
+  kind: z3.string(),
+  code: z3.number().int().optional(),
   // WS close code, when reported
-  reason: z4.string().optional(),
+  reason: z3.string().optional(),
   // classified diagnostic message / close reason
-  online: z4.boolean(),
-  vis: z4.string()
+  online: z3.boolean(),
+  vis: z3.string()
 });
-var clientLogBatchSchema = z4.object({
-  ua: z4.string().optional(),
-  shell: z4.string().optional(),
-  events: z4.array(clientLogEventSchema).min(1).max(500)
+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 = z5.string().min(1).max(64);
-var mediaResultSchema = z5.enum(["ok", "forbidden", "not-found", "too-large", "error"]);
+var id = z4.string().min(1).max(64);
+var mediaResultSchema = z4.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 }),
+  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).
-  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 })
+  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.
-  z5.object({
-    type: z5.literal("media"),
+  z4.object({
+    type: z4.literal("media"),
     id,
     result: mediaResultSchema,
-    mediaType: z5.string().optional(),
-    size: z5.number().int().nonnegative().optional()
+    mediaType: z4.string().optional(),
+    size: z4.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() }),
+  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`.
-  z5.object({ type: z5.literal("browserClosed"), stream: id }),
-  z5.object({ type: z5.literal("clientLogAck"), id, ok: z5.boolean() })
+  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 = z6.enum(
+var workspaceStatusSchema = z5.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(),
+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: z6.object({ owner: z6.string(), repo: z6.string(), ownerType: z6.enum(["user", "org"]).optional() }).optional(),
+  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: z6.boolean().optional(),
+  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: z6.string().optional(),
-  parentId: z6.string().optional(),
-  waitingOn: z6.literal("parent").optional(),
-  asking: z6.boolean().optional()
+  agentAddress: z5.string().optional(),
+  parentId: z5.string().optional(),
+  waitingOn: z5.literal("parent").optional(),
+  asking: z5.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(),
+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: z6.number().optional(),
+    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: z6.number().optional(),
+    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: z6.number().optional()
+    oomKills: z5.number().optional()
   }).optional()
 });
-var clientMessageSchema = z6.discriminatedUnion("type", [
+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).
-  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() }),
+  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.
-  z6.object({ type: z6.literal("makeDir"), parent: z6.string(), name: z6.string() }),
-  z6.object({ type: z6.literal("listRoots") }),
+  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.
-  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") }),
-  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() }),
+  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`.
-  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() }),
+  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.
-  z6.object({ type: z6.literal("lastReply"), workspaceId: z6.string() }),
-  z6.object({ type: z6.literal("resize"), workspaceId: z6.string(), cols: dim, rows: dim }),
+  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.
-  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 }),
+  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.
-  z6.object({ type: z6.literal("setUrgent"), workspaceId: z6.string(), urgent: z6.boolean() }),
+  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`.
-  z6.object({ type: z6.literal("startBrowser"), workspaceId: z6.string() }),
+  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`.
-  z6.object({ type: z6.literal("ping") }),
+  z5.object({ type: z5.literal("ping") }),
   ...sessionClientMessageSchemas
 ]);
-var detachReasonSchema = z6.enum(["opened-elsewhere", "closed", "error"]);
+var detachReasonSchema = z5.enum(["opened-elsewhere", "closed", "error"]);
 var PROTOCOL_VERSION = 1;
-var AGENT_FEATURES = { lastReply: "lastReply" };
-var agentMessageSchema = z6.discriminatedUnion("type", [
+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.
-  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),
+  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).
-    agent: z6.object({ protocol: z6.number().int(), version: z6.string().optional(), features: z6.array(z6.string()).optional().catch(void 0) }).optional().catch(void 0)
+    // `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.
-  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()) }),
+  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.
-  z6.object({ type: z6.literal("roots"), roots: z6.array(z6.string()).default([]) }),
+  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.
-  z6.object({ type: z6.literal("launchers"), detected: z6.array(z6.string()).default([]), custom: z6.array(z6.string()).default([]) }),
+  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.
-  z6.object({ type: z6.literal("keyterms"), keyterms: z6.array(z6.string()).default([]) }),
+  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…").
-  z6.object({ type: z6.literal("dirEntries"), path: z6.string(), subdirs: z6.array(z6.string()), files: z6.array(z6.string()).default([]) }),
+  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).
-  z6.object({
-    type: z6.literal("fileContents"),
-    path: z6.string(),
-    data: z6.string(),
-    truncated: z6.boolean().default(false),
-    binary: z6.boolean().default(false)
+  z5.object({
+    type: z5.literal("fileContents"),
+    path: z5.string(),
+    data: z5.string(),
+    truncated: z5.boolean().default(false),
+    binary: z5.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() }),
+  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).
-  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() }),
+  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.
-  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() }),
+  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.
-  z6.object({ type: z6.literal("browserSessions"), sessions: z6.array(browserSessionSchema).default([]) }),
+  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.
-  z6.object({ type: z6.literal("stats"), stats: machineStatsSchema }),
+  z5.object({ type: z5.literal("stats"), stats: machineStatsSchema }),
   // Reply to the client's liveness `ping` (see clientMessageSchema).
-  z6.object({ type: z6.literal("pong") }),
+  z5.object({ type: z5.literal("pong") }),
   ...sessionAgentMessageSchemas
 ]);
 function parseClientMessage(raw) {
@@ -5518,64 +5650,64 @@ function parseClientMessage(raw) {
 }
 
 // ../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() }),
+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.
-  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(),
+  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
   }),
-  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(),
+  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
   }),
-  z7.object({
-    type: z7.literal("input_touch"),
-    eventType: z7.string(),
-    touchPoints: z7.array(z7.object({ x: z7.number(), y: z7.number() }).passthrough()),
+  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.
-  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") }),
+  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).
-  z7.object({
-    type: z7.literal("setViewport"),
-    width: z7.number().int().positive(),
-    height: z7.number().int().positive()
+  z6.object({
+    type: z6.literal("setViewport"),
+    width: z6.number().int().positive(),
+    height: z6.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(),
+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: z7.object({ deviceWidth: z7.number(), deviceHeight: z7.number() }).passthrough()
+    metadata: z6.object({ deviceWidth: z6.number(), deviceHeight: z6.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()
+  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);
@@ -5584,7 +5716,267 @@ function parseBrowserAgentMessage(raw) {
   return browserAgentMessageSchema.parse(raw);
 }
 
+// src/application/dictation-keys.ts
+var DICTATION_PROVIDERS = ["elevenlabs", "openrouter"];
+var MAX_KEY_LENGTH = 512;
+function providerOf(name) {
+  return DICTATION_PROVIDERS.includes(name) ? name : null;
+}
+function checkKey(raw) {
+  const key2 = raw.trim();
+  if (key2 === "") return { ok: false, error: "no key given" };
+  if (/\s/.test(key2)) return { ok: false, error: "a key holds no whitespace" };
+  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 {
+    value = JSON.parse(raw);
+  } catch {
+    return "malformed";
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return "malformed";
+  const keys = {};
+  for (const provider of DICTATION_PROVIDERS) {
+    const candidate = value[provider];
+    if (typeof candidate !== "string") continue;
+    const checked = checkKey(candidate);
+    if (checked.ok) keys[provider] = checked.key;
+  }
+  return keys;
+}
+function withKey(keys, provider, key2) {
+  return { ...keys, [provider]: key2 };
+}
+function withoutKey(keys, provider) {
+  const { [provider]: _removed, ...rest } = keys;
+  return rest;
+}
+async function changeDictationKey(store, provider, raw) {
+  let key2 = null;
+  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));
+  return "problem" in result ? { ok: false, error: result.problem } : { ok: true };
+}
+
+// src/infrastructure/file-dictation-keys-store.ts
+import { readFile as readFile6, stat as stat3 } from "node:fs/promises";
+
+// src/application/private-files.ts
+function exposedFiles(files) {
+  return files.filter(({ mode }) => (mode & 63) !== 0).map(({ path, mode }) => `${path} is readable or writable by other users (mode ${(mode & 511).toString(8)}): run \`chmod 600 ${path}\``);
+}
+
+// src/infrastructure/file-dictation-keys-store.ts
+var STALE_LOCK_MS = 1e4;
+var FileDictationKeysStore = class {
+  constructor(path, report = () => {
+  }) {
+    this.path = path;
+    this.report = report;
+  }
+  path;
+  report;
+  async load() {
+    let mode;
+    try {
+      mode = (await stat3(this.path)).mode;
+    } catch (err) {
+      if (err.code === "ENOENT") return { keys: {} };
+      return { problem: `${this.path} cannot be read (${err.code ?? "error"})` };
+    }
+    const exposed = exposedFiles([{ path: this.path, mode }]);
+    if (exposed.length > 0) return { problem: exposed[0] };
+    let raw;
+    try {
+      raw = await readFile6(this.path, "utf8");
+    } catch (err) {
+      return { problem: `${this.path} cannot be read (${err.code ?? "error"})` };
+    }
+    const keys = parseDictationKeys(raw);
+    return keys === "malformed" ? { problem: `${this.path} is malformed` } : { keys };
+  }
+  async read() {
+    const loaded = await this.load();
+    if ("problem" in loaded) {
+      this.report(loaded.problem);
+      return {};
+    }
+    return loaded.keys;
+  }
+  async update(change) {
+    return withFileLock(this.path, STALE_LOCK_MS, async () => {
+      const loaded = await this.load();
+      if ("problem" in loaded) return { problem: loaded.problem };
+      await atomicWrite(this.path, `${JSON.stringify(change(loaded.keys), null, 2)}
+`, 384);
+      return { ok: true };
+    });
+  }
+};
+
+// src/application/pairing.ts
+var PAIRING_TTL_MS = 20 * 6e4;
+var PAIRING_RETAIN_MS = 24 * 60 * 6e4;
+var retained = (list, now) => list.filter((p) => Date.parse(p.expiresAt) + PAIRING_RETAIN_MS > now.getTime());
+function stateOf(p, now) {
+  if (p.usedAt) return "used";
+  return now.getTime() < Date.parse(p.expiresAt) ? "live" : "expired";
+}
+function addPairing(list, secret, now, ttlMs = PAIRING_TTL_MS) {
+  return [...retained(list, now), { secret, expiresAt: new Date(now.getTime() + ttlMs).toISOString() }];
+}
+function redeemPairing(list, secret, now, device2) {
+  const kept = retained(list, now);
+  const match = secret ? kept.find((p) => constantTimeEqual(p.secret, secret)) : void 0;
+  if (!match) return { list: kept, outcome: "unknown" };
+  if (match.usedAt && match.usedBy === device2) return { list: kept, outcome: "mine" };
+  const state = stateOf(match, now);
+  if (state !== "live") return { list: kept, outcome: state };
+  const at = now.toISOString();
+  const spent = { secret: match.secret, expiresAt: at, usedAt: at, usedBy: device2 };
+  return { list: kept.map((p) => p === match ? spent : p), outcome: "redeemed" };
+}
+
+// src/application/pairing-link.ts
+var GENERIC_MACHINE_IDS = /* @__PURE__ */ new Set(["", "local", "localhost"]);
+function pairingName(machineId, hostname) {
+  return GENERIC_MACHINE_IDS.has(machineId) ? hostname.split(".")[0] : machineId;
+}
+function announcedAddresses(phoneAddresses2) {
+  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)) {
+    throw new Error(`TARFA_DEFAULT_PATH must be an absolute path of at most 128 characters (got ${deps.defaultPath})`);
+  }
+  const secret = deps.newSecret();
+  await deps.pairings.update((list) => addPairing(list, secret, deps.now(), deps.ttlMs));
+  return {
+    urls: input.phoneUrls,
+    agentKey: deps.keys.x25519.publicKey,
+    secret,
+    name: deps.machineId,
+    ...deps.defaultPath !== void 0 ? { defaultPath: deps.defaultPath } : {}
+  };
+}
+
+// src/infrastructure/file-pairing-store.ts
+import { readFile as readFile7 } from "node:fs/promises";
+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;
+    this.staleLockMs = staleLockMs;
+  }
+  filePath;
+  staleLockMs;
+  async read() {
+    try {
+      const parsed = schema.safeParse(JSON.parse(await readFile7(this.filePath, "utf8")));
+      return parsed.success ? parsed.data : [];
+    } catch {
+      return [];
+    }
+  }
+  async update(change) {
+    return withFileLock(this.filePath, this.staleLockMs, async () => {
+      const current = await this.read();
+      const next = change(current);
+      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";
 var FileStatusStore = class {
   constructor(filePath, now = Date.now) {
     this.filePath = filePath;
@@ -5697,7 +6089,7 @@ var FileStatusStore = class {
     }
   }
   persist() {
-    mkdirSync(dirname8(this.filePath), { recursive: true });
+    mkdirSync(dirname9(this.filePath), { recursive: true });
     writeFileSync(this.filePath, JSON.stringify(Object.fromEntries(this.statuses), null, 2), "utf8");
   }
 };
@@ -5726,8 +6118,8 @@ function parseEntry(value) {
 }
 
 // src/infrastructure/file-parked-store.ts
-import { readFile as readFile8, writeFile as writeFile5, mkdir as mkdir7 } from "node:fs/promises";
-import { dirname as dirname9 } from "node:path";
+import { readFile as readFile9, writeFile as writeFile6, mkdir as mkdir8 } from "node:fs/promises";
+import { dirname as dirname10 } from "node:path";
 var FileParkedStore = class {
   constructor(filePath) {
     this.filePath = filePath;
@@ -5736,7 +6128,7 @@ var FileParkedStore = class {
   async list() {
     let raw;
     try {
-      raw = await readFile8(this.filePath, "utf8");
+      raw = await readFile9(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -5761,8 +6153,8 @@ var FileParkedStore = class {
     await this.persist(rest);
   }
   async persist(entries) {
-    await mkdir7(dirname9(this.filePath), { recursive: true });
-    await writeFile5(this.filePath, JSON.stringify(entries, null, 2), "utf8");
+    await mkdir8(dirname10(this.filePath), { recursive: true });
+    await writeFile6(this.filePath, JSON.stringify(entries, null, 2), "utf8");
   }
 };
 function parseEntry2(value) {
@@ -5796,10 +6188,10 @@ function parseEntry2(value) {
 }
 
 // src/infrastructure/fs-file-writer.ts
-import { mkdir as mkdir8, writeFile as writeFile6, access } from "node:fs/promises";
+import { mkdir as mkdir9, writeFile as writeFile7, access } from "node:fs/promises";
 var FsFileWriter = class {
   async ensureDir(dir) {
-    await mkdir8(dir, { recursive: true });
+    await mkdir9(dir, { recursive: true });
   }
   async exists(path) {
     try {
@@ -5810,7 +6202,7 @@ var FsFileWriter = class {
     }
   }
   async writeFile(path, bytes) {
-    await writeFile6(path, bytes);
+    await writeFile7(path, bytes);
   }
 };
 
@@ -6111,11 +6503,10 @@ export {
   parseDeviceHello,
   deviceFingerprint,
   MAX_ADDRESSES,
-  isPairingPath,
   generatePairingSecret,
   pairingLink,
-  parsePairingLink,
   isMachineUrl,
+  pairingCode,
   REFUSAL,
   IN_BAND_REFUSAL,
   DEVICE_REFUSED,
@@ -6158,7 +6549,9 @@ export {
   getRecentPaths,
   pathWithinRoots,
   browseDir,
+  atomicWrite,
   loadOrCreateAgentKeys,
+  readAgentPublicKey,
   enrolmentMode,
   withEnrolmentMode,
   standingOf,
@@ -6166,13 +6559,6 @@ export {
   revokeDevice,
   forgetDevice,
   FileDeviceStore,
-  PAIRING_TTL_MS,
-  addPairing,
-  redeemPairing,
-  FilePairingStore,
-  mainCheckout,
-  locateAgentEnv,
-  agentEnvFile,
   isWorkspaceStatus,
   runsClaude,
   imageMediaType,
@@ -6183,6 +6569,21 @@ export {
   parseClientMessage,
   parseBrowserClientMessage,
   parseBrowserAgentMessage,
+  workspaceLink,
+  DICTATION_PROVIDERS,
+  providerOf,
+  changeDictationKey,
+  exposedFiles,
+  FileDictationKeysStore,
+  PAIRING_TTL_MS,
+  redeemPairing,
+  pairingName,
+  announcedAddresses,
+  mintPairing,
+  FilePairingStore,
+  mainCheckout,
+  locateAgentEnv,
+  agentEnvFile,
   FileStatusStore,
   FileParkedStore,
   FsFileWriter,