@lawaty/lacode 0.1.0 → 0.1.2

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"] });
@@ -81,37 +101,64 @@ var have = (command2) => {
     return false;
   }
 };
-function sendLocal(request) {
-  if (!have("notify-send")) return { ok: false, detail: "notify-send is not installed", transport: "local" };
-  const args = [
-    safeTitle(request.title),
-    safeMessage(request.message),
-    `--urgency=${normalizeUrgency(request.urgency)}`,
-    `--icon=${normalizeIcon(request.icon)}`
-  ];
-  const result = run("notify-send", args, 5e3);
+var CHANNEL_BINARY = {
+  "notify-send": "notify-send",
+  osascript: "osascript",
+  "terminal-notifier": "terminal-notifier"
+};
+var DARWIN_SCRIPT = [
+  "on run argv",
+  "  display notification (item 3 of argv) with title (item 2 of argv)",
+  "end run"
+].join("\n");
+var DARWIN_ARGV_MARKER = "lacode";
+function localChannel(platform = process.platform) {
+  if (platform === "darwin") {
+    if (have(CHANNEL_BINARY.osascript)) return "osascript";
+    if (have(CHANNEL_BINARY["terminal-notifier"])) return "terminal-notifier";
+    return "none";
+  }
+  return have(CHANNEL_BINARY["notify-send"]) ? "notify-send" : "none";
+}
+var NO_CHANNEL = {
+  linux: "notify-send is not installed",
+  darwin: "neither osascript nor terminal-notifier is installed"
+};
+function sendLocal(request, platform = process.platform) {
+  const channel = localChannel(platform);
+  if (channel === "none") {
+    return { ok: false, detail: NO_CHANNEL[platform] ?? `no local notification channel on ${platform}`, transport: "local" };
+  }
+  const title = safeTitle(request.title);
+  const body = safeMessage(request.message);
+  const args = channel === "osascript" ? ["-e", DARWIN_SCRIPT, DARWIN_ARGV_MARKER, title, body] : channel === "terminal-notifier" ? ["-title", title, "-message", body, "-appName", "LaCode", "-priority", normalizeUrgency(request.urgency)] : (
+    // Byte-identical to the notify-send call this package has always made.
+    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
+  );
+  const result = run(CHANNEL_BINARY[channel], args, 5e3);
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
 }
 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) {
+function notify(request, env = process.env, platform = process.platform) {
   try {
-    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request);
+    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
   } catch (error) {
     return { ok: false, detail: String(error), transport: "none" };
   }
@@ -127,13 +174,17 @@ function forward(host, argv2, options = {}) {
     stdout: result.stdout
   };
 }
-function describe(env = process.env) {
+function describe(env = process.env, platform = process.platform) {
   const tunnel = resolveTunnel(env);
   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),
+    // Still exactly what it always meant -- is the notify-send binary present --
+    // rather than a second opinion about which channel runs.
     notifySend: have("notify-send")
   };
 }
@@ -144,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" } }
@@ -212,7 +263,44 @@ switch (command) {
     if (info.running.startsWith("remote")) {
       if (info.user === "(unset)") console.log("\nOC_LOCAL_USER is unset: the hop cannot name the desktop user, and guessing with `id -un` is wrong on most remote accounts.");
       console.log("Set OC_LOCAL_USER, OC_TUNNEL_PORT and OC_NOTIFY_KEY, or point OC_NOTIFY_HELPER at a helper that knows them.");
+    } else if (info.channel === "none") {
+      console.log("\nNo local notification channel: `lacode notify` on this machine has nothing to deliver with, and every send will be reported as failed rather than shown.");
+    }
+    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;
   }

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"] });
@@ -76,37 +94,64 @@ var have = (command) => {
     return false;
   }
 };
-function sendLocal(request) {
-  if (!have("notify-send")) return { ok: false, detail: "notify-send is not installed", transport: "local" };
-  const args = [
-    safeTitle(request.title),
-    safeMessage(request.message),
-    `--urgency=${normalizeUrgency(request.urgency)}`,
-    `--icon=${normalizeIcon(request.icon)}`
-  ];
-  const result = run("notify-send", args, 5e3);
+var CHANNEL_BINARY = {
+  "notify-send": "notify-send",
+  osascript: "osascript",
+  "terminal-notifier": "terminal-notifier"
+};
+var DARWIN_SCRIPT = [
+  "on run argv",
+  "  display notification (item 3 of argv) with title (item 2 of argv)",
+  "end run"
+].join("\n");
+var DARWIN_ARGV_MARKER = "lacode";
+function localChannel(platform = process.platform) {
+  if (platform === "darwin") {
+    if (have(CHANNEL_BINARY.osascript)) return "osascript";
+    if (have(CHANNEL_BINARY["terminal-notifier"])) return "terminal-notifier";
+    return "none";
+  }
+  return have(CHANNEL_BINARY["notify-send"]) ? "notify-send" : "none";
+}
+var NO_CHANNEL = {
+  linux: "notify-send is not installed",
+  darwin: "neither osascript nor terminal-notifier is installed"
+};
+function sendLocal(request, platform = process.platform) {
+  const channel = localChannel(platform);
+  if (channel === "none") {
+    return { ok: false, detail: NO_CHANNEL[platform] ?? `no local notification channel on ${platform}`, transport: "local" };
+  }
+  const title = safeTitle(request.title);
+  const body = safeMessage(request.message);
+  const args = channel === "osascript" ? ["-e", DARWIN_SCRIPT, DARWIN_ARGV_MARKER, title, body] : channel === "terminal-notifier" ? ["-title", title, "-message", body, "-appName", "LaCode", "-priority", normalizeUrgency(request.urgency)] : (
+    // Byte-identical to the notify-send call this package has always made.
+    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
+  );
+  const result = run(CHANNEL_BINARY[channel], args, 5e3);
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
 }
 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) {
+function notify(request, env = process.env, platform = process.platform) {
   try {
-    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request);
+    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
   } catch (error) {
     return { ok: false, detail: String(error), transport: "none" };
   }
@@ -122,13 +167,17 @@ function forward(host, argv, options = {}) {
     stdout: result.stdout
   };
 }
-function describe(env = process.env) {
+function describe(env = process.env, platform = process.platform) {
   const tunnel = resolveTunnel(env);
   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),
+    // Still exactly what it always meant -- is the notify-send binary present --
+    // rather than a second opinion about which channel runs.
     notifySend: have("notify-send")
   };
 }
@@ -139,9 +188,11 @@ export {
   encodePayload,
   forward,
   isRemote,
+  localChannel,
   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

@@ -19,7 +19,15 @@ gets it back.
   └──────────────────┘                          └────────────────────────┘
 ```
 
-Two things are load-bearing here.
+**Direct ssh (the default).** Set `OC_LOCAL_HOST` and the hop is a plain `ssh`
+to the desktop with `ControlMaster=auto` + `ControlPersist`, so one warm
+connection carries every notification. There is no reverse forward, no listening
+port, no systemd unit and nothing to sync: the plugin owns the transport. The
+desktop needs one `authorized_keys` line, which `lacode tunnel setup` prints. The
+reverse-forward description below is the legacy path, used only when
+`OC_LOCAL_HOST` is unset.
+
+**Reverse forward (legacy).** 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
@@ -46,7 +54,9 @@ spaces, quotes or `*` survives intact.
 ## Sending
 
 The CLI picks the transport by where it is running — `SSH_CLIENT` or `SSH_TTY`
-means remote, so it forwards; otherwise it calls `notify-send` directly.
+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.
 
 ```bash
 lacode notify "build finished" "lapode: 4 files changed" normal dialog-information
@@ -55,19 +65,25 @@ lacode forward web-01 -- systemctl --user status oc-tunnel
 lacode doctor
 ```
 
-`notify` is fire-and-forget by design. An unreachable desktop, a missing key, a
-missing `notify-send` — all of them print a warning on stderr and exit 0. A
+`notify` is fire-and-forget by design. An unreachable desktop, a missing key, no
+notifier installed at all — all of them print a warning on stderr and exit 0. A
 notification must never be able to fail the process that tried to send one; an
 agent must not go down because a laptop went to sleep. `forward` is the
 exception: it exits with the remote's status, because its caller wants to know.
 
+On macOS the text is passed to `osascript` as arguments to an `on run argv`
+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.
 
 ## Configuration
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
-| `OC_LOCAL_USER` | *(unset)* | The desktop user the tunnel authenticates as. **Required for the remote hop.** |
+| `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. Set it and the reverse forward/port/systemd unit are not used at all. |
 | `OC_TUNNEL_PORT` | `10022` | Reverse-forward listener port on the desktop. Give each remote host its own. |
 | `OC_NOTIFY_KEY` | `~/.ssh/lacode_notify` | The dedicated key. Never a personal key. |
 | `OC_CONNECT_TIMEOUT_MS` | `5000` | Ceiling on the hop. |
@@ -80,10 +96,12 @@ 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:
+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/you/.local/bin/lacode-notify-receiver" ssh-ed25519 AAAA… oc-notify tunnel auth
+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
@@ -96,12 +114,36 @@ The receiver must satisfy this contract:
    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;
+   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