@lawaty/lacode 0.1.1 → 0.1.3

package/dist/lacode.js

@@ -2,6 +2,8 @@
 
 // bin/lacode
 import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync as spawnSync2 } from "node:child_process";
 
 // src/tunnel/index.ts
 import { spawnSync } from "node:child_process";
@@ -19,6 +21,7 @@ function resolveTunnel(env = process.env) {
   const port = Number(env.OC_TUNNEL_PORT);
   return {
     user: env.OC_LOCAL_USER ?? "",
+    host: env.OC_LOCAL_HOST ?? "",
     port: Number.isFinite(port) && port > 0 ? port : 10022,
     key: env.OC_NOTIFY_KEY ?? join(homedir(), ".ssh", "lacode_notify"),
     connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
@@ -41,6 +44,15 @@ var safeText = (raw, fallback, max) => {
 var safeTitle = (raw) => safeText(raw ?? "", "LaCode", 120);
 var safeMessage = (raw) => safeText(raw ?? "", "", 400);
 var FIELD_SEPARATOR = "\n";
+function parsePayload(raw) {
+  const [title, message, urgency, icon] = raw.split(FIELD_SEPARATOR);
+  return {
+    title: safeTitle(title),
+    message: safeMessage(message),
+    urgency: normalizeUrgency(urgency),
+    icon: normalizeIcon(icon)
+  };
+}
 var encodePayload = (request) => [
   safeTitle(request.title),
   safeMessage(request.message),
@@ -59,6 +71,14 @@ var SSH_OPTS = [
   "-o",
   "StrictHostKeyChecking=accept-new"
 ];
+var CONTROL_OPTS = [
+  "-o",
+  "ControlMaster=auto",
+  "-o",
+  "ControlPersist=300",
+  "-o",
+  `ControlPath=${join(homedir(), ".ssh", "lacode-cm-%C")}`
+];
 var run = (command2, args, timeout) => {
   try {
     const result = spawnSync(command2, args, { timeout, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
@@ -120,19 +140,20 @@ function sendLocal(request, platform = process.platform) {
 }
 function sendRemote(request, tunnel) {
   if (!tunnel.user) return { ok: false, detail: "OC_LOCAL_USER is unset; the desktop user for the tunnel is unknown", transport: "remote" };
-  const args = [
-    ...SSH_OPTS,
-    "-o",
-    `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`,
-    "-i",
-    tunnel.key,
-    "-p",
-    String(tunnel.port),
-    `${tunnel.user}@localhost`,
-    "--",
-    encodePayload(request)
-  ];
-  const result = run("ssh", args, tunnel.connectTimeoutMs + 2e3);
+  const connect = ["-o", `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`];
+  if (tunnel.host) {
+    const result2 = run(
+      "ssh",
+      [...SSH_OPTS, ...CONTROL_OPTS, ...connect, "-i", tunnel.key, `${tunnel.user}@${tunnel.host}`, "--", encodePayload(request)],
+      tunnel.connectTimeoutMs + 2e3
+    );
+    return { ok: result2.ok, detail: result2.ok ? void 0 : result2.stderr || result2.detail, transport: "remote" };
+  }
+  const result = run(
+    "ssh",
+    [...SSH_OPTS, ...connect, "-i", tunnel.key, "-p", String(tunnel.port), `${tunnel.user}@localhost`, "--", encodePayload(request)],
+    tunnel.connectTimeoutMs + 2e3
+  );
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "remote" };
 }
 function notify(request, env = process.env, platform = process.platform) {
@@ -158,6 +179,7 @@ function describe(env = process.env, platform = process.platform) {
   return {
     running: isRemote(env) ? "remote (over ssh)" : "local",
     user: tunnel.user || "(unset)",
+    host: tunnel.host || "(unset)",
     port: tunnel.port,
     key: tunnel.key,
     channel: localChannel(platform),
@@ -173,8 +195,8 @@ if (!process.features?.typescript) {
     console.error("lacode: this node cannot load TypeScript sources; node >= 22.18 is required.");
     process.exit(1);
   }
-  const { spawnSync: spawnSync2 } = await import("node:child_process");
-  const result = spawnSync2(
+  const { spawnSync: spawnSync3 } = await import("node:child_process");
+  const result = spawnSync3(
     process.execPath,
     ["--experimental-strip-types", "--no-warnings", fileURLToPath(import.meta.url), ...process.argv.slice(2)],
     { stdio: "inherit", env: { ...process.env, LACODE_STRIP_TYPECHECKED: "1" } }
@@ -247,6 +269,41 @@ switch (command) {
     process.exit(0);
     break;
   }
+  case "receive": {
+    const request = parsePayload(process.env.SSH_ORIGINAL_COMMAND ?? "");
+    const result = sendLocal(request);
+    if (!result.ok) console.error(`lacode receive: ${result.detail ?? "not delivered"}`);
+    process.exit(result.ok ? 0 : 1);
+    break;
+  }
+  case "tunnel": {
+    const sub = argv.shift();
+    if (sub !== "setup") {
+      console.error("lacode tunnel: usage: lacode tunnel setup");
+      process.exit(2);
+    }
+    const { user, host, key } = resolveTunnel();
+    const pub = `${key}.pub`;
+    if (!existsSync(key)) {
+      const gen = spawnSync2("ssh-keygen", ["-t", "ed25519", "-N", "", "-C", "lacode-notify", "-f", key], { stdio: ["ignore", "ignore", "inherit"] });
+      if (gen.status !== 0) {
+        console.error("lacode tunnel setup: ssh-keygen failed; create the key by hand and re-run.");
+        process.exit(1);
+      }
+      console.log(`Generated ${key}`);
+    }
+    const pubkey = existsSync(pub) ? readFileSync(pub, "utf8").trim() : "(public key missing)";
+    const self = process.argv[1] ?? "lacode";
+    console.log("\nOn the REMOTE host (where opencode runs), export:");
+    console.log(`  OC_LOCAL_USER=${user || "<desktop-user>"}`);
+    console.log(`  OC_LOCAL_HOST=${host || "<desktop-host>"}`);
+    console.log(`  OC_NOTIFY_KEY=${key}`);
+    console.log("\nAdd ONE line to the DESKTOP's ~/.ssh/authorized_keys (this is the trust boundary):");
+    console.log(`  restrict,command="${self} receive" ${pubkey}`);
+    console.log("\nDirect ssh + ControlPersist: no reverse forward, no systemd unit, no port, nothing to sync.");
+    process.exit(0);
+    break;
+  }
   default:
     console.error(`lacode: unknown command ${JSON.stringify(safeTitle(command))}`);
     console.error(USAGE);

package/dist/pool.js

@@ -10,12 +10,13 @@ var CATALOG_TTL_MS = 10 * 60 * 1e3;
 var STUCK_MIN_AGE_MS = 5 * 60 * 1e3;
 var STUCK_IDLE_MS = 3 * 60 * 1e3;
 var HANG_COOLDOWN_MS = 10 * 60 * 1e3;
+var UNAVAILABLE_COOLDOWN_MS = 60 * 1e3;
 var MAX_WEIGHT = 100;
 var MAX_SLOTS = 4;
 var COOLDOWN_BASE_MS = 60 * 1e3;
 var COOLDOWN_MAX_MS = 15 * 60 * 1e3;
 var STRIKE_DECAY_MS = 30 * 60 * 1e3;
-var BASES = ["explore-fast", "implement-fast", "context-manager"];
+var BASES = ["explore", "implement", "context"];
 var findPackageRoot = (start) => {
   let dir = start;
   for (let up = 0; up < 6; up++) {
@@ -141,6 +142,7 @@ function readWeight(entry, at, model, problems) {
   }
   return weight;
 }
+var UNAVAILABLE_PATTERN = /endpoint\s+is\s+unavailable/i;
 var LIMIT_PATTERNS = [
   /rate[\s_-]?limit/i,
   /usage limit/i,
@@ -148,9 +150,11 @@ var LIMIT_PATTERNS = [
   /\b429\b/,
   /quota/i,
   /freelimiterror/i,
-  /overloaded/i
+  /overloaded/i,
+  UNAVAILABLE_PATTERN
 ];
 var isLimitText = (text) => LIMIT_PATTERNS.some((re) => re.test(text));
+var isUnavailableText = (text) => UNAVAILABLE_PATTERN.test(text);
 var statedCooldown = (text) => {
   const hm = /resets?\s+in\s+(\d+)\s*(?:h|hr|hour)s?\s*(\d+)?\s*(?:m|min|minute)?s?/i.exec(text);
   if (hm) return (Number(hm[1]) * 60 + (hm[2] ? Number(hm[2]) : 0)) * 60 * 1e3;
@@ -332,6 +336,22 @@ function recordStrike(s, model, reason, stated) {
   }
   return strike;
 }
+function coolUnavailable(s, model) {
+  if (!s.dirReady) return;
+  const now = Date.now();
+  const prior = s.cooling.get(model);
+  const until = now + UNAVAILABLE_COOLDOWN_MS;
+  if (prior && prior.until > until) return prior;
+  const strike = { model, until, strikes: 1, reason: "endpoint-unavailable", last: now };
+  s.cooling.set(model, strike);
+  const path = join(s.dir, limitFile(model));
+  try {
+    writeFileSync(`${path}.tmp`, JSON.stringify(strike));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+  }
+  return strike;
+}
 function refreshCatalog(s, serverUrl) {
   if (!serverUrl || Date.now() - s.catalogAt < CATALOG_TTL_MS) return;
   s.catalogAt = Date.now();
@@ -448,6 +468,7 @@ export {
   PRESETS_DIR,
   STUCK_IDLE_MS,
   STUCK_MIN_AGE_MS,
+  UNAVAILABLE_COOLDOWN_MS,
   USER_CONFIG_DIR,
   USER_MODELS_PATH,
   acquire,
@@ -455,6 +476,7 @@ export {
   bindChild,
   claimKey,
   coolProvider,
+  coolUnavailable,
   ensureSlots,
   ensureUserConfigDir,
   findStuck,
@@ -462,6 +484,7 @@ export {
   init,
   isAvailable,
   isLimitText,
+  isUnavailableText,
   noteActivity,
   parseSlots,
   pickSlot,

package/dist/tunnel.js

@@ -14,6 +14,7 @@ function resolveTunnel(env = process.env) {
   const port = Number(env.OC_TUNNEL_PORT);
   return {
     user: env.OC_LOCAL_USER ?? "",
+    host: env.OC_LOCAL_HOST ?? "",
     port: Number.isFinite(port) && port > 0 ? port : 10022,
     key: env.OC_NOTIFY_KEY ?? join(homedir(), ".ssh", "lacode_notify"),
     connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
@@ -36,6 +37,15 @@ var safeText = (raw, fallback, max) => {
 var safeTitle = (raw) => safeText(raw ?? "", "LaCode", 120);
 var safeMessage = (raw) => safeText(raw ?? "", "", 400);
 var FIELD_SEPARATOR = "\n";
+function parsePayload(raw) {
+  const [title, message, urgency, icon] = raw.split(FIELD_SEPARATOR);
+  return {
+    title: safeTitle(title),
+    message: safeMessage(message),
+    urgency: normalizeUrgency(urgency),
+    icon: normalizeIcon(icon)
+  };
+}
 var encodePayload = (request) => [
   safeTitle(request.title),
   safeMessage(request.message),
@@ -54,6 +64,14 @@ var SSH_OPTS = [
   "-o",
   "StrictHostKeyChecking=accept-new"
 ];
+var CONTROL_OPTS = [
+  "-o",
+  "ControlMaster=auto",
+  "-o",
+  "ControlPersist=300",
+  "-o",
+  `ControlPath=${join(homedir(), ".ssh", "lacode-cm-%C")}`
+];
 var run = (command, args, timeout) => {
   try {
     const result = spawnSync(command, args, { timeout, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
@@ -115,19 +133,20 @@ function sendLocal(request, platform = process.platform) {
 }
 function sendRemote(request, tunnel) {
   if (!tunnel.user) return { ok: false, detail: "OC_LOCAL_USER is unset; the desktop user for the tunnel is unknown", transport: "remote" };
-  const args = [
-    ...SSH_OPTS,
-    "-o",
-    `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`,
-    "-i",
-    tunnel.key,
-    "-p",
-    String(tunnel.port),
-    `${tunnel.user}@localhost`,
-    "--",
-    encodePayload(request)
-  ];
-  const result = run("ssh", args, tunnel.connectTimeoutMs + 2e3);
+  const connect = ["-o", `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`];
+  if (tunnel.host) {
+    const result2 = run(
+      "ssh",
+      [...SSH_OPTS, ...CONTROL_OPTS, ...connect, "-i", tunnel.key, `${tunnel.user}@${tunnel.host}`, "--", encodePayload(request)],
+      tunnel.connectTimeoutMs + 2e3
+    );
+    return { ok: result2.ok, detail: result2.ok ? void 0 : result2.stderr || result2.detail, transport: "remote" };
+  }
+  const result = run(
+    "ssh",
+    [...SSH_OPTS, ...connect, "-i", tunnel.key, "-p", String(tunnel.port), `${tunnel.user}@localhost`, "--", encodePayload(request)],
+    tunnel.connectTimeoutMs + 2e3
+  );
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "remote" };
 }
 function notify(request, env = process.env, platform = process.platform) {
@@ -153,6 +172,7 @@ function describe(env = process.env, platform = process.platform) {
   return {
     running: isRemote(env) ? "remote (over ssh)" : "local",
     user: tunnel.user || "(unset)",
+    host: tunnel.host || "(unset)",
     port: tunnel.port,
     key: tunnel.key,
     channel: localChannel(platform),
@@ -172,6 +192,7 @@ export {
   normalizeIcon,
   normalizeUrgency,
   notify,
+  parsePayload,
   resolveTunnel,
   safeMessage,
   safeTitle,

package/docs/CONTEXT.md

@@ -69,14 +69,14 @@ something has gone wrong.
 
 ## How it stays current
 
-The `context-manager` agent maintains the map. It runs in two ways: on its own,
+The `context` agent maintains the map. It runs in two ways: on its own,
 after a session that changed something, and on demand through the three
 commands — both of which go through the same agent, so they behave the same way.
 
 ### Automatically
 
 After a **root** session goes idle, and only if that session edited a file
-inside the project, LaCode starts a `context-manager` run:
+inside the project, LaCode starts a `context` run:
 
 1. It collects the paths the session touched, dropping anything generated,
    vendored or outside the project (`node_modules`, `dist`, `coverage`,
@@ -123,7 +123,7 @@ as you wrote it — the same merge-without-clobber rule the agents follow.
 
 ## One writer
 
-Only `context-manager` writes the map. Every other agent is told never to edit
+Only `context` writes the map. Every other agent is told never to edit
 it, and to say in its final report if its work revealed something that belongs
 in there. The cartographer, in turn, is denied permission to write anything
 outside the map — not by convention, but by an `edit` rule that allows
@@ -199,7 +199,7 @@ thing to check is that permission rule, not the map's content.
 | `auto update finished without changing the map` | Nothing landed. Either nothing needed saying, or the cartographer could not write. |
 | `auto update failed: …` | The run errored. The paths it was given are queued again for the next window, so the work is not lost. |
 | `context map is not writable: …` | Your config's one-writer rule does not match the path opencode evaluates. Nothing will update until you fix it. |
-| `context map has more than one writer: …` | An agent other than `context-manager` would be granted the map. The offending agent and the winning rule are named. |
+| `context map has more than one writer: …` | An agent other than `context` would be granted the map. The offending agent and the winning rule are named. |
 
 ## Reference
 

package/docs/TUNNEL.md

@@ -9,23 +9,23 @@ gets it back.
 
 ```
   remote host                                   your desktop
-  ┌──────────────────┐                          ┌────────────────────────┐
-  │ opencode session │                          │ oc-notify-receiver     │
-  │      │           │  ssh (reverse forward)   │  (forced command,      │
-  │      ▼           │ ───────────────────────► │   restrict)            │
-  │ bin/lacode      │  ONE argument:            │      │                 │
-  │   notify         │  title\nmessage\n         │      ▼                 │
-  │                  │  urgency\nicon            │  notify-send           │
+  ┌──────────────────┐   direct ssh             ┌────────────────────────┐
+  │ opencode session │   (ControlPersist)       │  lacode receive        │
+  │      │           │ ───────────────────────► │  (authorized_keys      │
+  │      ▼           │   ONE argument:          │   forced command)      │
+  │ lacode notify    │   title\nmessage\n       │      │                 │
+  │                  │   urgency\nicon          │      ▼                 │
+  │                  │                          │  notify-send /         │
+  │                  │                          │  osascript             │
   └──────────────────┘                          └────────────────────────┘
 ```
 
-Two things are load-bearing here.
-
-**The reverse forward.** The remote opens an SSH connection to *your* machine
-and asks sshd on the desktop to listen on a port. A notification is then an ssh
-call to `localhost:<port>` with a dedicated key that is authorized to run
-exactly one command. It is not a login, it is not a shell, and it does not
-depend on which terminal connected first.
+**Direct ssh, one warm connection.** The hop is a plain `ssh` to the desktop with
+`ControlMaster=auto` + `ControlPersist`, so the first notification opens the
+connection and every later one rides it. There is no reverse forward, no
+listening port, no systemd unit and nothing to sync: the plugin owns the
+transport, and it exists only while opencode runs — which is the only time a
+notification matters.
 
 **One argument, not four.** ssh concatenates everything after the host into a
 single command string, and a forced command starts with *no* positional
@@ -43,17 +43,46 @@ the free-text fields before assembling or reading it, and `urgency` and `icon`
 come from whitelists. No field can contain the delimiter, so a message full of
 spaces, quotes or `*` survives intact.
 
+## Setting it up
+
+Once, on the **remote host** (where opencode runs):
+
+```bash
+lacode tunnel setup
+```
+
+It generates the dedicated key (`~/.ssh/lacode_notify` by default) and prints the
+environment to export there, and the single `authorized_keys` line to add on the
+desktop:
+
+```
+OC_LOCAL_USER=<desktop user>
+OC_LOCAL_HOST=<desktop hostname>
+OC_NOTIFY_KEY=~/.ssh/lacode_notify
+```
+
+On the **desktop**, add the printed line to `~/.ssh/authorized_keys`:
+
+```
+restrict,command="lacode receive" ssh-ed25519 AAAA… lacode-notify
+```
+
+`restrict` does the security work: no shell, no PTY, no agent forwarding, no port
+forwarding. The key can do exactly one thing — hand one notification to
+`lacode receive` — and nothing else. Use the absolute path to `lacode` if it is
+not on the forced command's `PATH`.
+
 ## Sending
 
 The CLI picks the transport by where it is running — `SSH_CLIENT` or `SSH_TTY`
 means remote, so it forwards; otherwise it delivers locally through whichever
-desktop notifier this platform has: `notify-send` everywhere else, `osascript` on
-macOS, with `terminal-notifier` as the macOS fallback when `osascript` is missing.
+desktop notifier this platform has: `notify-send` on Linux, `osascript` on macOS,
+with `terminal-notifier` as the macOS fallback when `osascript` is missing.
 
 ```bash
-lacode notify "build finished" "lapode: 4 files changed" normal dialog-information
+lacode notify "build finished" "4 files changed" normal dialog-information
 lacode notify "question" "which database should I use?" critical dialog-warning
-lacode forward web-01 -- systemctl --user status oc-tunnel
+lacode forward web-01 -- systemctl --user status something
 lacode doctor
 ```
 
@@ -68,107 +97,38 @@ handler, never spliced into the script source — a session title is not trusted
 input. `lacode doctor` prints the channel that would actually run, so it is
 useful on a Mac rather than reporting only whether a Linux binary is installed.
 
-`lacode doctor` prints what the environment resolves to and never gates on it.
+## The desktop side: `lacode receive`
+
+`lacode receive` is the forced command. It reads the newline payload from
+`$SSH_ORIGINAL_COMMAND`, sanitizes each field again at the trust boundary, and
+delivers locally through the platform channel — `notify-send` on Linux,
+`osascript`/`terminal-notifier` on macOS. Because it delegates to the same local
+channel as a local send, **the desktop half is not Linux-only**: a Mac desktop
+receives notifications too.
+
+It never forwards: `SSH_CLIENT` is set for a forced command as well, so it calls
+the local channel directly rather than `notify()` (which would loop back).
 
 ## Configuration
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
-| `OC_LOCAL_USER` | *(unset)* | The desktop user the tunnel authenticates as. **Required for the remote hop.** |
-| `OC_TUNNEL_PORT` | `10022` | Reverse-forward listener port on the desktop. Give each remote host its own. |
+| `OC_LOCAL_USER` | *(unset)* | The desktop user the hop authenticates as. **Required for the remote hop.** |
+| `OC_LOCAL_HOST` | *(unset)* | Desktop hostname for the direct ssh hop. The default; set it and no reverse forward or port is used. |
 | `OC_NOTIFY_KEY` | `~/.ssh/lacode_notify` | The dedicated key. Never a personal key. |
 | `OC_CONNECT_TIMEOUT_MS` | `5000` | Ceiling on the hop. |
 | `OC_SSH_TIMEOUT_MS` | `30000` | Ceiling on `forward`. |
+| `OC_TUNNEL_PORT` | `10022` | **Legacy** reverse-forward listener port. Used only when `OC_LOCAL_HOST` is unset. |
 
 `OC_LOCAL_USER` is read rather than probed on purpose. `id -un` on a remote
 account frequently returns `root`, and a dbus path built from that reaches
 nobody's desktop. Guessing the desktop user is worse than failing.
 
-## Setting the tunnel up on the desktop
-
-The receiver runs on the machine with the desktop, as an `authorized_keys`
-forced command restricted to that one script. `$HOME` must be the expanded
-absolute path — a `~` is not expanded there, and an unexpanded one produces an
-`authorized_keys` entry that names a file that does not exist:
-
-```
-restrict,command="/home/yourname/.local/bin/lacode-notify-receiver" ssh-ed25519 AAAA… oc-notify tunnel auth
-```
-
-`restrict` is doing the security work: no shell, no PTY, no agent forwarding, no
-port forwarding. The key can do exactly one thing and nothing else.
-
-The receiver must satisfy this contract:
-
-1. read the payload from **`$SSH_ORIGINAL_COMMAND`**, never from `$1`..`$4`;
-2. **never** `eval` it, never hand it to `sh -c`, never splice it into an
-   argument list — it is attacker-controlled, because it is whatever the remote
-   user typed;
-3. split it on newlines into title / message / urgency / icon, each with a
-   default — **using only constructs bash 3.2 has**, not just bash 4+;
-4. whitelist `urgency` against `low|normal|critical` and `icon` against the six
-   supported names, both of which become command-line flags;
-5. resolve `DISPLAY` / `DBUS_SESSION_BUS_ADDRESS` for the session it is running
-   in, then `exec notify-send "$TITLE" "$MSG" --urgency=… --icon=…`.
-
-Point 3 is not a detail. `mapfile`/`readarray` are bash 4.0+, and where they are
-missing — macOS ships bash 3.2, as do some minimal Linux images — the array is
-simply never built, every field falls back to its default, and the desktop gets
-a notification titled "LaCode" with an empty body. No error is printed anywhere
-that anyone will read, because the receiver's stderr goes to whoever happened to
-open the ssh connection. A `while IFS= read -r` loop is equivalent and works
-everywhere; `bin/oc-notify-receiver` uses one.
-
-### This half of the hop is Linux
-
-The receiver delivers through `notify-send`, and the forward that reaches it is
-a systemd `--user` unit (below). Both are Linux, so **the desktop half of this
-tunnel does not exist on macOS**, and that is by design rather than a gap.
-
-On a Mac you do not need it: `lacode notify` run locally picks `osascript` (or
-`terminal-notifier`) and shows the notification itself, with no tunnel, no
-`authorized_keys` entry and no systemd unit involved. The tunnel exists for the
-case opencode runs *somewhere else*, and a Mac is not going to be running it.
-
-If you point the receiver at a machine with no `notify-send` anyway, it exits
-non-zero and says so, naming `lacode notify` as the path that does work there.
-`bin/oc-sync` refuses the same machine for the same reason, and names each
-missing prerequisite instead of failing somewhere less obvious.
-
-> **Note.** The published package ships the built CLI (`dist/lacode.js`, linked
-> as `lacode`) and the tunnel behind it (`dist/tunnel.js`, importable as
-> `@lawaty/lacode/tunnel`), not a receiver script. The receiver is the
-> desktop-side half and is yours to install — keep it out of your shell's
-> `$PATH` reach and pinned in `authorized_keys`.
-
-If the two halves disagree you get a blank popup, which points nowhere. A
-receiver that sees a payload with no newline in it should say so on stderr
-rather than silently defaulting everything.
-
-## Holding the forward open
-
-The tunnel has to exist whenever a notification is sent. Anything that survives
-your logout works: a `--user` systemd unit is the usual choice, one per remote
-host, each with its own port.
-
-```ini
-# ~/.config/systemd/user/oc-tunnel@<host>.service
-[Service]
-ExecStart=/usr/bin/ssh -NT -R 10022:localhost -o ClearAllForwardings=yes -o ExitOnForwardFailure=yes \
-          -i %h/.ssh/lacode_notify you@localhost
-```
-
-Then `systemctl --user enable --now oc-tunnel@web-01`.
-
-Two details that matter:
-
-- **`-o ExitOnForwardFailure=yes`** — without it, ssh stays up with no forward
-  and the notifications fail silently.
-- **`-o ClearAllForwardings=yes`** on every *other* ssh call that touches that
-  host, including rsync's `-e`. A `RemoteForward` in `~/.ssh/config` competes
-  for the same port, and a half-claimed listener starves the one session that
-  needed it.
+## Legacy: the reverse forward
 
-Do not hold the forward open with a `RemoteForward` line in `~/.ssh/config`. It
-is per-connection: the port exists only while some terminal is open, and it is
-claimed by whichever terminal connects first.
+The original design opened a reverse forward (`ssh -R`) held by a `systemd --user`
+unit on the desktop, and delivered to a `notify-send`-only bash receiver
+(`bin/oc-notify-receiver`). It is kept only for hosts that still set
+`OC_TUNNEL_PORT` and leave `OC_LOCAL_HOST` unset: `sendRemote` falls back to an
+ssh call to `localhost:<port>`. New setups should use the direct ssh above. See
+the git history for the old systemd unit shape.