@lawaty/lacode 0.2.2 → 0.4.0

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/pool.js

@@ -243,6 +243,7 @@ function state(opts = {}) {
       cooling: /* @__PURE__ */ new Map(),
       strikes: /* @__PURE__ */ new Map(),
       activity: /* @__PURE__ */ new Map(),
+      children: /* @__PURE__ */ new Map(),
       reaped: 0,
       reaping: false,
       lastSweep: 0,
@@ -284,7 +285,7 @@ function init(s, onWarn) {
 }
 function pruneOwn(s) {
   const now = Date.now();
-  for (const [key, claim] of s.own) if (now - claim.t > CLAIM_TTL_MS) s.own.delete(key);
+  for (const [key, claim] of s.own) if (now - (claim.hb ?? claim.t) > CLAIM_TTL_MS) s.own.delete(key);
 }
 function publish(s) {
   if (!s.dirReady) return;
@@ -349,7 +350,7 @@ function readSiblings(s) {
     try {
       const parsed = JSON.parse(readFileSync2(path, "utf8"));
       const claims = Object.values(parsed).filter(
-        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - c.t <= CLAIM_TTL_MS
+        (c) => c && typeof c.v === "string" && typeof c.m === "string" && now - (c.hb ?? c.t) <= CLAIM_TTL_MS
       );
       siblings.push({ id: match[1], claims });
     } catch {
@@ -463,26 +464,72 @@ function snapshot(s) {
 }
 var loadOf = (counts, model) => counts.get(model) ?? 0;
 var underCeiling = (slot, counts) => loadOf(counts, slot.model) < slot.weight;
-function pickSlot(s, snap) {
+function roundRobinSequence(slots) {
+  const seq = [];
+  for (const slot of slots) for (let turn = 0; turn < slot.weight; turn++) seq.push(slot.index);
+  return seq;
+}
+var CURSOR_FILE = "cursor.json";
+function readCursor(s) {
+  try {
+    const parsed = JSON.parse(readFileSync2(join2(s.dir, CURSOR_FILE), "utf8"));
+    if (typeof parsed.seq === "number" && Number.isInteger(parsed.seq) && parsed.seq >= 0) return parsed.seq;
+  } catch {
+  }
+  return 0;
+}
+function writeCursor(s, seq) {
+  if (!s.dirReady) return;
+  const path = join2(s.dir, CURSOR_FILE);
+  try {
+    writeFileSync(`${path}.tmp`, JSON.stringify({ seq }));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+  }
+}
+function pickSlot(s, snap, options) {
+  const advance = options?.advance !== false;
   const slots = s.slots.length > 0 ? s.slots : FALLBACK_SLOTS;
+  const seq = roundRobinSequence(slots);
+  if (seq.length > 0) {
+    const byIndex = new Map(slots.map((slot) => [slot.index, slot]));
+    const start = readCursor(s) % seq.length;
+    for (let step = 0; step < seq.length; step++) {
+      const at = (start + step) % seq.length;
+      const slot = byIndex.get(seq[at]);
+      if (slot && isAvailable(s, slot.model, snap.cooling) && underCeiling(slot, snap.counts)) {
+        if (advance) writeCursor(s, at + 1);
+        return slot;
+      }
+    }
+  }
   const usable = slots.filter((slot) => isAvailable(s, slot.model, snap.cooling));
   const pool = usable.length > 0 ? usable : slots;
-  const open = pool.filter((slot) => underCeiling(slot, snap.counts));
-  if (open.length > 0) return open.reduce((best, slot) => slot.weight > best.weight ? slot : best, open[0]);
   return pool.reduce((best, slot) => loadOf(snap.counts, slot.model) < loadOf(snap.counts, best.model) ? slot : best, pool[0]);
 }
 function agentFor(base, slot) {
   return `${base}-${slot}`;
 }
 function acquire(s, base, slot, ownerSession, key, target) {
-  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: Date.now(), s: ownerSession, g: target });
-  if (target) s.activity.set(target, Date.now());
+  const now = Date.now();
+  s.own.set(key, { v: base, k: slot.index, m: slot.model, t: now, hb: now, s: ownerSession, g: target });
+  if (target) s.activity.set(target, now);
   publish(s);
 }
 function release(s, key) {
   if (s.own.delete(key)) publish(s);
 }
+var CHILD_RING = 8;
+var CHILD_MEMORY_MS = 30 * 6e4;
+var CHILD_SLACK_MS = 1e3;
+function noteChild(s, parentID, childID) {
+  const ring = s.children.get(parentID) ?? [];
+  ring.push({ id: childID, t: Date.now() });
+  while (ring.length > CHILD_RING) ring.shift();
+  s.children.set(parentID, ring);
+}
 function bindChild(s, parentID, childID) {
+  noteChild(s, parentID, childID);
   const candidates = [...s.own.entries()].filter(([, c]) => c.s === parentID && !c.g).sort((a, b) => a[1].t - b[1].t);
   if (candidates.length === 0) return false;
   candidates[0][1].g = childID;
@@ -490,8 +537,29 @@ function bindChild(s, parentID, childID) {
   publish(s);
   return true;
 }
+function backfillChild(s, claim) {
+  if (claim.g || !claim.s) return false;
+  const now = Date.now();
+  const taken = new Set([...s.own.values()].map((c) => c.g).filter((g) => typeof g === "string"));
+  const ring = s.children.get(claim.s) ?? [];
+  for (let i = ring.length - 1; i >= 0; i--) {
+    const child = ring[i];
+    if (now - child.t > CHILD_MEMORY_MS) break;
+    if (child.t < claim.t - CHILD_SLACK_MS) continue;
+    if (taken.has(child.id)) continue;
+    claim.g = child.id;
+    s.activity.set(child.id, now);
+    publish(s);
+    return true;
+  }
+  return false;
+}
 function noteActivity(s, sessionID) {
-  s.activity.set(sessionID, Date.now());
+  const now = Date.now();
+  s.activity.set(sessionID, now);
+  let touched = false;
+  for (const claim of s.own.values()) if (claim.g === sessionID) claim.hb = now, touched = true;
+  if (touched) publish(s);
 }
 function idleFor(s, claim, now) {
   const target = claim.g;
@@ -555,6 +623,7 @@ export {
   USER_MODELS_TXT,
   acquire,
   agentFor,
+  backfillChild,
   bindChild,
   claimKey,
   coolProvider,
@@ -585,6 +654,7 @@ export {
   releaseStuck,
   resolveModels,
   retryAfterMs,
+  roundRobinSequence,
   selfFile,
   slotFor,
   snapshot,

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`