airpocket 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ Every change people using Airpocket would notice, newest first. The form is
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.1 - 2026-11-06
+
+A fix for typing from the phone. Reported from a real install: the
+conversation kept updating on the phone, and a reply answered "Something went
+wrong on the Mac."
+
+### Fixed
+
+- **A terminal that fails as the keys land now says which terminal, and what
+  its own program said**, instead of the one message nobody can act on. Reading
+  a session and typing into it are different paths: the conversation comes from
+  hook events and session files and never touches a terminal, so a failure was
+  always in the last step, and that step had nothing around it. Sending a
+  message, pressing a key and running a session command are all guarded now,
+  and point at `airpocket doctor`.
+- **A session in a Superset terminal is read-only up front when Superset isn't
+  installed**, rather than looking writable and failing at the keystroke.
+  Airpocket was choosing that route from the ids on record without asking
+  whether Superset was still there. The list now says why in a few words, and
+  says the thing that helps rather than suggesting `airpocket run`, which
+  wouldn't.
+
+### Added
+
+- **`airpocket doctor` says when sessions in Superset terminals are
+  read-only**, counting only the ones that would really lose their route: an
+  agent started with `airpocket run` inside a Superset terminal is reached
+  through its tmux pane and is left alone.
+
 ## 0.1.0 - 2026-09-17
 
 The first version. Airpocket runs on each Mac where you use Claude Code or

package/README.md

@@ -30,8 +30,9 @@ and on the phone.
 
 <p align="center"><img src="docs/images/phones.png" width="100%" alt="Three phones running Airpocket. First, the session list: three sessions need you (one asking permission to use Bash, one asking which Stripe API version to target, one finished) above two open ones. Second, a session asking &quot;Do you want to proceed?&quot; with three numbered answers and a reply box. Third, a TypeScript file the agent wrote, open with line numbers."></p>
 
-> **Status: private, work in progress.** Not on npm yet: to try it, install
-> from a clone (below). See [docs/PLAN.md](docs/PLAN.md), and
+> **Status: 0.1.1, young.** It does what this page says and it is tested, but
+> it has run on few Macs other than its author's. See
+> [docs/PLAN.md](docs/PLAN.md) for how it was built, and
 > [CONTRIBUTING.md](CONTRIBUTING.md) to send a change.
 
 ## What it will do
@@ -119,20 +120,30 @@ it serves stays inside your tailnet.
 Sharing a tailnet doesn't share sessions: every Mac still asks the phone for a
 pairing code of its own, and hands out its own token.
 
-### Try it from a clone
+### Install it
 
-Airpocket isn't on npm yet. Until it is, install it from a clone:
+```sh
+npm install -g airpocket
+airpocket setup --dry-run   # every change it would make; changes nothing
+airpocket setup
+```
+
+No dependencies: the tarball is Airpocket and the fonts the phone app uses,
+and nothing else.
+
+### Or from a clone
+
+To read the code as you run it, or to send a change:
 
 ```sh
 git clone https://github.com/airpocket-sh/airpocket.git
 cd airpocket
-npm install -g .            # puts the airpocket command on your PATH; no dependencies
-airpocket setup --dry-run   # every change it would make; changes nothing
+npm install -g .            # the airpocket command, from your clone
 airpocket setup
 ```
 
-`npm install -g .` links the command to your clone. Setup copies Airpocket
-into its data folder and runs that copy (see
+Either way, setup copies Airpocket into its data folder and runs that copy, so
+the service keeps working if you move or delete the clone (see
 [Keeping it up to date](#keeping-it-up-to-date)).
 
 Setup checks first and stops with a plain explanation if something is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airpocket",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Your Claude Code and Codex sessions, from every Mac, on your phone.",
   "keywords": [
     "claude-code",

package/src/bridges.js

@@ -44,7 +44,9 @@ const { execFile } = require("child_process");
 const { processInfo, pidOf } = require("./proc");
 
 const ESC = String.fromCharCode(27);
-const SUPERSET = path.join(os.homedir(), ".superset", "bin", "superset");
+/** Superset's own command, under a home folder: the only way into a Superset terminal. */
+const supersetBin = (home = os.homedir()) => path.join(home, ".superset", "bin", "superset");
+const SUPERSET = supersetBin();
 // Homebrew on Apple silicon, Homebrew on Intel, MacPorts.
 const TMUX_BINS = Object.freeze(["/opt/homebrew/bin/tmux", "/usr/local/bin/tmux", "/opt/local/bin/tmux"]);
 // tmux takes one command of 16 KB at most (MAX_IMSGSIZE), so text goes in pieces well under that.
@@ -60,6 +62,12 @@ const NOT_IN_PANE = Object.freeze({ error: "not_in_pane",
   message: "Its agent isn't running in that tmux pane (it was only started from there), so Airpocket won't type into the pane." });
 const NOT_IN_TERMINAL = Object.freeze({ error: "not_in_terminal",
   message: "Its agent isn't running in a terminal (it was only started from one), so Airpocket won't type into it." });
+const NO_SUPERSET = Object.freeze({ error: "no_superset",
+  message: "That terminal belongs to Superset, which isn't on this Mac, so the session is read-only here.",
+  why: "Superset isn't on this Mac, so its terminal can't be reached." });
+const NO_ROUTE = Object.freeze({ error: "no_route",
+  message: "This session isn't in a terminal Airpocket can type into, so it's read-only here. Start it with airpocket run and the phone can answer.",
+  why: "Start it with airpocket run and the phone can answer." });
 const NOT_FOREGROUND = Object.freeze({ error: "not_foreground",
   message: "Something else holds its terminal right now (the agent is stopped, in the background, or behind another program), so Airpocket won't type into it." });
 
@@ -93,7 +101,7 @@ function runFile(file, args, timeout = 15000, env) {
 function runSuperset(args, o = {}) { return runFile(SUPERSET, args, o.timeout || 15000); }
 
 const executable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
-const supersetInstalled = () => executable(SUPERSET);
+const supersetInstalled = (home) => executable(home ? supersetBin(home) : SUPERSET);
 
 // The tmux program: the first of the two usual places that holds one. Looked
 // for again at most once a minute, so installing tmux needs no restart.
@@ -147,6 +155,9 @@ function createBridges(o = {}) {
   const superset = o.superset || runSuperset;
   const tmux = o.tmux || runTmux;
   const hasTmux = o.hasTmux || (() => !!findTmux());
+  // Superset's CLI is what reaches a Superset terminal: without it a recorded
+  // workspace and terminal id name a terminal nothing here can type into.
+  const hasSuperset = o.hasSuperset || (o.superset ? () => true : supersetInstalled);
   const uid = o.uid ?? process.getuid();
   const inspect = o.inspect || processInfo;
   // A burst of text and an Enter right behind it reads as a paste with a line
@@ -207,6 +218,11 @@ function createBridges(o = {}) {
   /** Refused unless the agent's process group holds its terminal; else `then`. */
   const foreground = (agent, then) => (agent.pgid > 0 && agent.pgid === agent.tpgid ? then : NOT_FOREGROUND);
 
+  /** A record that names a Superset terminal, whether or not Superset is still here. */
+  const namesSuperset = (e) => !!e && TERMINAL_ID.test(String(e.workspace || "")) && TERMINAL_ID.test(String(e.terminal || ""));
+  /** Why there is no bridge: Superset gone, or never started where we could type. */
+  const noRoute = (e) => (namesSuperset(e) ? NO_SUPERSET : NO_ROUTE);
+
   /** The bridge to a session's terminal, from its record; null when it has none (read-only). */
   function of(e) {
     if (!e) return null;
@@ -214,7 +230,7 @@ function createBridges(o = {}) {
       const sock = tmuxSocket(e.tmux, uid);
       if (sock) return tmuxBridge(sock, e.pane, e.tmux_pid);
     }
-    if (TERMINAL_ID.test(String(e.workspace || "")) && TERMINAL_ID.test(String(e.terminal || ""))) return supersetBridge(e.workspace, e.terminal);
+    if (namesSuperset(e) && hasSuperset()) return supersetBridge(e.workspace, e.terminal);
     return null;
   }
 
@@ -227,7 +243,7 @@ function createBridges(o = {}) {
     const b = of(e);
     const known = !!(e && e.pid && e.started);
     const can = !!b && known && !!live;
-    const why = !b ? "Start it with airpocket run and the phone can answer." : !known ? "Airpocket doesn't know which process runs it."
+    const why = !b ? noRoute(e).why : !known ? "Airpocket doesn't know which process runs it."
       : !live ? "Its agent has exited." : "";
     return { bridge: b ? b.name : null, read: !!b, send: can, keys: can, controls: can, why };
   }
@@ -239,7 +255,7 @@ function createBridges(o = {}) {
    */
   async function writable(e) {
     const b = of(e);
-    if (!b) return { error: "no_route", message: "This session isn't in a terminal Airpocket can type into, so it's read-only here. Start it with airpocket run and the phone can answer." };
+    if (!b) { const r = noRoute(e); return { error: r.error, message: r.message }; }
     const started = e && Number.isSafeInteger(e.started) && e.started > 0 ? e.started : 0;
     const agent = pidOf(e.pid) && started ? inspect(e.pid) : null;
     if (!agent || agent.started !== started) return { error: "ended", message: "Its agent has exited, so Airpocket won't type into that terminal." };
@@ -251,4 +267,4 @@ function createBridges(o = {}) {
   return { of, caps, writable };
 }
 
-module.exports = { createBridges, KEYS, tmuxSocket, tmuxLiteral, tmuxPieces, runFile, runSuperset, runTmux, findTmux, supersetInstalled, TMUX_BINS };
+module.exports = { createBridges, KEYS, supersetBin, tmuxSocket, tmuxLiteral, tmuxPieces, runFile, runSuperset, runTmux, findTmux, supersetInstalled, TMUX_BINS };

package/src/doctor.js

@@ -9,7 +9,9 @@ const ts = require("./tailscale");
 const li = require("./loginitem");
 const sa = require("./shellalias");
 const own = require("./ownterm");
-const { survey, probe, majorOf, SOCKET_MAX, ownSessions } = require("./setup");
+const { survey, probe, majorOf, SOCKET_MAX, ownSessions, sessionRecords } = require("./setup");
+const { supersetInstalled, createBridges } = require("./bridges");
+const { stillRunning } = require("./proc");
 
 async function checks(ctx) {
   const f = await survey(ctx);
@@ -129,6 +131,23 @@ async function checks(ctx) {
     const running = ownSessions(ctx).length;
     add("PASS", "tmux", `${f.tmuxVersion ? f.tmuxVersion + " " : ""}(${f.tmux})${running ? `, ${running} agent${running === 1 ? "" : "s"} started with airpocket run` : ""}`);
   }
+  // Superset: its CLI is the only way to reach a Superset terminal. Without it,
+  // sessions recorded in one are read-only on the phone, which is worth saying
+  // before someone finds out by typing.
+  // An agent started with airpocket run inside a Superset terminal has both
+  // addresses on record, and its tmux pane is the one the phone types into. So
+  // ask the same chooser the service asks, with Superset taken away: what it
+  // still routes needs no Superset, and only the rest would go read-only.
+  const withoutSuperset = createBridges({ hasSuperset: () => false, hasTmux: () => !!f.tmux, uid: ctx.uid });
+  const live = sessionRecords(ctx).filter((r) => r && r.workspace && r.terminal && stillRunning(r.pid, r.started));
+  const stranded = live.filter((r) => !withoutSuperset.of(r)).length;
+  const sup = supersetInstalled(ctx.home);
+  const agents = (n) => `${n} session${n === 1 ? "" : "s"}`;
+  if (sup) add("PASS", "Superset", live.length ? `installed, ${agents(live.length)} in a Superset terminal` : "installed");
+  else if (stranded) add("WARN", "Superset", `not installed, and ${agents(stranded)} run in a Superset terminal: read-only on the phone`,
+    "Those terminals can only be typed into through Superset's own command. Start the agent with airpocket run instead, or install Superset.");
+  else add("INFO", "Superset", "not installed: new sessions can't be started from the phone, and nothing here needs it");
+
   if (aliases && aliased.length) add("PASS", "Shell aliases", `${t(aliases)}: ${aliased.join(", ")} start with airpocket run`);
   else if (aliases) add("WARN", "Shell aliases", `setup added them to ${t(aliases)}, and they're gone`, "Add them again with: airpocket setup --alias");
   else add("INFO", "Shell aliases", "not added: sessions started the usual way are read-only on the phone outside Superset and tmux", "Add them with: airpocket setup --alias");

package/src/server.js

@@ -916,6 +916,7 @@ function createServer(opts = {}) {
     superset: deps.superset,
     tmux: opts.tmux || runTmux,
     hasTmux: opts.hasTmux || (opts.tmux ? () => true : () => !!findTmux()),
+    hasSuperset: deps.hasSuperset,
     uid: opts.uid,
     inspect: opts.inspectAgent,
     gap: opts.typeGap,
@@ -1184,6 +1185,24 @@ function createServer(opts = {}) {
     return null;
   }
 
+  /**
+   * A write to a terminal that passed writable() a moment ago. What the terminal's
+   * own program reports becomes an answer that names it, instead of an unhandled
+   * failure the phone can only call "something went wrong on the Mac". The typed
+   * text never reaches the message: runFile keeps it out (see bridges.js).
+   * True when the keys landed.
+   */
+  async function typedOr502(bridge, res, cors, write) {
+    try { await write(); return true; } catch (err) {
+      const why = String((err && err.message) || "").trim().slice(0, 200);
+      const where = bridge.name === "tmux" ? "tmux pane" : "Superset terminal";
+      deps.log(`write failed (${bridge.name})${why ? ": " + why : ""}`);
+      json(res, 502, { error: "write_failed",
+        message: `Couldn't type into its ${where}.${why ? " " + why + "." : ""} It may have closed; airpocket doctor on the Mac says more.` }, cors);
+      return false;
+    }
+  }
+
   async function pair(res, body, cors) {
     const r = deps.store.useCode(body.code);
     if (r === "ok") {
@@ -1279,7 +1298,7 @@ function createServer(opts = {}) {
     const submit = body.submit !== false;
     const bridge = await writableOr409(e, res, cors);
     if (!bridge) return res.statusCode;
-    await bridge.type(full, submit);
+    if (!(await typedOr502(bridge, res, cors, () => bridge.type(full, submit)))) return res.statusCode;
     return json(res, 200, { ok: true, via: "terminal", submitted: submit, photos: shots.length }, cors);
   }
 
@@ -1314,7 +1333,7 @@ function createServer(opts = {}) {
     if (!key) return json(res, 400, { error: "bad_key" }, cors);
     const bridge = await writableOr409(e, res, cors);
     if (!bridge) return res.statusCode;
-    await bridge.press(key);
+    if (!(await typedOr502(bridge, res, cors, () => bridge.press(key)))) return res.statusCode;
     return json(res, 200, { ok: true }, cors);
   }
 
@@ -1495,9 +1514,12 @@ function createServer(opts = {}) {
     if (live.menu) return json(res, 409, { error: "menu_open", message: "Answer the question on screen first." }, cors);
     if (live.staged) return json(res, 409, { error: "typed_text", message: "There's unsent text in its box. Send or clear it first." }, cors);
     if (live.state === "working") return json(res, 409, { error: "busy", message: "It's working. Wait for it to finish, or press Esc first." }, cors);
-    await bridge.type(text, false);
-    await wait(300);                        // let the slash-command list catch up before Enter
-    await bridge.type("", true);
+    const typed = await typedOr502(bridge, res, cors, async () => {
+      await bridge.type(text, false);
+      await wait(300);                      // let the slash-command list catch up before Enter
+      await bridge.type("", true);
+    });
+    if (!typed) return res.statusCode;
     return json(res, 200, { ok: true, sent: text }, cors);
   }
 

package/src/setup.js

@@ -633,16 +633,22 @@ const UNSEEN = {
 };
 const unseenLine = (kind, n) => (n === 1 ? UNSEEN[kind][0] : `${n} ${UNSEEN[kind][1]}`);
 
-/**
- * Why the phone may not show every agent yet, right after setup: agents running
- * in a terminal that no session record names, and Codex hooks not trusted yet.
- */
-function unseenLines(ctx) {
+/** The service's session records, as they are on disk. Reads nothing else. */
+function sessionRecords(ctx) {
   const records = [];
   const dir = path.join(ctx.paths.dataDir, "sessions");
   let names = [];
   try { names = fs.readdirSync(dir).filter((n) => n.endsWith(".json")); } catch {}
   for (const name of names.slice(0, 5000)) { const r = readJson(path.join(dir, name)); if (r && typeof r === "object") records.push(r); }
+  return records;
+}
+
+/**
+ * Why the phone may not show every agent yet, right after setup: agents running
+ * in a terminal that no session record names, and Codex hooks not trusted yet.
+ */
+function unseenLines(ctx) {
+  const records = sessionRecords(ctx);
   const scan = ctx.processes() || {};
   const n = byAgent(unrecordedAgents(Array.isArray(scan.agents) ? scan.agents : [], records));
   const lines = ["claude", "codex"].filter((kind) => n[kind]).map((kind) => unseenLine(kind, n[kind]));
@@ -828,4 +834,4 @@ function listBackups(ctx) {
 }
 
 module.exports = { context, stableNode, survey, planSetup, runSetup, unseenLines, unseenLine, UNSEEN, planUninstall, runUninstall, pairingLines, readLock, readInstall,
-  probe, listening, versionOf, majorOf, SOCKET_MAX, copyApp, tail, unsafeDataDir, ownSessions };
+  probe, listening, versionOf, majorOf, SOCKET_MAX, copyApp, tail, unsafeDataDir, ownSessions, sessionRecords};