From 68b54f6fb1fcad263d36fbaaa0745b20d3c5b4eb Mon Sep 17 00:00:00 2001
From: oratis <wangharp@gmail.com>
Date: Fri, 19 Jun 2026 14:56:19 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat(cli):=20`lisa=20pair`=20=E2=80=94=20sh?=
 =?UTF-8?q?ow=20a=20QR=20to=20pair=20a=20phone?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Mac-side counterpart to Lisa Pocket's QR scanner (docs/IOS_COMPANION_PLAN.md
§5.3). Until now /api/pair/start minted a per-device token but nothing rendered
the lisa-pair:// QR — so the phone scanner had nothing to scan and you had to
paste the string by hand.

`lisa pair [--host H] [--port N] [--name LABEL]` is a thin loopback client to a
running serve: POSTs /api/pair/start (loopback-only), builds
lisa-pair://v1?host=&port=&token=&name=, and renders it as a terminal QR (+ a
pasteable URL fallback). --host defaults to the first non-internal LAN IPv4;
pass a tailnet name to pair over Tailscale.

Adds qrcode-terminal (zero runtime deps — bundles its own encoder). node-pty is
kept in the lockfile (lock recomputed with --package-lock-only so the optional
dep isn't pruned under Node 26; CI on Node 22 still builds it).

Verified: typecheck + build clean; npm test -> 811 pass / 1 skip; pure helpers
(parsePairArgs / detectLanHost / buildPairUrl) unit-tested; terminal QR render
smoke-tested.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package-lock.json    |  18 +++++-
 package.json         |   2 +
 src/cli.ts           |  13 ++++-
 src/cli/pair.test.ts |  74 +++++++++++++++++++++++++
 src/cli/pair.ts      | 128 +++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 232 insertions(+), 3 deletions(-)
 create mode 100644 src/cli/pair.test.ts
 create mode 100644 src/cli/pair.ts

diff --git a/package-lock.json b/package-lock.json
index dd7505a..0c483c9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,8 +12,8 @@
         "@anthropic-ai/sdk": "^0.92.0",
         "@google/genai": "^2.0.1",
         "@modelcontextprotocol/sdk": "^1.29.0",
-        "node-pty": "*",
         "openai": "^6.35.0",
+        "qrcode-terminal": "^0.12.0",
         "undici": "^8.2.0"
       },
       "bin": {
@@ -21,6 +21,7 @@
       },
       "devDependencies": {
         "@types/node": "^22.10.0",
+        "@types/qrcode-terminal": "^0.12.2",
         "sharp": "^0.34.5",
         "tsx": "^4.21.0",
         "typescript": "^5.7.0"
@@ -1153,6 +1154,13 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@types/qrcode-terminal": {
+      "version": "0.12.2",
+      "resolved": "https://registry.npmjs.org/@types/qrcode-terminal/-/qrcode-terminal-0.12.2.tgz",
+      "integrity": "sha512-v+RcIEJ+Uhd6ygSQ0u5YYY7ZM+la7GgPbs0V/7l/kFs2uO4S8BcIUEMoP7za4DNIqNnUD5npf0A/7kBhrCKG5Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/retry": {
       "version": "0.12.0",
       "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz",
@@ -2340,6 +2348,14 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/qrcode-terminal": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/qrcode-terminal/-/qrcode-terminal-0.12.0.tgz",
+      "integrity": "sha512-EXtzRZmC+YGmGlDFbXKxQiMZNwCLEO6BANKXG4iCtSIM0yqc/pappSx3RIKr4r0uh5JsBckOXeKrB3Iz7mdQpQ==",
+      "bin": {
+        "qrcode-terminal": "bin/qrcode-terminal.js"
+      }
+    },
     "node_modules/qs": {
       "version": "6.15.1",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
diff --git a/package.json b/package.json
index 83af806..29e6530 100644
--- a/package.json
+++ b/package.json
@@ -69,10 +69,12 @@
     "@google/genai": "^2.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "openai": "^6.35.0",
+    "qrcode-terminal": "^0.12.0",
     "undici": "^8.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/qrcode-terminal": "^0.12.2",
     "sharp": "^0.34.5",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0"
diff --git a/src/cli.ts b/src/cli.ts
index 10fd49f..eadc84d 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -66,6 +66,8 @@ INSPECTION
                                revoke-all.
   lisa sense [list]            Recent ambient sense events + granted signals.
   lisa agents                  Snapshot of agent sessions across all observers.
+  lisa pair [--host H]         Show a QR to pair a phone (Lisa Pocket) — mints a
+                               per-device token via a running serve (localhost).
 
 LIFECYCLE
   lisa birth                   Run the birth ritual (auto-runs on first launch).
@@ -172,7 +174,8 @@ interface ParsedArgs {
     | "model"
     | "consent"
     | "sense"
-    | "agents";
+    | "agents"
+    | "pair";
   subargs: string[];
   serveWeb: boolean;
   serveImessage: boolean;
@@ -294,7 +297,8 @@ function parseArgs(argv: string[]): ParsedArgs {
       first === "model" ||
       first === "consent" ||
       first === "sense" ||
-      first === "agents"
+      first === "agents" ||
+      first === "pair"
     ) {
       out.subcommand = first;
       out.subargs = positional.slice(1);
@@ -490,6 +494,11 @@ async function main(): Promise<void> {
     process.exit(await runAgentsCommand(args.subargs));
   }
 
+  if (args.subcommand === "pair") {
+    const { runPairCommand } = await import("./cli/pair.js");
+    process.exit(await runPairCommand(args.subargs));
+  }
+
   if (args.subcommand === "sessions") {
     const sessions = await listSessionsOnDisk();
     for (const s of sessions) {
diff --git a/src/cli/pair.test.ts b/src/cli/pair.test.ts
new file mode 100644
index 0000000..379a22c
--- /dev/null
+++ b/src/cli/pair.test.ts
@@ -0,0 +1,74 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { parsePairArgs, detectLanHost, buildPairUrl } from "./pair.js";
+import type os from "node:os";
+
+describe("parsePairArgs", () => {
+  test("defaults: port 5757, name 'phone', host undefined", () => {
+    const prevPort = process.env.LISA_WEB_PORT;
+    delete process.env.LISA_WEB_PORT;
+    assert.deepEqual(parsePairArgs([]), { host: undefined, port: 5757, name: "phone" });
+    if (prevPort !== undefined) process.env.LISA_WEB_PORT = prevPort;
+  });
+
+  test("--host / --port / --name (space and = forms)", () => {
+    assert.deepEqual(parsePairArgs(["--host", "mac.tailnet.ts.net", "--port", "6000", "--name", "iPhone"]), {
+      host: "mac.tailnet.ts.net",
+      port: 6000,
+      name: "iPhone",
+    });
+    assert.deepEqual(parsePairArgs(["--host=10.0.0.5", "--port=8080", "--name=Pixel"]), {
+      host: "10.0.0.5",
+      port: 8080,
+      name: "Pixel",
+    });
+  });
+
+  test("missing value / bad port / unknown arg → error", () => {
+    assert.ok("error" in parsePairArgs(["--host"]));
+    assert.ok("error" in parsePairArgs(["--port", "0"]));
+    assert.ok("error" in parsePairArgs(["--port", "abc"]));
+    assert.ok("error" in parsePairArgs(["--nope"]));
+  });
+});
+
+describe("detectLanHost", () => {
+  test("returns the first non-internal IPv4", () => {
+    const ifaces = {
+      lo0: [{ family: "IPv4", internal: true, address: "127.0.0.1" }],
+      en0: [
+        { family: "IPv6", internal: false, address: "fe80::1" },
+        { family: "IPv4", internal: false, address: "192.168.1.42" },
+      ],
+    } as unknown as NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+    assert.equal(detectLanHost(ifaces), "192.168.1.42");
+  });
+
+  test("only loopback → undefined", () => {
+    const ifaces = {
+      lo0: [{ family: "IPv4", internal: true, address: "127.0.0.1" }],
+    } as unknown as NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+    assert.equal(detectLanHost(ifaces), undefined);
+  });
+});
+
+describe("buildPairUrl", () => {
+  test("encodes host/port/token/name into a lisa-pair:// v1 URL", () => {
+    const url = buildPairUrl("192.168.1.42", 5757, "abc123", "my phone");
+    const u = new URL(url);
+    assert.equal(u.protocol, "lisa-pair:");
+    assert.equal(u.searchParams.get("host"), "192.168.1.42");
+    assert.equal(u.searchParams.get("port"), "5757");
+    assert.equal(u.searchParams.get("token"), "abc123");
+    assert.equal(u.searchParams.get("name"), "my phone"); // spaces survive a round-trip
+  });
+
+  test("the app's pairing parser can read it back (host/token/port)", () => {
+    // Mirrors AppState.applyPairing: read query items, fall back to URL parts.
+    const url = buildPairUrl("10.0.0.5", 6000, "tok-XYZ", "iPad");
+    const u = new URL(url);
+    assert.equal(u.searchParams.get("host"), "10.0.0.5");
+    assert.equal(Number(u.searchParams.get("port")), 6000);
+    assert.equal(u.searchParams.get("token"), "tok-XYZ");
+  });
+});
diff --git a/src/cli/pair.ts b/src/cli/pair.ts
new file mode 100644
index 0000000..c87330d
--- /dev/null
+++ b/src/cli/pair.ts
@@ -0,0 +1,128 @@
+/**
+ * `lisa pair` — mint a per-device token and show a scannable QR so a phone pairs
+ * without hand-typing host/token (docs/IOS_COMPANION_PLAN.md §5.3). This is the
+ * Mac-side counterpart to Lisa Pocket's QR scanner.
+ *
+ * A thin client to a running `lisa serve --web` (loopback, like `lisa agents
+ * pty`): it POSTs /api/pair/start — which is loopback-only and mints a per-device
+ * token, returned ONCE — then builds a `lisa-pair://` URL and renders it as a
+ * terminal QR. The token rides in the QR (and the printed URL fallback); the
+ * phone then authenticates with it like any device token.
+ */
+// qrcode-terminal is CommonJS — Node's ESM loader only exposes its default
+// export, so import the module object and call .generate off it.
+import qrcodeTerminal from "qrcode-terminal";
+import os from "node:os";
+
+const DEFAULT_PORT = 5757;
+
+export interface PairArgs {
+  /** Host the phone will reach the Mac at (LAN IP or tailnet name). */
+  host?: string;
+  /** Port of the running serve (loopback target + encoded for the phone). */
+  port: number;
+  /** Device label stored alongside the minted token. */
+  name: string;
+}
+
+const USAGE = "usage: lisa pair [--host <ip-or-tailnet>] [--port N] [--name <label>]";
+
+/** Parse `lisa pair` argv. Pure (no I/O). */
+export function parsePairArgs(argv: string[]): PairArgs | { error: string } {
+  let host: string | undefined;
+  let port = Number(process.env.LISA_WEB_PORT) || DEFAULT_PORT;
+  let name = "phone";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    const valOf = (flag: string): string | undefined =>
+      a === flag ? argv[++i] : a.startsWith(flag + "=") ? a.slice(flag.length + 1) : undefined;
+    if (a === "--host" || a.startsWith("--host=")) {
+      const v = valOf("--host");
+      if (!v) return { error: "--host needs a value (an IP or tailnet name)" };
+      host = v;
+    } else if (a === "--port" || a.startsWith("--port=")) {
+      const v = valOf("--port");
+      if (!v) return { error: "--port needs a value" };
+      port = Number(v);
+    } else if (a === "--name" || a.startsWith("--name=")) {
+      const v = valOf("--name");
+      if (!v) return { error: "--name needs a value" };
+      name = v;
+    } else {
+      return { error: `unknown argument "${a}"\n${USAGE}` };
+    }
+  }
+  if (!Number.isInteger(port) || port <= 0) return { error: "--port must be a positive integer" };
+  return { host, port, name };
+}
+
+/** First non-internal IPv4 — a reasonable default host when --host is omitted. Pure. */
+export function detectLanHost(
+  ifaces: NodeJS.Dict<os.NetworkInterfaceInfo[]> = os.networkInterfaces(),
+): string | undefined {
+  for (const addrs of Object.values(ifaces)) {
+    for (const a of addrs ?? []) {
+      if (a.family === "IPv4" && !a.internal) return a.address;
+    }
+  }
+  return undefined;
+}
+
+/** Build the `lisa-pair://` deep-link the phone scans/pastes. Pure. */
+export function buildPairUrl(host: string, port: number, token: string, name: string): string {
+  const q = new URLSearchParams({ host, port: String(port), token, name });
+  return `lisa-pair://v1?${q.toString()}`;
+}
+
+export async function runPairCommand(argv: string[]): Promise<number> {
+  const parsed = parsePairArgs(argv);
+  if ("error" in parsed) {
+    console.error(parsed.error);
+    return 2;
+  }
+  const { port, name } = parsed;
+  const host = parsed.host ?? detectLanHost();
+  if (!host) {
+    console.error("Couldn't detect a LAN IP — pass --host <ip-or-tailnet-name>.");
+    return 1;
+  }
+
+  const base = `http://127.0.0.1:${port}`;
+  let res: Response;
+  try {
+    res = await fetch(`${base}/api/pair/start`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name, platform: "ios" }),
+    });
+  } catch (err) {
+    console.error(
+      `Could not reach LISA at ${base} — is \`lisa serve --web\` running? (${(err as Error).message})`,
+    );
+    return 1;
+  }
+  if (res.status === 403) {
+    console.error("Pairing can only be started on the Mac itself (localhost).");
+    return 1;
+  }
+  if (!res.ok) {
+    console.error(`pair failed (${res.status}): ${(await res.text().catch(() => "")).trim()}`);
+    return 1;
+  }
+
+  const body = (await res.json().catch(() => ({}))) as { token?: string; id?: string; port?: number };
+  if (!body.token) {
+    console.error("server returned no token");
+    return 1;
+  }
+  const url = buildPairUrl(host, body.port ?? port, body.token, name);
+
+  console.log(`\nScan in Lisa Pocket → Settings → Scan QR code:\n`);
+  await new Promise<void>((resolve) => qrcodeTerminal.generate(url, { small: true }, () => resolve()));
+  console.log(`\nOr paste this in Settings → Pair:\n  ${url}\n`);
+  console.log(`Paired device "${name}" (id ${body.id ?? "?"}). Revoke it later from the app or POST /api/devices/revoke.`);
+  console.log(
+    `The phone must reach http://${host}:${port} — run serve with --host 0.0.0.0 on the same Wi-Fi, or use a Tailscale name as --host.`,
+  );
+  return 0;
+}

From 32a992560596be69db9826cd63dbeb710b5f07aa Mon Sep 17 00:00:00 2001
From: oratis <wangharp@gmail.com>
Date: Fri, 19 Jun 2026 14:59:36 +0800
Subject: [PATCH 2/2] feat(push): deep-link ntfy notifications to the session
 (Click URL)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-event pushes (done / error / needs-permission) now carry a `Click`
deep-link — `lisapocket://session?agent=&id=` (agentDeepLink) — set as the
ntfy `Click` header, so tapping the notification opens Lisa Pocket at that
roster session instead of just the app root. Payload stays metadata-only.

The iOS side registers the `lisapocket://` scheme and routes it (follow-up,
on the iOS branch); the same scheme is reused for the home-screen Widget tap
target. No-op until the app handles it — harmless if absent.

Verified: typecheck clean; npm test -> all pass (+ new agentDeepLink and
Click-header tests in push.test.ts).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/IOS_COMPANION_PLAN.md |  2 ++
 src/web/push.test.ts       | 24 ++++++++++++++++++++++++
 src/web/push.ts            | 29 ++++++++++++++++++++++++-----
 3 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/docs/IOS_COMPANION_PLAN.md b/docs/IOS_COMPANION_PLAN.md
index a375f67..17eca0f 100644
--- a/docs/IOS_COMPANION_PLAN.md
+++ b/docs/IOS_COMPANION_PLAN.md
@@ -376,6 +376,8 @@ GET/POST /api/control/policy    # {remoteControl:bool, remoteAdoptExternal:bool}
 // 不含 prompt/模型回复/完整命令/文件内容/PTY 输出。E2E 时这部分是密文。
 ```
 
+**深链（已落地，ntfy 侧）**：agent 事件推送带一个 `Click` 深链 `lisapocket://session?agent=&id=`（`src/web/push.ts` 的 `agentDeepLink`），点通知直接跳到对应 roster session。iOS 侧需注册 `lisapocket://` scheme 并路由（待建，见 Appendix B `Push/`）。同一 scheme 复用于主屏 Widget 点按。
+
 ---
 
 ## 7. 隐私与安全（守住地板）
diff --git a/src/web/push.test.ts b/src/web/push.test.ts
index b29db61..de391f5 100644
--- a/src/web/push.test.ts
+++ b/src/web/push.test.ts
@@ -13,6 +13,7 @@ const {
   defaultPushPrefs,
   normalizePushPrefs,
   agentPushEvents,
+  agentDeepLink,
   sendNtfy,
   PushBridge,
   registerPush,
@@ -68,6 +69,15 @@ describe("agentPushEvents (pure trigger)", () => {
   test("first sight already done (prev undefined) → fires", () => {
     assert.equal(agentPushEvents(undefined, sess({ state: "done" }))[0]!.pref, "done");
   });
+  test("events carry a lisapocket:// deep-link to the session", () => {
+    const [e] = agentPushEvents(sess({ state: "working" }), sess({ state: "done", agent: "codex", sessionId: "s9" }));
+    assert.equal(e!.click, agentDeepLink("codex", "s9"));
+    const u = new URL(e!.click!);
+    assert.equal(u.protocol, "lisapocket:");
+    assert.equal(u.host, "session");
+    assert.equal(u.searchParams.get("agent"), "codex");
+    assert.equal(u.searchParams.get("id"), "s9");
+  });
 });
 
 describe("sendNtfy", () => {
@@ -87,6 +97,20 @@ describe("sendNtfy", () => {
     assert.equal(captured!.init.body, "B");
     assert.equal(captured!.init.headers.Title, "T");
     assert.equal(captured!.init.headers.Priority, "high");
+    assert.equal(captured!.init.headers.Click, undefined); // omitted when no click
+  });
+  test("sets the Click header when the event has a deep-link", async () => {
+    let headers: Record<string, string> = {};
+    await sendNtfy(
+      "https://ntfy.sh",
+      "t",
+      { title: "T", body: "B", priority: "default", click: "lisapocket://session?agent=codex&id=s9" },
+      async (_url, init) => {
+        headers = init.headers;
+        return { ok: true };
+      },
+    );
+    assert.equal(headers.Click, "lisapocket://session?agent=codex&id=s9");
   });
   test("network throw → false", async () => {
     const ok = await sendNtfy("https://x", "t", { title: "a", body: "b", priority: "default" }, async () => {
diff --git a/src/web/push.ts b/src/web/push.ts
index 071978d..300fd9c 100644
--- a/src/web/push.ts
+++ b/src/web/push.ts
@@ -112,6 +112,16 @@ export function setPushPrefs(id: string, prefs: Partial<PushPrefs>): PushSubscri
 }
 
 // ── pure trigger ──────────────────────────────────────────────────────────
+/** Custom URL scheme Lisa Pocket registers for push / widget deep-links. */
+export const POCKET_SCHEME = "lisapocket";
+
+/** Deep-link that opens Lisa Pocket at a specific roster session. Pure. The app
+ *  routes on host="session" + the agent/id query (Lisa Pocket's URL handler). */
+export function agentDeepLink(agent: string, sessionId: string): string {
+  const q = new URLSearchParams({ agent, id: sessionId });
+  return `${POCKET_SCHEME}://session?${q.toString()}`;
+}
+
 export interface PushEvent {
   pref: keyof PushPrefs;
   title: string;
@@ -119,19 +129,22 @@ export interface PushEvent {
   priority: "high" | "default";
   /** Throttle/dedup tag within a session. */
   tag: string;
+  /** Optional deep-link opened when the notification is tapped (ntfy `Click`). */
+  click?: string;
 }
 
 /** Which notifications a session's prev→next transition warrants. Pure. */
 export function agentPushEvents(prev: AgentSession | undefined, next: AgentSession): PushEvent[] {
   const out: PushEvent[] = [];
   const who = `${next.agent} · ${next.project || next.agent}`;
+  const click = agentDeepLink(next.agent, next.sessionId);
   if (next.state === "done" && prev?.state !== "done")
-    out.push({ pref: "done", title: `${who} — done`, body: "Finished.", priority: "default", tag: "done" });
+    out.push({ pref: "done", title: `${who} — done`, body: "Finished.", priority: "default", tag: "done", click });
   if (next.state === "error" && prev?.state !== "error")
-    out.push({ pref: "error", title: `${who} — error`, body: next.stateReason || "errored", priority: "high", tag: "error" });
+    out.push({ pref: "error", title: `${who} — error`, body: next.stateReason || "errored", priority: "high", tag: "error", click });
   const pend = next.activity?.pendingPermission;
   if (pend && pend !== prev?.activity?.pendingPermission)
-    out.push({ pref: "permission", title: `${who} — needs permission`, body: `waiting on: ${pend}`, priority: "high", tag: "permission" });
+    out.push({ pref: "permission", title: `${who} — needs permission`, body: `waiting on: ${pend}`, priority: "high", tag: "permission", click });
   return out;
 }
 
@@ -144,7 +157,7 @@ type FetchLike = (
 export async function sendNtfy(
   server: string,
   topic: string,
-  ev: { title: string; body: string; priority: "high" | "default" },
+  ev: { title: string; body: string; priority: "high" | "default"; click?: string },
   fetchImpl: FetchLike = fetch as unknown as FetchLike,
 ): Promise<boolean> {
   try {
@@ -152,7 +165,13 @@ export async function sendNtfy(
     const res = await fetchImpl(`${base}/${encodeURIComponent(topic)}`, {
       method: "POST",
       body: ev.body,
-      headers: { Title: ev.title, Priority: ev.priority === "high" ? "high" : "default" },
+      headers: {
+        Title: ev.title,
+        Priority: ev.priority === "high" ? "high" : "default",
+        // ntfy opens this URL when the notification is tapped — a lisapocket://
+        // deep-link routes into the app (see agentDeepLink).
+        ...(ev.click ? { Click: ev.click } : {}),
+      },
     });
     return res.ok;
   } catch {