sessionpipe 0.2.0 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ enroll at this terminal; the receiver can queue a message but can never forge on
 ([spec](https://sessionpipe.org/protocol/control/)).
 
 ```sh
-sessionpipe control pair https://receiver.example --folder ~/code   # confirm with your passkey; installs the daemon
+sessionpipe control pair spacesheep.dev   # one link: approve with your passkey; installs the daemon (this folder by default)
 sessionpipe control status          # receivers, parked waiters, sessions mid-turn, open permission prompts
 sessionpipe control keys [remove <id>]
 sessionpipe control off             # tell the receiver, forget its token and keys

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// sessionpipe 0.2.0 · Apache-2.0 · https://sessionpipe.org
+// sessionpipe 0.4.0 · Apache-2.0 · https://sessionpipe.org
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -723,7 +723,7 @@ var OPTS = {
   timeoutFor: (e) => e === "PermissionRequest" ? 130 : void 0
 };
 var DESKTOP_ID = /^local_[A-Za-z0-9-]{1,64}$/;
-function claudeDirs(env = process.env, home = HOME) {
+function claudeDirs(env = process.env, home = env.HOME || HOME) {
   const out2 = [];
   const add = (d) => {
     if (!d) return;
@@ -1946,7 +1946,8 @@ function parseCaps(help2) {
     hasMode: !!pm,
     modes: pm ? [...pm.matchAll(/"([A-Za-z]+)"/g)].map((m) => m[1]) : [],
     promptsNone: !!pp && /"none"/.test(pp),
-    fork: !!optionBlock(help2, "--fork-session")
+    fork: !!optionBlock(help2, "--fork-session"),
+    stream: !!optionBlock(help2, "--include-partial-messages")
   };
 }
 function modeFlags(mode, caps) {
@@ -2148,7 +2149,26 @@ function runClaude(bin, args2, o) {
         }
       }
     };
+    let partial = "";
     child.stdout?.on("data", (b) => {
+      if (o.onLine) {
+        const chunk = partial + b.toString("utf8");
+        const lines = chunk.split("\n");
+        partial = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            o.onLine(line);
+          } catch {
+          }
+          if (line.includes('"type":"result"')) {
+            out2 = [Buffer.from(line)];
+            outLen = line.length;
+          }
+        }
+        if (partial.length > OUT_CAP) partial = "";
+        return;
+      }
       if (tooBig) return;
       if (outLen + b.length > OUT_CAP) {
         tooBig = true;
@@ -2182,7 +2202,20 @@ function runClaude(bin, args2, o) {
     };
     child.on("error", (e) => finish({ error: e.message }));
     child.on("exit", (code, signal) => setTimeout(() => finish(result(code, signal)), 2e3).unref());
-    child.on("close", (code, signal) => finish(result(code, signal)));
+    child.on("close", (code, signal) => {
+      if (o.onLine && partial.trim()) {
+        try {
+          o.onLine(partial);
+        } catch {
+        }
+        if (partial.includes('"type":"result"')) {
+          out2 = [Buffer.from(partial)];
+          outLen = partial.length;
+        }
+        partial = "";
+      }
+      finish(result(code, signal));
+    });
   });
 }
 function parseResult(stdout) {
@@ -2850,13 +2883,14 @@ var SKEW_MS = 5 * 6e4;
 var MACHINE_MAX_AGE_MS = 24 * 36e5;
 var RECEIVER_MAX_AGE_MS = 10 * 6e4;
 var NONCE_TTL_MS = 25 * 36e5;
-var CMD_MAX = 12e3;
-var TEXT_MAX = 4e3;
+var CMD_MAX = 48e3;
+var TEXT_MAX = 2e4;
 var NOTE_MAX = 2e3;
 var GRANT_STR_MAX = 2e3;
 var COMMAND_TYPE = "sessionpipe.control";
 var GRANT_TYPE = "sessionpipe.grant";
-var CONTROL_KINDS = ["prompt", "permission.answer", "cancel", "start"];
+var CONTROL_KINDS = ["prompt", "permission.answer", "cancel", "start", "key.add"];
+var KEY_STORE_SESSION = "sessionpipe:keys";
 var ES256 = -7;
 var RS256 = -257;
 var NONCE_RE = /^[A-Za-z0-9_-]{22,64}$/;
@@ -3066,7 +3100,20 @@ function parseCommand(str) {
       if (has2("text") || has2("for") || has2("decision") || has2("cwd"))
         return bad("bad_fields", "a cancel carries nothing");
       break;
+    case "key.add": {
+      if (c.session !== KEY_STORE_SESSION) return bad("bad_session", `a key.add names ${KEY_STORE_SESSION}`);
+      const k = c.key;
+      const b64 = (v, min, max) => typeof v === "string" && v.length >= min && v.length <= max && /^[A-Za-z0-9_-]+$/.test(v);
+      if (!k || typeof k !== "object" || !b64(k.id, 16, 1400) || k.alg !== -7 && k.alg !== -257 || !b64(k.spki, 40, 2e3))
+        return bad("bad_fields", "a key.add carries the key: id, alg (-7 or -257) and spki");
+      if (has2("name") && (typeof c.name !== "string" || !c.name.trim() || c.name.length > 80))
+        return bad("bad_fields", "a device name is text, at most 80 characters");
+      if (has2("text") || has2("for") || has2("decision") || has2("cwd"))
+        return bad("bad_fields", "a key.add carries the key and a name");
+      break;
+    }
   }
+  if (c.kind !== "key.add" && (has2("key") || has2("name"))) return bad("bad_fields", "only a key.add carries a key");
   if (has2("note") && (typeof c.note !== "string" || c.note.length > NOTE_MAX))
     return bad("bad_fields", `a note is text, at most ${NOTE_MAX} characters`);
   return { ok: true, cmd: c };
@@ -3217,6 +3264,7 @@ async function awaitAnswer(file, from, o) {
       }
       const a = answerIn(lines);
       if (a.done) return a.text || null;
+      if (a.text) o.onText?.(a.text);
     }
     await sleep2(o.pollMs ?? 500);
   }
@@ -3392,6 +3440,83 @@ function readState(file) {
 }
 var writeState = (file, s) => writePrivate(file, s);
 
+// src/control/stream.ts
+function streamJsonPiece(line) {
+  let j;
+  try {
+    j = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (j.type !== "stream_event" || !j.event) return null;
+  if (j.parent_tool_use_id) return null;
+  const e = j.event;
+  if (e.type === "content_block_delta" && e.delta?.type === "text_delta" && typeof e.delta.text === "string")
+    return { text: e.delta.text };
+  if (e.type === "message_start") return { boundary: true };
+  return null;
+}
+var AnswerStream = class {
+  constructor(send, everyMs = 400) {
+    this.send = send;
+    this.everyMs = everyMs;
+  }
+  send;
+  everyMs;
+  text = "";
+  sent = "";
+  seq = 0;
+  timer = null;
+  inFlight = false;
+  closed = false;
+  /** A stream-json line from a headless run. */
+  feed(line) {
+    const p = streamJsonPiece(line);
+    if (!p) return;
+    if (p.boundary) {
+      if (this.text && !this.text.endsWith("\n\n")) this.text += "\n\n";
+      return;
+    }
+    if (p.text) {
+      this.text += p.text;
+      this.schedule();
+    }
+  }
+  /** The whole answer so far (a live session's transcript). */
+  set(text) {
+    if (text === this.text) return;
+    this.text = text;
+    this.schedule();
+  }
+  /** No more progress: the final ack follows. */
+  close() {
+    this.closed = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+  schedule() {
+    if (this.closed || this.timer || this.inFlight) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.everyMs);
+    this.timer.unref?.();
+  }
+  async flush() {
+    const t = this.text.trim();
+    if (this.closed || !t || t === this.sent) return;
+    this.inFlight = true;
+    this.sent = t;
+    try {
+      await this.send(t, ++this.seq);
+    } catch {
+    } finally {
+      this.inFlight = false;
+    }
+    if (this.text.trim() !== this.sent) this.schedule();
+  }
+};
+
 // src/control/daemon.ts
 var {
   claudeEnv: claudeEnv2,
@@ -3404,7 +3529,7 @@ var {
   recentlyWritten: recentlyWritten2,
   sessionFolder: sessionFolder2
 } = claude_code_control_exports;
-var VERSION = true ? "0.2.0" : "0.0.0";
+var VERSION = true ? "0.4.0" : "0.0.0";
 var MAX_REPLY = 2e4;
 var HELLO_EVERY_MS = 10 * 6e4;
 var TURN_FALLBACK_MS = 30 * 6e4;
@@ -3418,6 +3543,12 @@ var CLOSES_ATTENTION = /* @__PURE__ */ new Set([
   "UserPromptSubmit",
   "SessionEnd"
 ]);
+function sessionToolsFrom(v) {
+  if (!Array.isArray(v)) return [];
+  return [
+    ...new Set(v.filter((t) => typeof t === "string" && /^mcp__[A-Za-z0-9_-]{1,64}$/.test(t)))
+  ].slice(0, 8);
+}
 var LIMITS = { startConcurrent: 2, startPerHour: 10, headless: 3 };
 var ControlDaemon = class {
   constructor(cfg, dir, sock, deps) {
@@ -3449,6 +3580,8 @@ var ControlDaemon = class {
   helloTimer = null;
   helloSoon = null;
   aborts = /* @__PURE__ */ new Set();
+  /** Per receiver: the MCP servers its sessions may use unattended (its well-known). */
+  sessionTools = /* @__PURE__ */ new Map();
   startsRunning = 0;
   startTimes = [];
   procs = 0;
@@ -3729,7 +3862,31 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
     }, 1500);
     this.helloSoon.unref();
   }
+  /** Read each receiver's well-known for its session tools (at start, then with every hello). */
+  async refreshSessionTools() {
+    for (const r of this.cfg.receivers) {
+      try {
+        const res = await this.deps.fetch(`${r.url.replace(/\/$/, "")}/.well-known/sessionpipe`, {
+          signal: AbortSignal.timeout(8e3)
+        });
+        if (!res.ok) continue;
+        const wk = await res.json();
+        const tools = sessionToolsFrom(wk.control?.session_tools);
+        const key = r.control + r.machine;
+        if (JSON.stringify(tools) !== JSON.stringify(this.sessionTools.get(key) ?? []))
+          this.deps.log(
+            `${r.url}: sessions it messages may use ${tools.length ? tools.join(", ") : "nothing extra"} without asking`
+          );
+        this.sessionTools.set(key, tools);
+      } catch {
+      }
+    }
+  }
+  allowedFor(r) {
+    return this.sessionTools.get(r.control + r.machine) ?? [];
+  }
   async helloAll() {
+    void this.refreshSessionTools();
     const waiting = [...this.live].filter(([, l]) => l.waiter).map(([k]) => k);
     const modes = ["waiter", "turn", "resume", "fork", ...this.deps.sdk ? ["sdk"] : []];
     for (const r of this.cfg.receivers) {
@@ -3825,6 +3982,7 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
       return this.finish(r, m.id, { outcome: "refused", code: v.code, detail: v.why });
     }
     const cmd2 = v.cmd;
+    if (cmd2.kind === "key.add") return this.addKey(r, m.id, cmd2, sent);
     const ref = parseSessionRef(cmd2.session);
     const kp = kindPath(cmd2.kind, ref.harness);
     if (typeof kp === "object") return this.finish(r, m.id, { outcome: "unsupported", detail: kp.unsupported });
@@ -4015,15 +4173,26 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
     await this.serial(ref.id, async () => {
       const target = this.state.copies[ref.id] ?? ref.id;
       const resume = mode === "fork" ? ["--resume", target, "--fork-session"] : ["--resume", target];
-      const args2 = ["-p", "--output-format", "json", ...mf.args, ...resume, frame(cmd2.text, r.url)];
+      const allow = this.allowedFor(r);
+      const args2 = [
+        "-p",
+        ...this.outputArgs(claude.caps),
+        ...mf.args,
+        ...allow.length ? [`--allowedTools=${allow.join(",")}`] : [],
+        ...resume,
+        frame(cmd2.text, r.url)
+      ];
       this.deps.log(`${id.slice(-8)}: claude -p ${[...mf.args, ...resume].join(" ")} in ${place.folder}`);
+      const stream = this.answerStream(r, id);
       const res = await this.slot(
         () => this.deps.run(claude.bin, args2, {
           cwd: place.folder,
           env: claudeEnv2(place.transcript?.configDir, this.deps.env),
-          timeoutMs: JOB_TIMEOUT_MS2
+          timeoutMs: JOB_TIMEOUT_MS2,
+          ...claude.caps.stream ? { onLine: (l) => stream.feed(l) } : {}
         })
       );
+      stream.close();
       this.lastEnd.set(target, this.deps.now());
       const out2 = this.outcome(res);
       if ("failed" in out2) return this.finish(r, id, { outcome: "failed", detail: out2.failed });
@@ -4061,6 +4230,33 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
     const text = typeof j.result === "string" && j.result.trim() ? j.result : "(Claude Code finished without a written reply.)";
     return { reply: text + tail2, ...typeof j.session_id === "string" ? { session: j.session_id } : {} };
   }
+  addKey(r, id, cmd2, sent) {
+    const k = cmd2.key;
+    const name = typeof cmd2.name === "string" ? cmd2.name.trim().slice(0, 80) : void 0;
+    const rec = this.cfg.receivers.find((x) => x.control === r.control && x.machine === r.machine) ?? r;
+    if (rec.keys.some((x) => x.id === k.id))
+      return this.finish(r, id, { outcome: "delivered", detail: "that device was already trusted" }, sent);
+    rec.keys.push({
+      id: k.id,
+      alg: k.alg,
+      spki: k.spki,
+      ...name ? { name } : {},
+      added_at: new Date(this.deps.now()).toISOString()
+    });
+    try {
+      writeControl(this.cfg, this.deps.env);
+    } catch (e) {
+      rec.keys = rec.keys.filter((x) => x.id !== k.id);
+      return this.finish(r, id, {
+        outcome: "failed",
+        detail: `couldn't save the key: ${String(e?.message || e)}`
+      });
+    }
+    this.deps.log(
+      `trusted a new device${name ? ` (${name})` : ""} on ${r.url}: ${k.id.slice(0, 12)}\u2026, vouched for by a key it already trusted`
+    );
+    this.finish(r, id, { outcome: "delivered", detail: `trusted ${name || "a new device"}` }, sent);
+  }
   /** Where the session's transcript ends right now: its answer starts after this. */
   answerFrom(session) {
     const ref = parseSessionRef(session);
@@ -4075,14 +4271,38 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
   followAnswer(r, id, mode, session, from, sent) {
     this.deps.log(`${id.slice(-8)}: in ${session.slice(0, 24)} via ${mode} ${this.deps.now() - sent} ms after send`);
     this.finish(r, id, { outcome: "taken" });
+    const stream = this.answerStream(r, id);
     void (async () => {
       const answer = from ? await awaitAnswer(from.file, from.offset, {
         timeoutMs: this.deps.answerWaitMs ?? ANSWER_WAIT_MS,
-        now: this.deps.now
+        now: this.deps.now,
+        onText: (t) => stream.set(t)
       }) : null;
+      stream.close();
       this.finish(r, id, { outcome: "delivered", mode, ...answer ? { reply: answer } : {} }, sent);
     })().catch((e) => this.finish(r, id, { outcome: "delivered", mode, detail: String(e?.message || e) }));
   }
+  /** The answer so far, sent as a `progress` ack: whole, with a rising seq, at most
+   *  one in flight. Fire-and-forget — the final ack carries everything. */
+  answerStream(r, id) {
+    return new AnswerStream(async (text, seq) => {
+      await this.post(r, "/ack", {
+        acks: [
+          {
+            id,
+            outcome: "progress",
+            at: new Date(this.deps.now()).toISOString(),
+            seq,
+            reply: redactSecrets(text).slice(0, MAX_REPLY)
+          }
+        ]
+      });
+    });
+  }
+  /** How a headless run prints: streamed where this Claude Code can, else one JSON at the end. */
+  outputArgs(caps) {
+    return caps.stream ? ["--output-format", "stream-json", "--verbose", "--include-partial-messages"] : ["--output-format", "json"];
+  }
   limits() {
     const l = this.cfg.limits ?? {};
     const n = (v, d) => typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : d;
@@ -4139,7 +4359,7 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
     if (this.deps.sdk) {
       const sdk = this.deps.sdk;
       const out3 = await this.slot(async () => {
-        const s = sdk.start({ session: ref.id, cwd, mode: this.cfg.mode });
+        const s = sdk.start({ session: ref.id, cwd, mode: this.cfg.mode, allowedTools: this.allowedFor(r) });
         this.sdkSessions.set(ref.id, s);
         return s.send(frame(cmd2.text, r.url));
       });
@@ -4155,13 +4375,28 @@ ${IN_PLACE_ANSWER}`, id: p.msgId });
       return this.finish(r, id, { outcome: "failed", detail: "Claude Code isn't installed on this machine" });
     const mf = modeFlags2(this.cfg.mode, claude.caps);
     if ("error" in mf) return this.finish(r, id, { outcome: "refused", code: "mode", detail: mf.error });
+    const stream = this.answerStream(r, id);
     const res = await this.slot(
       () => this.deps.run(
         claude.bin,
-        ["-p", "--output-format", "json", ...mf.args, "--session-id", ref.id, frame(cmd2.text, r.url)],
-        { cwd, env: claudeEnv2(void 0, this.deps.env), timeoutMs: JOB_TIMEOUT_MS2 }
+        [
+          "-p",
+          ...this.outputArgs(claude.caps),
+          ...mf.args,
+          ...this.allowedFor(r).length ? [`--allowedTools=${this.allowedFor(r).join(",")}`] : [],
+          "--session-id",
+          ref.id,
+          frame(cmd2.text, r.url)
+        ],
+        {
+          cwd,
+          env: claudeEnv2(void 0, this.deps.env),
+          timeoutMs: JOB_TIMEOUT_MS2,
+          ...claude.caps.stream ? { onLine: (l) => stream.feed(l) } : {}
+        }
       )
     );
+    stream.close();
     this.lastEnd.set(ref.id, this.deps.now());
     const out2 = this.outcome(res);
     if ("failed" in out2) return this.finish(r, id, { outcome: "failed", detail: out2.failed });
@@ -4222,10 +4457,11 @@ function ask(sock, req, timeoutMs) {
 
 // src/control/pair.ts
 import { execFileSync as execFileSync5 } from "node:child_process";
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { existsSync as existsSync10, mkdirSync as mkdirSync9, unlinkSync as unlinkSync5, writeFileSync as writeFileSync7 } from "node:fs";
 import os4 from "node:os";
 import path15 from "node:path";
-var VERSION2 = true ? "0.2.0" : "0.0.0";
+var VERSION2 = true ? "0.4.0" : "0.0.0";
 async function json(r) {
   try {
     return await r.json();
@@ -4240,23 +4476,34 @@ async function discover(url, f) {
   const wk = await r.json();
   if (!wk.capabilities?.includes("control") || !wk.endpoints?.control || !wk.control?.signing?.rp_id)
     throw new Error(`${base} doesn't serve control yet (its well-known file lists no control.signing)`);
-  const ep = wk.endpoints.control;
-  return { control: /^https?:\/\//.test(ep) ? ep : base + ep, rpId: wk.control.signing.rp_id };
+  const abs = (ep) => /^https?:\/\//.test(ep) ? ep : base + ep;
+  return {
+    control: abs(wk.endpoints.control),
+    rpId: wk.control.signing.rp_id,
+    open: wk.control.open_pairing === true,
+    events: wk.endpoints.events ? abs(wk.endpoints.events) : null
+  };
 }
 async function pair(o) {
   const f = o.fetch ?? fetch;
   const sleep2 = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  const { control, rpId } = await discover(o.url, f);
+  const { control, rpId, open } = await discover(o.url, f);
+  if (!o.token && !open)
+    throw new Error(
+      `${o.url} needs a key to pair: add it as a sink first (\`sessionpipe sink add ${o.url} --token \u2026\`) or pass --token.`
+    );
+  const pollKey = o.token ? null : randomBytes2(32).toString("base64url");
   const cfg = readControl(o.env) ?? { name: o.name, folders: [], mode: o.mode, receivers: [] };
   cfg.name = o.name || cfg.name;
   cfg.mode = o.mode;
   cfg.folders = [.../* @__PURE__ */ new Set([...cfg.folders, ...o.folders.map((d) => path15.resolve(d))])];
   const existing = cfg.receivers.find((r) => r.control === control);
-  const auth = { authorization: `Bearer ${o.token}`, "content-type": "application/json" };
+  const auth = { authorization: `Bearer ${o.token ?? pollKey}`, "content-type": "application/json" };
   const started = await f(`${control}/pair`, {
     method: "POST",
-    headers: auth,
+    headers: o.token ? auth : { "content-type": "application/json" },
     body: JSON.stringify({
+      ...pollKey ? { poll_key: pollKey } : {},
       ...existing ? { machine: existing.machine } : {},
       name: cfg.name,
       harnesses: ["claude-code"],
@@ -4274,9 +4521,16 @@ async function pair(o) {
   const machine = String(s.machine);
   const code = String(s.code);
   o.out("");
-  o.out(`  Open this link and confirm with your passkey (Touch ID, Face ID, a security key):`);
-  o.out(`    ${String(s.url)}`);
-  o.out(`  The page shows these digits too: ${String(s.check)}`);
+  const digits = String(s.check);
+  const spaced = /^\d{6}$/.test(digits) ? `${digits.slice(0, 3)} ${digits.slice(3)}` : digits;
+  if (pollKey) {
+    o.out(`  Open ${String(s.url)} and enter:  ${spaced}`);
+    o.out("  then approve with your passkey (Touch ID, Face ID, a security key).");
+  } else {
+    o.out("  Open this link and confirm with your passkey (Touch ID, Face ID, a security key):");
+    o.out(`    ${String(s.url)}`);
+    o.out(`  The page shows these digits too: ${digits}`);
+  }
   o.out("");
   const until = Date.parse(String(s.expires_at)) || Date.now() + 10 * 6e4;
   for (; ; ) {
@@ -4307,6 +4561,9 @@ async function pair(o) {
     if (!existing) cfg.receivers.push(rec);
     writeControl(cfg, o.env);
     o.out(`  \u2713 Paired with ${rec.url} as ${machine} \xB7 ${rec.keys.length} key(s) trusted on this machine`);
+    if (typeof p.account === "string")
+      o.out(`  Approved by ${p.account}. If that isn't you, run \`sessionpipe control off\` now.`);
+    if (typeof p.sink_token === "string" && o.addSink) o.addSink(p.sink_token);
     return cfg;
   }
 }
@@ -4440,7 +4697,8 @@ async function loadSdk(o) {
     start({
       session,
       cwd,
-      mode
+      mode,
+      allowedTools
     }) {
       const queue = [];
       let wake = null;
@@ -4459,6 +4717,7 @@ async function loadSdk(o) {
           sessionId: session,
           cwd,
           permissionMode: mode === "auto" ? "auto" : "dontAsk",
+          ...allowedTools?.length ? { allowedTools } : {},
           ...o.claudeBin ? { pathToClaudeCodeExecutable: o.claudeBin } : {},
           env: { ...o.env ?? process.env, SESSIONPIPE_CONTROL_JOB: "1" }
         }
@@ -4534,8 +4793,34 @@ ${RE_ARM}`;
 // src/control/cli.ts
 var { detectCaps: detectCaps2, findClaude: findClaude2, runClaude: runClaude2 } = claude_code_control_exports;
 var CONTROL_HELP = `  sessionpipe control pair <receiver> [--folder DIR]\u2026 [--mode safe|auto] [--token T] [--name N] [--no-service]
+  sessionpipe control mode auto|safe                (how sessions run when you message them)
   sessionpipe control status | keys [remove <id>] | off [<receiver>] | run
   sessionpipe wait [--session <harness>:<id>]      (a session runs this in the background)`;
+var MODE_TEXT = `  auto  Claude Code's auto mode: the session reads, edits and runs commands, and Claude Code's
+        own safety check stops what looks dangerous. Pick this to get work done from your phone.
+  safe  Only what each folder's Claude Code settings already allow: with no allow rules, a
+        session can't even read a file. Pick this if this machine holds things no agent
+        should touch unattended.`;
+async function askMode(out2) {
+  if (!process.stdin.isTTY) {
+    out2("  Mode: safe for now. Run `sessionpipe control mode auto` to let sessions you message work unattended.");
+    return "safe";
+  }
+  out2("");
+  out2("  When you message a session on this machine from your phone, how may it run?");
+  out2(MODE_TEXT);
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (; ; ) {
+      const a = (await rl.question("  auto or safe? [auto] ")).trim().toLowerCase();
+      if (a === "" || a === "a" || a === "auto") return "auto";
+      if (a === "s" || a === "safe") return "safe";
+    }
+  } finally {
+    rl.close();
+  }
+}
 async function controlMain(argv, out2, distDir2) {
   const flag2 = (n) => {
     const i = argv.indexOf(n);
@@ -4545,24 +4830,37 @@ async function controlMain(argv, out2, distDir2) {
   const sub = argv[1];
   switch (sub) {
     case "pair": {
-      const url = argv[2];
-      if (!url || !/^https?:\/\//.test(url)) return out2(`usage:
+      const raw = argv[2];
+      if (!raw || raw.startsWith("-")) return out2(`usage:
 ${CONTROL_HELP}`);
+      const url = (/^https?:\/\//.test(raw) ? raw : `https://${raw}`).replace(/\/$/, "");
       const cfg = readConfig();
-      const sink2 = cfg.sinks.find((s) => s.url.replace(/\/$/, "") === url.replace(/\/$/, ""));
-      const token = flag2("--token") ?? sink2?.token;
-      if (!token)
+      const sink2 = cfg.sinks.find((s) => s.url.replace(/\/$/, "") === url);
+      const token = flag2("--token") ?? sink2?.token ?? null;
+      if (token !== null && !/^[\x21-\x7e]+$/.test(token))
         return out2(
-          `  No token for ${url}: add it as a sink first (\`sessionpipe sink add ${url} --token \u2026\`) or pass --token.`
+          "  That token has a character a key never has (a placeholder like ss_\u2026 pasted as is?). Leave --token out to pair with a link instead."
         );
       const folders = flags("--folder");
       const existing = readControl();
       if (!folders.length && !existing?.folders.length) folders.push(process.cwd());
+      const mode = flag2("--mode") === "auto" || flag2("--mode") === "safe" ? flag2("--mode") : existing?.mode && existing.receivers.length ? existing.mode : await askMode(out2);
       await pair({
         url,
         token,
+        // The key the receiver handed over at pairing becomes this machine's sink for it,
+        // state only (tier 0), unless one is configured already.
+        addSink: (t) => {
+          const now = readConfig();
+          if (now.sinks.some((x) => x.url.replace(/\/$/, "") === url)) return;
+          now.sinks.push({ name: new URL(url).host, url, tier: 0, pii: false, control: false, token: t });
+          writeConfig(now);
+          out2(
+            `  \u2713 Sink ${new URL(url).host} added (tier 0: session state, no conversation text). \`sessionpipe sink add ${url} --tier 2\` sends transcripts too.`
+          );
+        },
         folders,
-        mode: flag2("--mode") === "auto" ? "auto" : existing?.mode ?? "safe",
+        mode,
         name: flag2("--name") ?? existing?.name ?? cfg.machine ?? os5.hostname(),
         out: out2
       });
@@ -4581,6 +4879,22 @@ ${CONTROL_HELP}`);
       else out2(`  Daemon: ${installService({ node: process.execPath, cli })}`);
       return;
     }
+    case "mode": {
+      const want = argv[2];
+      if (want !== "auto" && want !== "safe") {
+        const c2 = readControl();
+        return out2(`  mode: ${c2?.mode ?? "not set up"}
+  usage: sessionpipe control mode auto|safe
+${MODE_TEXT}`);
+      }
+      const c = readControl();
+      if (!c) return out2("  control isn't set up on this machine: run `sessionpipe control pair <receiver>` first");
+      c.mode = want;
+      writeControl(c);
+      return out2(
+        `  \u2713 Sessions you message now run in ${want} mode${want === "auto" ? " (Claude Code's auto mode decides what's safe)" : " (only what each folder's settings already allow)"}.`
+      );
+    }
     case "keys": {
       const c = readControl();
       if (argv[2] === "remove" && argv[3]) {
@@ -4779,7 +5093,7 @@ async function tellDaemon(state2, job, session, transcript) {
     300
   );
 }
-var VERSION3 = true ? "0.2.0" : "0.0.0";
+var VERSION3 = true ? "0.4.0" : "0.0.0";
 function enqueueJob(state2, job) {
   const jobs = jobsDir(state2);
   mkdirSync10(jobs, { recursive: true, mode: 448 });