@tarfa/cli 0.1.4 → 0.1.6

package/dist/{chunk-OC5VX7K3.js → chunk-UPCCR4ZA.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"),
@@ -4432,8 +4609,9 @@ var TmuxAdapter = class {
     return set;
   }
   async createSession(input) {
+    const env = Object.entries(input.env ?? {}).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
     try {
-      await this.tmux(["new-session", "-d", "-s", input.name, "-c", input.cwd, input.command]);
+      await this.tmux(["new-session", "-d", "-s", input.name, "-c", input.cwd, ...env, input.command]);
     } catch (err) {
       if ((err.stderr ?? "").includes("duplicate session")) throw new DuplicateSessionError(input.name);
       throw err;
@@ -4937,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);
@@ -4947,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) {
@@ -5020,8 +5214,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() });
@@ -5068,7 +5262,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;
   }
@@ -5082,8 +5276,112 @@ var FileDeviceStore = class {
   }
 };
 
+// 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 };
+}
+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;
+    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 = 10 * 6e4;
+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) {
@@ -5105,8 +5403,32 @@ function redeemPairing(list, secret, now, 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 valid = phoneAddresses2.length > 0 && phoneAddresses2.length <= MAX_ADDRESSES && phoneAddresses2.every(isMachineUrl);
+  return valid ? 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 readFile6 } from "node:fs/promises";
+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() }));
 var FilePairingStore = class {
@@ -5118,7 +5440,7 @@ var FilePairingStore = class {
   staleLockMs;
   async read() {
     try {
-      const parsed = schema.safeParse(JSON.parse(await readFile6(this.filePath, "utf8")));
+      const parsed = schema.safeParse(JSON.parse(await readFile7(this.filePath, "utf8")));
       return parsed.success ? parsed.data : [];
     } catch {
       return [];
@@ -5138,8 +5460,8 @@ var FilePairingStore = class {
 // 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 { 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";
 
@@ -5159,10 +5481,10 @@ function withoutGitVars(env) {
 }
 async function mainCheckout(kind2 = installKind()) {
   if (kind2 === "package") return null;
-  const here = dirname7(fileURLToPath2(import.meta.url));
+  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 dirname7(stdout.trim());
+    return dirname8(stdout.trim());
   } catch {
     return resolve5(here, "..", "..", "..", "..");
   }
@@ -5175,7 +5497,7 @@ function agentEnvFile(path, now = () => /* @__PURE__ */ new Date()) {
     path,
     read: async () => {
       try {
-        return await readFile7(path, "utf8");
+        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`);
@@ -5187,14 +5509,14 @@ function agentEnvFile(path, now = () => /* @__PURE__ */ new Date()) {
       let backup = `${path}.bak-${now().toISOString().replace(/[:.]/g, "-")}`;
       try {
         await copyFile(path, backup);
-        await chmod(backup, 384);
+        await chmod2(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);
+      await mkdir7(dirname8(path), { recursive: true, mode: 448 });
+      await writeFile5(path, text, { mode: 384 });
+      await chmod2(path, 384);
       return backup;
     }
   };
@@ -5202,7 +5524,7 @@ function agentEnvFile(path, now = () => /* @__PURE__ */ new Date()) {
 
 // src/infrastructure/file-status-store.ts
 import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "node:fs";
-import { dirname as dirname8 } from "node:path";
+import { dirname as dirname9 } from "node:path";
 
 // ../contracts/src/domain/workspace-status.ts
 var WORKSPACE_STATUSES = [
@@ -5387,6 +5709,7 @@ var machineStatsSchema = z6.object({
     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() }),
@@ -5403,6 +5726,13 @@ var clientMessageSchema = z6.discriminatedUnion("type", [
   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() }),
@@ -5439,7 +5769,12 @@ var clientMessageSchema = z6.discriminatedUnion("type", [
 ]);
 var detachReasonSchema = z6.enum(["opened-elsewhere", "closed", "error"]);
 var PROTOCOL_VERSION = 1;
-var AGENT_FEATURES = { lastReply: "lastReply" };
+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
@@ -5454,7 +5789,14 @@ var agentMessageSchema = z6.discriminatedUnion("type", [
     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).
-    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: 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.
@@ -5473,6 +5815,16 @@ var agentMessageSchema = z6.discriminatedUnion("type", [
   // 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…").
@@ -5696,7 +6048,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");
   }
 };
@@ -5725,8 +6077,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;
@@ -5735,7 +6087,7 @@ var FileParkedStore = class {
   async list() {
     let raw;
     try {
-      raw = await readFile8(this.filePath, "utf8");
+      raw = await readFile9(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -5760,8 +6112,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) {
@@ -5795,10 +6147,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 {
@@ -5809,7 +6161,7 @@ var FsFileWriter = class {
     }
   }
   async writeFile(path, bytes) {
-    await writeFile6(path, bytes);
+    await writeFile7(path, bytes);
   }
 };
 
@@ -5878,12 +6230,12 @@ function loginShellResolver(shell = process.env.SHELL || "/bin/sh") {
 }
 
 // src/infrastructure/codex-app-server.ts
-import { homedir } from "node:os";
+import { realpath as realpath3 } from "node:fs/promises";
 import { join as join7 } from "node:path";
 import { WebSocket } from "ws";
 var CodexAppServerDown = class extends Error {
-  constructor() {
-    super("the Codex app server is not running");
+  constructor(socketPath) {
+    super(`the Codex app server is not running (no socket at ${socketPath})`);
   }
 };
 var CodexRpcError = class extends Error {
@@ -5954,8 +6306,8 @@ var Connection = class {
 var CodexAppServer = class {
   socketPath;
   timeoutMs;
-  constructor(options = {}) {
-    this.socketPath = options.socketPath ?? join7(homedir(), ".codex", "app-server-control", "app-server-control.sock");
+  constructor(options) {
+    this.socketPath = "socketPath" in options ? options.socketPath : join7(options.codexHome, "app-server-control", "app-server-control.sock");
     this.timeoutMs = options.timeoutMs ?? 5e3;
   }
   loadedThreads() {
@@ -6009,9 +6361,15 @@ var CodexAppServer = class {
       return thread.id;
     });
   }
-  call(run) {
+  // Codex 0.167 binds the socket under /tmp/codex-daemon-<uid>/ and publishes this path as a link
+  // to it. Connecting to the link's target keeps the path within the 107 bytes a unix socket
+  // address holds, however deep CODEX_HOME is; a link to nothing means no daemon.
+  async call(run) {
+    const target = await realpath3(this.socketPath).catch((err) => {
+      throw err.code === "ENOENT" ? new CodexAppServerDown(this.socketPath) : err;
+    });
     return new Promise((resolve6, reject) => {
-      const ws = new WebSocket(`ws+unix://${this.socketPath}:/`, { perMessageDeflate: false });
+      const ws = new WebSocket(`ws+unix://${target}:/`, { perMessageDeflate: false });
       const c = new Connection(ws);
       let settled = false;
       const settle = (fn) => {
@@ -6030,7 +6388,7 @@ var CodexAppServer = class {
       }, this.timeoutMs);
       ws.once("error", (err) => {
         const down = err.code === "ENOENT" || err.code === "ECONNREFUSED";
-        settle(() => reject(down ? new CodexAppServerDown() : err));
+        settle(() => reject(down ? new CodexAppServerDown(this.socketPath) : err));
       });
       ws.once("close", () => settle(() => reject(new Error("the Codex app server closed the connection"))));
       ws.once("open", () => {
@@ -6046,6 +6404,45 @@ var CodexAppServer = class {
   }
 };
 
+// src/infrastructure/codex-versions.ts
+import { execFile as execFile5 } from "node:child_process";
+function loginShell(shell = process.env.SHELL || "/bin/sh", extraEnv = {}) {
+  return (script) => new Promise((resolve6, reject) => {
+    execFile5(shell, ["-lc", script], { env: { ...childEnv(), ...extraEnv }, timeout: 15e3 }, (err, stdout) => err ? reject(err) : resolve6(stdout));
+  });
+}
+function codexVersions(run = loginShell()) {
+  return async () => {
+    const [cliOut, daemonOut] = await Promise.all([
+      run("codex --version").catch((err) => {
+        throw new Error(`cannot run codex --version: ${err.message}`);
+      }),
+      run("codex app-server daemon version").catch((err) => {
+        throw new Error(`cannot read the Codex app server's version: ${err.message}`);
+      })
+    ]);
+    const cli = cliOut.trim().split(/\s+/).pop() ?? "";
+    let appServer;
+    try {
+      appServer = JSON.parse(daemonOut).appServerVersion;
+    } catch {
+      appServer = void 0;
+    }
+    if (typeof appServer !== "string" || appServer === "") throw new Error("the Codex app server is not running");
+    return { cli, appServer };
+  };
+}
+
+// src/infrastructure/codex-home.ts
+import { join as join8 } from "node:path";
+var MARK = "codex-home=";
+async function resolveCodexHome(env, home, run = loginShell()) {
+  if (env.CODEX_HOME) return env.CODEX_HOME;
+  const out = await run(`printf '\\n${MARK}%s\\n' "\${CODEX_HOME-}"`).catch(() => "");
+  const value = out.split("\n").reverse().find((line) => line.startsWith(MARK))?.slice(MARK.length);
+  return value || join8(home, ".codex");
+}
+
 export {
   packageRoot,
   packageVersion,
@@ -6065,11 +6462,10 @@ export {
   parseDeviceHello,
   deviceFingerprint,
   MAX_ADDRESSES,
-  isPairingPath,
   generatePairingSecret,
   pairingLink,
-  parsePairingLink,
   isMachineUrl,
+  pairingCode,
   REFUSAL,
   IN_BAND_REFUSAL,
   DEVICE_REFUSED,
@@ -6112,6 +6508,7 @@ export {
   getRecentPaths,
   pathWithinRoots,
   browseDir,
+  atomicWrite,
   loadOrCreateAgentKeys,
   enrolmentMode,
   withEnrolmentMode,
@@ -6120,9 +6517,16 @@ export {
   revokeDevice,
   forgetDevice,
   FileDeviceStore,
+  DICTATION_PROVIDERS,
+  providerOf,
+  changeDictationKey,
+  exposedFiles,
+  FileDictationKeysStore,
   PAIRING_TTL_MS,
-  addPairing,
   redeemPairing,
+  pairingName,
+  announcedAddresses,
+  mintPairing,
   FilePairingStore,
   mainCheckout,
   locateAgentEnv,
@@ -6149,5 +6553,8 @@ export {
   detectInstalled,
   loginShellResolver,
   CodexAppServerDown,
-  CodexAppServer
+  CodexAppServer,
+  loginShell,
+  codexVersions,
+  resolveCodexHome
 };