@lawaty/lacode 0.1.0 → 0.1.1

package/README.md

@@ -39,6 +39,12 @@ directory to create. Do not run `npm i -g @lawaty/lacode`: a global npm install
 is never consulted by opencode, so it changes nothing about whether the plugin
 loads.
 
+It is also the form to keep as your default: if your opencode does not load the
+bare specifier, add to this line rather than replacing it. The
+[procedure below](#if-the-agents-are-missing) says when that is, and
+[which versions this is known on](#which-opencode-versions-this-is-known-on)
+says what is actually verified.
+
 To install it explicitly instead — or to install it once for every project on
 the machine rather than per config — use the CLI, which does the same thing:
 
@@ -53,25 +59,53 @@ agent set will look stale for no visible reason.
 
 ### Where it is installed
 
-opencode installs npm plugins itself, into one directory per specifier under
-its cache — not into your project's `node_modules`, and not from anywhere a
-global npm install put them:
+opencode installs npm plugins itself, into one directory per specifier under its
+cache — not into your project's `node_modules`, and not from anywhere a global
+npm install put them. Ask opencode where that cache is instead of assuming,
+because where it lives differs by platform:
+
+```bash
+opencode debug paths
+```
+
+It prints the directories opencode is using on this machine — config, data, log
+and the rest. Find the **cache** line and append
+`/packages/<specifier>/node_modules/` to the path it reports. On Linux with no
+`XDG_CACHE_HOME` set, that comes out as, for example:
 
 ```
-$XDG_CACHE_HOME/opencode/packages/<specifier>/node_modules/
-# ~/.cache/opencode/packages/@lawaty/lacode@latest/node_modules/ by default
+~/.cache/opencode/packages/@lawaty/lacode@latest/node_modules/
 ```
 
-`$XDG_CACHE_HOME` defaults to `~/.cache`; set it if you keep a cache elsewhere.
-To inspect what a specifier actually resolved to, list its directory under
-`~/.cache/opencode/packages/`. An empty directory with no `node_modules` inside
-it means the install failed — almost always an unpublished or misspelled package
-— and opencode starts normally **without** the plugin.
+**That last line is an illustration of one platform's layout, not a path to
+copy.** Where the same cache root sits on another operating system is not
+something this document should guess at — read it from `opencode debug paths`
+and use what it prints.
+
+To inspect what a specifier actually resolved to, list its directory under that
+cache root. An **empty** directory with no `node_modules` inside it means the
+install failed — almost always an unpublished or misspelled package — and
+opencode starts normally **without** the plugin. A **populated** directory there
+means the install succeeded and tells you nothing at all about whether the
+plugin was loaded; that is the next section, and telling those two apart is the
+whole reason for reading it.
+
+### If the agents are missing
+
+A plugin that fails to load is silent: opencode starts normally, prints nothing,
+logs nothing, and the agents are simply not there. Work down this. Every step
+below is written to hold whichever opencode version you are running — none of
+them depends on knowing the answer in advance.
+
+**1 — Write the bare specifier and restart.**
+
+```json
+{ "plugin": ["@lawaty/lacode"] }
+```
 
-### Verifying the install
+Nothing here hot-reloads, so the restart is part of the step, not a footnote.
 
-A plugin that fails to install is silent: there is no error, opencode starts,
-and it simply does not have the agents. Check for them:
+**2 — Check whether the plugin loaded.**
 
 ```bash
 opencode agent list | grep -E '^(explore-fast|implement-fast|explore-deep|implement-deep)'
@@ -79,11 +113,123 @@ opencode agent list | grep -E '^(explore-fast|implement-fast|explore-deep|implem
 
 A working install prints `explore-fast`, `implement-fast`, `explore-deep` and
 `implement-deep`, each with the hidden `-1`..`-4` pool variants alongside. If the
-grep returns nothing but opencode's built-ins, the plugin did not load: check the
-cache directory above, and check that `plugin` is in the config file opencode
-actually reads. Run this in the same shell environment opencode runs in — an
+grep returns nothing and the list holds only opencode's own built-ins, the plugin
+did not load. Run it in the same shell environment opencode runs in — an
 `agent list` under a different `HOME` or `XDG_CONFIG_HOME` tests a different
-machine.
+machine. **If the agents are listed, stop here: the one line above is the whole
+install**, and nothing further in this section applies to you.
+
+**3 — Decide which failure you are looking at.** Inspect the package directory
+under the cache root from
+[Where it is installed](#where-it-is-installed), and also check that `plugin`
+really is in the config file opencode reads.
+
+- **Empty** (no `node_modules` inside): the install failed — check the package
+  name, and that it is published. There is nothing to load yet.
+- **Populated**: the install worked and the loader dropped the plugin. Go to
+  step 4. These two look identical from the outside, which is why this step
+  exists.
+
+**4 — If the install worked and the agents are still missing, point the loader
+at the built file.** Add a second entry; leave the bare name in place:
+
+```json
+{
+  "plugin": [
+    "@lawaty/lacode",
+    "file:///ABSOLUTE-PATH-FROM-debug-paths/packages/@lawaty/lacode@latest/node_modules/@lawaty/lacode/dist/index.js"
+  ]
+}
+```
+
+`ABSOLUTE-PATH-FROM-debug-paths` is a placeholder to be replaced, not a
+directory: take the cache path `opencode debug paths` reports for **your**
+machine and put it in front of `/packages/…`. It must be an absolute path with
+`$HOME` already expanded and no `~` left in it. Re-derive it after a cache wipe
+or a reinstall — the directory is keyed by specifier, so it moves when the
+version does.
+
+Why keep both entries instead of swapping the bare name out:
+
+- The bare name is what makes opencode install the package into its cache, and
+  therefore what creates the path the `file://` entry points at.
+- The `file://` entry is what actually loads the plugin.
+- They **cannot double-inject** on opencode 1.18.35, where the bare name
+  contributes nothing at all: the pair loads the plugin exactly once. On any
+  other version this is untested, which is precisely why step 4 is something you
+  take *because* step 2 showed the agents missing, and never on the expectation
+  that it would help.
+
+**5 — Restart, and expect two restarts after a cache wipe.** The first start
+installs the package and creates the path the `file://` entry points at, but a
+path that does not exist at startup is a path that cannot be loaded in that same
+run. The second start finds it and loads the plugin. After that it is steady
+state.
+
+This package also publishes `main` and an `exports["./server"]` entry pointing at
+the same built file, because those are two of the shapes a plugin loader
+resolving an entry point consults. They are forward-compatibility metadata and
+they cost nothing — but they do **not** fix this on 1.18.35: adding either one to
+the *installed* cache copy was tested there and the bare specifier still loaded
+nothing. No other version has been observed where they help either. Use the
+`file://` entry.
+
+### Which opencode versions this is known on
+
+Exactly one version has been measured, and the procedure above is deliberately
+not built around that fact. Treat this table as the evidence it is, which is one
+row wide.
+
+| opencode version | bare spec loads? | `file://` needed? | evidence |
+| --- | --- | --- | --- |
+| 1.18.35 | No — installs the package, then silently drops it | Yes | **Verified** on 1.18.35: a populated cache directory, zero agents injected, no error and no log line; the `file://` entry loads the full agent set. |
+| Any other version | **Unknown** | **Unknown** | **Untested.** No other opencode version has been run against this package in either direction. |
+
+Every command quoted on this page was run against 1.18.35. **If your version is
+not the one measured here, follow the procedure above rather than reading this
+table as coverage of your build**: each step stands on its own, and step 2 tells
+you which situation you are in before any version-specific advice is relevant.
+
+### macOS
+
+The plugin runs on macOS. It is plain JavaScript with no native dependency, and
+what the package publishes is the built JavaScript rather than TypeScript
+sources, so nothing about loading it is Linux-only. Use the procedure above
+unchanged.
+
+Three things differ, and all three are worth reading rather than assuming:
+
+- **Paths.** Do not copy a cache path out of this document — the example under
+  [Where it is installed](#where-it-is-installed) is one platform's layout. Run
+  `opencode debug paths` and build the `file://` entry from what it reports.
+  This page deliberately does not name a macOS cache root: where opencode keeps
+  it on a Mac has not been established here, and a plausible-looking guess is
+  worse than an instruction to look.
+- **Notifications** are delivered through `osascript`, or through
+  `terminal-notifier` when `osascript` is not installed, rather than through the
+  Linux `notify-send` (US-26). `lacode doctor` reports which channel your machine
+  would actually use.
+- **The repository's shell scripts are Linux-only by design**, and are not in the
+  published package. They drive one person's SSH topology, so each is on the side
+  it belongs to:
+
+  | Script | Runs on | Why it is Linux-only |
+  | --- | --- | --- |
+  | `bin/oc`, `bin/oc-notify` | the **remote host** that runs opencode | Server-side. They are pushed to `~/bin/` on each host by `bin/oc-sync` and notify *your desktop* over the tunnel. |
+  | `bin/oc-notify-receiver` | your **desktop** | Delivers through `notify-send` (libnotify), and the persistent forward that reaches it is a systemd user unit. |
+  | `bin/oc-sync` | your **desktop** | Installs those systemd user units and runs `loginctl enable-linger`. |
+
+  None of this is a limitation of the package: a macOS client installs the plugin
+  and uses the `lacode` CLI, and both are portable. The scripts above are the
+  author's personal remote-tunnel tooling. `bin/oc-sync` refuses to run where it
+  cannot work and says which `lacode` subcommand to use instead, rather than
+  failing somewhere less obvious.
+
+**The test suite runs on macOS.** It is written to pass on a Mac as well as on
+Linux, so "it works on a Mac" is a supported claim rather than an intention. The
+few checks that exercise the Linux-only shell scripts above skip themselves on a
+machine that cannot run them, naming the reason — a bash 3.2 with no `mapfile`,
+or no GNU `timeout` — rather than passing silently or failing confusingly.
 
 ### The `lacode` CLI
 
@@ -407,7 +553,8 @@ they call the same `scripts/build.mjs` the tarball does.
 is the guard: it reads the `### US-N:` headings out of `docs/USER-STORIES.md`
 and the `[US-N]` markers out of the test names and fails if they disagree, in
 either direction. **A test that covers a story must have the id at the start of
-its name** — `test("[US-7] a paid model is accepted")` — or CI's guard fails it.
+its name** — `test("[US-7] a paid model is accepted")` — or the coverage guard
+fails it.
 A story with no test is as much a failure as a test naming a story that does not
 exist.
 

package/dist/lacode.js

@@ -81,15 +81,41 @@ 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) {
@@ -109,9 +135,9 @@ function sendRemote(request, tunnel) {
   const result = run("ssh", args, 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 +153,16 @@ 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)",
     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")
   };
 }
@@ -212,6 +241,8 @@ 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;

package/dist/tunnel.js

@@ -76,15 +76,41 @@ 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) {
@@ -104,9 +130,9 @@ function sendRemote(request, tunnel) {
   const result = run("ssh", args, 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 +148,16 @@ 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)",
     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,6 +168,7 @@ export {
   encodePayload,
   forward,
   isRemote,
+  localChannel,
   normalizeIcon,
   normalizeUrgency,
   notify,

package/docs/TUNNEL.md

@@ -46,7 +46,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,12 +57,17 @@ 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
@@ -80,10 +87,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 +105,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

package/docs/USER-STORIES.md

@@ -246,6 +246,24 @@ does not.
 - [ ] Given a payload containing shell metacharacters (`$(…)`, backticks, `;`, `&&`) or extra fields, When the receiver handles it, Then it is parsed as data only: nothing is executed and the argument list passed to `notify-send` is unchanged.
 - [ ] Given a payload that cannot be understood at all, When it arrives, Then the receiver still exits 0 and pops up what it received, rather than failing the hop.
 
+### US-26: A local notification is delivered on macOS, not only on Linux
+**As a** user whose desktop is a Mac, **I want** a notification to actually appear when a session finishes, **so that** installing the package on macOS is not the same as getting no notifications at all.
+
+**Story ID(s) for tests:** US-26
+**Acceptance criteria:**
+- [ ] Given the notification is raised on macOS, When it is delivered locally, Then it goes to `osascript` — or to `terminal-notifier` if `osascript` is not installed — and not to `notify-send`, which does not exist there. Before this, the send exited 0, printed nothing, and popped up nothing.
+- [ ] Given the channel is chosen, When it is picked, Then it is decided by `process.platform` and by which binary is actually installed, never by guessing, and every platform other than macOS keeps the `notify-send` call it has always made.
+- [ ] Given the title and the body reach `osascript`, When the script runs, Then they are passed as arguments to an `on run argv` handler and never concatenated into the script source, because both fields are attacker-influenced text — a session title, a file path, a command.
+- [ ] Given a body containing `"`, `'`, `;`, `$(…)` or backticks, When the macOS send runs, Then it reaches `display notification` byte-for-byte as data and nothing is executed.
+- [ ] Given a machine has no notifier for its platform, When a notification is sent, Then the result is a failed delivery with a reason and no exception, and `lacode doctor` names the channel that would run — or reports that there is none — instead of reporting a binary that is not used there.
+- [ ] Given the CLI runs on macOS, When the send does not complete, Then it is still bounded by a timeout, exactly as on Linux.
+- [ ] Given the repository's own shell scripts, When each is classified, Then the doc says which side of the hop it runs on — `bin/oc` and `bin/oc-notify` on the remote host that runs opencode, `bin/oc-notify-receiver` and `bin/oc-sync` on the desktop — and says plainly why the desktop pair is Linux-only (a `notify-send` channel behind a systemd user unit), so a Mac user is not sent to debug an ssh script that was never meant to run on their machine.
+- [ ] Given a machine without GNU `timeout` or with bash older than 4.0, When `bin/oc-sync` runs, Then it refuses **before** touching anything, names each missing prerequisite, and names the `lacode` subcommand to use instead. It must never report a misleading cause: the host list is read with `mapfile`, so without it the run used to die at "no hosts configured" — a confident wrong answer that sends the reader to edit `.env`.
+- [ ] Given `bin/oc-notify-receiver` runs where `notify-send` does not exist, When it is invoked, Then it exits non-zero and names both the missing channel and the portable path, because its stderr reaches whoever opened the ssh connection and nobody else, and a bare "command not found" reads as a desktop that quietly stopped notifying.
+- [ ] Given the payload is parsed, When the receiver splits `$SSH_ORIGINAL_COMMAND`, Then it splits on newlines only using constructs that exist in bash 3.2 as well as bash 5, and the suite **proves the split by running the receiver** rather than by finding the word `mapfile` in the file. Under bash 3.2 — the version macOS ships — a bash-4-only builtin left every field at its default, so the popup said "LaCode" with an empty body and no error anywhere: the same silent blank notification the argv bug caused once, reached again through a different door.
+- [ ] Given the whole suite, When it runs on macOS, Then it passes there too. Checks that exercise the Linux-only shell scripts **skip** on a machine that cannot run them, each naming the specific missing prerequisite (a bash version below 4.0, an absent GNU `timeout`) rather than passing silently.
+- [ ] Given the local notification channel differs by platform, When a test asserts on the notifier's argv, Then it reads **every** channel's stub rather than only `notify-send`. A Mac picks `osascript` and never invokes `notify-send` at all, so a suite that stubbed only `notify-send` would pass on Linux, read an empty log on a Mac, and in the process invoke the runner's real `osascript` against a desktop session that is not there.
+
 ---
 
 ## Epic F — Adoption and safety
@@ -258,6 +276,12 @@ does not.
 - [ ] Given a fresh machine with no LaCode config, When the install runs, Then one config line is sufficient and no further manual step is required.
 - [ ] Given no configuration is present at all, When LaCode boots, Then it falls back to shipped defaults and still functions.
 - [ ] Given the plugin package is installed, When its peer dependency is unmet, Then the requirement is declared rather than silently duplicated inside the package.
+- [ ] Given the published manifest, When a plugin loader looks for an entry point, Then it finds one in both shapes a resolver may consult — a top-level `main` and `exports["./server"]` — while `exports["."]` keeps pointing at the same built plugin, and the documentation states plainly that these are forward-compatibility metadata and **not** a fix for opencode 1.18.35, where adding them to the installed copy was tested and the bare specifier still loaded nothing.
+- [ ] Given an opencode that does not load the bare specifier, When the reader follows the install documentation, Then the README offers a numbered procedure that holds **whichever version they run** — write the bare specifier and restart, verify with `opencode agent list`, and only if the agents are still missing while the package is installed, add a `file://` entry and restart — rather than instructions scoped to one build. Each step is justified by what the previous step showed, not by what the reader's version is known to do.
+- [ ] Given a version nobody has tested, When the reader checks the version table, Then **every** row other than the measured one is marked untested or unknown, the README claims no loading behaviour for any version it has not run, and it tells the reader to follow the procedure rather than to read the table as coverage of their build. The one row that does claim behaviour records the evidence behind it, and says that installing the package and then silently dropping it is what was measured.
+- [ ] Given any operating system, When the reader needs the package directory to build a `file://` entry, Then the path comes from `opencode debug paths` rather than a hardcoded root, and any literal path in the document is marked as an illustration of one platform's layout instead of a value to copy. Where a platform's cache root has not been established, the README says so rather than guessing it.
+- [ ] Given a macOS user, When they look for what works on their machine, Then the README documents macOS: the plugin runs there, notifications are delivered through `osascript` or `terminal-notifier`, paths still come from `opencode debug paths` with no asserted macOS cache root, and the remote-host and tunnel scripts are marked Linux-only rather than implied to run there.
+- [ ] Given a user whose cache holds an installed package, When the plugin's agents are nevertheless absent, Then the README distinguishes that from a failed install (an empty cache directory) and points at the loader workaround, so "installed" and "loaded" are never reported as the same fact.
 
 ### US-16: Merges, never clobbers
 **As a** user with an existing opencode config, **I want** LaCode to add its agents/commands only where absent and never overwrite my own definitions, **so that** installing it cannot break my setup.
@@ -378,6 +402,7 @@ table was filled in.
 | US-13 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/notify-test.mjs`, `tests/oc-test.mjs` |
 | US-14 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
 | US-18 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
+| US-26 | E | `tests/stories/e-remote-ssh.test.mjs`, `tests/oc-test.mjs` |
 | US-15 | F | `tests/stories/f-adoption-safety.test.mjs` |
 | US-16 | F | `tests/stories/f-adoption-safety.test.mjs` |
 | US-17 | F | `tests/stories/f-adoption-safety.test.mjs` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,10 @@
   "engines": {
     "node": ">=22.18"
   },
-"exports": {
+  "main": "./dist/index.js",
+  "exports": {
     ".": "./dist/index.js",
+    "./server": "./dist/index.js",
     "./pool": "./dist/pool.js",
     "./agents": "./dist/agents.js",
     "./commands": "./dist/commands.js",