@lawaty/lacode 0.2.1 → 0.3.0

package/README.md

@@ -284,6 +284,7 @@ option is optional:
 | `modelsFile` | — | An explicit slot file; short-circuits the chain below. |
 | `reapMs` | `30000` | Hang-reaper interval. |
 | `selfUpdate` | `true` | Check for a newer release at most once per ~6h and install it in the background; it applies on the next opencode start. `false` — or `LACODE_NO_SELFUPDATE=1` — turns the check off. |
+| `sound` | `true` | Play a short tone with each notification, one per outcome, so you can tell a finished session from a question or a permission prompt without reading the popup. It is opt-out: `false` — or `LACODE_SOUND=0` (`false`, `off`, `no` work too, and beat the option) — turns the sound off, and anything else, a typo included, leaves it on. |
 | `omniroute` | — | Optional [OmniRoute](#configuring-omniroute) gateway integration. Absent or `{ enabled: false }` changes nothing. |
 
 ### Staying up to date
@@ -324,6 +325,29 @@ request across many providers with fallback and "combos". LaCode can register it
 as an opencode provider for you. It is **off by default**: if you do not set
 `omniroute.enabled: true`, nothing below happens and LaCode makes no request.
 
+**Setting it up on a client machine.** Four steps, in this order:
+
+1. Install OmniRoute, then make it stay up: run `omniroute autostart enable`
+   once. That writes a systemd user unit in a headless session, or an XDG
+   autostart entry in a graphical one, and OmniRoute supervises itself from
+   there on. Its gateway listens on `http://localhost:20128/v1`. The gateway's
+   lifecycle is **the client's responsibility**: LaCode never starts, supervises
+   or stops it, it only probes it. The gateway must therefore already be
+   running **before** you start opencode — one that is down at startup is
+   disabled for that run, and the integration is per-run.
+2. Add the plugin block to your opencode config:
+   `["@lawaty/lacode", { "omniroute": { "enabled": true, "apiKey": "<your omniroute key>", "combo": "auto", "models": [] } }]`
+3. Optionally, to route pooled work through it, make `omniroute/auto 3` the
+   **first** line of `~/.config/lacode/pool.txt`. `pool.txt` is optional user
+   config; the bundled default preset does **not** include OmniRoute.
+4. **Restart opencode.** Nothing here hot-reloads.
+
+With `models: []` and `combo: "auto"`, the plugin registers exactly one model,
+`omniroute/auto`, which then appears in the model picker for any agent — no
+hand-maintained model list.
+
+The full option set, for reference:
+
 ```jsonc
 {
   "plugin": [
@@ -357,7 +381,7 @@ as an opencode provider for you. It is **off by default**: if you do not set
 | `tiers` | — | `{ "primary": [...], "backup": [...] }` preference order over models the allowlist already permits. |
 | `stickyPerSession` | `true` | Keep a session on one model while that model is healthy. |
 | `healthCheck` | `true` | Probe `GET /models` at startup; a failed check disables the integration for that run only. |
-| `timeoutMs` | `5000` | Budget for LaCode's own calls to the gateway. |
+| `timeoutMs` | `5000` | Budget for LaCode's own probe and model-cache calls to the gateway. It is not written into the provider options, so it does not bound real traffic — opencode's own default applies there. |
 
 An enabled but invalid block (bad `baseURL`, a non-array `models`, …) is rejected
 as a whole: LaCode logs one warning naming the problem and continues exactly as
@@ -372,12 +396,14 @@ already have a `provider.omniroute` block, LaCode leaves it completely untouched
 and warns; it also never adds a `whitelist`. Because opencode loads
 `@ai-sdk/openai-compatible` itself, no extra dependency is installed.
 
-**Combo vs. allowlist.** Set `combo` and OmniRoute does the fallback for you (let
-it route). Without a combo, LaCode exposes the allowlist ordered by `tiers`
-(primary first), tracks a rolling latency and error rate per model, and skips a
-model while it is cooling after a transient failure — 429, 408 and 5xx, honouring
-`Retry-After` and otherwise using capped exponential backoff. Non-transient
-errors (400, 401, 403, 404) are surfaced to you, never failed over.
+**Combo vs. allowlist.** Set `combo` and OmniRoute does the fallback for you
+(let it route): the combo leads the exposed models, so opencode can hand a failed
+request to the gateway's own fallback chain. Without a combo, LaCode exposes the
+allowlist ordered by `tiers` (primary first). Candidate order is `filterModels`
+(combo first, then the hard allowlist) followed by `orderByTier`, and that is
+all — LaCode picks which model is exposed and in what order; it does not measure
+latency or error rate at runtime, and it does not skip a model because it
+failed.
 
 **Using OmniRoute in the pool.** The integration only *registers* the provider —
 it never touches your pool, and it does not place a slot for you. To route pooled
@@ -415,7 +441,9 @@ local instance with `REQUIRE_API_KEY=false`, the literal placeholder
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `omniroute health check failed` at startup | Gateway not running, wrong `baseURL`, or a startup race | Start OmniRoute on `http://localhost:20128` and restart opencode. The integration is disabled for that run only, not permanently. |
+| `omniroute health check failed` at startup | Gateway not running, wrong `baseURL`, or a startup race | Start OmniRoute on `http://localhost:20128` and restart opencode; `omniroute autostart enable` makes that durable across restarts. The integration is disabled for that run only, not permanently. |
+| `omniroute health check failed` at startup, then a repeating `cooling omniroute/<id> (hang)` and `Model not found` churn on one slot | OmniRoute was started *after* opencode, and `pool.txt` names an `omniroute/<id>` slot | The integration is off for that run, but the pool still routes to the slot: the request hangs, the reaper cools it for 600s, and the cycle repeats. Start OmniRoute, then restart opencode. |
+| `ProviderModelNotFoundError: Model not found` on an id the gateway serves | The id is a valid OmniRoute route but is not in the plugin's `models` allowlist, so the plugin never exposed it | Add the id to `models`, or use `combo: "auto"` with `omniroute/auto`. A valid gateway route is not automatically an exposed model. |
 | `no usable models` | The gateway returned an empty list, or every id was filtered out by `models` | `curl -H "Authorization: Bearer $OMNIROUTE_API_KEY" http://localhost:20128/v1/models` and check `models`/`combo` against the returned ids. |
 | `401` / `Invalid API key` | `REQUIRE_API_KEY=true` and the key is missing or wrong | Create a key in the dashboard, export `OMNIROUTE_API_KEY`, or set `REQUIRE_API_KEY=false` locally and use `sk_omniroute`. |
 | `404` on a URL containing `/v1/v1/` | A `baseURL` that already carried `/v1` was given twice | LaCode normalises this, so it should not come from LaCode; check a hand-written `provider.omniroute` block, which LaCode leaves untouched. |
@@ -531,6 +559,7 @@ are reading:
 /context-init      # build the map, or verify and refresh an existing one
 /context-update    # incremental refresh; accepts a focus, e.g. /context-update src/payments
 /context-review    # audit it for staleness, contradictions, duplication and bloat
+/lacode-doctor     # check the pool, model resolution and the OmniRoute gateway. Report only
 ```
 
 The map is local and untracked — it describes your checkout on your machine, so
@@ -617,7 +646,7 @@ open are in [docs/TUNNEL.md](docs/TUNNEL.md).
 
 ## User stories
 
-Twenty-three stories across seven epics, each written as a behavioural contract
+Twenty-nine stories across seven epics, each written as a behavioural contract
 with acceptance criteria a test can assert mechanically — the pains behind them,
 the Given/When/Then criteria, and the story-to-test mapping are in
 [docs/USER-STORIES.md](docs/USER-STORIES.md).

package/dist/commands.js

@@ -67,6 +67,36 @@ Audit the five context files for:
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
+  },
+  "lacode-doctor": {
+    description: "Check the LaCode setup \u2014 pool slots, model resolution, and the OmniRoute gateway. Report only; changes nothing.",
+    template: `Diagnose this machine's LaCode setup. Report only; change nothing.
+
+Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
+
+1. Pool status \u2014 call the \`pool_status\` tool. Report the slot list, each
+   slot's load against its weight ceiling, and which models are cooling.
+
+2. OmniRoute configured \u2014 inspect the \`@lawaty/lacode\` plugin options in the
+   user's opencode config for an \`omniroute\` block with \`enabled: true\`. If it
+   is absent or disabled, print the two OmniRoute checks below as "not
+   configured" and stop after the pool section.
+
+3. Gateway reachable \u2014 when omniroute is configured, request its model list
+   (\`GET <baseURL>/v1/models\`, default baseURL \`http://localhost:20128/v1\`)
+   and report reachable or not. On failure, say plainly: start OmniRoute BEFORE
+   opencode, then restart opencode \u2014 provider registration is per-run. To make
+   that durable, run \`omniroute autostart enable\` (OmniRoute's own autostart;
+   LaCode never starts the gateway itself).
+
+4. Slots resolve \u2014 for every pool slot whose provider is \`omniroute\`, confirm
+   the model id is one the gateway advertises AND is registered. The known
+   trap: an id that is a valid gateway route but is NOT in the plugin's
+   \`omniroute.models\` allowlist fails with
+   \`ProviderModelNotFoundError: Model not found\`; the fix is to add that id to
+   the \`models\` array, or use the always-registered \`auto\`.
+
+Change nothing. Print a final one-line summary of failures.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {

package/dist/index.js

@@ -1272,6 +1272,36 @@ Audit the five context files for:
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
+  },
+  "lacode-doctor": {
+    description: "Check the LaCode setup \u2014 pool slots, model resolution, and the OmniRoute gateway. Report only; changes nothing.",
+    template: `Diagnose this machine's LaCode setup. Report only; change nothing.
+
+Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
+
+1. Pool status \u2014 call the \`pool_status\` tool. Report the slot list, each
+   slot's load against its weight ceiling, and which models are cooling.
+
+2. OmniRoute configured \u2014 inspect the \`@lawaty/lacode\` plugin options in the
+   user's opencode config for an \`omniroute\` block with \`enabled: true\`. If it
+   is absent or disabled, print the two OmniRoute checks below as "not
+   configured" and stop after the pool section.
+
+3. Gateway reachable \u2014 when omniroute is configured, request its model list
+   (\`GET <baseURL>/v1/models\`, default baseURL \`http://localhost:20128/v1\`)
+   and report reachable or not. On failure, say plainly: start OmniRoute BEFORE
+   opencode, then restart opencode \u2014 provider registration is per-run. To make
+   that durable, run \`omniroute autostart enable\` (OmniRoute's own autostart;
+   LaCode never starts the gateway itself).
+
+4. Slots resolve \u2014 for every pool slot whose provider is \`omniroute\`, confirm
+   the model id is one the gateway advertises AND is registered. The known
+   trap: an id that is a valid gateway route but is NOT in the plugin's
+   \`omniroute.models\` allowlist fails with
+   \`ProviderModelNotFoundError: Model not found\`; the fix is to add that id to
+   the \`models\` array, or use the always-registered \`auto\`.
+
+Change nothing. Print a final one-line summary of failures.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {
@@ -1875,15 +1905,16 @@ var INTERNAL_TITLE_PREFIXES = [
   // it would announce the cartographer's own bookkeeping as a finished task.
   "context (auto"
 ];
+var NOTIFY_OUTCOMES = ["done", "question", "permission", "error"];
 var notifyMessage = (outcome, detail) => {
   if (outcome === "error") return detail ? `Failed \u2014 ${detail}` : "Failed";
   if (outcome === "question") return detail ? `Awaiting your response \u2014 ${detail}` : "Awaiting your response";
   if (outcome === "permission") return detail ? `Awaiting your permission \u2014 ${detail}` : "Awaiting your permission";
   return "Task finished, waiting for your review";
 };
-var helperArgv = (helper, title, message, urgency, icon) => {
+var helperArgv = (helper, title, message, urgency, icon, sound) => {
   const name = helper.split(/[\\/]/).pop() ?? "";
-  return name === "lacode" || name === "lacode.js" ? ["notify", title, message, urgency, icon] : [title, message, urgency, icon];
+  return name === "lacode" || name === "lacode.js" ? ["notify", title, message, urgency, icon, sound] : [title, message, urgency, icon, sound];
 };
 var safeStringify = (value) => {
   try {
@@ -2038,6 +2069,8 @@ var Notifier = class {
 // src/plugins/notify.ts
 var SERVICE3 = "notify";
 var COOLDOWN_MS2 = 5e3;
+var SOUND_ENV = "LACODE_SOUND";
+var SOUND_OFF_VALUES = ["0", "false", "off", "no"];
 var findHelper = () => {
   const home = process.env.HOME ?? "";
   const candidates = [
@@ -2051,7 +2084,10 @@ var findHelper = () => {
   for (const candidate of candidates) if (existsSync3(candidate)) return candidate;
   return void 0;
 };
-var notifyHooks = (async ({ client, directory }, _options, deps = {}) => {
+var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
+  const opts = options ?? {};
+  const soundEnv = (process.env[SOUND_ENV] ?? "").trim().toLowerCase();
+  const soundOn = !SOUND_OFF_VALUES.includes(soundEnv) && opts.sound !== false;
   const notifier = new Notifier(COOLDOWN_MS2);
   const active = /* @__PURE__ */ new Set();
   const titles = /* @__PURE__ */ new Map();
@@ -2064,7 +2100,7 @@ var notifyHooks = (async ({ client, directory }, _options, deps = {}) => {
     const info = await client.session.get({ path: { id: sessionID }, query: { directory } }).then((result) => result.data).catch(() => void 0);
     return info;
   };
-  const deliverViaHelper = (title, message, urgency) => new Promise((resolve3) => {
+  const deliverViaHelper = (title, message, urgency, sound) => new Promise((resolve3) => {
     const helper = findHelper();
     if (!helper) {
       if (!warnedHelper) {
@@ -2074,7 +2110,7 @@ var notifyHooks = (async ({ client, directory }, _options, deps = {}) => {
       resolve3({ ok: false, detail: "no oc-notify helper found" });
       return;
     }
-    const child = spawn(helper, helperArgv(helper, title, message, urgency, "utilities-terminal"), {
+    const child = spawn(helper, helperArgv(helper, title, message, urgency, "utilities-terminal", sound), {
       stdio: ["ignore", "ignore", "pipe"],
       detached: true
     });
@@ -2133,7 +2169,8 @@ var notifyHooks = (async ({ client, directory }, _options, deps = {}) => {
         return;
       }
       const message = isRemote ? `${decision.message} (remote)` : decision.message;
-      const sent = await deliver(decision.title, message, decision.urgency);
+      const sound = soundOn && NOTIFY_OUTCOMES.includes(outcome) ? outcome : "none";
+      const sent = await deliver(decision.title, message, decision.urgency, sound);
       void log(sent.ok ? "info" : "error", sent.ok ? "notified" : "notification failed", {
         sessionID,
         outcome,
@@ -2617,7 +2654,7 @@ var omniRouteHooks = async (input, options, deps = {}) => {
       });
       if (!healthy) {
         disabled = true;
-        await warnOnce(`omniroute health check failed at ${config.baseURL}; falling back to lacode's normal behaviour for this run`);
+        await warnOnce(`omniroute health check failed at ${config.baseURL}; falling back to lacode's normal behaviour for this run; pool slots naming omniroute/<id> will fail until the gateway is up`);
         return;
       }
     }
@@ -2667,8 +2704,7 @@ var omniRouteHooks = async (input, options, deps = {}) => {
         baseURL: config.baseURL,
         // Absent rather than blank: an empty bearer on a keyless gateway is a
         // 401 that looks like a configuration error.
-        ...config.apiKey ? { apiKey: config.apiKey } : {},
-        timeout: config.timeoutMs
+        ...config.apiKey ? { apiKey: config.apiKey } : {}
       },
       models
     };

package/dist/lacode.js

@@ -2,13 +2,36 @@
 
 // bin/lacode
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { existsSync, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
 import { spawnSync as spawnSync2 } from "node:child_process";
 
 // src/tunnel/index.ts
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join as join2 } from "node:path";
+
+// src/lib/package-root.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "@lawaty/lacode";
+var findPackageRoot = (start) => {
+  let dir = start;
+  for (let up = 0; up < 6; up++) {
+    try {
+      if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === PACKAGE_NAME) return dir;
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(start, "..", "..");
+};
+var PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+
+// src/tunnel/index.ts
 var ICONS = [
   "utilities-terminal",
   "dialog-information",
@@ -17,13 +40,20 @@ var ICONS = [
   "system-run",
   "emblem-default"
 ];
+var SOUNDS = [
+  "none",
+  "done",
+  "question",
+  "permission",
+  "error"
+];
 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"),
+    key: env.OC_NOTIFY_KEY ?? join2(homedir(), ".ssh", "lacode_notify"),
     connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
   };
 }
@@ -36,6 +66,9 @@ function normalizeUrgency(raw) {
 function normalizeIcon(raw) {
   return ICONS.includes(raw) ? raw : "utilities-terminal";
 }
+function normalizeSound(raw) {
+  return SOUNDS.includes(raw) ? raw : "none";
+}
 var safeText = (raw, fallback, max) => {
   const clean = raw.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
   if (!clean) return fallback;
@@ -45,19 +78,21 @@ 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);
+  const [title, message, urgency, icon, sound] = raw.split(FIELD_SEPARATOR);
   return {
     title: safeTitle(title),
     message: safeMessage(message),
     urgency: normalizeUrgency(urgency),
-    icon: normalizeIcon(icon)
+    icon: normalizeIcon(icon),
+    sound: normalizeSound(sound)
   };
 }
 var encodePayload = (request) => [
   safeTitle(request.title),
   safeMessage(request.message),
   normalizeUrgency(request.urgency),
-  normalizeIcon(request.icon)
+  normalizeIcon(request.icon),
+  normalizeSound(request.sound)
 ].join(FIELD_SEPARATOR);
 var SSH_OPTS = [
   "-o",
@@ -77,7 +112,7 @@ var CONTROL_OPTS = [
   "-o",
   "ControlPersist=300",
   "-o",
-  `ControlPath=${join(homedir(), ".ssh", "lacode-cm-%C")}`
+  `ControlPath=${join2(homedir(), ".ssh", "lacode-cm-%C")}`
 ];
 var run = (command2, args, timeout) => {
   try {
@@ -106,6 +141,22 @@ var CHANNEL_BINARY = {
   osascript: "osascript",
   "terminal-notifier": "terminal-notifier"
 };
+var SOUND_BINARY = {
+  afplay: "afplay",
+  paplay: "paplay",
+  aplay: "aplay",
+  "pw-play": "pw-play"
+};
+function soundChannel(platform = process.platform) {
+  if (platform === "darwin") {
+    if (have(SOUND_BINARY.afplay)) return "afplay";
+  } else {
+    for (const cmd of [SOUND_BINARY.paplay, SOUND_BINARY.aplay, SOUND_BINARY["pw-play"]]) {
+      if (have(cmd)) return cmd;
+    }
+  }
+  return "none";
+}
 var DARWIN_SCRIPT = [
   "on run argv",
   "  display notification (item 3 of argv) with title (item 2 of argv)",
@@ -125,8 +176,21 @@ var NO_CHANNEL = {
   darwin: "neither osascript nor terminal-notifier is installed"
 };
 function sendLocal(request, platform = process.platform) {
+  const sound = normalizeSound(request.sound);
+  const playSound = () => {
+    if (sound === "none") return;
+    const channel2 = soundChannel(platform);
+    if (channel2 === "none") return;
+    const path = join2(PACKAGE_ROOT, "sounds", `${sound}.wav`);
+    if (!existsSync(path)) return;
+    const child = spawn(channel2, [path], { detached: true, stdio: "ignore" });
+    child.on("error", () => {
+    });
+    child.unref();
+  };
   const channel = localChannel(platform);
   if (channel === "none") {
+    playSound();
     return { ok: false, detail: NO_CHANNEL[platform] ?? `no local notification channel on ${platform}`, transport: "local" };
   }
   const title = safeTitle(request.title);
@@ -136,6 +200,7 @@ function sendLocal(request, platform = process.platform) {
     [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
   );
   const result = run(CHANNEL_BINARY[channel], args, 5e3);
+  playSound();
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
 }
 function sendRemote(request, tunnel) {
@@ -189,28 +254,8 @@ function describe(env = process.env, platform = process.platform) {
   };
 }
 
-// src/lib/package-root.ts
-import { readFileSync } from "node:fs";
-import { dirname, join as join2 } from "node:path";
-import { fileURLToPath } from "node:url";
-var PACKAGE_NAME = "@lawaty/lacode";
-var findPackageRoot = (start) => {
-  let dir = start;
-  for (let up = 0; up < 6; up++) {
-    try {
-      if (JSON.parse(readFileSync(join2(dir, "package.json"), "utf8")).name === PACKAGE_NAME) return dir;
-    } catch {
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return join2(start, "..", "..");
-};
-var PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
-
 // src/lib/selfupdate.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import { closeSync, mkdirSync, openSync, readFileSync as readFileSync2, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname2, join as join3, resolve } from "node:path";
@@ -299,7 +344,7 @@ async function checkForUpdate(opts) {
 }
 async function refreshCache(opts) {
   const { cacheRoot, bin, latest } = opts;
-  const spawnImpl = opts.spawnImpl ?? spawn;
+  const spawnImpl = opts.spawnImpl ?? spawn2;
   const timeoutMs = opts.timeoutMs ?? INSTALL_TIMEOUT_MS;
   const fresh = join3(cacheRoot, "node_modules", "@lawaty", "lacode");
   const aside = `${cacheRoot}.stale-${Date.now()}`;
@@ -366,10 +411,13 @@ if (!process.features?.typescript) {
 }
 var USAGE = `lacode \u2014 portable notifications and remote exec for LaCode
 
-  lacode notify TITLE [MESSAGE] [URGENCY] [ICON]
+  lacode notify TITLE [MESSAGE] [URGENCY] [ICON] [SOUND]
       Send one desktop notification. Local host: straight to the desktop
       session. Over ssh: handed to the desktop through the reverse forward.
-      URGENCY is low | normal | critical. Fire-and-forget: always exits 0.
+      URGENCY is low | normal | critical. SOUND is none | done | question |
+      permission | error; an omitted or unrecognised SOUND is none, so a
+      four-argument caller simply gets no sound. Fire-and-forget: always
+      exits 0.
 
   lacode forward HOST -- COMMAND [ARG...]
       Run COMMAND on HOST over ssh. Exits with the remote's status.
@@ -400,13 +448,13 @@ switch (command) {
     process.exit(0);
     break;
   case "notify": {
-    const [rawTitle, message, urgency, icon] = argv;
+    const [rawTitle, message, urgency, icon, sound] = argv;
     if (!rawTitle) {
       console.error("lacode notify: TITLE is required");
       console.error(USAGE);
       process.exit(2);
     }
-    const result = notify({ title: rawTitle, message, urgency, icon });
+    const result = notify({ title: rawTitle, message, urgency, icon, sound: normalizeSound(sound) });
     if (!result.ok) console.error(`lacode: notification not delivered via ${result.transport}: ${result.detail ?? "unknown reason"}`);
     process.exit(0);
     break;
@@ -486,7 +534,7 @@ switch (command) {
     }
     const { user, host, key } = resolveTunnel();
     const pub = `${key}.pub`;
-    if (!existsSync(key)) {
+    if (!existsSync2(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.");
@@ -494,7 +542,7 @@ switch (command) {
       }
       console.log(`Generated ${key}`);
     }
-    const pubkey = existsSync(pub) ? readFileSync3(pub, "utf8").trim() : "(public key missing)";
+    const pubkey = existsSync2(pub) ? readFileSync3(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>"}`);

package/dist/tunnel.js

@@ -1,7 +1,30 @@
 // src/tunnel/index.ts
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join as join2 } from "node:path";
+
+// src/lib/package-root.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "@lawaty/lacode";
+var findPackageRoot = (start) => {
+  let dir = start;
+  for (let up = 0; up < 6; up++) {
+    try {
+      if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === PACKAGE_NAME) return dir;
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(start, "..", "..");
+};
+var PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+
+// src/tunnel/index.ts
 var ICONS = [
   "utilities-terminal",
   "dialog-information",
@@ -10,13 +33,20 @@ var ICONS = [
   "system-run",
   "emblem-default"
 ];
+var SOUNDS = [
+  "none",
+  "done",
+  "question",
+  "permission",
+  "error"
+];
 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"),
+    key: env.OC_NOTIFY_KEY ?? join2(homedir(), ".ssh", "lacode_notify"),
     connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
   };
 }
@@ -29,6 +59,9 @@ function normalizeUrgency(raw) {
 function normalizeIcon(raw) {
   return ICONS.includes(raw) ? raw : "utilities-terminal";
 }
+function normalizeSound(raw) {
+  return SOUNDS.includes(raw) ? raw : "none";
+}
 var safeText = (raw, fallback, max) => {
   const clean = raw.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
   if (!clean) return fallback;
@@ -38,19 +71,21 @@ 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);
+  const [title, message, urgency, icon, sound] = raw.split(FIELD_SEPARATOR);
   return {
     title: safeTitle(title),
     message: safeMessage(message),
     urgency: normalizeUrgency(urgency),
-    icon: normalizeIcon(icon)
+    icon: normalizeIcon(icon),
+    sound: normalizeSound(sound)
   };
 }
 var encodePayload = (request) => [
   safeTitle(request.title),
   safeMessage(request.message),
   normalizeUrgency(request.urgency),
-  normalizeIcon(request.icon)
+  normalizeIcon(request.icon),
+  normalizeSound(request.sound)
 ].join(FIELD_SEPARATOR);
 var SSH_OPTS = [
   "-o",
@@ -70,7 +105,7 @@ var CONTROL_OPTS = [
   "-o",
   "ControlPersist=300",
   "-o",
-  `ControlPath=${join(homedir(), ".ssh", "lacode-cm-%C")}`
+  `ControlPath=${join2(homedir(), ".ssh", "lacode-cm-%C")}`
 ];
 var run = (command, args, timeout) => {
   try {
@@ -99,6 +134,22 @@ var CHANNEL_BINARY = {
   osascript: "osascript",
   "terminal-notifier": "terminal-notifier"
 };
+var SOUND_BINARY = {
+  afplay: "afplay",
+  paplay: "paplay",
+  aplay: "aplay",
+  "pw-play": "pw-play"
+};
+function soundChannel(platform = process.platform) {
+  if (platform === "darwin") {
+    if (have(SOUND_BINARY.afplay)) return "afplay";
+  } else {
+    for (const cmd of [SOUND_BINARY.paplay, SOUND_BINARY.aplay, SOUND_BINARY["pw-play"]]) {
+      if (have(cmd)) return cmd;
+    }
+  }
+  return "none";
+}
 var DARWIN_SCRIPT = [
   "on run argv",
   "  display notification (item 3 of argv) with title (item 2 of argv)",
@@ -118,8 +169,21 @@ var NO_CHANNEL = {
   darwin: "neither osascript nor terminal-notifier is installed"
 };
 function sendLocal(request, platform = process.platform) {
+  const sound = normalizeSound(request.sound);
+  const playSound = () => {
+    if (sound === "none") return;
+    const channel2 = soundChannel(platform);
+    if (channel2 === "none") return;
+    const path = join2(PACKAGE_ROOT, "sounds", `${sound}.wav`);
+    if (!existsSync(path)) return;
+    const child = spawn(channel2, [path], { detached: true, stdio: "ignore" });
+    child.on("error", () => {
+    });
+    child.unref();
+  };
   const channel = localChannel(platform);
   if (channel === "none") {
+    playSound();
     return { ok: false, detail: NO_CHANNEL[platform] ?? `no local notification channel on ${platform}`, transport: "local" };
   }
   const title = safeTitle(request.title);
@@ -129,6 +193,7 @@ function sendLocal(request, platform = process.platform) {
     [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
   );
   const result = run(CHANNEL_BINARY[channel], args, 5e3);
+  playSound();
   return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
 }
 function sendRemote(request, tunnel) {
@@ -184,12 +249,14 @@ function describe(env = process.env, platform = process.platform) {
 export {
   FIELD_SEPARATOR,
   ICONS,
+  SOUNDS,
   describe,
   encodePayload,
   forward,
   isRemote,
   localChannel,
   normalizeIcon,
+  normalizeSound,
   normalizeUrgency,
   notify,
   parsePayload,
@@ -197,5 +264,6 @@ export {
   safeMessage,
   safeTitle,
   sendLocal,
-  sendRemote
+  sendRemote,
+  soundChannel
 };

package/docs/TUNNEL.md

@@ -14,7 +14,7 @@ gets it back.
   │      │           │ ───────────────────────► │  (authorized_keys      │
   │      ▼           │   ONE argument:          │   forced command)      │
   │ lacode notify    │   title\nmessage\n       │      │                 │
-  │                  │   urgency\nicon          │      ▼                 │
+  │                  │   urgency\nicon\nsound   │      ▼                 │
   │                  │                          │  notify-send /         │
   │                  │                          │  osascript             │
   └──────────────────┘                          └────────────────────────┘
@@ -27,21 +27,26 @@ 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
+**One argument, not five.** ssh concatenates everything after the host into a
 single command string, and a forced command starts with *no* positional
-parameters. A sender that passes four quoted arguments arrives as the single
-string `"a b c d"`; a receiver reading `$1..$4` sees four empty strings, falls
-back to four defaults, and pops up a blank notification. So the payload crosses
+parameters. A sender that passes five quoted arguments arrives as the single
+string `"a b c d e"`; a receiver reading `$1..$5` sees five empty strings, falls
+back to five defaults, and pops up a blank notification. So the payload crosses
 as one newline-delimited argument:
 
 ```
-title\nmessage\nurgency\nicon
+title\nmessage\nurgency\nicon\nsound
 ```
 
+Five fields, and only the last one is new: `sound` is `none`, `done`,
+`question`, `permission` or `error`. A sender that stops at `icon` simply
+leaves it empty, and an empty or unrecognised name is `none`, so a four-field
+payload is still a valid one.
+
 Newline is safe as the delimiter because both ends strip control characters from
-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.
+the free-text fields before assembling or reading it, and `urgency`, `icon` and
+`sound` come from whitelists. No field can contain the delimiter, so a message
+full of spaces, quotes or `*` survives intact.
 
 ## Setting it up
 
@@ -81,11 +86,15 @@ with `terminal-notifier` as the macOS fallback when `osascript` is missing.
 
 ```bash
 lacode notify "build finished" "4 files changed" normal dialog-information
-lacode notify "question" "which database should I use?" critical dialog-warning
+lacode notify "question" "which database should I use?" critical dialog-warning done
 lacode forward web-01 -- systemctl --user status something
 lacode doctor
 ```
 
+SOUND is optional and last: `none`, `done`, `question`, `permission` or `error`,
+one bundled tone per outcome. Leave it off and nothing plays; the line above
+without a fifth word is still correct.
+
 `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
@@ -109,6 +118,14 @@ 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).
 
+It plays the sound too, and that is not decoration. The notification is rendered
+on the desktop, so that is the only place a tone can be heard: the remote host
+runs the session and has no speakers. The name is validated against the sound
+whitelist at the same trust boundary as `urgency` and `icon`, and the receiver
+looks the file up in the package's own `sounds/` directory — the sender's word
+never becomes a path. `afplay` plays it on macOS, `paplay`, `aplay` or
+`pw-play` on Linux, and a machine with none of them still gets the notification.
+
 ## Configuration
 
 | Variable | Default | Meaning |
@@ -124,6 +141,16 @@ the local channel directly rather than `notify()` (which would loop back).
 account frequently returns `root`, and a dbus path built from that reaches
 nobody's desktop. Guessing the desktop user is worse than failing.
 
+`LACODE_SOUND` is deliberately absent from that table, and not by oversight:
+every `OC_*` name above is read by the hop — either by `lacode notify` or by the
+ssh call it makes — and `lacode tunnel setup` prints what it exports. Sound is
+not that. It is a plugin-level mute switch read by the process running opencode
+(`sound: false` is the same switch in the config), so listing it here would send
+you to export a variable into a hop environment where nothing looks at it. It is
+documented with the other plugin options in the README. Set it to `0`, `false`,
+`off` or `no` to silence notifications; anything else — a typo included — leaves
+sound on, because a misspelt variable must not be how you turn a feature off.
+
 ## Legacy: the reverse forward
 
 The original design opened a reverse forward (`ssh -R`) held by a `systemd --user`

package/docs/USER-STORIES.md

@@ -222,6 +222,18 @@ does not.
 - [ ] Given the plugin observes a permission prompt, When it handles the event, Then it is a read-only observer: the payload is not mutated and no `permission.ask` hook is registered, because that hook's `output.status` is the permission decision itself.
 - [ ] Given a `permission` notification is raised, When it is evaluated against the cooldown, Then it bypasses it, since an unannounced block is the failure this story exists to remove.
 
+### US-29: Notification sounds distinguish outcomes and can be switched off
+**As a** user running many parallel sessions, **I want** each notification to arrive with its own sound, **so that** I can tell a finished session from a question or a permission prompt without looking at the popup.
+
+**Story ID(s) for tests:** US-29
+**Acceptance criteria:**
+- [ ] Given any of the four outcomes, When its notification is delivered, Then it carries that outcome's own sound name — `done`, `question`, `permission` or `error` — and no two share one, so the four are distinguishable by ear alone.
+- [ ] Given a notification raised on a remote host, When it reaches the desktop, Then the sound plays where the notification is delivered and never on the opencode host, because a headless host has no speakers for you to hear.
+- [ ] Given no sound player is installed, or the player cannot start, When the notification is delivered, Then the notification is delivered unchanged and only the sound is skipped, because a missing audio tool must never cost you the alert itself.
+- [ ] Given a machine with no notification channel at all, When a notification is raised, Then its sound still plays, because on such a desktop the tone is the only alert there is.
+- [ ] Given the plugin option `sound` is `false`, or `LACODE_SOUND` is `0`, `false`, `off` or `no`, When a notification is delivered, Then its sound is `none`; when both are set the environment wins over the option, and any other value — a typo included — leaves sound on, because a misspelt variable must not be how you get silence.
+- [ ] Given a sound name that is not one of `none`, `done`, `question`, `permission` or `error`, When it arrives, Then it is treated as `none` and never becomes a path or a command, because the hop carries data only (see US-18).
+
 ---
 
 ## Epic E — Remote hosts over SSH
@@ -431,6 +443,7 @@ table was filled in.
 | US-11 | D | `tests/stories/d-notifications.test.mjs`, `tests/notify-test.mjs` |
 | US-12 | D | `tests/stories/d-notifications.test.mjs`, `tests/notify-test.mjs` |
 | US-25 | D | `tests/stories/d-notifications.test.mjs` |
+| US-29 | D | `tests/stories/d-notifications.test.mjs` |
 | 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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
   "files": [
     "dist",
     "presets",
+    "sounds",
     "LICENSE",
     "README.md",
     "docs"