@tarfa/cli 0.1.5 → 0.1.6

package/README.md

@@ -17,13 +17,14 @@ tarfa setup --machine-id <name> --project-roots ~/workspace --tailscale serve --
 
 `tarfa setup` writes `~/.tarfa/agent.env`, the agent key, the service (a systemd user unit or a
 launchd agent) and the Claude Code hooks, publishes the phone port with Tailscale, and prints a
-pairing link and QR code. Open it on the phone, inside the installed app. `tarfa setup --help`
+pairing code and its QR code. In the installed app on the phone, Settings → Add machine: scan it,
+or paste the code. `tarfa setup --help`
 lists every flag.
 
 ## Day to day
 
 ```sh
-tarfa pair        # a one-time pairing link for another phone
+tarfa pair        # a one-time pairing code for another phone (--link: a link, for an older app)
 tarfa devices     # paired phones; revoke or forget one
 tarfa update      # install the newest release and restart the agent; workspaces survive
 tarfa ls          # this machine's workspaces

package/dist/{chunk-KTUXNG4Q.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"),
@@ -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) {
@@ -5021,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() });
@@ -5069,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;
   }
@@ -5083,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) {
@@ -5106,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 {
@@ -5119,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 [];
@@ -5139,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";
 
@@ -5160,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, "..", "..", "..", "..");
   }
@@ -5176,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`);
@@ -5188,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;
     }
   };
@@ -5203,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 = [
@@ -5388,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() }),
@@ -5404,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() }),
@@ -5440,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
@@ -5455,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.
@@ -5474,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…").
@@ -5697,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");
   }
 };
@@ -5726,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;
@@ -5736,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 [];
     }
@@ -5761,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) {
@@ -5796,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 {
@@ -5810,7 +6161,7 @@ var FsFileWriter = class {
     }
   }
   async writeFile(path, bytes) {
-    await writeFile6(path, bytes);
+    await writeFile7(path, bytes);
   }
 };
 
@@ -6111,11 +6462,10 @@ export {
   parseDeviceHello,
   deviceFingerprint,
   MAX_ADDRESSES,
-  isPairingPath,
   generatePairingSecret,
   pairingLink,
-  parsePairingLink,
   isMachineUrl,
+  pairingCode,
   REFUSAL,
   IN_BAND_REFUSAL,
   DEVICE_REFUSED,
@@ -6158,6 +6508,7 @@ export {
   getRecentPaths,
   pathWithinRoots,
   browseDir,
+  atomicWrite,
   loadOrCreateAgentKeys,
   enrolmentMode,
   withEnrolmentMode,
@@ -6166,9 +6517,16 @@ export {
   revokeDevice,
   forgetDevice,
   FileDeviceStore,
+  DICTATION_PROVIDERS,
+  providerOf,
+  changeDictationKey,
+  exposedFiles,
+  FileDictationKeysStore,
   PAIRING_TTL_MS,
-  addPairing,
   redeemPairing,
+  pairingName,
+  announcedAddresses,
+  mintPairing,
   FilePairingStore,
   mainCheckout,
   locateAgentEnv,

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import {
   CodexAppServer,
+  DICTATION_PROVIDERS,
   FileClaudeSessionsStore,
   FileDeviceStore,
+  FileDictationKeysStore,
   FileHiddenFoldersStore,
   FilePairingStore,
   FileParkedStore,
@@ -17,9 +19,10 @@ import {
   STATE_DIR,
   ShortWorkspaceIds,
   TmuxAdapter,
-  addPairing,
   agentEnvFile,
+  atomicWrite,
   browseDir,
+  changeDictationKey,
   childEnv,
   cloneOfUnit,
   codexVersions,
@@ -37,7 +40,6 @@ import {
   isEntrypoint,
   isHiddenPath,
   isMachineUrl,
-  isPairingPath,
   listWorkspaces,
   loadConfig,
   loadOrCreateAgentKeys,
@@ -46,14 +48,17 @@ import {
   loginShellResolver,
   mainCheckout,
   migrateStateDir,
+  mintPairing,
   packageRoot,
   packageVersion,
+  pairingCode,
   pairingLink,
+  pairingName,
   parseEnvFile,
-  parsePairingLink,
   parseSetupFlags,
   planCli,
   planSetup,
+  providerOf,
   renderService,
   resolveCodexHome,
   resolveStateDir,
@@ -66,13 +71,13 @@ import {
   unitRunsLauncher,
   withEnrolmentMode,
   withLegacyEnv
-} from "./chunk-KTUXNG4Q.js";
+} from "./chunk-UPCCR4ZA.js";
 
 // src/cli.ts
 import { randomBytes } from "node:crypto";
 import { homedir, hostname, userInfo } from "node:os";
-import { readFile as readFile6, mkdir as mkdir4, realpath as realpath2 } from "node:fs/promises";
-import { dirname as dirname4, join as joinPath, resolve as resolvePath } from "node:path";
+import { readFile as readFile6, mkdir as mkdir3, realpath as realpath2 } from "node:fs/promises";
+import { dirname as dirname3, join as joinPath, resolve as resolvePath } from "node:path";
 
 // src/application/format-workspace-table.ts
 var TITLE_MAX = 40;
@@ -653,29 +658,13 @@ async function firstOnPath(name, pathVar) {
   return null;
 }
 
-// src/infrastructure/atomic-write.ts
-import { chmod as chmod3, mkdir as mkdir3, rename as rename2, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname3 } from "node:path";
-async function atomicWrite(path, text, mode) {
-  await mkdir3(dirname3(path), { recursive: true });
-  const temp = `${path}.tmp-${process.pid}`;
-  try {
-    await writeFile2(temp, text, { mode });
-    await chmod3(temp, mode);
-    await rename2(temp, path);
-  } catch (err) {
-    await rm2(temp, { force: true });
-    throw err;
-  }
-}
-
 // src/infrastructure/agent-log.ts
 import { open, readFile as readFile4, stat as stat3 } from "node:fs/promises";
 import { join as join5 } from "node:path";
 
 // src/infrastructure/service-install.ts
 import { execFile as execFile2 } from "node:child_process";
-import { chmod as chmod4, cp, copyFile as copyFile3, readFile as readFile3, rm as rm3, stat as stat2 } from "node:fs/promises";
+import { chmod as chmod3, cp, copyFile as copyFile3, readFile as readFile3, rm as rm2, stat as stat2 } from "node:fs/promises";
 import { join as join4 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 var exec2 = promisify2(execFile2);
@@ -705,7 +694,7 @@ async function backupFile(path) {
   if (!await exists(path)) return null;
   const copy = `${path}.bak-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
   await copyFile3(path, copy);
-  await chmod4(copy, (await stat2(path)).mode & 511);
+  await chmod3(copy, (await stat2(path)).mode & 511);
   return copy;
 }
 var LABEL_GONE_MS = 1e4;
@@ -759,7 +748,7 @@ function serviceInstall(options) {
         return [`launchctl bootout ${domain}/${LEGACY_LABEL}`];
       },
       async removeLegacy() {
-        await rm3(legacyPlist, { force: true });
+        await rm2(legacyPlist, { force: true });
         return [`removed ${legacyPlist}`];
       }
     };
@@ -811,9 +800,9 @@ function serviceInstall(options) {
       return ran.map(([command, args]) => `${command} ${args.join(" ")}`);
     },
     async removeLegacy() {
-      await rm3(legacyUnit, { force: true });
+      await rm2(legacyUnit, { force: true });
       if (await exists(legacyDropIns) && !await exists(dropIns)) await cp(legacyDropIns, dropIns, { recursive: true });
-      await rm3(legacyDropIns, { recursive: true, force: true });
+      await rm2(legacyDropIns, { recursive: true, force: true });
       await run4("systemctl", ["--user", "daemon-reload"]);
       return [`removed ${legacyUnit} and its drop-ins`, "systemctl --user daemon-reload"];
     }
@@ -980,29 +969,50 @@ function attempt(port, ms) {
   });
 }
 
-// src/cli.ts
-import encodeQR from "qr";
-
-// src/application/pairing-link.ts
-var GENERIC_MACHINE_IDS = /* @__PURE__ */ new Set(["", "local", "localhost"]);
-function pairingName(machineId, hostname2) {
-  return GENERIC_MACHINE_IDS.has(machineId) ? hostname2.split(".")[0] : machineId;
-}
-async function mintPairingLink(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})`);
+// src/infrastructure/read-secret.ts
+async function readSecret(prompt) {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  process.stderr.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding("utf8");
+  try {
+    return await new Promise((resolve2, reject) => {
+      let typed = "";
+      const onData = (data) => {
+        for (const ch of data) {
+          if (ch === "\r" || ch === "\n" || ch === "") {
+            stdin.off("data", onData);
+            resolve2(typed);
+            return;
+          }
+          if (ch === "") {
+            stdin.off("data", onData);
+            reject(new Error("cancelled"));
+            return;
+          }
+          if (ch === "\x7F" || ch === "\b") typed = typed.slice(0, -1);
+          else typed += ch;
+        }
+      };
+      stdin.on("data", onData);
+      stdin.once("end", () => reject(new Error("cancelled")));
+    });
+  } finally {
+    stdin.setRawMode(false);
+    stdin.pause();
+    process.stderr.write("\n");
   }
-  const secret = deps.newSecret();
-  await deps.pairings.update((list) => addPairing(list, secret, deps.now(), deps.ttlMs));
-  return pairingLink(input.pwaOrigin, {
-    urls: input.phoneUrls,
-    agentKey: deps.keys.x25519.publicKey,
-    secret,
-    name: deps.machineId,
-    ...deps.defaultPath !== void 0 ? { defaultPath: deps.defaultPath } : {}
-  });
 }
 
+// src/cli.ts
+import encodeQR from "qr";
+
 // src/infrastructure/agent-service.ts
 import { execFile as execFile5 } from "node:child_process";
 import { promisify as promisify5 } from "node:util";
@@ -1252,6 +1262,8 @@ async function run3(argv, rawEnv, home, io = {}) {
     }
     case "devices":
       return devices(new FileDeviceStore(config.devicesPath), rest);
+    case "dictation-key":
+      return dictationKey(new FileDictationKeysStore(config.dictationKeysPath), rest, io.secret ?? readSecret);
     default:
       throw new UsageError(`unknown command: ${command} (run \`tarfa --help\`)`);
   }
@@ -1260,8 +1272,9 @@ var HELP = `usage: tarfa <command> [options]   (\`tarfa setup --help\`, \`tarfa
 
 Set up this machine:
   setup          write agent.env, the agent key, the service and the hooks, then check the phone port
-  pair           print a one-time pairing link and QR code for a phone
+  pair           print a one-time pairing code and QR code for a phone (--link: a link, for an older app)
   devices        list, revoke or forget paired phones; open or close enrolment
+  dictation-key  store the ElevenLabs or OpenRouter key every paired phone dictates with
   update         install the newest @tarfa/cli and apply it (package installs)
   apply          rewrite the launcher and service if they changed, reinstall the hooks, restart
   install-hooks  install the Claude Code and Codex hooks that report each workspace's status
@@ -1287,6 +1300,7 @@ var COMMANDS = /* @__PURE__ */ new Set([
   "connect",
   "relay-key",
   "devices",
+  "dictation-key",
   "install-hooks",
   "ls",
   "spawn",
@@ -1587,7 +1601,8 @@ async function readStdin(ttyError) {
   return Buffer.concat(chunks).toString("utf8");
 }
 var RELAYS_GONE = "relays are gone: tarfa setup sets a machine up for phones, and tarfa pair pairs one";
-var PAIR_USAGE = "usage: tarfa pair [--pwa <PWA origin>] [--ttl <minutes, 1-10, default 10>]";
+var MAX_PAIRING_NAME = 64;
+var PAIR_USAGE = `usage: tarfa pair [--pwa <PWA origin>] [--ttl <minutes, 1-${PAIRING_TTL_MS / 6e4}, default ${PAIRING_TTL_MS / 6e4}>] [--link]`;
 function takeOption(args, name, usage, Failure = Error) {
   const at = args.indexOf(name);
   if (at === -1) return void 0;
@@ -1629,6 +1644,8 @@ async function pair(argv, env, home) {
   const config = loadConfig({ ...env, ...await agentEnvValues(env, home) }, home);
   let origin = pwaOrigin(takeOption(args, "--pwa", PAIR_USAGE));
   const ttl = takeOption(args, "--ttl", PAIR_USAGE) ?? String(PAIRING_TTL_MS / 6e4);
+  const linkAt = args.indexOf("--link");
+  if (linkAt !== -1) args.splice(linkAt, 1);
   const minutes = Number(ttl);
   if (!/^\d+$/.test(ttl) || minutes < 1 || minutes * 6e4 > PAIRING_TTL_MS) throw new Error(`--ttl takes whole minutes from 1 to ${PAIRING_TTL_MS / 6e4} (got ${ttl})`);
   if (args.length > 0) throw new Error(PAIR_USAGE);
@@ -1643,19 +1660,21 @@ async function pair(argv, env, home) {
   const bad = config.phoneAddresses.find((url) => !isMachineUrl(url));
   if (bad) throw new Error(`TARFA_PHONE_ADDRESSES holds ${bad}, which a phone refuses: wss://<host>[:port][/<slug>] (run tarfa setup)`);
   if (config.phoneAddresses.length > MAX_ADDRESSES) throw new Error(`TARFA_PHONE_ADDRESSES holds more than ${MAX_ADDRESSES} addresses`);
-  const link = await mintPairingLink(
+  const machineId = pairingName(config.machineId, hostname());
+  if (machineId.trim().length > MAX_PAIRING_NAME) throw new Error(`TARFA_MACHINE_ID must be at most ${MAX_PAIRING_NAME} characters, the name phones show (got ${machineId.length})`);
+  const pairing = await mintPairing(
     {
       keys: await loadOrCreateAgentKeys(config.agentKeyPath),
-      machineId: pairingName(config.machineId, hostname()),
+      machineId,
       ...config.defaultPath ? { defaultPath: config.defaultPath } : {},
       pairings: new FilePairingStore(config.pairingPath),
       newSecret: generatePairingSecret,
       now: () => /* @__PURE__ */ new Date(),
       ttlMs: minutes * 6e4
     },
-    { phoneUrls: config.phoneAddresses, pwaOrigin: origin }
+    { phoneUrls: config.phoneAddresses }
   );
-  return pairingInstructions(link, minutes);
+  return pairingInstructions(pairing, { origin, minutes, link: linkAt !== -1 });
 }
 var WaitTimeout = class extends Error {
   exitCode = 124;
@@ -1675,11 +1694,16 @@ replace anything it did not make (an agent key, another tailscale serve entry).
 
   --machine-id <id>             the name phones show for this machine
   --project-roots <dir,dir>     absolute folders new workspaces may be made in
-  --default-path <dir>          where a phone resolves relative paths (in pairing links)
+  --default-path <dir>          where a phone resolves relative paths (sent when pairing)
   --phone-port <n>              loopback port phones reach (default 8797); every Linux user on one
                                 machine needs their own, e.g. 8797 and 8798
-  --tailscale serve|funnel|none publish the phone port on the tailnet (serve), also on the public
-                                internet (funnel), or not at all (none, the default)
+  --tailscale funnel|serve|none how phones reach this machine: with or without Tailscale (funnel,
+                                public through Funnel), only with Tailscale on (serve), or through an
+                                address published some other way (none, with --address). Ask the
+                                operator. Without it, setup keeps the TARFA_PHONE_ADDRESSES or the
+                                serve handler for the phone port the machine already has, picks
+                                funnel for a machine phones reached through a relay, and otherwise
+                                refuses. Every run prints a reachability: line saying which
   --tailscale-port <n>          the HTTPS port Tailscale serves it on (default 443 for serve, 10000
                                 for funnel; Funnel allows only 443, 8443 and 10000)
   --slug <name>                 serve under /<name>, so several agents share one port
@@ -1687,7 +1711,7 @@ replace anything it did not make (an agent key, another tailscale serve entry).
                                 4 in all), e.g. a reverse proxy
   --pwa <origin>                where phones open the app (default https://tarfa.app; an existing
                                 TARFA_PWA_ORIGIN is kept unless this is given)
-  --pair                        print a pairing link and QR code at the end
+  --pair                        print a pairing code and QR code at the end
   --adopt                       a machine whose service runs a clone's deploy/run-agent.sh: move it to
                                 the installed package (copies deploy/agent.env to ~/.tarfa/agent.env,
                                 keeps the original, repoints the service, replaces the ~/.local/bin links
@@ -1795,9 +1819,10 @@ ${SETUP_USAGE.split("\n")[0]}
     stateDir: stateDirLayout(home),
     phonePortOwner: await owner(flags.phonePort),
     hooksPortOwner: await owner(config.port),
-    tailscale: flags.tailscale === "none" ? null : await tailscale.status(),
-    // Under --tailscale none, read only to word the operator's line: unreadable means the serve form.
-    serve: flags.tailscale === "none" && !flags.slug ? null : await tailscale.serveStatus(),
+    // Read whatever --tailscale says: they settle how the port is published when no flag does, and word
+    // whether phones need Tailscale. Both answer null when Tailscale is absent or will not tell.
+    tailscale: await tailscale.status(),
+    serve: await tailscale.serveStatus(),
     cli: kind === "package" ? await cliState(home, env) : null,
     adoption: cloneRepo === null ? null : { repo: cloneRepo, copyEnv, agentLive: { path: agentLivePath, kind: await linkKind(agentLivePath) } }
   };
@@ -1813,7 +1838,7 @@ ${SETUP_USAGE.split("\n")[0]}
         await loadOrCreateAgentKeys(config.agentKeyPath);
       },
       writeRoster: async () => {
-        await mkdir4(dirname4(config.devicesPath), { recursive: true, mode: 448 });
+        await mkdir3(dirname3(config.devicesPath), { recursive: true, mode: 448 });
         await devices2.update((roster) => roster);
       },
       writeLauncher: (path, text) => atomicWrite(path, text, 493),
@@ -1946,20 +1971,52 @@ async function apply2(argv, env, home, io) {
   if (!result.ok) throw new Error(result.lines.join("\n"));
   return result.lines.join("\n");
 }
-function pairingInstructions(link, minutes = PAIRING_TTL_MS / 6e4) {
-  return [
+function pairingInstructions(pairing, options) {
+  const { origin, minutes } = options;
+  const text = options.link ? pairingLink(origin, pairing) : pairingCode(pairing);
+  const how = options.link ? [
     "On the phone, in Tarfa: Settings \u2192 Scan QR code, then scan this. Or open the link below on the",
-    "phone (Android opens the installed app; on an iPhone copy it and use Settings \u2192 Paste pairing link).",
+    "phone (Android opens the installed app; on an iPhone copy it and use Settings \u2192 Paste pairing link)."
+  ] : [
+    `On the phone, open the Tarfa app (install it from ${origin} first), then Settings \u2192 Add machine:`,
+    "Scan QR code and scan this, or copy the code below to the phone and tap Paste pairing code."
+  ];
+  return [
+    ...how,
     "",
     // Half-height blocks: about 60 columns, where `term` needs twice that.
-    encodeQR(link, "ascii", { ecc: "low" }),
-    link,
+    encodeQR(text, "ascii", { ecc: "low" }),
+    text,
     "",
     // The phone asks before pairing and shows this fingerprint: they must match.
-    `The phone will show machine key ${deviceFingerprint(parsePairingLink(link).agentKey)}; check it matches.`,
+    `The phone will show machine key ${deviceFingerprint(pairing.agentKey)}; check it matches.`,
     `It works once, for ${minutes} minute${minutes === 1 ? "" : "s"}. \`tarfa pair\` makes another.`
   ].join("\n");
 }
+var DICTATION_KEY_USAGE = [
+  `usage: tarfa dictation-key [status | set ${DICTATION_PROVIDERS.join("|")} | remove ${DICTATION_PROVIDERS.join("|")}]`,
+  "  set     reads the key on stdin, or asks for it with echo off; never as an argument",
+  "  every phone paired with this machine dictates into its workspaces with it, at its next connect"
+].join("\n");
+async function dictationKey(store, [action = "status", name, ...extra], secret) {
+  if (action === "status") {
+    if (name !== void 0) throw new UsageError(DICTATION_KEY_USAGE);
+    const loaded2 = await store.load();
+    if ("problem" in loaded2) throw new Error(loaded2.problem);
+    return DICTATION_PROVIDERS.map((p) => `${p}  ${loaded2.keys[p] ? "set" : "not set"}`).join("\n");
+  }
+  if (action !== "set" && action !== "remove") throw new UsageError(DICTATION_KEY_USAGE);
+  if (action === "set" && extra.length > 0) {
+    throw new UsageError("pass the key on stdin or type it at the prompt, never as an argument: any local user can read a process's arguments");
+  }
+  const provider = name ? providerOf(name) : null;
+  if (!provider || extra.length > 0) throw new UsageError(DICTATION_KEY_USAGE);
+  const loaded = await store.load();
+  if ("problem" in loaded) throw new Error(loaded.problem);
+  const result = await changeDictationKey(store, provider, action === "remove" ? null : await secret(`${provider} key: `));
+  if (!result.ok) throw new Error(result.error);
+  return action === "remove" ? `${provider}: removed; phones stop getting it at their next connect. Rotate it at the provider if a phone that had it is lost` : `${provider}: stored; every phone paired with this machine gets it at its next connect`;
+}
 var DEVICES_USAGE = [
   "usage: tarfa devices [list | revoke <id|key> | forget <id|key> | enrolment open|closed]",
   "  enrolment open    a pairing code from `tarfa pair` enrols a new phone",

package/dist/serve.js

@@ -6,6 +6,7 @@ import {
   DEVICE_REFUSED,
   FileClaudeSessionsStore,
   FileDeviceStore,
+  FileDictationKeysStore,
   FileHiddenFoldersStore,
   FilePairingStore,
   FileParkedStore,
@@ -25,9 +26,11 @@ import {
   ShortWorkspaceIds,
   TmuxAdapter,
   WrongStaticKeyError,
+  announcedAddresses,
   audioMediaType,
   b64url,
   browseDir,
+  changeDictationKey,
   childEnv,
   cliOfCommand,
   configWarnings,
@@ -39,6 +42,7 @@ import {
   enrolDevice,
   enrolmentMode,
   exactTarget,
+  exposedFiles,
   formatAgentMessage,
   fsIsDirectory,
   getRecentPaths,
@@ -74,7 +78,7 @@ import {
   systemPathResolver,
   withLegacyEnv,
   writeFileAtomic
-} from "./chunk-KTUXNG4Q.js";
+} from "./chunk-UPCCR4ZA.js";
 
 // src/serve.ts
 import { homedir as homedir2 } from "node:os";
@@ -1284,6 +1288,7 @@ var PRE_AUTH_MAX_MESSAGE_BYTES = 8 * 1024;
 var MAX_AUTH_ATTEMPTS = 3;
 var MAX_HELD_MESSAGES = 16;
 var PAIRING_SECRET = /^[A-Za-z0-9_-]{43}$/;
+var FEATURES = [AGENT_FEATURES.lastReply, AGENT_FEATURES.dictationKeys, AGENT_FEATURES.setDictationKey];
 var NoiseClientConnection = class {
   constructor(socket, staticPrivate, options) {
     this.socket = socket;
@@ -1332,7 +1337,15 @@ var NoiseClientConnection = class {
       return;
     }
     if (message.type === "authResult" && message.ok) {
-      const accepted = { ...message, agent: { protocol: PROTOCOL_VERSION, ...this.options.agentVersion ? { version: this.options.agentVersion } : {}, features: [AGENT_FEATURES.lastReply] } };
+      const { agentVersion: agentVersion2, phoneAddresses } = this.options;
+      const features = [...this.options.features ?? FEATURES];
+      const agent = {
+        protocol: PROTOCOL_VERSION,
+        ...agentVersion2 ? { version: agentVersion2 } : {},
+        features: phoneAddresses ? [...features, AGENT_FEATURES.addresses] : features,
+        ...phoneAddresses ? { addresses: phoneAddresses } : {}
+      };
+      const accepted = { ...message, agent };
       message = accepted;
       if (!this.awaitingPhone) this.cancelDeadline();
       this.session.raiseCap(MAX_MESSAGE_BYTES);
@@ -2386,6 +2399,12 @@ var ConnectionHandler = class {
         this.conn.send({ type: "keyterms", keyterms: await this.deps.keyterms.list() });
         return;
       }
+      case "getDictationKeys":
+        this.conn.send({ type: "dictationKeys", ...await this.deps.dictationKeys?.read() });
+        return;
+      case "setDictationKey":
+        this.conn.send({ type: "dictationKeySet", id: message.id, provider: message.provider, ...await this.setDictationKey(message.provider, message.key) });
+        return;
       case "readFile": {
         const { binary, data, truncated } = await readFile10({ reader }, message.path, await this.allowedRoots());
         this.conn.send({ type: "fileContents", path: message.path, data, truncated, binary });
@@ -2679,6 +2698,17 @@ var ConnectionHandler = class {
     });
     this.conn.send({ type: "attached", workspaceId });
   }
+  // Any enrolled phone of this machine may change its key: it can already run anything in a
+  // terminal here. A thrown error may name the file, never the key, but is worded here anyway.
+  async setDictationKey(provider, key) {
+    const store = this.deps.dictationKeys;
+    if (!store) return { ok: false, error: "this agent keeps no dictation keys" };
+    try {
+      return await changeDictationKey(store, provider, key);
+    } catch {
+      return { ok: false, error: "the keys file could not be written" };
+    }
+  }
   // A dictation lives only as long as its attachment: without one the held spaces go nowhere,
   // and the machine's one dictation slot would stay taken.
   cancelVoice(reason) {
@@ -3876,7 +3906,7 @@ function startDeviceGate(deps) {
   return {
     staticPrivate: b64url.decode(keys.x25519.privateKey),
     devices,
-    options: (extra) => ({ devices, log, refusalLog, pushBudget, agentVersion: deps.agentVersion, ...extra }),
+    options: (extra) => ({ devices, log, refusalLog, pushBudget, agentVersion: deps.agentVersion, phoneAddresses: deps.phoneAddresses, ...extra }),
     roster: () => last,
     pollRoster: () => monitor.poll(),
     stop: () => clearInterval(poll)
@@ -4127,13 +4157,6 @@ import { join as join6 } from "node:path";
 
 // src/infrastructure/private-dir.ts
 import { chmod, mkdir as mkdir7, stat as stat4 } 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/private-dir.ts
 async function securePrivateDir(dir) {
   await mkdir7(dir, { recursive: true, mode: 448 });
   await chmod(dir, 448);
@@ -4196,6 +4219,7 @@ async function main() {
     config.devicesPath,
     config.pairingPath,
     join7(config.stateDir, "token"),
+    config.dictationKeysPath,
     // The launcher sources it: whoever can write it runs code as this user.
     await locateAgentEnv(env, homedir2())
   ]);
@@ -4238,6 +4262,8 @@ async function main() {
     launchers: new FileLaunchersStore(config.launchersPath),
     detectInstalled: (names) => detectInstalled(names, loginShellResolver()),
     keyterms: new FileKeytermsStore(config.keytermsPath),
+    dictationKeys: new FileDictationKeysStore(config.dictationKeysPath, (problem) => process.stderr.write(`tarfa agent: no dictation keys sent: ${problem}
+`)),
     clientLog: new FileClientLogStore(config.clientLogPath),
     hookEventLog: new FileHookEventLog(config.hookEventLogPath),
     messaging: {
@@ -4277,7 +4303,8 @@ async function main() {
     pairings: new FilePairingStore(config.pairingPath),
     log,
     rosterPollMs: ROSTER_POLL_MS,
-    agentVersion
+    agentVersion,
+    phoneAddresses: announcedAddresses(config.phoneAddresses)
   });
   try {
     const phones = await startPhoneListener({

package/package.json

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