lazyclaw 4.2.1 → 4.3.0

package/README.md

@@ -301,6 +301,50 @@ lazyclaw agent reflect planner --task t_20260518_xxxxxx
 # and set "memoryWrite": "off" (other values: "auto" default, "manual").
 ```
 
+### Self-improving skills (v4.3)
+
+Reflection writes free-text *lessons* to an agent's memory. A **skill**
+goes further: it distils a finished task into a reusable, structured
+`SKILL.md` (`## When to Use` / `## Procedure` / `## Pitfalls` /
+`## Verification`) that any future agent can load. This is the Hermes
+self-improving-skill pattern — synthesise once, recall forever.
+
+```bash
+# Synthesise a skill from a finished task. Mirrors `agent reflect`:
+# one LLM call over the transcript → a SKILL.md installed into
+# ~/.lazyclaw/skills/<name>.md (frontmatter created_by: agent).
+lazyclaw agent skill-synth planner --task t_20260518_xxxxxx
+lazyclaw agent skill-synth planner --task t_20260518_xxxxxx --dry-run  # print, don't write
+
+# Opt an agent into AUTOMATIC synthesis on task done (default is manual):
+lazyclaw agent add researcher --skill-write auto   # auto | manual (default) | off
+```
+
+**Recall is progressive-disclosure.** Every agent turn gets a compact
+*index* of installed skills (name + one-line summary) injected into its
+system prompt — cheap, a line per skill. The agent pulls a full skill
+body on demand with the built-in read-only **`skill_view`** tool, so
+skill bodies never bloat the prompt until they're actually needed.
+`skill_view` ships in the default tool whitelist, so newly-created
+agents recall skills out of the box; older agents pick it up via
+`lazyclaw agent edit <name> --tools bash,read,write,grep,skill_view`.
+
+`skill-synth` defaults to `manual` (you run the command, or pass
+`--dry-run` to review first) because a synthesised skill feeds every
+future agent's prompt — keep it opt-in until you trust an agent's
+output. Flip the trigger any time with
+`lazyclaw agent edit <name> --skill-write auto|manual|off`.
+
+Auto-synthesis is defended for the cases where it runs unattended:
+secret-shaped tokens (`sk-…`, `ghp_…`, `AKIA…`, bearer tokens,
+`*_KEY=…`, PEM blocks) are redacted from both the transcript sent to
+the model and the saved skill; synthesised bodies are size-capped and
+the `[[TASK_DONE]]` marker is neutralised; and a synthesised skill
+**never overwrites a human-authored skill** — on a name collision it
+takes the next free `name-N` slug, only ever overwriting (and
+version-bumping) its own prior output. Skill bodies are framed to the
+model as untrusted reference, not instructions.
+
 Slack inbound (a user pings `@lazyclaw` in a channel, the bot replies)
 runs through the Socket Mode listener:
 
@@ -308,6 +352,55 @@ runs through the Socket Mode listener:
 lazyclaw slack listen     # foreground; connects, reacts with :eyes:, replies in thread
 ```
 
+### Telegram — zero-install mobile control (v4.3)
+
+Control lazyclaw from your phone with no app to install and no public
+URL: the Telegram listener long-polls the Bot API (works behind NAT),
+pipes each inbound message through the active provider, and replies in
+the same chat. Push notifications are handled by Telegram itself.
+
+```bash
+# 1) Create a bot with @BotFather, then store its token:
+echo 'TELEGRAM_BOT_TOKEN=123456:ABC...' >> ~/.lazyclaw/.env
+
+# 2) (recommended) restrict who can drive it — your Telegram numeric user id:
+lazyclaw pairing add 987654321
+
+# 3) Listen. Foreground; Ctrl-C to stop. An empty pairing allowlist
+#    means "reply to anyone who messages the bot".
+lazyclaw telegram listen --provider anthropic --model claude-opus-4-7
+```
+
+The `pairing` allowlist doubles as the Telegram sender allowlist, so
+only paired ids get a reply.
+
+### Matrix + generic inbound (v4.3)
+
+The same pattern extends to **Matrix** over the client-server `/sync`
+long-poll (no SDK):
+
+```bash
+printf 'MATRIX_HOMESERVER=https://matrix.org\nMATRIX_ACCESS_TOKEN=...\nMATRIX_USER_ID=@you:matrix.org\n' >> ~/.lazyclaw/.env
+lazyclaw matrix listen                        # pairing allowlist = @user:server ids
+```
+
+For any platform lazyclaw doesn't natively speak (Discord DMs, WhatsApp,
+Signal, Email — each needs a heavy SDK or external binary), run your own
+relay and forward messages to the **generic inbound webhook** on the
+daemon — no extra dependency in lazyclaw:
+
+```bash
+curl -s localhost:<port>/inbound -H 'content-type: application/json' \
+  -d '{"text":"hi from anywhere","senderId":"123","threadId":"discord:42"}'
+# → { "reply": "...", "threadId": "discord:42" }
+```
+
+`/inbound` runs the active provider and is auth-token-gated; when a
+`pairing` allowlist exists, `senderId` must be on it. Native adapters
+(Telegram, Matrix, Slack) all implement the same `channels/base.mjs`
+contract, so an SDK-backed channel can be dropped in later behind an
+explicit dependency review.
+
 The CLI is mirrored by daemon HTTP routes (`GET/POST/PATCH/DELETE
 /agents|teams|tasks`, `GET /tasks/<id>/transcript`) and by the
 browser dashboard's Agents / Teams / Tasks tabs:
@@ -342,8 +435,18 @@ lazyclaw skills list                          # markdown skill bundles
 lazyclaw skills show review
 lazyclaw skills install ./my-skill.md
 lazyclaw skills remove review
+
+lazyclaw skills classify deploy-flow          # active | stale (30d) | archived (90d)
+lazyclaw skills curate                        # archive agent skills unused >90d → skills/.archive/
 ```
 
+`skills curate` is the lifecycle sweep for self-improving skills:
+agent-authored skills that haven't been recalled (`skill_view`) in 90
+days move to `skills/.archive/` (recoverable); human-authored skills are
+never touched. Pair it with a `HEARTBEAT.md` routine (see
+`lazyclaw workspace init`, which now scaffolds AGENTS / SOUL / TOOLS /
+**HEARTBEAT**) and `lazyclaw cron` to run it on a schedule.
+
 <img src="docs/screenshots/providers.png" alt="lazyclaw providers info anthropic — model list + capabilities" width="760">
 
 ## Workflows (DAG / sequential / persistent)
@@ -372,6 +475,58 @@ lazyclaw daemon --rate-limit 60 --log info    # 60 req/min/IP, JSON access logs
 lazyclaw daemon --once                        # serve a single request, then exit
 ```
 
+### Device gateway — companion nodes (v4.3)
+
+A companion node (a future mobile/menu-bar app, or just `curl`)
+authenticates to the daemon with per-device Ed25519 keys, gated by
+explicit operator approval — the OpenClaw gateway model, realised over
+HTTP + SSE (no extra dependency). The daemon stays loopback-bound;
+expose it remotely only behind a tunnel (Tailscale / Cloudflare) + TLS,
+and set `--auth-token` for the non-gateway routes.
+
+Handshake (all under `/gateway/`, which has its own device-auth so it
+sits outside the daemon's shared `--auth-token` gate):
+
+1. `POST /gateway/connect/challenge` → `{ nonce, ts }` (single-use, time-boxed).
+2. `POST /gateway/connect` with `{ payload, signature, publicKey, nonce }`
+   — the node signs the canonical payload with its Ed25519 key. The
+   gateway verifies the signature, **binds the key to the claimed device
+   id**, enforces nonce single-use (anti-replay) and freshness. An
+   unapproved device gets `403 { status: 'pending', requestId }`; an
+   approved one gets its rotated bearer `token`.
+3. Operator approves out-of-band:
+
+```bash
+lazyclaw nodes pending                 # list pending pairing requests
+lazyclaw nodes approve <requestId>     # mint + rotate the device token (never printed)
+lazyclaw nodes devices                 # approved devices (token masked)
+lazyclaw nodes revoke <deviceId>       # drop a device's approval + token
+```
+
+4. The node reconnects → receives its `token`, then calls authenticated
+   routes with `Authorization: Bearer <token>` + `x-device-id: <id>`:
+   `GET /gateway/whoami` and `GET /gateway/events` (an SSE push stream).
+
+**Remote tool-call approval (SSE event producer).** A trusted local
+caller requests human approval for a sensitive action; the paired device
+approves it from anywhere:
+
+```text
+POST /exec/request {tool,args,summary}   ← auth-token-gated (local/operator)
+   → broadcasts `exec.approval.requested` over /gateway/events
+   → device POSTs /gateway/exec/resolve {id, decision:"approve"}  (device-authed)
+   → the request long-poll resolves { approved, by }  (or denied on timeout)
+```
+
+The MAS tool-use loop accepts an `approve` hook (`runTaskTurn` →
+`runAgentTurn` → `runTool`) that gates the sensitive tools (`bash`,
+`write`) on exactly this decision; read-only tools run ungated. Pending
+approvals are bounded and the summary shown to the device is redacted.
+
+Tokens are stored owner-only (`0600`) under
+`~/.lazyclaw/gateway/devices.json`, compared in constant time, and
+rotated on every re-approval.
+
 ## Cost rate cards
 
 ```bash

package/agents.mjs

@@ -19,8 +19,8 @@ import { ensureValidName as cronEnsureValidName } from './cron.mjs';
 
 const AGENTS_DIRNAME = 'agents';
 
-export const DEFAULT_TOOLS = ['bash', 'read', 'write', 'grep'];
-export const ALL_TOOLS = ['bash', 'read', 'write', 'grep', 'web_search', 'web_fetch', 'slack_post'];
+export const DEFAULT_TOOLS = ['bash', 'read', 'write', 'grep', 'skill_view'];
+export const ALL_TOOLS = ['bash', 'read', 'write', 'grep', 'skill_view', 'web_search', 'web_fetch', 'slack_post'];
 
 export class AgentError extends Error {
   constructor(message, code) {
@@ -80,6 +80,13 @@ function defaultShape(name) {
     // for `lazyclaw agent reflect`; 'off' disables writes entirely.
     memoryWrite: 'auto',
     memoryMaxChars: 12 * 1024,
+    // Phase 20 — self-improving skill synthesis trigger. 'manual'
+    // (default) means a skill is only written when the user runs
+    // `lazyclaw agent skill-synth`; 'auto' fires synthesis on terminal
+    // `done` alongside reflection; 'off' disables it. Defaults to
+    // 'manual' (unlike memoryWrite) because a synthesised SKILL.md
+    // feeds every future agent's prompt, so we keep it opt-in.
+    skillWrite: 'manual',
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
   };
@@ -94,8 +101,9 @@ function writeAtomic(filePath, obj) {
 }
 
 const VALID_MEMORY_WRITE = ['auto', 'manual', 'off'];
+const VALID_SKILL_WRITE = ['auto', 'manual', 'off'];
 
-export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars } = {}, configDir = defaultConfigDir()) {
+export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars, skillWrite } = {}, configDir = defaultConfigDir()) {
   ensureValidName(name);
   const p = agentPath(name, configDir);
   if (fs.existsSync(p)) {
@@ -106,6 +114,10 @@ export function registerAgent({ name, displayName, role = '', provider = 'claude
   if (!VALID_MEMORY_WRITE.includes(mw)) {
     throw new AgentError(`memoryWrite must be one of ${VALID_MEMORY_WRITE.join(', ')}`, 'AGENT_BAD_MEMORY_WRITE');
   }
+  const sw = skillWrite ?? 'manual';
+  if (!VALID_SKILL_WRITE.includes(sw)) {
+    throw new AgentError(`skillWrite must be one of ${VALID_SKILL_WRITE.join(', ')}`, 'AGENT_BAD_SKILL_WRITE');
+  }
   const data = {
     ...defaultShape(name),
     displayName: displayName || titleCase(name),
@@ -117,6 +129,7 @@ export function registerAgent({ name, displayName, role = '', provider = 'claude
     iconEmoji: String(iconEmoji || ''),
     memoryWrite: mw,
     memoryMaxChars: Number.isFinite(+memoryMaxChars) && +memoryMaxChars > 0 ? +memoryMaxChars : 12 * 1024,
+    skillWrite: sw,
   };
   writeAtomic(p, data);
   return data;
@@ -155,6 +168,9 @@ export function patchAgent(name, patch, configDir = defaultConfigDir()) {
   if (patch.memoryWrite !== undefined && !VALID_MEMORY_WRITE.includes(patch.memoryWrite)) {
     throw new AgentError(`memoryWrite must be one of ${VALID_MEMORY_WRITE.join(', ')}`, 'AGENT_BAD_MEMORY_WRITE');
   }
+  if (patch.skillWrite !== undefined && !VALID_SKILL_WRITE.includes(patch.skillWrite)) {
+    throw new AgentError(`skillWrite must be one of ${VALID_SKILL_WRITE.join(', ')}`, 'AGENT_BAD_SKILL_WRITE');
+  }
   writeAtomic(agentPath(name, configDir), next);
   return next;
 }

package/channels/matrix.mjs

@@ -0,0 +1,417 @@
+// Matrix channel adapter.
+//
+// Speaks the Matrix client-server HTTP API directly — no SDK dependency,
+// mirroring Telegram's getUpdates long-poll discipline. Two secrets are
+// read from the constructor or the environment ONLY (never from goal
+// files, never logged):
+//   MATRIX_HOMESERVER    https://matrix.org — the homeserver base URL
+//   MATRIX_ACCESS_TOKEN  syt_…             — bearer token for every call
+//
+// Inbound arrives via long-poll `GET /_matrix/client/v3/sync`: the request
+// is held open up to `timeout` ms; when room timeline events arrive we
+// route every `m.room.message` of `msgtype: m.text` through
+// `_simulateInbound(syncResponse)`, which calls
+// `handler({ channel:'matrix', threadId:'matrix:<roomId>', text, senderId })`
+// and posts the reply with `send()`. The `since` token is advanced from the
+// sync response's `next_batch` ONLY after the batch is processed without
+// throwing, so a failed reply isn't silently dropped (mirrors Telegram's
+// _processBatch offset-after-success discipline).
+//
+// Outbound (`send(threadId, text)`) issues
+// `PUT /_matrix/client/v3/rooms/<roomId>/send/m.room.message/<txnId>` with a
+// unique counter-based txnId so the homeserver doesn't dedupe distinct
+// replies.
+//
+// `start({ poll: false })` validates credentials and registers the handler
+// without bringing up the poll loop, so unit tests can drive
+// `_simulateInbound` / `send` directly. The default poll path is intended to
+// be driven by a `matrix listen` subcommand (mirrors `telegram listen`).
+//
+// LAZYCLAW_MATRIX_API_BASE (or opts.apiBase) overrides the API base URL so
+// the Phase 30 spec can point the adapter at a local mock HTTP server. When
+// unset it defaults to the homeserver.
+
+import { Channel, ChannelGated } from './base.mjs';
+
+const THREAD_PREFIX = 'matrix';
+// Server-side long-poll window for /sync (milliseconds). The homeserver
+// holds the request open up to this long when no events are pending, so an
+// idle bot makes ~1 request per LONG_POLL_MS instead of spinning.
+const LONG_POLL_MS = 30000;
+
+export class MatrixError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'MatrixError';
+    this.code = code || 'MATRIX_ERR';
+  }
+}
+
+// Resolve credentials + base URLs, preferring an explicit override, then
+// the env. Trailing slashes are trimmed so paths join cleanly. apiBase
+// defaults to the homeserver when neither override nor env is set.
+export function readMatrixEnv(env = process.env) {
+  return {
+    homeserver: env.MATRIX_HOMESERVER || null,
+    accessToken: env.MATRIX_ACCESS_TOKEN || null,
+    userId: env.MATRIX_USER_ID || null,
+    apiBase: env.LAZYCLAW_MATRIX_API_BASE || null,
+  };
+}
+
+// Extract the routable text messages from a parsed /sync response. Walks
+// `rooms.join.<roomId>.timeline.events`, keeps only `m.room.message` events
+// whose `content.msgtype` is `m.text`, and returns one normalized event per
+// message. Returns [] for any shape we don't handle so callers can skip
+// without special-casing. Kept as a pure export so the filter is unit
+// testable without a transport.
+export function extractMessageEvents(syncResponse) {
+  if (!syncResponse || typeof syncResponse !== 'object') return [];
+  const join = syncResponse.rooms && syncResponse.rooms.join;
+  if (!join || typeof join !== 'object') return [];
+  const out = [];
+  for (const roomId of Object.keys(join)) {
+    const room = join[roomId];
+    const events = room && room.timeline && Array.isArray(room.timeline.events)
+      ? room.timeline.events
+      : [];
+    for (const ev of events) {
+      if (!ev || typeof ev !== 'object') continue;
+      if (ev.type !== 'm.room.message') continue;
+      const content = ev.content;
+      if (!content || typeof content !== 'object') continue;
+      if (content.msgtype !== 'm.text') continue;
+      const text = typeof content.body === 'string' ? content.body : '';
+      const senderId = ev.sender != null ? String(ev.sender) : null;
+      out.push({
+        roomId,
+        text,
+        senderId,
+        eventId: ev.event_id != null ? String(ev.event_id) : null,
+        threadId: `${THREAD_PREFIX}:${roomId}`,
+      });
+    }
+  }
+  return out;
+}
+
+export class MatrixChannel extends Channel {
+  constructor(opts = {}) {
+    super('matrix');
+    this._env = { ...readMatrixEnv(), ...opts };
+    // apiBase falls back to the homeserver when no override is supplied.
+    if (!this._env.apiBase) this._env.apiBase = this._env.homeserver;
+    // A pairing allowlist of Matrix user ids (strings). When set, only
+    // senders on the list reach the handler; everything else is dropped
+    // silently (no handler call, no reply leak to an unpaired room).
+    const allow = opts.allowlist || opts.allowedSenders || null;
+    this._allowlist = Array.isArray(allow) ? new Set(allow.map((id) => String(id))) : null;
+    this._pollHandle = null;     // { stop() } once the loop is running
+    this._since = opts.since || null; // /sync batch cursor
+    this._txnCounter = 0;        // monotonic txnId source (deterministic-friendly)
+    this._inflight = null;       // AbortController for the held-open /sync
+    // Per-event dedup: when a mid-batch send fails we leave `since`
+    // un-advanced and the homeserver re-delivers the WHOLE batch, so we
+    // remember already-handled event ids (bounded, FIFO-evicted) to avoid
+    // re-replying to events that already got a reply.
+    this._seen = new Set();
+    this._seenOrder = [];
+    this._seenCap = 2000;
+    // Diagnostic sink. Defaults to a no-op until start() wires one up so
+    // _simulateInbound can log internal errors without leaking them to the
+    // room. Replaced (never appended) on every start().
+    this._logger = () => {};
+  }
+
+  // Begin accepting messages. With the default `poll: true` this spins up
+  // the long-poll loop; tests pass `poll: false` to keep the adapter pure
+  // and drive `_simulateInbound` / `send` directly.
+  //
+  // opts (beyond the base gate):
+  //   poll?: boolean          — start the /sync loop (default true)
+  //   since?: string          — initial sync cursor (default none → full sync)
+  //   timeoutMs?: number      — server-side long-poll window (default 30000)
+  //   logger?: (line) => void — diagnostic sink (stderr in CLI, no-op in tests)
+  async start(handler, opts = {}) {
+    if (!this._env.accessToken) {
+      throw new MatrixError(
+        'cannot start Matrix channel without an access token — set MATRIX_ACCESS_TOKEN or pass { accessToken }',
+        'MATRIX_MISSING_TOKEN'
+      );
+    }
+    // The homeserver identifies the bot's domain and is required even when
+    // an explicit apiBase override (test mock) supplies the transport host.
+    if (!this._env.homeserver) {
+      throw new MatrixError(
+        'cannot start Matrix channel without a homeserver — set MATRIX_HOMESERVER or pass { homeserver }',
+        'MATRIX_MISSING_HOMESERVER'
+      );
+    }
+    if (!this._env.apiBase) {
+      throw new MatrixError(
+        'cannot resolve a Matrix API base URL — set MATRIX_HOMESERVER, LAZYCLAW_MATRIX_API_BASE, or pass { apiBase }',
+        'MATRIX_MISSING_API_BASE'
+      );
+    }
+    await super.start(handler, opts);
+    this._logger = typeof opts.logger === 'function' ? opts.logger : () => {};
+    if (typeof opts.since === 'string') this._since = opts.since;
+    this._timeoutMs = typeof opts.timeoutMs === 'number' ? opts.timeoutMs : LONG_POLL_MS;
+    const poll = opts.poll !== false; // default true
+    if (poll) this._startPollLoop({ logger: this._logger });
+    return this;
+  }
+
+  // Called by the poll loop (or tests) for each parsed /sync response. Walks
+  // the room timelines, enforces the self-filter + pairing allowlist, calls
+  // the handler per text message, and posts the reply back to the
+  // originating room. A null / empty-string reply skips the send entirely so
+  // a handler that decides to stay silent doesn't leak a placeholder. Throws
+  // if any send() throws so the caller can decline to advance the `since`
+  // cursor (mirrors Telegram's _processBatch).
+  async _simulateInbound(syncResponse) {
+    const events = extractMessageEvents(syncResponse);
+    for (const evt of events) {
+      // Already handled in a prior (re-delivered) batch → don't re-reply.
+      if (evt.eventId && this._seen.has(evt.eventId)) continue;
+      // Never reply to ourselves — that's an infinite loop. (Not marked
+      // seen: a no-op skip is cheap to re-evaluate, and marking it could
+      // mask a genuinely different later event.)
+      if (this._env.userId && evt.senderId === String(this._env.userId)) continue;
+      // Not paired — drop silently. We deliberately do NOT reply so an
+      // unknown room can't be used to probe the bot. (Also not marked seen
+      // — re-evaluating is a cheap no-op with no side effect.)
+      if (this._allowlist && (!evt.senderId || !this._allowlist.has(evt.senderId))) continue;
+
+      let reply;
+      try {
+        reply = await this._processInbound({
+          threadId: evt.threadId,
+          text: evt.text,
+          // base.mjs's bucket gate reads req.token || req.key, so the sender
+          // id rides under `key`: an authToken gate compares against it and a
+          // rate-limit gate keys per-sender. We keep senderId for downstream
+          // handler context too.
+          gateInput: { key: evt.senderId, senderId: evt.senderId },
+        });
+      } catch (err) {
+        if (err instanceof ChannelGated || err?.code === 'CHANNEL_GATED') {
+          // A gate denial is an expected, user-facing condition; the reason
+          // ('rate_limited' / 'unauthorized') is safe to surface.
+          await this.send(evt.threadId, `(gated: ${err.message})`);
+          this._markSeen(evt.eventId);
+          continue;
+        }
+        // An unexpected handler/transport error may carry internal detail
+        // (stack, secrets in messages). Reply a generic notice to the room
+        // and log the full error to the diagnostic sink only.
+        this._logger(`[matrix] handler error: ${err?.stack || err?.message || err}\n`);
+        try {
+          await this.send(evt.threadId, '(internal error)');
+        } catch (sendErr) {
+          this._logger(`[matrix] failed to deliver error notice: ${sendErr?.message || sendErr}\n`);
+        }
+        this._markSeen(evt.eventId);
+        continue;
+      }
+      if (reply == null || (typeof reply === 'string' && reply.trim() === '')) { this._markSeen(evt.eventId); continue; }
+      // If this send throws, the event is left UNSEEN so the re-delivered
+      // batch retries it (while already-replied events above are skipped).
+      await this.send(evt.threadId, reply);
+      this._markSeen(evt.eventId);
+    }
+  }
+
+  // Remember a handled event id, FIFO-evicting beyond the cap so the set
+  // can't grow without bound on a long-lived listener.
+  _markSeen(eventId) {
+    if (!eventId || this._seen.has(eventId)) return;
+    this._seen.add(eventId);
+    this._seenOrder.push(eventId);
+    if (this._seenOrder.length > this._seenCap) {
+      const old = this._seenOrder.shift();
+      this._seen.delete(old);
+    }
+  }
+
+  // The base _processInbound forwards { channel, threadId, text }; we enrich
+  // the event the router sees with senderId so memory / pairing hooks
+  // downstream can key on the human. Override stays in lockstep with
+  // base.mjs's contract — it only adds fields, never drops them.
+  async _processInbound({ threadId, text, gateInput }) {
+    if (this._gate) {
+      const verdict = this._gate.check(gateInput || {});
+      if (!verdict.ok) {
+        const err = new Error(verdict.reason || 'denied');
+        err.code = 'CHANNEL_GATED';
+        throw err;
+      }
+    }
+    if (!this._handler) throw new Error(`channel "${this.name}" has no handler`);
+    return await this._handler({
+      channel: this.name,
+      threadId,
+      text,
+      senderId: gateInput && gateInput.senderId != null ? gateInput.senderId : null,
+    });
+  }
+
+  // Deliver a reply. threadId encodes the room as `matrix:<roomId>` (the
+  // shape extractMessageEvents emits); a bare room id is also accepted so
+  // callers can address a room directly.
+  async send(threadId, text, _opts = {}) {
+    if (!this._env.accessToken) throw new MatrixError('cannot send without a Matrix access token', 'MATRIX_NO_TOKEN');
+    const roomId = this._decodeRoomId(threadId);
+    if (!roomId) throw new MatrixError(`cannot resolve roomId from threadId "${threadId}"`, 'MATRIX_BAD_THREAD');
+    const txnId = this._nextTxnId();
+    const base = String(this._env.apiBase).replace(/\/$/, '');
+    const url = `${base}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/m.room.message/${encodeURIComponent(txnId)}`;
+    const body = { msgtype: 'm.text', body: String(text) };
+    let res;
+    try {
+      res = await fetch(url, {
+        method: 'PUT',
+        headers: {
+          'Authorization': `Bearer ${this._env.accessToken}`,
+          'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      throw new MatrixError(`matrix send transport error: ${err?.message || err}`, 'MATRIX_TRANSPORT');
+    }
+    if (!res.ok) {
+      throw new MatrixError(`matrix send failed: HTTP ${res.status}`, 'MATRIX_HTTP_FAIL');
+    }
+    const json = await res.json().catch(() => ({}));
+    if (json && json.errcode) {
+      throw new MatrixError(`matrix send failed: ${json.error || json.errcode}`, 'MATRIX_API_FAIL');
+    }
+    return json;
+  }
+
+  // Translate a `matrix:<roomId>` threadId (or a bare room id) into a room
+  // id string. Room ids contain a ':' (e.g. !abc:example), so we only strip
+  // the leading `matrix:` prefix — never split on the first ':'.
+  _decodeRoomId(threadId) {
+    if (threadId == null) return null;
+    const s = String(threadId);
+    if (s.startsWith(`${THREAD_PREFIX}:`)) {
+      const rest = s.slice(THREAD_PREFIX.length + 1);
+      return rest || null;
+    }
+    return s || null;
+  }
+
+  // Monotonic, deterministic-friendly transaction id. The homeserver dedupes
+  // PUT /send retries by (room, txnId), so each distinct reply needs its own
+  // id. We seed with the process start time so a restarted daemon doesn't
+  // collide with a previous run's low counters.
+  _nextTxnId() {
+    this._txnCounter += 1;
+    return `lazyclaw-${this._txnCounter}-${Date.now()}`;
+  }
+
+  // Spin up the long-poll loop. Each iteration issues a single held-open
+  // /sync; the held-open request is what paces the idle loop (no per-turn
+  // sleep). The batch is handed to _simulateInbound which throws if a reply
+  // fails to deliver, in which case we leave `since` un-advanced so the
+  // homeserver re-delivers on the next poll. Errors are logged and the loop
+  // backs off rather than crashing the daemon. The in-flight AbortController
+  // is held so stop() can abort the ~30s held-open request for prompt
+  // shutdown.
+  _startPollLoop({ logger }) {
+    let stopped = false;
+    const loop = async () => {
+      while (!stopped) {
+        try {
+          const sync = await this._fetchSync(() => stopped);
+          if (stopped) break;
+          if (sync) {
+            await this._simulateInbound(sync);
+            // Advance the cursor ONLY after the batch processed without
+            // throwing, so a failed send isn't silently acked away.
+            if (sync.next_batch != null) this._since = sync.next_batch;
+          }
+        } catch (err) {
+          if (stopped) break;
+          if (err?.name === 'AbortError' || err?.code === 'MATRIX_ABORTED') break;
+          // A dead/forbidden token will never recover — stop the listener
+          // and surface it rather than spinning forever on a 500ms back-off.
+          if (err?.code === 'MATRIX_AUTH_FATAL') {
+            logger(`[matrix] FATAL: ${err.message} — stopping listener\n`);
+            this._fatal = err;
+            break;
+          }
+          logger(`[matrix] poll error: ${err?.message || err}\n`);
+          // Back off a beat so we don't spin hot against a failing endpoint.
+          await new Promise((r) => setTimeout(r, 500));
+        }
+      }
+    };
+    const promise = loop();
+    this._pollHandle = {
+      stop: async () => {
+        stopped = true;
+        // Abort the held-open /sync so shutdown doesn't block ~30s.
+        try { this._inflight?.abort(); } catch { /* best-effort */ }
+        try { await promise; } catch { /* best-effort */ }
+      },
+    };
+  }
+
+  // One /sync call. Uses the homeserver's server-side long-poll (timeout in
+  // ms) so an idle bot holds a single request open. The held-open request's
+  // AbortController is stashed in `this._inflight` so stop() can cut it
+  // short. Returns the parsed sync response (or null when aborted mid-flight
+  // during shutdown). Kept separate from the loop so it stays unit-testable.
+  async _fetchSync(isStopped = () => false) {
+    const base = String(this._env.apiBase).replace(/\/$/, '');
+    const params = new URLSearchParams();
+    if (this._since) params.set('since', this._since);
+    params.set('timeout', String(this._timeoutMs ?? LONG_POLL_MS));
+    const url = `${base}/_matrix/client/v3/sync?${params.toString()}`;
+    const controller = new AbortController();
+    this._inflight = controller;
+    let res;
+    try {
+      res = await fetch(url, {
+        method: 'GET',
+        headers: { 'Authorization': `Bearer ${this._env.accessToken}` },
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (err?.name === 'AbortError') {
+        if (isStopped()) return null;
+        const e = new MatrixError('matrix sync aborted', 'MATRIX_ABORTED');
+        throw e;
+      }
+      throw new MatrixError(`matrix sync transport error: ${err?.message || err}`, 'MATRIX_TRANSPORT');
+    } finally {
+      this._inflight = null;
+    }
+    if (!res.ok) {
+      // 401/403 mean the access token is dead/forbidden — retrying forever
+      // is pointless. Mark it fatal so the loop stops and surfaces instead
+      // of spinning on a 500ms back-off against a revoked credential.
+      if (res.status === 401 || res.status === 403) {
+        throw new MatrixError(`matrix sync auth failed: HTTP ${res.status} (check MATRIX_ACCESS_TOKEN)`, 'MATRIX_AUTH_FATAL');
+      }
+      throw new MatrixError(`matrix sync failed: HTTP ${res.status}`, 'MATRIX_HTTP_FAIL');
+    }
+    const json = await res.json().catch(() => ({}));
+    return json && typeof json === 'object' ? json : {};
+  }
+
+  async stop() {
+    if (this._pollHandle && typeof this._pollHandle.stop === 'function') {
+      try { await this._pollHandle.stop(); } catch { /* best-effort */ }
+    }
+    this._pollHandle = null;
+    // Defensive: abort any straggling in-flight request even if the loop
+    // wasn't running (e.g. a bare _fetchSync was driven by a test).
+    try { this._inflight?.abort(); } catch { /* best-effort */ }
+    this._inflight = null;
+    await super.stop();
+  }
+}