@lawaty/lacode 0.0.0-stage → 0.1.0

package/dist/tunnel.js

@@ -0,0 +1,150 @@
+// src/tunnel/index.ts
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var ICONS = [
+  "utilities-terminal",
+  "dialog-information",
+  "dialog-error",
+  "dialog-warning",
+  "system-run",
+  "emblem-default"
+];
+function resolveTunnel(env = process.env) {
+  const port = Number(env.OC_TUNNEL_PORT);
+  return {
+    user: env.OC_LOCAL_USER ?? "",
+    port: Number.isFinite(port) && port > 0 ? port : 10022,
+    key: env.OC_NOTIFY_KEY ?? join(homedir(), ".ssh", "lacode_notify"),
+    connectTimeoutMs: Number(env.OC_CONNECT_TIMEOUT_MS) || 5e3
+  };
+}
+function isRemote(env = process.env) {
+  return Boolean(env.SSH_CLIENT || env.SSH_TTY);
+}
+function normalizeUrgency(raw) {
+  return raw === "low" || raw === "critical" || raw === "normal" ? raw : "normal";
+}
+function normalizeIcon(raw) {
+  return ICONS.includes(raw) ? raw : "utilities-terminal";
+}
+var safeText = (raw, fallback, max) => {
+  const clean = raw.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  if (!clean) return fallback;
+  return clean.length > max ? `${clean.slice(0, max - 1)}\u2026` : clean;
+};
+var safeTitle = (raw) => safeText(raw ?? "", "LaCode", 120);
+var safeMessage = (raw) => safeText(raw ?? "", "", 400);
+var FIELD_SEPARATOR = "\n";
+var encodePayload = (request) => [
+  safeTitle(request.title),
+  safeMessage(request.message),
+  normalizeUrgency(request.urgency),
+  normalizeIcon(request.icon)
+].join(FIELD_SEPARATOR);
+var SSH_OPTS = [
+  "-o",
+  "BatchMode=yes",
+  "-o",
+  "IdentitiesOnly=yes",
+  "-o",
+  "ClearAllForwardings=yes",
+  "-o",
+  "LogLevel=ERROR",
+  "-o",
+  "StrictHostKeyChecking=accept-new"
+];
+var run = (command, args, timeout) => {
+  try {
+    const result = spawnSync(command, args, { timeout, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return {
+      ok: result.status === 0,
+      stdout: result.stdout ?? "",
+      stderr: (result.stderr ?? "").trim(),
+      // spawnSync reports a timeout as a null status and an ETIMEDOUT error; both
+      // are "did not arrive", not "crashed", and neither may throw.
+      detail: result.error ? String(result.error.code ?? result.error.message) : void 0
+    };
+  } catch (error) {
+    return { ok: false, stdout: "", stderr: "", detail: String(error) };
+  }
+};
+var have = (command) => {
+  try {
+    return spawnSync("sh", ["-c", `command -v ${command}`], { encoding: "utf8" }).status === 0;
+  } catch {
+    return false;
+  }
+};
+function sendLocal(request) {
+  if (!have("notify-send")) return { ok: false, detail: "notify-send is not installed", transport: "local" };
+  const args = [
+    safeTitle(request.title),
+    safeMessage(request.message),
+    `--urgency=${normalizeUrgency(request.urgency)}`,
+    `--icon=${normalizeIcon(request.icon)}`
+  ];
+  const result = run("notify-send", args, 5e3);
+  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "local" };
+}
+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 args = [
+    ...SSH_OPTS,
+    "-o",
+    `ConnectTimeout=${Math.max(1, Math.round(tunnel.connectTimeoutMs / 1e3))}`,
+    "-i",
+    tunnel.key,
+    "-p",
+    String(tunnel.port),
+    `${tunnel.user}@localhost`,
+    "--",
+    encodePayload(request)
+  ];
+  const result = run("ssh", args, tunnel.connectTimeoutMs + 2e3);
+  return { ok: result.ok, detail: result.ok ? void 0 : result.stderr || result.detail, transport: "remote" };
+}
+function notify(request, env = process.env) {
+  try {
+    return isRemote(env) ? sendRemote(request, resolveTunnel(env)) : sendLocal(request);
+  } catch (error) {
+    return { ok: false, detail: String(error), transport: "none" };
+  }
+}
+function forward(host, argv, options = {}) {
+  const env = options.env ?? process.env;
+  const timeoutMs = options.timeoutMs ?? (Number(env.OC_SSH_TIMEOUT_MS) || 3e4);
+  const result = run("ssh", [...SSH_OPTS, "-o", `ConnectTimeout=${Math.max(1, Math.round(timeoutMs / 1e3))}`, host, "--", ...argv], timeoutMs);
+  return {
+    ok: result.ok,
+    detail: result.ok ? void 0 : result.stderr || result.detail,
+    transport: "remote",
+    stdout: result.stdout
+  };
+}
+function describe(env = process.env) {
+  const tunnel = resolveTunnel(env);
+  return {
+    running: isRemote(env) ? "remote (over ssh)" : "local",
+    user: tunnel.user || "(unset)",
+    port: tunnel.port,
+    key: tunnel.key,
+    notifySend: have("notify-send")
+  };
+}
+export {
+  FIELD_SEPARATOR,
+  ICONS,
+  describe,
+  encodePayload,
+  forward,
+  isRemote,
+  normalizeIcon,
+  normalizeUrgency,
+  notify,
+  resolveTunnel,
+  safeMessage,
+  safeTitle,
+  sendLocal,
+  sendRemote
+};

package/docs/BENCHMARKS.md

@@ -0,0 +1,127 @@
+# Cost benchmarks
+
+**This file contains no results.** It explains how to produce your own. The table
+below is empty on purpose, and the harness refuses to invent a number to fill it
+in.
+
+There is no published savings figure for LaCode, because none has been
+independently measured. A number in a README is a claim about somebody's
+workload, and yours is not that workload. The plugin changes two things: *which
+model does the bulk exploration work*, and *how much of that work has to be done
+at all* — agents start from the maintained context map in [CONTEXT.md](CONTEXT.md)
+instead of re-deriving the structure of your repository on every task. What that
+is worth in money depends entirely on your token mix and on what you compare the
+pooled run against. So the harness exists to let you compute the number for
+yourself rather than to hand you one to believe.
+
+## What the harness measures
+
+`tests/benchmark/run.mjs` runs one scenario twice — once on your main model, once
+on a pooled model — and prints tokens and cost for both.
+
+The comparison only means something because both runs do *identical* work. The
+scenario is stated once in the harness and passed to both configurations: the
+same four prompts, the same number of calls, a different model doing them.
+
+```
+Map the modules that handle authentication and the entry points that reach them.
+Find every place a request is authorized and list the file:line for each check.
+List the config files that affect routing and the defaults each one sets.
+Find the test files covering the auth path and name what each asserts.
+```
+
+It is a small, deliberately mechanical scenario. It is not a representative
+workload for you, and the harness does not claim it is. Its only job is to make
+the two sides of the ratio comparable.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run benchmark` | Simulation (the offline default). No credentials, no network. |
+| `npm run benchmark -- --real` | Runs both configurations for real against the `opencode` binary and reads token counts back out of the runs. |
+| `npm run benchmark -- --refresh` | Rebuilds `tests/models-snapshot.json` from models.dev first (network), then proceeds as usual. |
+| `npm run benchmark -- --out docs/BENCHMARKS.generated.md` | Writes the generated table to the *generated* filename. See below. |
+
+Useful flags for both modes:
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--baseline-model` / `--model` | `anthropic/claude-opus-4-1` | Which model plays "what it would have cost without LaCode". A **name**, never a price. |
+| `--calls` | `40` | Simulation only. Number of delegated calls in the task profile. |
+| `--input-tokens` | `12000` | Simulation only. Input tokens per call. |
+| `--output-tokens` | `1500` | Simulation only. Output tokens per call. |
+| `--allow-unknown` | off | Accepts `unknown` in the cost column for a model you named explicitly. Without it the run exits non-zero. |
+
+`--real` additionally honours `OPENCODE_BIN` to locate the opencode binary, and
+reads credentials from `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` /
+`OPENROUTER_API_KEY` / `OPENCODE_API_KEY` or from the opencode `auth.json`.
+
+## Simulation vs real
+
+They are different kinds of claim, and the output says which one you are looking
+at in every table header.
+
+**Simulation** (the default) is arithmetic over stated assumptions. It takes the
+task profile above, multiplies it out, and prices it from the pinned snapshot.
+Nothing is executed and nothing is observed. It is a projection, and it is
+useful for exactly one thing: seeing how the two rows compare when you change
+the profile or the models.
+
+**Real** runs the scenario twice and reads the token counts back out of each
+run's own output. That is a measurement of the harness scenario on your machine
+on that day. It is still not a measurement of your work.
+
+`--real` degrades rather than failing when it cannot run: with no credentials or
+no binary it prints `SKIPPED`, exits 0, and reports nothing. A real run that
+fails mid-way exits 3 and refuses to fall through to a projection. If the runs
+report no token usage at all, that is an error, not a cost of zero.
+
+## Pricing
+
+Prices come from `tests/models-snapshot.json`, checked in so a run is
+reproducible and offline. Regenerate it with `npm run benchmark -- --refresh`
+(or `node tests/refresh-models-snapshot.mjs`) when you want current figures.
+
+A model the snapshot has never seen is **skipped with a named reason**. It is
+never priced at 0 and never priced at a guess. If you name such a model
+explicitly with `--model` / `--baseline-model`, the run exits non-zero and tells
+you to refresh or to pass `--allow-unknown`.
+
+This is the reason the results table below is empty. The pinned snapshot covers
+the bundled free preset only; the default baseline model is not in it, so the
+default offline run cannot produce an honest ratio. That is the harness working
+as designed.
+
+## Results
+
+Run it yourself and put the output here.
+
+| configuration | models | calls | input tokens | output tokens | cost |
+| --- | --- | ---: | ---: | ---: | ---: |
+| baseline (main model) | — | not yet measured | — | — | — |
+| LaCode (pooled subagent) | — | not yet measured | — | — | — |
+
+Difference: not yet measured — run it yourself.
+
+Nothing in this repository asserts a savings percentage. There is no constant
+anywhere in the harness: every ratio in the output is computed at runtime from
+the rows printed above it, with both the numerator and the denominator shown, so
+the arithmetic can be checked by hand. If a number cannot be derived, the
+harness prints `unknown`.
+
+## Why the generated table is a separate file
+
+`--out` writes to `docs/BENCHMARKS.generated.md`. It **refuses**
+`--out docs/BENCHMARKS.md` and exits 2.
+
+That refusal is the point. This file ships inside the npm tarball (`files`
+includes `docs`). A generated table dropped on top of it would replace the
+explanation with a dated artifact that reads as a published measurement of the
+package, and it would outlive the machine and the day that produced it. So the
+hand-written explainer is protected, and the generated output — which carries a
+footer pointing back here — goes to its own gitignored filename.
+
+```bash
+npm run benchmark -- --out docs/BENCHMARKS.generated.md
+```

package/docs/CONTEXT.md

@@ -0,0 +1,211 @@
+# The context map
+
+Every task an agent starts, it starts by exploring: list the directories, open
+the entry points, work out which layer a change belongs to, discover which files
+call which. On a large repository that is the single most expensive part of the
+job, and it happens *every time* — for a question that touches one file, for a
+refactor that moves one module, for a session you start after an hour of
+something else.
+
+LaCode keeps a short, maintained map of your repository at `.opencode/context/`
+and makes every agent read it before exploring. The map answers one question —
+**"what should I look at first?"** — and nothing else.
+
+This document is the user-facing description of the system: what the files are,
+who writes them, when they are refreshed, and what you can do by hand.
+
+## Why it exists
+
+Agents are stateless between tasks. Anything an agent learns about your
+codebase in one session is discarded at the end of it, and re-derived — at full
+price — by the next agent. Writing the findings down once, in a form small
+enough to read in one call, is what turns that repeated cost into a single
+upfront one.
+
+The mechanism is deliberately narrow, because a map that costs more to read than
+the exploration it replaces is worse than no map:
+
+- **Conclusions, not inventories.** "`OrderService` is the application boundary
+  for order mutations", not "there is a file called OrderService in
+  `src/orders/`". The cartographer is forbidden by name from writing directory
+  listings, copying source, or restating what the README already says.
+- **One file per question.** Five files, each with a defined scope, so an agent
+  reads one of them rather than all of them.
+- **Canonical entry points.** The highest-value thing in the map is a short
+  "Start here" list per subsystem: the five files an agent should open, each
+  with a one-phrase reason.
+- **It links out.** Your project's own README, ADRs and docs are authoritative
+  and are not duplicated here.
+
+On cost: the saving is in **tokens not spent re-discovering structure**, and it
+is paid by exploration tokens rather than by the expensive main model — the
+cartographer that maintains the map runs on a pooled model like every other
+subagent. **No savings percentage is published here, because none has been
+independently measured.** A number derived from somebody else's repository and
+token mix is not a claim about yours; see [BENCHMARKS.md](BENCHMARKS.md) for the
+harness that produces a number for your own workload.
+
+## The five files
+
+`.opencode/context/` holds exactly these, and nothing else:
+
+| File | What belongs in it |
+| --- | --- |
+| `architecture.md` | The high-level shape: layers, boundaries, entry points, dependency rules. Read this for an architectural question. |
+| `contexts.md` | The major subsystems. For each: what it is for, where to start reading it, what it depends on, what must not change while you are in there. Read this for a subsystem question. |
+| `conventions.md` | Repository-specific rules: naming, module layout, error handling, testing, persistence. Read this before writing code, not after. |
+| `workflows.md` | The few runtime flows worth tracing end to end — how a request becomes a mutation, how a plugin hook reaches the thing it hooks. Read this when you need to know what actually happens at runtime. |
+| `decisions.md` | Architectural decisions that the repository's own decision log does not already record. Concise, variable length. |
+
+Files the user or the plan explicitly names always win over the map. The map is
+a shortcut to the right starting point, not an authority: when it disagrees with
+the source, the source is right and the map is wrong.
+
+The map is **local and untracked**. It describes *your* checkout on *this*
+machine, so committing it would churn on every session that edits a file, and
+syncing it to another host would push a description of one machine's projects
+onto hosts that have different ones. If you see `.opencode/context/` in a diff,
+something has gone wrong.
+
+## How it stays current
+
+The `context-manager` agent maintains the map. It runs in two ways: on its own,
+after a session that changed something, and on demand through the three
+commands — both of which go through the same agent, so they behave the same way.
+
+### Automatically
+
+After a **root** session goes idle, and only if that session edited a file
+inside the project, LaCode starts a `context-manager` run:
+
+1. It collects the paths the session touched, dropping anything generated,
+   vendored or outside the project (`node_modules`, `dist`, `coverage`,
+   `.git`, and — importantly — the map itself, so the cartographer's own writes
+   never trigger another run).
+2. It picks `bootstrap` or `update` from what is on disk: if
+   `.opencode/context/` does not exist, the run builds the map from scratch;
+   if it exists, the run updates it.
+3. It borrows a slot from the same pool every other subagent uses, creates a
+   session, and hands it the changed paths as *starting context* — not as an
+   exhaustive list and not as an instruction to document all of them.
+
+Three things deliberately do **not** trigger a run: a session that edited
+nothing, a subagent going idle (they go idle constantly, mid-task), and a second
+run within ten minutes of the last one.
+
+An update defaults to *no edit*. A changed file is not a changed fact:
+formatting, local renames, added tests and dependency bumps rarely alter what
+the map should say. The cartographer is told to edit only when the work
+introduced or revealed something that will help a future agent — a new boundary,
+a new or moved entry point, a changed workflow, a new convention, an
+architectural decision, a previously undocumented invariant — and to report
+"no update needed" otherwise.
+
+If the map is missing entirely, nothing breaks: agents check, find nothing, and
+explore as they always did. The standing rule that tells them to check is
+injected into your config only when you have no `instructions` array of your own.
+
+### On demand
+
+```bash
+/context-init      # build the map, or verify and refresh an existing one
+/context-update    # incremental refresh; accepts a focus, e.g. /context-update src/payments
+/context-review    # audit it for staleness, contradictions, duplication and bloat
+```
+
+All three delegate to the same agent, which is why they are consistent with the
+automatic run rather than a separate mechanism. `/context-review` treats
+everything outside `.opencode/context/` as read-only: it fixes the map, never
+your source.
+
+If you have defined a command of the same name, yours wins and is left exactly
+as you wrote it — the same merge-without-clobber rule the agents follow.
+
+## One writer
+
+Only `context-manager` writes the map. Every other agent is told never to edit
+it, and to say in its final report if its work revealed something that belongs
+in there. The cartographer, in turn, is denied permission to write anything
+outside the map — not by convention, but by an `edit` rule that allows
+`.opencode/context/**` and nothing else.
+
+The rule runs in both directions. The agents that *could* write anywhere else in
+the repository — the root `build` agent and both implement tiers — carry the
+mirror image of the cartographer's grant: `"*": "allow"` followed by a `deny` on
+`.opencode/context/**`, so they edit everything except the map. The instruction
+telling them not to touch it is still there, and still matters — a permission
+denial tells an agent nothing about what it should have done instead — but it is
+no longer the only thing standing between them and the map.
+
+This exists because two writers produce a map that is neither current nor
+trustworthy. Concurrent sessions rewriting the same five files produce
+contradictions that no later reader can resolve, and the reader has no way to
+tell which version is newer.
+
+Ordering in those rules is not cosmetic. opencode resolves a file permission by
+taking the **last** matching rule in declaration order, with no specificity
+sorting: a `deny` written above a broad `"*": "allow"` loses. LaCode therefore
+writes every narrow rule last, in both files (`src/agents.ts` and your own
+`opencode.jsonc`), and `src/lib/writer-rule.ts` checks that order rather than
+grepping for the word `allow` — which is what stops a correctly-placed deny from
+being reported as a hole.
+
+The rule has a sharp edge worth knowing about, because it has already bitten
+this project: **opencode evaluates a file permission against the path relative
+to the project root, not the absolute path the tool was given.** A rule written
+as `*/.opencode/context/**` matches an absolute path and therefore matches
+nothing at all. Both spellings are therefore required — `.opencode/context/**`
+for a normally-rooted project and `*/.opencode/context/**` for one rooted at
+`/` — and LaCode ships both. At startup the plugin checks your config for that,
+and logs an error naming the rules it saw if neither form would ever fire.
+
+### The residual risk: a subdirectory worktree
+
+Those patterns are matched against `relative(worktree, filepath)`, and the
+spelling that is supposed to fire depends on where the worktree root sits:
+
+- **worktree = repo root** → the map is `.opencode/context/architecture.md`, and
+  `.opencode/context/**` fires. `*/.opencode/context/**` does not.
+- **worktree = `/`** → the map is `home/<you>/…/.opencode/context/…`, and only
+  `*/.opencode/context/**` fires.
+
+Shipping both spellings covers those two. What it does **not** cover is a third
+case: if the worktree is a subdirectory rather than the repo root — you opened
+opencode one directory down from the repository root — then the evaluated path
+gains a prefix that matches *neither* pattern. Both rules match nothing, the
+deny against other agents silently stops applying, and **nothing is reported**,
+because a rule matching nothing is not an error in opencode's evaluator and the
+startup check has no way to see a worktree it was not told about.
+
+How to detect it: open opencode from the repository root, not from a
+subdirectory of it. If `ls .opencode/context` from your shell's current
+directory does not list the five files, your shell is not at the root and
+neither is opencode's worktree. The cost of getting it wrong is not a crash —
+it is a silent return to a map maintained only by prompt, which is the exact
+state US-21 exists to eliminate.
+
+The symptom of getting this wrong is not a crash. The cartographer's writes are
+simply denied, its run still "succeeds", and the map quietly stops changing. So
+a run that changed nothing on disk is reported as a warning, not as a success:
+if you see `auto update finished without changing the map` repeatedly, the first
+thing to check is that permission rule, not the map's content.
+
+## What you will see in the log
+
+| Line | Meaning |
+| --- | --- |
+| `borrowed pool slot N (model, wW) for auto update` | A refresh started, on a pooled model. |
+| `auto update finished` | The run completed and changed at least one map file. |
+| `auto update finished without changing the map` | Nothing landed. Either nothing needed saying, or the cartographer could not write. |
+| `auto update failed: …` | The run errored. The paths it was given are queued again for the next window, so the work is not lost. |
+| `context map is not writable: …` | Your config's one-writer rule does not match the path opencode evaluates. Nothing will update until you fix it. |
+| `context map has more than one writer: …` | An agent other than `context-manager` would be granted the map. The offending agent and the winning rule are named. |
+
+## Reference
+
+- The agent and command definitions, as injected: `src/agents.ts`, `src/commands.ts`.
+- The idle/edit trigger: `src/plugins/context-autoupdate.ts`.
+- The one-writer rule check: `src/lib/writer-rule.ts`.
+- The behavioural contracts, with acceptance criteria a test asserts:
+  [USER-STORIES.md](USER-STORIES.md), US-19 to US-22.
+- Tests: `tests/stories/g-context-management.test.mjs`.

package/docs/TUNNEL.md

@@ -0,0 +1,141 @@
+# Notifications from remote hosts
+
+opencode runs on your laptop. It also runs on the remote hosts you ssh into. A
+notification raised on a remote host has nowhere to go: that machine has no
+desktop, no session bus, and possibly no `notify-send`. This is the hop that
+gets it back.
+
+## The shape
+
+```
+  remote host                                   your desktop
+  ┌──────────────────┐                          ┌────────────────────────┐
+  │ opencode session │                          │ oc-notify-receiver     │
+  │      │           │  ssh (reverse forward)   │  (forced command,      │
+  │      ▼           │ ───────────────────────► │   restrict)            │
+  │ bin/lacode      │  ONE argument:            │      │                 │
+  │   notify         │  title\nmessage\n         │      ▼                 │
+  │                  │  urgency\nicon            │  notify-send           │
+  └──────────────────┘                          └────────────────────────┘
+```
+
+Two things are load-bearing here.
+
+**The reverse forward.** The remote opens an SSH connection to *your* machine
+and asks sshd on the desktop to listen on a port. A notification is then an ssh
+call to `localhost:<port>` with a dedicated key that is authorized to run
+exactly one command. It is not a login, it is not a shell, and it does not
+depend on which terminal connected first.
+
+**One argument, not four.** 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
+as one newline-delimited argument:
+
+```
+title\nmessage\nurgency\nicon
+```
+
+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.
+
+## Sending
+
+The CLI picks the transport by where it is running — `SSH_CLIENT` or `SSH_TTY`
+means remote, so it forwards; otherwise it calls `notify-send` directly.
+
+```bash
+lacode notify "build finished" "lapode: 4 files changed" normal dialog-information
+lacode notify "question" "which database should I use?" critical dialog-warning
+lacode forward web-01 -- systemctl --user status oc-tunnel
+lacode doctor
+```
+
+`notify` is fire-and-forget by design. An unreachable desktop, a missing key, a
+missing `notify-send` — all of them print a warning on stderr and exit 0. A
+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 doctor` prints what the environment resolves to and never gates on it.
+
+## Configuration
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OC_LOCAL_USER` | *(unset)* | The desktop user the tunnel authenticates as. **Required for the remote hop.** |
+| `OC_TUNNEL_PORT` | `10022` | Reverse-forward listener port on the desktop. Give each remote host its own. |
+| `OC_NOTIFY_KEY` | `~/.ssh/lacode_notify` | The dedicated key. Never a personal key. |
+| `OC_CONNECT_TIMEOUT_MS` | `5000` | Ceiling on the hop. |
+| `OC_SSH_TIMEOUT_MS` | `30000` | Ceiling on `forward`. |
+
+`OC_LOCAL_USER` is read rather than probed on purpose. `id -un` on a remote
+account frequently returns `root`, and a dbus path built from that reaches
+nobody's desktop. Guessing the desktop user is worse than failing.
+
+## Setting the tunnel up on the desktop
+
+The receiver runs on the machine with the desktop, as an `authorized_keys`
+forced command restricted to that one script:
+
+```
+restrict,command="/home/you/.local/bin/lacode-notify-receiver" ssh-ed25519 AAAA… oc-notify tunnel auth
+```
+
+`restrict` is doing the security work: no shell, no PTY, no agent forwarding, no
+port forwarding. The key can do exactly one thing and nothing else.
+
+The receiver must satisfy this contract:
+
+1. read the payload from **`$SSH_ORIGINAL_COMMAND`**, never from `$1`..`$4`;
+2. **never** `eval` it, never hand it to `sh -c`, never splice it into an
+   argument list — it is attacker-controlled, because it is whatever the remote
+   user typed;
+3. split it on newlines into title / message / urgency / icon, each with a
+   default;
+4. whitelist `urgency` against `low|normal|critical` and `icon` against the six
+   supported names, both of which become command-line flags;
+5. resolve `DISPLAY` / `DBUS_SESSION_BUS_ADDRESS` for the session it is running
+   in, then `exec notify-send "$TITLE" "$MSG" --urgency=… --icon=…`.
+
+> **Note.** The published package ships the built CLI (`dist/lacode.js`, linked
+> as `lacode`) and the tunnel behind it (`dist/tunnel.js`, importable as
+> `@lawaty/lacode/tunnel`), not a receiver script. The receiver is the
+> desktop-side half and is yours to install — keep it out of your shell's
+> `$PATH` reach and pinned in `authorized_keys`.
+
+If the two halves disagree you get a blank popup, which points nowhere. A
+receiver that sees a payload with no newline in it should say so on stderr
+rather than silently defaulting everything.
+
+## Holding the forward open
+
+The tunnel has to exist whenever a notification is sent. Anything that survives
+your logout works: a `--user` systemd unit is the usual choice, one per remote
+host, each with its own port.
+
+```ini
+# ~/.config/systemd/user/oc-tunnel@<host>.service
+[Service]
+ExecStart=/usr/bin/ssh -NT -R 10022:localhost -o ClearAllForwardings=yes -o ExitOnForwardFailure=yes \
+          -i %h/.ssh/lacode_notify you@localhost
+```
+
+Then `systemctl --user enable --now oc-tunnel@web-01`.
+
+Two details that matter:
+
+- **`-o ExitOnForwardFailure=yes`** — without it, ssh stays up with no forward
+  and the notifications fail silently.
+- **`-o ClearAllForwardings=yes`** on every *other* ssh call that touches that
+  host, including rsync's `-e`. A `RemoteForward` in `~/.ssh/config` competes
+  for the same port, and a half-claimed listener starves the one session that
+  needed it.
+
+Do not hold the forward open with a `RemoteForward` line in `~/.ssh/config`. It
+is per-connection: the port exists only while some terminal is open, and it is
+claimed by whichever terminal connects first.