@lawaty/lacode 0.2.2 → 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
@@ -645,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/index.js

@@ -1905,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 {
@@ -2068,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 = [
@@ -2081,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();
@@ -2094,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) {
@@ -2104,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
     });
@@ -2163,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,

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.2",
+  "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"