@lawaty/lacode 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -8,6 +8,72 @@ Versions come from git release commits; the npm version is bumped in the same
 commit as the changelog entry it describes.
 ## [Unreleased]
 
+## [0.10.0] — a notification waits for you instead of timing out, and a permission can be answered from the popup
+
+### Added
+
+- **A permission prompt can be answered from the notification itself.** The
+  plugin reads the permission request id off opencode's `permission.asked`
+  event and puts it in the helper's environment (`LACODE_REQUEST_ID`), so the
+  notification carries three buttons: **Allow once**, **Always allow** and
+  **Deny**. Their names are opencode's own reply values — `once`, `always` and
+  `reject` ("reject" is the server's word for deny) — so a click is already a
+  valid answer and nothing has to be translated on the way.
+
+  The answer travels back over the same path the notification came. The desktop
+  end is an ssh forced command, so its stdout comes back down the ssh
+  connection and the plugin reads the chosen button's name off the helper's
+  stdout — no new key, no listener, no HTTP server. The hop was one-way until
+  now, and what made it two-way was a channel that was already there: the
+  forced command's stdout is carried to whoever opened the connection, so the
+  answer rides home on the connection that is already open. The plugin then
+  answers the permission through opencode's own API, and a permission that was
+  already answered in the terminal is recognised rather than reported as a
+  failure.
+
+  The wire payload is six newline-delimited fields on both wires —
+  `title\nmessage\nurgency\nicon\nsound\nrequestID`, the request id last — and a
+  payload with fewer than six fields carries no request id, so an older sender
+  still works.
+
+  Two limits, stated plainly. The scope is **permissions only**: a question is
+  not answerable this way, because opencode's v1 SDK client — the one this
+  plugin has — has no question API at all, and the v2 routes need a bound TCP
+  socket that the default opencode TUI does not have. And the buttons are
+  **Linux only**: `osascript` and `terminal-notifier` have no action support,
+  so a macOS desktop still gets a plain notice, and the answer there still has
+  to be given in the terminal.
+
+### Changed
+
+- **A desktop notification now waits for you instead of timing out on its own.**
+  `notify-send` is called with `--expire-time=0` — the freedesktop "never
+  expire" timeout — at all three call sites: `sendLocal` in
+  `src/tunnel/index.ts`, the tunnel's forced command
+  (`bin/oc-notify-receiver`), and `send_notify` in `bin/oc`. Without it the
+  desktop daemon's own timer dismissed the popup by itself: measured on KDE
+  Plasma 6.7.4, a normal-urgency notification is closed with reason 1
+  ("expired") after about five seconds, so a notice the user had not acted on
+  within that window was simply gone — the difference between a notice you can
+  still act on and one you missed. A notification now stays on the desktop
+  until you close it.
+
+  Nothing else about it changed: the `--urgency` values are untouched (a
+  question or a permission prompt is deliberately not `critical`, so it does
+  not escalate to a modal on most desktops), and the whitelists and the
+  cooldown behaviour are exactly as they were.
+
+### Documented
+
+- **The npm publish notice does not say which dist-tag a release lands on.** npm
+  12 prints "Publishing to https://registry.npmjs.org/ with tag latest" for every
+  publish, including one whose `publishConfig.tag` sends it to `beta`: the
+  message reports the CLI's default, not the resolved tag. 0.9.0 was published
+  that way and landed on `beta`, with `latest` still at 0.4.2. The registry is
+  the authority, not the notice — after publishing, read
+  `npm view @lawaty/lacode dist-tags` before assuming anything about where the
+  release went.
+
 ## [0.9.0] — the cartographer keeps an active backlog, and the model stops naming slot variants
 
 ### Added
@@ -464,7 +530,8 @@ experimental; `latest` remains 0.4.2.
 
 - First published release: pooled subagents over a shared set of models.
 
-[Unreleased]: https://github.com/lawaty/lacode/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/lawaty/lacode/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/lawaty/lacode/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/lawaty/lacode/compare/v0.7.1...v0.8.0
 [0.7.1]: https://github.com/lawaty/lacode/compare/v0.7.0...v0.7.1

package/README.md

@@ -346,9 +346,11 @@ lacode doctor                                        # what the environment reso
 ```
 
 `lacode notify` is fire-and-forget and always exits 0 — an unreachable desktop
-must never be able to fail the process that tried to notify you. `lacode forward
-HOST -- COMMAND` runs a command on another host over ssh and exits with its
-status.
+must never be able to fail the process that tried to notify you. The one
+exception is an actionable notification — one carrying a permission request id
+— which waits for the click, because the answer is the whole point of it.
+`lacode forward HOST -- COMMAND` runs a command on another host over ssh and
+exits with its status.
 
 The full CLI is `notify`, `forward`, `doctor`, `version`, `update`, `receive`
 and `tunnel setup`. `version` reports which copy of LaCode is running — and

package/dist/index.js

@@ -2832,6 +2832,8 @@ var helperArgv = (helper, title, message, urgency, icon, sound) => {
   const name = helper.split(/[\\/]/).pop() ?? "";
   return name === "lacode" || name === "lacode.js" ? ["notify", title, message, urgency, icon, sound] : [title, message, urgency, icon, sound];
 };
+var PERMISSION_REPLIES = ["once", "always", "reject"];
+var REQUEST_ID_ENV = "LACODE_REQUEST_ID";
 var safeStringify = (value) => {
   try {
     return JSON.stringify(value) ?? void 0;
@@ -2901,12 +2903,16 @@ var shouldNotify = (input) => {
   if (outcome === "done" && input.awaitingResponse) {
     return { notify: false, reason: "awaiting your response" };
   }
-  return {
+  const notification = {
     notify: true,
     title: `opencode \u2014 ${title}`,
     message: notifyMessage(outcome, detail),
     urgency: outcome === "error" ? "critical" : "normal"
   };
+  if (outcome === "permission" && input.requestID) {
+    return { ...notification, actionable: { requestID: input.requestID } };
+  }
+  return notification;
 };
 var questionHeadline = (questions) => {
   const first = questions?.find((entry) => typeof entry?.question === "string" && entry.question.trim());
@@ -2987,6 +2993,7 @@ var SERVICE3 = "notify";
 var COOLDOWN_MS2 = 5e3;
 var MAX_INFLIGHT_HELPERS = 4;
 var HELPER_TIMEOUT_MS = 3e4;
+var ACTION_TIMEOUT_MS = 10 * 6e4 + 3e4;
 var MAX_TRACKED_SESSIONS = 500;
 var SOUND_ENV = "LACODE_SOUND";
 var SOUND_OFF_VALUES = ["0", "false", "off", "no"];
@@ -3026,11 +3033,50 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
   };
   const log = (level, message, extra) => client.app.log({ body: { service: SERVICE3, level, message, extra } }).catch(() => {
   });
+  const answerPermission = async (sessionID, requestID, action) => {
+    const response = PERMISSION_REPLIES.find((candidate) => candidate === action);
+    if (!response) {
+      void log("warn", `notification action ignored: ${JSON.stringify(action)} is not a permission reply`, {
+        sessionID,
+        requestID
+      });
+      return;
+    }
+    const errorStatus = (error) => {
+      const candidate = error;
+      const status2 = candidate?.response?.status ?? candidate?.cause?.status ?? candidate?.status;
+      return typeof status2 === "number" ? status2 : void 0;
+    };
+    const reply = await client.postSessionIdPermissionsPermissionId({
+      path: { id: sessionID, permissionID: requestID },
+      body: { response }
+    }).then((result) => ({ result })).catch((error) => ({ error }));
+    const status = "result" in reply ? reply.result.response?.status : errorStatus(reply.error);
+    if (status === 404) {
+      void log("debug", "permission already answered", { sessionID, requestID });
+      return;
+    }
+    if ("error" in reply) {
+      void log("warn", `permission reply failed: ${errorDetail(reply.error) ?? String(reply.error)}`, {
+        sessionID,
+        requestID
+      });
+      return;
+    }
+    if (reply.result.error) {
+      void log("warn", `permission reply failed: ${errorDetail(reply.result.error) ?? String(reply.result.error)}`, {
+        sessionID,
+        requestID
+      });
+      return;
+    }
+    void log("info", "permission answered from the notification", { sessionID, requestID, response });
+  };
   const fetchInfo = async (sessionID) => {
     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, sound) => new Promise((resolve3) => {
+  const deliverViaHelper = (title, message, urgency, sound, requestID) => new Promise((resolve3) => {
     if (inflight >= maxInflight) {
       void log("warn", `notification dropped: ${inflight} helpers already in flight`, { title });
       resolve3({ ok: false, detail: `too many notification helpers in flight (${inflight})` });
@@ -3045,7 +3091,13 @@ 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", sound), {
+    const actionable = Boolean(requestID);
+    const timeoutMs = actionable ? ACTION_TIMEOUT_MS : helperTimeoutMs;
+    const child = actionable ? spawn(helper, helperArgv(helper, title, message, urgency, "utilities-terminal", sound), {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+      env: { ...process.env, [REQUEST_ID_ENV]: requestID }
+    }) : spawn(helper, helperArgv(helper, title, message, urgency, "utilities-terminal", sound), {
       stdio: ["ignore", "ignore", "pipe"],
       detached: true
     });
@@ -3064,11 +3116,15 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
         child.kill("SIGKILL");
       } catch {
       }
-      void log("warn", `notification helper timed out after ${helperTimeoutMs}ms`, { title });
-      finish({ ok: false, detail: `helper timed out after ${helperTimeoutMs}ms` });
-    }, helperTimeoutMs);
+      void log("warn", `notification helper timed out after ${timeoutMs}ms`, { title });
+      finish({ ok: false, detail: `helper timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
     timer.unref?.();
+    let stdout = "";
     let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < 400) stdout += String(chunk);
+    });
     child.stderr?.on("data", (chunk) => {
       if (stderr.length < 400) stderr += String(chunk);
     });
@@ -3085,12 +3141,13 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
           message
         });
       }
-      finish({ ok, detail: noise || void 0 });
+      const action = actionable ? stdout.trim() : "";
+      finish({ ok, detail: noise || void 0, ...action ? { action } : {} });
     });
-    child.unref();
+    if (!actionable) child.unref();
   });
   const deliver = deps.deliver ?? deliverViaHelper;
-  const announce = async (sessionID, outcome, detail) => {
+  const announce = async (sessionID, outcome, detail, requestID) => {
     try {
       const info = await fetchInfo(sessionID);
       if (!info) {
@@ -3106,7 +3163,8 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
         sawMessage: active.has(sessionID),
         // Either kind of block suppresses the idle event's "finished": a session
         // parked on a permission prompt has not finished, it is waiting.
-        awaitingResponse: pending.has(sessionID) || permissions.has(sessionID)
+        awaitingResponse: pending.has(sessionID) || permissions.has(sessionID),
+        requestID
       });
       if (!decision.notify) {
         void log("debug", `suppressed: ${decision.reason}`, { sessionID });
@@ -3124,8 +3182,10 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
       }
       const message = isRemote ? `${decision.message} (remote)` : decision.message;
       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", {
+      const sent = await deliver(decision.title, message, decision.urgency, sound, requestID);
+      if (sent.action && requestID) await answerPermission(sessionID, requestID, sent.action);
+      const answered = Boolean(sent.action);
+      void log(answered || sent.ok ? "info" : "error", answered ? "permission answered from the notification" : sent.ok ? "notified" : "notification failed", {
         sessionID,
         outcome,
         title: decision.title,
@@ -3169,7 +3229,8 @@ var notifyHooks = (async ({ client, directory }, options, deps = {}) => {
           if (!sessionID2) return;
           permissions.add(sessionID2);
           rememberActive(sessionID2);
-          void announce(sessionID2, "permission", permissionHeadline(properties) || void 0);
+          const requestID = typeof properties?.id === "string" && properties.id ? properties.id : void 0;
+          void announce(sessionID2, "permission", permissionHeadline(properties) || void 0, requestID);
           return;
         }
         if (event.type === "permission.replied") {

package/dist/lacode.js

@@ -76,15 +76,21 @@ var safeText = (raw, fallback, max) => {
 };
 var safeTitle = (raw) => safeText(raw ?? "", "LaCode", 120);
 var safeMessage = (raw) => safeText(raw ?? "", "", 400);
+var safeRequestId = (raw) => {
+  const clean = (raw ?? "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  if (!clean) return void 0;
+  return clean.length > 128 ? clean.slice(0, 128) : clean;
+};
 var FIELD_SEPARATOR = "\n";
 function parsePayload(raw) {
-  const [title, message, urgency, icon, sound] = raw.split(FIELD_SEPARATOR);
+  const [title, message, urgency, icon, sound, requestID] = raw.split(FIELD_SEPARATOR);
   return {
     title: safeTitle(title),
     message: safeMessage(message),
     urgency: normalizeUrgency(urgency),
     icon: normalizeIcon(icon),
-    sound: normalizeSound(sound)
+    sound: normalizeSound(sound),
+    requestID: safeRequestId(requestID)
   };
 }
 var encodePayload = (request) => [
@@ -92,7 +98,10 @@ var encodePayload = (request) => [
   safeMessage(request.message),
   normalizeUrgency(request.urgency),
   normalizeIcon(request.icon),
-  normalizeSound(request.sound)
+  normalizeSound(request.sound),
+  // The sixth field, empty when there is no request id: an absent id and an
+  // empty one mean the same thing, and the field count never changes.
+  safeRequestId(request.requestID) ?? ""
 ].join(FIELD_SEPARATOR);
 var SSH_OPTS = [
   "-o",
@@ -175,6 +184,13 @@ var NO_CHANNEL = {
   linux: "notify-send is not installed",
   darwin: "neither osascript nor terminal-notifier is installed"
 };
+var NEVER_EXPIRE_FLAG = "--expire-time=0";
+var NOTIFICATION_ACTIONS = [
+  ["once", "Allow once"],
+  ["always", "Always allow"],
+  ["reject", "Deny"]
+];
+var ACTION_WAIT_MS = 10 * 6e4;
 function sendLocal(request, platform = process.platform) {
   const sound = normalizeSound(request.sound);
   const playSound = () => {
@@ -195,35 +211,66 @@ function sendLocal(request, platform = process.platform) {
   }
   const title = safeTitle(request.title);
   const body = safeMessage(request.message);
+  const requestID = safeRequestId(request.requestID);
+  const actionable = channel === "notify-send" && requestID !== void 0;
+  const actionArgs = actionable ? NOTIFICATION_ACTIONS.map(([name, label]) => `--action=${name}=${label}`) : [];
   const args = channel === "osascript" ? ["-e", DARWIN_SCRIPT, DARWIN_ARGV_MARKER, title, body] : channel === "terminal-notifier" ? ["-title", title, "-message", body, "-appName", "LaCode", "-priority", normalizeUrgency(request.urgency)] : (
-    // Byte-identical to the notify-send call this package has always made.
-    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
+    // Never auto-dismissed: the notification waits for the user to close it.
+    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`, NEVER_EXPIRE_FLAG, ...actionArgs]
   );
-  const result = run(CHANNEL_BINARY[channel], args, 5e3);
+  const result = run(CHANNEL_BINARY[channel], args, actionable ? ACTION_WAIT_MS : 5e3);
   playSound();
-  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
+  const action = actionable ? result.stdout.trim() : "";
+  return {
+    ok: result.ok,
+    detail: result.ok ? void 0 : result.stderr || result.detail,
+    transport: "local",
+    ...action ? { action } : {}
+  };
 }
 function sendRemote(request, tunnel) {
   if (!tunnel.user) return { ok: false, detail: "OC_LOCAL_USER is unset; the desktop user for the tunnel is unknown", transport: "remote" };
   const connect = ["-o", `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`];
+  const actionable = safeRequestId(request.requestID) !== void 0;
+  const timeoutMs = actionable ? Math.max(tunnel.connectTimeoutMs + 2e3, ACTION_WAIT_MS + 2e3) : tunnel.connectTimeoutMs + 2e3;
+  const deliver = (args) => {
+    const result = run("ssh", args, timeoutMs);
+    const action = actionable ? result.stdout.trim() : "";
+    return {
+      ok: result.ok,
+      detail: result.ok ? void 0 : result.stderr || result.detail,
+      transport: "remote",
+      ...action ? { action } : {}
+    };
+  };
   if (tunnel.host) {
-    const result2 = run(
-      "ssh",
-      [...SSH_OPTS, ...CONTROL_OPTS, ...connect, "-i", tunnel.key, `${tunnel.user}@${tunnel.host}`, "--", encodePayload(request)],
-      tunnel.connectTimeoutMs + 2e3
-    );
-    return { ok: result2.ok, detail: result2.ok ? void 0 : result2.stderr || result2.detail, transport: "remote" };
-  }
-  const result = run(
-    "ssh",
-    [...SSH_OPTS, ...connect, "-i", tunnel.key, "-p", String(tunnel.port), `${tunnel.user}@localhost`, "--", encodePayload(request)],
-    tunnel.connectTimeoutMs + 2e3
-  );
-  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "remote" };
+    return deliver([
+      ...SSH_OPTS,
+      ...CONTROL_OPTS,
+      ...connect,
+      "-i",
+      tunnel.key,
+      `${tunnel.user}@${tunnel.host}`,
+      "--",
+      encodePayload(request)
+    ]);
+  }
+  return deliver([
+    ...SSH_OPTS,
+    ...connect,
+    "-i",
+    tunnel.key,
+    "-p",
+    String(tunnel.port),
+    `${tunnel.user}@localhost`,
+    "--",
+    encodePayload(request)
+  ]);
 }
 function notify(request, env = process.env, platform = process.platform) {
   try {
-    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
+    const result = isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
+    return result.action ? { ...result, action: result.action } : result;
   } catch (error) {
     return { ok: false, detail: String(error), transport: "none" };
   }
@@ -639,6 +686,8 @@ var USAGE = `lacode \u2014 portable notifications and remote exec for LaCode
       permission | error; an omitted or unrecognised SOUND is none, so a
       four-argument caller simply gets no sound. Fire-and-forget: always
       exits 0.
+      With LACODE_REQUEST_ID set, the notification carries buttons and the
+      name of the clicked one is printed on stdout.
 
   lacode forward HOST -- COMMAND [ARG...]
       Run COMMAND on HOST over ssh. Exits with the remote's status.
@@ -666,7 +715,9 @@ Environment:
   OC_LOCAL_USER        desktop user the tunnel authenticates as
   OC_TUNNEL_PORT       reverse-forward listener port (default 10022)
   OC_NOTIFY_KEY        dedicated key (default ~/.ssh/lacode_notify)
-  OC_CONNECT_TIMEOUT_MS / OC_SSH_TIMEOUT_MS`;
+  OC_CONNECT_TIMEOUT_MS / OC_SSH_TIMEOUT_MS
+  LACODE_REQUEST_ID    makes a notification actionable: it carries buttons, and
+                        the clicked one is printed on stdout`;
 var argv = process.argv.slice(2);
 var command = argv.shift();
 switch (command) {
@@ -684,8 +735,16 @@ switch (command) {
       console.error(USAGE);
       process.exit(2);
     }
-    const result = notify({ title: rawTitle, message, urgency, icon, sound: normalizeSound(sound) });
+    const result = notify({
+      title: rawTitle,
+      message,
+      urgency,
+      icon,
+      sound: normalizeSound(sound),
+      requestID: process.env.LACODE_REQUEST_ID
+    });
     if (!result.ok) console.error(`lacode: notification not delivered via ${result.transport}: ${result.detail ?? "unknown reason"}`);
+    if (result.action) console.log(result.action);
     process.exit(0);
     break;
   }
@@ -765,6 +824,7 @@ ${report.note}`);
     const request = parsePayload(process.env.SSH_ORIGINAL_COMMAND ?? "");
     const result = sendLocal(request);
     if (!result.ok) console.error(`lacode receive: ${result.detail ?? "not delivered"}`);
+    if (result.action) console.log(result.action);
     process.exit(result.ok ? 0 : 1);
     break;
   }

package/dist/tunnel.js

@@ -69,15 +69,21 @@ var safeText = (raw, fallback, max) => {
 };
 var safeTitle = (raw) => safeText(raw ?? "", "LaCode", 120);
 var safeMessage = (raw) => safeText(raw ?? "", "", 400);
+var safeRequestId = (raw) => {
+  const clean = (raw ?? "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  if (!clean) return void 0;
+  return clean.length > 128 ? clean.slice(0, 128) : clean;
+};
 var FIELD_SEPARATOR = "\n";
 function parsePayload(raw) {
-  const [title, message, urgency, icon, sound] = raw.split(FIELD_SEPARATOR);
+  const [title, message, urgency, icon, sound, requestID] = raw.split(FIELD_SEPARATOR);
   return {
     title: safeTitle(title),
     message: safeMessage(message),
     urgency: normalizeUrgency(urgency),
     icon: normalizeIcon(icon),
-    sound: normalizeSound(sound)
+    sound: normalizeSound(sound),
+    requestID: safeRequestId(requestID)
   };
 }
 var encodePayload = (request) => [
@@ -85,7 +91,10 @@ var encodePayload = (request) => [
   safeMessage(request.message),
   normalizeUrgency(request.urgency),
   normalizeIcon(request.icon),
-  normalizeSound(request.sound)
+  normalizeSound(request.sound),
+  // The sixth field, empty when there is no request id: an absent id and an
+  // empty one mean the same thing, and the field count never changes.
+  safeRequestId(request.requestID) ?? ""
 ].join(FIELD_SEPARATOR);
 var SSH_OPTS = [
   "-o",
@@ -168,6 +177,13 @@ var NO_CHANNEL = {
   linux: "notify-send is not installed",
   darwin: "neither osascript nor terminal-notifier is installed"
 };
+var NEVER_EXPIRE_FLAG = "--expire-time=0";
+var NOTIFICATION_ACTIONS = [
+  ["once", "Allow once"],
+  ["always", "Always allow"],
+  ["reject", "Deny"]
+];
+var ACTION_WAIT_MS = 10 * 6e4;
 function sendLocal(request, platform = process.platform) {
   const sound = normalizeSound(request.sound);
   const playSound = () => {
@@ -188,35 +204,66 @@ function sendLocal(request, platform = process.platform) {
   }
   const title = safeTitle(request.title);
   const body = safeMessage(request.message);
+  const requestID = safeRequestId(request.requestID);
+  const actionable = channel === "notify-send" && requestID !== void 0;
+  const actionArgs = actionable ? NOTIFICATION_ACTIONS.map(([name, label]) => `--action=${name}=${label}`) : [];
   const args = channel === "osascript" ? ["-e", DARWIN_SCRIPT, DARWIN_ARGV_MARKER, title, body] : channel === "terminal-notifier" ? ["-title", title, "-message", body, "-appName", "LaCode", "-priority", normalizeUrgency(request.urgency)] : (
-    // Byte-identical to the notify-send call this package has always made.
-    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`]
+    // Never auto-dismissed: the notification waits for the user to close it.
+    [title, body, `--urgency=${normalizeUrgency(request.urgency)}`, `--icon=${normalizeIcon(request.icon)}`, NEVER_EXPIRE_FLAG, ...actionArgs]
   );
-  const result = run(CHANNEL_BINARY[channel], args, 5e3);
+  const result = run(CHANNEL_BINARY[channel], args, actionable ? ACTION_WAIT_MS : 5e3);
   playSound();
-  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
+  const action = actionable ? result.stdout.trim() : "";
+  return {
+    ok: result.ok,
+    detail: result.ok ? void 0 : result.stderr || result.detail,
+    transport: "local",
+    ...action ? { action } : {}
+  };
 }
 function sendRemote(request, tunnel) {
   if (!tunnel.user) return { ok: false, detail: "OC_LOCAL_USER is unset; the desktop user for the tunnel is unknown", transport: "remote" };
   const connect = ["-o", `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`];
+  const actionable = safeRequestId(request.requestID) !== void 0;
+  const timeoutMs = actionable ? Math.max(tunnel.connectTimeoutMs + 2e3, ACTION_WAIT_MS + 2e3) : tunnel.connectTimeoutMs + 2e3;
+  const deliver = (args) => {
+    const result = run("ssh", args, timeoutMs);
+    const action = actionable ? result.stdout.trim() : "";
+    return {
+      ok: result.ok,
+      detail: result.ok ? void 0 : result.stderr || result.detail,
+      transport: "remote",
+      ...action ? { action } : {}
+    };
+  };
   if (tunnel.host) {
-    const result2 = run(
-      "ssh",
-      [...SSH_OPTS, ...CONTROL_OPTS, ...connect, "-i", tunnel.key, `${tunnel.user}@${tunnel.host}`, "--", encodePayload(request)],
-      tunnel.connectTimeoutMs + 2e3
-    );
-    return { ok: result2.ok, detail: result2.ok ? void 0 : result2.stderr || result2.detail, transport: "remote" };
+    return deliver([
+      ...SSH_OPTS,
+      ...CONTROL_OPTS,
+      ...connect,
+      "-i",
+      tunnel.key,
+      `${tunnel.user}@${tunnel.host}`,
+      "--",
+      encodePayload(request)
+    ]);
   }
-  const result = run(
-    "ssh",
-    [...SSH_OPTS, ...connect, "-i", tunnel.key, "-p", String(tunnel.port), `${tunnel.user}@localhost`, "--", encodePayload(request)],
-    tunnel.connectTimeoutMs + 2e3
-  );
-  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "remote" };
+  return deliver([
+    ...SSH_OPTS,
+    ...connect,
+    "-i",
+    tunnel.key,
+    "-p",
+    String(tunnel.port),
+    `${tunnel.user}@localhost`,
+    "--",
+    encodePayload(request)
+  ]);
 }
 function notify(request, env = process.env, platform = process.platform) {
   try {
-    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
+    const result = isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request, platform);
+    return result.action ? { ...result, action: result.action } : result;
   } catch (error) {
     return { ok: false, detail: String(error), transport: "none" };
   }
@@ -249,6 +296,7 @@ function describe(env = process.env, platform = process.platform) {
 export {
   FIELD_SEPARATOR,
   ICONS,
+  NOTIFICATION_ACTIONS,
   SOUNDS,
   describe,
   encodePayload,
@@ -262,6 +310,7 @@ export {
   parsePayload,
   resolveTunnel,
   safeMessage,
+  safeRequestId,
   safeTitle,
   sendLocal,
   sendRemote,

package/docs/TUNNEL.md

@@ -15,8 +15,12 @@ gets it back.
   │      ▼           │   ONE argument:          │   forced command)      │
   │ lacode notify    │   title\nmessage\n       │      │                 │
   │                  │   urgency\nicon\nsound   │      ▼                 │
-  │                  │                          │  notify-send /         │
+  │                  │   \nrequestID            │  notify-send /         │
   │                  │                          │  osascript             │
+  │      ▲           │ ◄─────────────────────── │                        │
+  │                  │   the clicked button's   │                        │
+  │                  │   name, on the forced    │                        │
+  │                  │   command's stdout       │                        │
   └──────────────────┘                          └────────────────────────┘
 ```
 
@@ -27,27 +31,67 @@ 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 five.** ssh concatenates everything after the host into a
+**One argument, not six.** ssh concatenates everything after the host into a
 single command string, and a forced command starts with *no* positional
-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:
+parameters. A sender that passes six quoted arguments arrives as the single
+string `"a b c d e f"`; a receiver reading `$1..$6` sees six empty strings,
+falls back to six defaults, and pops up a blank notification. So the payload
+crosses as one newline-delimited argument:
 
 ```
-title\nmessage\nurgency\nicon\nsound
+title\nmessage\nurgency\nicon\nsound\nrequestID
 ```
 
-Five fields — `title`, `message`, `urgency`, `icon`, `sound`. `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 a valid one.
+Six fields — `title`, `message`, `urgency`, `icon`, `sound`, `requestID`.
+`sound` is `none`, `done`, `question`, `permission` or `error`. The request id
+is **last**, and it is opaque: it is never shown to you, never passed to a
+command, and never used to build an argument — the only thing it decides is
+whether the notification carries buttons. A sender that stops at `icon`
+simply leaves the rest empty, and an empty or unrecognised name is `none`, so a
+four-field payload is a valid one; a payload with fewer than six fields carries
+no request id at all, and therefore no buttons, so an older sender still works
+against a receiver that expects six.
 
 Newline is safe as the delimiter because both ends strip control characters from
 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.
 
+## The way back
+
+The hop was one-way until now: the notification went up to the desktop and
+nothing came back, because there was nothing on the wire to carry an answer.
+It is two-way now, and what made it two-way was not a new mechanism. **The
+desktop end is an ssh forced command, so its stdout comes back down the same
+ssh connection the notification went up.** That channel was already there and
+nobody used it: a forced command's stdout is carried to whoever opened the
+connection, so the answer rides home on the connection that is already open —
+no second connection, no listener, no port, no new key, no HTTP server.
+
+A permission notification that carries a request id is raised with three
+buttons: **Allow once**, **Always allow** and **Deny**. `notify-send` waits
+for the click and prints the chosen button's *name* on stdout — `once`,
+`always` or `reject`, and "reject" is opencode's own word for deny, not ours.
+The name needs no translation: it is already one of the values the server
+accepts as a permission reply. The plugin reads it off the helper's stdout and
+answers the permission through opencode's own reply route.
+
+Two things follow from the shape. An **empty** stdout means the popup was
+dismissed without a button being chosen: nothing is answered, and the
+permission is left exactly as it was. And a permission that was **already
+answered** — most often in the terminal — comes back as "not found" rather
+than as a failure, because the user did what they had to do and clicking a
+stale notification is not an error.
+
+The wait is bounded: ten minutes on the desktop side, and the hop's own
+deadline is stretched to outlast it, because an answer cut off by a timeout is
+worse than no answer at all.
+
+The buttons are **Linux-only**. `notify-send --action` is the only one of the
+three channels that can offer one — `osascript` and `terminal-notifier` have no
+action support — so a macOS desktop gets a plain notice, and the answer there
+still has to be given in the terminal.
+
 ## Setting it up
 
 Once, on the **remote host** (where opencode runs):
@@ -95,11 +139,20 @@ 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 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
-agent must not go down because a laptop went to sleep. `forward` is the
-exception: it exits with the remote's status, because its caller wants to know.
+`LACODE_REQUEST_ID` in the environment is the one thing that makes a send
+actionable: it is the permission request id, it is opaque, and it is set on the
+helper by the plugin rather than by you. A send with it carries the three
+buttons on Linux and prints the name of the clicked one on stdout; a send
+without it is an ordinary notice that prints nothing.
+
+A plain `notify` is fire-and-forget by design. An unreachable desktop, a
+missing key, no notifier installed at all — all of them print a warning on
+stderr and exit 0. A notification must never be able to fail the process that
+tried to send one; an agent must not go down because a laptop went to sleep.
+`forward` is the exception: it exits with the remote's status, because its
+caller wants to know. An **actionable** notify is the other exception, and it
+is bounded rather than open-ended: it waits for the click, because the answer
+is the whole point of it, and it still exits 0 whatever happens.
 
 On macOS the text is passed to `osascript` as arguments to an `on run argv`
 handler, never spliced into the script source — a session title is not trusted
@@ -115,6 +168,14 @@ delivers locally through the platform channel — `notify-send` on Linux,
 channel as a local send, **the desktop half is not Linux-only**: a Mac desktop
 receives notifications too.
 
+The buttons are the exception to that. Only `notify-send` can offer one, so a
+payload with a request id is an actionable notification on Linux and a plain
+notice — one that prints nothing — on macOS. What the receiver prints on stdout
+is the chosen button's name, and that stdout is what carries the answer back up
+the connection (see [The way back](#the-way-back)). The request id itself is
+never passed to a command and never printed — only its emptiness is ever
+tested.
+
 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).
 
@@ -152,6 +213,11 @@ 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.
 
+`LACODE_REQUEST_ID` is absent for the same kind of reason, and it is not yours
+to set either: the plugin puts the permission request id on the helper
+process, and the helper carries it as the payload's sixth field. The hop only
+ever asks whether it is there.
+
 ## The reverse forward
 
 A host that sets `OC_TUNNEL_PORT` and leaves `OC_LOCAL_HOST` unset reaches the
@@ -161,3 +227,7 @@ desktop through a reverse forward: `sendRemote` falls back to an ssh call to
 (`bin/oc-notify-receiver`). That receiver is the Linux end of the hop: it
 delivers through `notify-send`, and libnotify is a Linux thing, so a Mac cannot
 be this end of the tunnel.
+
+The way back works the same way here: the receiver's stdout comes back down
+the forward, on the connection the notification went up, so a click on one of
+the three buttons is carried home the same way it is on the direct hop.

package/docs/USER-STORIES.md

@@ -193,7 +193,7 @@ does not.
 
 **Story ID(s) for tests:** US-11
 **Acceptance criteria:**
-- [ ] Given a session went busy and is now idle, When the idle event fires, Then a `done` notification is delivered.
+- [ ] Given a session went busy and is now idle, When the idle event fires, Then a `done` notification is delivered and stays on the desktop until the user closes it.
 - [ ] Given a session ends with an unrecognized error, When the error event fires, Then an `error` notification is delivered, it bypasses the duplicate-suppression cooldown, and it carries the error's own message.
 - [ ] Given a recognized rate-limit or quota error, or a user abort, When a session error event fires, Then no failure notification is raised — the pool already handles the former and the user already knows the latter.
 - [ ] Given a session that never went busy, When it goes idle, Then no notification is sent.
@@ -211,7 +211,7 @@ does not.
 - [ ] Given a question and a completion occur inside the same cooldown window, When both are evaluated, Then they are not deduplicated against each other.
 
 ### US-25: Notification when opencode asks for permission
-**As a** user, **I want** to be notified when opencode is blocked asking me for permission — including permission to reach a directory outside the worktree — **so that** a silent permission prompt is never mistaken for a hung agent.
+**As a** user, **I want** to be notified when opencode is blocked asking me for permission — including permission to reach a directory outside the worktree — **so that** a silent permission prompt is never mistaken for a hung agent, and so that I can allow or deny it where the notification reaches me instead of going back to the terminal.
 
 **Story ID(s) for tests:** US-25
 **Acceptance criteria:**
@@ -219,8 +219,14 @@ does not.
 - [ ] Given opencode asks to reach a directory outside the worktree, When the prompt fires, Then the notification names that directory, resolved from `metadata.parentDir`/`metadata.filepath` and with the trailing glob trimmed, because a glob is not something the user can judge.
 - [ ] Given the permission is granted, denied, or dismissed, When `permission.replied` fires, Then no notification is sent — the prompt was the thing worth interrupting for, not the answer — and only the parked-session block is cleared.
 - [ ] Given a session is parked on a permission prompt, When the idle event fires, Then no "finished" notification is sent, because nothing finished.
-- [ ] 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 the plugin observes a permission prompt, When it handles the event, Then it registers no `permission.ask` hook and mutates nothing in the payload — that hook's `output.status` is the permission decision itself, and deciding a prompt inside a handler is not the same as answering the one the user was asked for. A permission is answered through the server's own reply route, and only when the user says which answer they meant.
 - [ ] 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.
+- [ ] Given a permission prompt on Linux, When the notification is delivered, Then it is exactly one notification carrying three buttons — **Allow once**, **Always allow** and **Deny** — and the click raises no second notification.
+- [ ] Given one of those buttons is clicked, When the answer comes back over the hop the notification came up, Then the permission is answered with that button's meaning through the server's reply route; the button names are opencode's own reply values (`once`, `always` and `reject` — the server's word for deny), so a click needs no translation to become an answer.
+- [ ] Given the popup is dismissed without a button being chosen, When the notification returns, Then nothing is answered and the permission is left exactly as it was.
+- [ ] Given the permission was already answered in the terminal, When a button is clicked, Then the reply is a no-op and is not reported as a failure.
+- [ ] Given the desktop is a macOS one, When the same prompt is delivered, Then it is a plain notice with no buttons, because `osascript` and `terminal-notifier` have no action support and the answer still has to be given in the terminal there.
+- [ ] Given a question is asked, When its notification is delivered, Then it carries no buttons and answers nothing, because a question is not a permission: the v1 client this plugin has has no question API at all, and the v2 routes need a bound socket the default TUI does not have.
 
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",