@openclaw/crabline 0.1.11 → 0.1.13

package/docs/channel-setup.md

@@ -4,7 +4,7 @@ Crabline is a local mock service for OpenClaw channel contracts. It has two
 surfaces:
 
 - fixture-level local mocks used directly by the Crabline CLI
-- local provider servers that OpenClaw live adapters can target
+- local provider servers that real OpenClaw channel plugins can target
 
 Live channel testing belongs in OpenClaw's live channel adapters. Crabline
 belongs in deterministic smoke CI and local QA where the test needs
@@ -56,6 +56,37 @@ remove stale config blocks or split them into separate provider ids.
 `loopback` has no externally meaningful webhook surface and is primarily useful
 for local direct adapter checks.
 
+## OpenClaw Support Matrix
+
+`ready` platforms have built-in local mock adapters. `bridge` platforms use the
+`script` adapter with commands supplied by the manifest owner.
+
+| Platform        | Status   |
+| --------------- | -------- |
+| `bluebubbles`   | `bridge` |
+| `discord`       | `ready`  |
+| `feishu`        | `ready`  |
+| `googlechat`    | `ready`  |
+| `imessage`      | `ready`  |
+| `irc`           | `bridge` |
+| `line`          | `bridge` |
+| `loopback`      | `ready`  |
+| `matrix`        | `ready`  |
+| `mattermost`    | `ready`  |
+| `msteams`       | `ready`  |
+| `nextcloudtalk` | `bridge` |
+| `nostr`         | `bridge` |
+| `signal`        | `bridge` |
+| `slack`         | `ready`  |
+| `synologychat`  | `bridge` |
+| `telegram`      | `ready`  |
+| `tlon`          | `bridge` |
+| `twitch`        | `bridge` |
+| `webchat`       | `bridge` |
+| `whatsapp`      | `ready`  |
+| `zalo`          | `ready`  |
+| `zalouser`      | `bridge` |
+
 ## Mock Config
 
 ```yaml
@@ -72,12 +103,18 @@ providers:
 ```
 
 Provider credential fields such as `botToken`, `accessToken`, `baseURL`, or
-`serverUrl` are optional mock metadata. They are not required for local mock
-execution.
+`serverUrl` are optional mock metadata for loopback execution. Externally
+reachable Discord webhooks require `publicKey` or `DISCORD_PUBLIC_KEY`.
 
 Optional webhook credentials enforce each provider's native authentication
 header before JSON parsing or recorder writes:
 
+- Authenticated external ingress must set `webhook.publicUrl` to an HTTPS URL;
+  Google Chat may use its HTTPS `endpointUrl` as the signed public callback
+  instead. A non-loopback bind without a public HTTPS endpoint is rejected even
+  when request credentials are configured. Plain HTTP is reserved for local
+  tests where both the listener host and advertised URL host are loopback; that
+  loopback-only case does not require provider callback authentication.
 - Discord `publicKey` or `DISCORD_PUBLIC_KEY` verifies
   `X-Signature-Ed25519` over `X-Signature-Timestamp` plus the raw request body.
 - Google Chat `endpointUrl` verifies Google ID tokens for the configured HTTP
@@ -87,33 +124,45 @@ header before JSON parsing or recorder writes:
   when omitted, and `credentials.client_email` remains the service-account
   email fallback when inline credentials are configured. Wrapped Pub/Sub
   `message.data` must be canonical base64 before Google Chat event
-  normalization.
+  normalization. Direct and wrapped Pub/Sub callbacks are POST-only. Successful
+  direct callbacks receive an empty `200` acknowledgement instead of a
+  synthetic chat message.
   Google Workspace add-on `chat.messagePayload` events are rejected until the
   adapter can bind the verified request to a configured add-on deployment
   identity.
 - Microsoft Teams `appId` or `TEAMS_APP_ID` verifies Bot Connector bearer
   tokens, including the activity channel and exact `serviceUrl`. An `appId` is
-  required when the webhook host is non-loopback or `publicUrl` is set; an
-  unauthenticated webhook remains available only on loopback.
+  required when the webhook host or advertised callback is non-loopback.
 - Matrix webhook ingress currently has no provider-native authentication mode,
-  so it is restricted to loopback hosts and cannot set `publicUrl`.
-- Mattermost and iMessage webhook ingress currently have no provider-native
-  authentication mode, so those adapter webhooks are restricted to loopback
-  hosts and cannot set `publicUrl`. Their API credentials do not authenticate
-  inbound callbacks.
+  so its listener and any advertised callback must remain loopback-only.
+- Mattermost `webhookToken` or `MATTERMOST_TOKEN` verifies the `token` field in
+  outgoing webhook form or JSON bodies. The token is removed before recorder
+  persistence. Externally reachable callbacks require this token and an HTTPS
+  `webhook.publicUrl`. Outgoing webhook ingress is POST-only.
+- iMessage webhook ingress currently has no provider-native authentication
+  mode, so its listener and any advertised callback must remain loopback-only.
 - Feishu `verificationToken` or `FEISHU_VERIFICATION_TOKEN` verifies plaintext
   callback tokens on loopback and remains an additional check when configured
   with encryption. Externally reachable webhooks require `encryptKey` or
-  `FEISHU_ENCRYPT_KEY` to verify `X-Lark-Signature` and decrypt encrypted event
-  envelopes before challenge handling or event normalization.
+  `FEISHU_ENCRYPT_KEY` to verify `X-Lark-Signature` on event callbacks and
+  decrypt encrypted envelopes before normalization. Initial encrypted
+  `url_verification` challenges may omit signature headers and are accepted
+  only when their decrypted token matches the configured verification token.
+  Text events must carry `message.content` as valid JSON containing a string
+  `text` field; malformed JSON is rejected instead of treated as plaintext.
 - Slack `signingSecret` or `SLACK_SIGNING_SECRET` verifies
   `X-Slack-Request-Timestamp` and `X-Slack-Signature`; it is required when the
-  webhook host is non-loopback or `publicUrl` is set.
+  webhook host or advertised callback is non-loopback.
 - Telegram `secretToken` or `TELEGRAM_WEBHOOK_SECRET_TOKEN` verifies
-  `X-Telegram-Bot-Api-Secret-Token`.
+  `X-Telegram-Bot-Api-Secret-Token`. The value must contain 1-256 letters,
+  digits, underscores, or hyphens; control characters are rejected.
 - Zalo `webhookSecret` or `ZALO_WEBHOOK_SECRET` verifies
   `X-Bot-Api-Secret-Token`.
 
+Webhook `path` values must already be canonical URL pathnames. Authority-form
+paths, dot-segment or backslash traversal, query strings, fragments, spaces,
+and other values changed by URL normalization are rejected.
+
 The built-in `whatsapp` adapter implements Meta's GET verification challenge
 and requires `X-Hub-Signature-256` on POST requests. Set `whatsapp.appSecret`
 and `whatsapp.verifyToken` (or `WHATSAPP_APP_SECRET` and
@@ -130,6 +179,9 @@ Treat manifests containing script providers as executable, trusted code.
 Crabline runs their declared commands with the configured environment, so load
 them only from sources you trust and review changes before use.
 
+Crabline does not ship a generic OpenClaw gateway command bridge. Supply and
+version the command implementations with the manifest that uses them:
+
 ```yaml
 providers:
   slack-openclaw:
@@ -141,19 +193,16 @@ providers:
       - OPENCLAW_TOKEN
     script:
       commands:
-        probe: node ./scripts/openclaw-bridge-probe.mjs
-        send: node ./scripts/openclaw-bridge-send.mjs
-        waitForInbound: node ./scripts/openclaw-bridge-wait.mjs
+        probe: node ./bridge/probe.mjs
+        send: node ./bridge/send.mjs
+        waitForInbound: node ./bridge/wait-for-inbound.mjs
 ```
 
-The complete multi-channel script fixture is available in
-`fixtures/examples/openclaw-bridge.yaml`.
-
 Each command receives one JSON document on stdin. Every payload contains the
 parsed `fixture` plus `provider.config`, `provider.id`, and
 `provider.manifestPath`. `send` adds `outbound` with `mode`, `nonce`, normalized
 `target`, and `text`; `waitForInbound` adds `wait` with `excludeIds`, `nonce`,
-`since`, normalized `target`, and `timeoutMs`. A stateless wait bridge must
+`since`, `threadId`, normalized `target`, and `timeoutMs`. A stateless wait bridge must
 exclude messages whose IDs are listed in `excludeIds` while retaining later
 messages with the same timestamp. Crabline retains at most 1024 unmatched IDs
 per wait. `watch` adds `watch` with optional `since` and normalized `target`.
@@ -175,15 +224,92 @@ watch commands are terminated when cancellation fires.
 
 ## Local Provider Servers
 
-Server-backed channels currently include Mattermost, Matrix, Signal, Slack,
-Telegram, WhatsApp, and Zalo. Loopback binds retain stable local credentials for
-fixture compatibility. Non-loopback binds generate fresh provider-shaped
-credentials unless the corresponding token or secret option is supplied.
+Server-backed channels currently include Discord, Mattermost, Matrix, Signal,
+Slack, Telegram, WhatsApp, and Zalo. Loopback binds retain stable local
+credentials for deterministic tests. Non-loopback binds generate fresh provider-shaped
+credentials unless the corresponding credential is supplied.
+WhatsApp is loopback-only because its HTTP and WebSocket endpoints carry bearer
+credentials over cleartext and the built-in server does not terminate TLS.
+
+Commands in this section use the installed-package form. In a source checkout,
+replace `crabline` with `pnpm dev`; `pnpm exec crabline` is not available.
+
+`serve` rejects credential values in command-line arguments because argv and
+shell history are not secret-safe. Use the `CRABLINE_ADMIN_TOKEN`,
+`CRABLINE_ACCESS_TOKEN`, `CRABLINE_BOT_TOKEN`, and
+`CRABLINE_SIGNING_SECRET` environment fallbacks, or pass a JSON object through
+a file descriptor. Package runners should use stdin:
+
+```bash
+pnpm dev --json serve slack --credentials-fd 0 < .crabline/serve-credentials.json
+```
+
+The installed CLI can also use an inherited descriptor when its launcher
+preserves descriptors above 2:
+
+```bash
+crabline --json serve slack --credentials-fd 3 3< .crabline/serve-credentials.json
+```
+
+The accepted JSON fields are `adminToken`, `accessToken`, `botToken`, and
+`signingSecret`. The input is bounded to 64 KiB, must contain only string
+values, and overrides environment fallbacks field by field. Do not pass
+descriptors above 2 through package runners such as `pnpm`; use fd 0 instead.
+Keep credential files owner-readable or pipe the JSON directly from a secret
+manager.
+
+Ready files contain generated provider and admin credentials. Crabline creates
+or replaces them with POSIX mode `0600`, but the parent directory still needs
+to be private. Exclude ready files from version control and CI artifact
+collection, and delete them after use. On non-POSIX or shared filesystems,
+verify the effective ACLs before publishing one.
 
-Serve credential flags take precedence over their optional environment
-fallbacks: `--admin-token` over `CRABLINE_ADMIN_TOKEN`, `--access-token` over
-`CRABLINE_ACCESS_TOKEN`, `--bot-token` over `CRABLINE_BOT_TOKEN`, and
-`--signing-secret` over `CRABLINE_SIGNING_SECRET`.
+### Discord
+
+```bash
+crabline --json serve discord --ready-file .crabline/discord-server.json
+```
+
+The ready manifest exposes `applicationId`, `botUserId`, `botToken`,
+`endpoints.apiRoot`, `endpoints.gatewayBotUrl`, `endpoints.gatewayUrl`,
+`endpoints.adminInboundUrl`, `adminToken`, and `recorderPath`. OpenClaw-specific
+endpoint injection and target translation belong to the Crabline OpenClaw
+bridge and the OpenClaw Discord plugin; the provider server itself implements
+Discord's public protocol subset and contains no OpenClaw behavior.
+
+Post an inbound user message to `endpoints.adminInboundUrl` with the manifest's
+admin token:
+
+```json
+{
+  "channelId": "135000000000000010",
+  "guildId": "135000000000000011",
+  "senderId": "135000000000000012",
+  "senderName": "Alice",
+  "content": "hello"
+}
+```
+
+The control plane creates provider state and emits a normal Discord
+`MESSAGE_CREATE` dispatch on an identified Gateway session. `parentChannelId`
+turns `channelId` into a public thread channel. Supported client boundaries are
+REST v10 bot/application identity, Gateway metadata, guild/channel/member
+lookups, DM creation, text message create/read/reply, typing, application
+command registration, and a v10 JSON Gateway with HELLO, IDENTIFY, READY,
+heartbeat acknowledgement, resume, and deterministic shutdown.
+
+Current fidelity limits are one Gateway shard, no transport compression, and no
+missed-dispatch replay: resume succeeds only from the retained session's latest
+sequence. The server also omits voice, interaction dispatch,
+attachment/multipart upload, and Discord's distributed permission or
+bucket-allocation systems.
+The server still returns provider-native authentication, JSON error, and basic
+rate-limit headers for its supported routes.
+
+This is not the fixture-level Discord local mock. The fixture adapter's
+interactions webhook remains available to Crabline fixture commands; the
+Discord provider server exists so the real OpenClaw Discord plugin can use
+normal REST and Gateway transports without contacting Discord.
 
 ### Mattermost
 
@@ -198,11 +324,16 @@ and credential. Because the server is loopback HTTP, trusted QA configuration
 must also set `channels.mattermost.network.dangerouslyAllowPrivateNetwork` to
 `true`. The OpenClaw bridge does this automatically.
 
-Admin inbound accepts `channelId`, `senderId`, `text`, optional `senderName`,
-`channelType`, and `rootId`. It emits the message through Mattermost's native
-`/api/v4/websocket` `posted` event. Text sends through `POST /api/v4/posts` are
-written to the manifest's recorder. QA agent delivery currently supports DM and
-channel targets; thread targets require the later OpenClaw QA wiring step.
+Admin inbound accepts 26-character lowercase alphanumeric Mattermost
+`channelId` and `senderId` values, `text`, optional `senderName`, `channelType`,
+`rootId`, `channelName`, and `channelDisplayName`; `rootId`, when present, uses
+the same strict 26-character format. It emits the message through Mattermost's
+native `/api/v4/websocket` channel-scoped `posted` event, including the
+configured channel names. Text sends through `POST /api/v4/posts` require a
+JSON media type and are written to the manifest's recorder. Fixture and QA
+channel/user targets must use provider-native Mattermost IDs rather than local
+labels. QA agent delivery currently supports DM and channel targets; thread
+targets require the later OpenClaw QA wiring step.
 
 The server itself is provider-shaped and has no OpenClaw runtime dependency. It
 implements Mattermost REST error/status behavior plus WebSocket authentication,
@@ -225,10 +356,17 @@ because the server is loopback HTTP, enable
 applies those settings automatically.
 
 Admin inbound accepts native `roomId`, `senderId`, and `text` fields plus
-optional `senderName` and `threadId`. It queues a native `m.room.message` event
-for delivery through Matrix `/sync`. Outbound room sends through
-`PUT /_matrix/client/v3/rooms/:roomId/send/:eventType/:txnId` are written to the
-manifest recorder.
+optional `senderName`, `roomName`, `direct`, and `threadId`. `roomName` names a
+newly created room, while `direct: true` marks membership as direct and
+publishes the room through `m.direct` account data. `threadId` is the raw Matrix
+root event ID, such as `$eventid:matrix.org`; Crabline emits it as both the
+`m.thread` relation target and `m.in_reply_to` root. The resulting native
+`m.room.message` event is delivered through Matrix `/sync`. Outbound room sends
+through `PUT /_matrix/client/v3/rooms/:roomId/send/:eventType/:txnId` are
+written to the manifest recorder.
+
+Post admin inbound payloads to the manifest's `endpoints.adminInboundUrl` with
+its `adminToken` in the `X-Crabline-Admin-Token` header.
 
 The provider server implements the unencrypted Client-Server API subset needed
 by the normal Matrix SDK: versions, `whoami`, filters, push rules, joined rooms
@@ -245,6 +383,17 @@ outcome together with the provider's exact send method and path. Rejected
 requests and lookalike route suffixes can remain diagnostic recorder entries,
 but they are never exposed as successful outbound deliveries.
 
+Use one filesystem name per recorder file. When multiple server processes must
+run without one shared writable OS account home or write through hardlinks to
+the same recorder inode, set
+`CRABLINE_RECORDER_LOCK_DIR` to one absolute writable directory shared by every
+writer and pre-create its ownership, group, or ACLs. Hardlinked server-recorder
+writes fail closed when this shared lock namespace is absent. The path must be
+canonical and contain no symlink components. Use a separate lock directory per
+recorder filesystem; lock identities omit device numbers so containers that
+mount the same inode under different device IDs still coordinate. Otherwise,
+Unix writers use `~/.cache/crabline/locks/server-recorder`.
+
 Slack:
 
 ```bash
@@ -273,7 +422,10 @@ The admin ingress accepts JSON like:
 ```
 
 OpenClaw consumes that message through Slack Events API shape; outbound adapter
-sends are recorded through Slack `chat.postMessage`.
+sends are recorded through Slack `chat.postMessage`. Outbound direct sends may
+use native user IDs beginning with `U` or `W`; Crabline opens the corresponding
+DM conversation before posting. Admin inbound still requires a conversation ID
+beginning with `C`, `D`, or `G` plus a sender user ID beginning with `U` or `W`.
 
 Signal:
 
@@ -321,8 +473,9 @@ Manifest fields:
 - `endpoints.adminInboundUrl`: authenticated admin ingress for test user messages
 - `recorderPath`: JSONL provider traffic recorder
 
-The admin token is generated randomly unless `--admin-token <token>` is
-provided. Requests may also use `Authorization: Bearer <token>`.
+The admin token is generated randomly unless `adminToken` is supplied through
+the credential ingress above. Requests may also use
+`Authorization: Bearer <token>`.
 
 The admin ingress accepts JSON like:
 
@@ -338,6 +491,16 @@ The admin ingress accepts JSON like:
 OpenClaw consumes that message through Telegram `getUpdates`; outbound adapter
 sends are recorded through Telegram `sendMessage` and the media send endpoints
 `sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, and `sendAnimation`.
+Compatible clients may switch to webhook delivery with `setWebhook`, including
+an optional `secret_token` that Crabline returns as
+`X-Telegram-Bot-Api-Secret-Token`. `deleteWebhook` restores polling. While a
+webhook is configured, `getUpdates` returns Telegram's native conflict error
+instead of consuming updates. The secret accepts only 1-256 letters, digits,
+underscores, or hyphens. Bot API text fields are string-only and limited to
+4,096 UTF-16 code units; media captions are string-only and limited to 1,024.
+Admin-injected message entities preserve native `url`, `user`, `language`, and
+`custom_emoji_id` metadata. Calls addressed to `@username` return a numeric
+`Chat.id`, as Telegram does.
 
 WhatsApp:
 
@@ -362,7 +525,6 @@ Manifest fields:
 - `endpoints.adminInboundUrl`: authenticated admin ingress for test user
   messages using the WhatsApp Business webhook payload shape
 - `endpoints.messagesUrl`: provider-native Cloud API message and status endpoint
-- `endpoints.statusUrl`: alias for the same provider-native status endpoint
 - `recorderPath`: JSONL provider traffic recorder for HTTP traffic and Baileys
   WebSocket stanzas. Multi-message webhook deliveries use one versioned batch
   line that Crabline's recorder APIs flatten into individual events.
@@ -378,7 +540,8 @@ Group outbound uses sender-key `skmsg` encryption and is outside this supported
 subset, so OpenClaw Crabline outbound targets are direct users only. Group
 inbound injection remains supported. The WebSocket endpoint rejects clients
 that do not present the access token embedded in the manifest URL. The admin
-token is generated randomly unless `--admin-token <token>` is provided.
+token is generated randomly unless `adminToken` is supplied through the
+credential ingress above.
 
 OpenClaw bridge callers should post injected user messages with the
 `providerUrl`, `providerHeaders`, and `providerBody` returned by
@@ -394,8 +557,8 @@ The admin ingress accepts JSON like:
 }
 ```
 
-Outbound text sends and composing presence are recorded through the fake
-provider messages and presence endpoints.
+Outbound text sends and composing presence are recorded through the local
+provider server's messages and presence endpoints.
 
 ### Zalo Server
 
@@ -410,6 +573,10 @@ Set trusted `ZALO_API_URL` to `endpoints.apiRoot` and configure the emitted
 does this mapping without adding provider-server-specific behavior to the Zalo
 adapter.
 
+For admin ingress, POST to the manifest's `endpoints.adminInboundUrl`
+(`/crabline/zalo/inbound`) and send the manifest's `adminToken` in
+`X-Crabline-Admin-Token`. `Authorization: Bearer <adminToken>` is also accepted.
+
 The server accepts the provider-native `/bot<TOKEN>/<METHOD>` API shape over
 GET or POST. It implements bot identity, single-update long polling, text and
 photo sends, chat actions, and webhook lifecycle calls. A configured webhook
@@ -418,6 +585,10 @@ receives the native Zalo `{ event_name, message }` update directly with
 otherwise injected messages are returned by `getUpdates`. Provider errors use
 Zalo's `{ ok, error_code, description }` shape.
 
+Programmatic `startZaloServer()` callers can tune the retained polling queue
+with `maxPendingInboundEvents` and `maxPendingInboundBytes`; the byte limit
+defaults to 64 MiB and remains reserved until the polling response commits.
+
 `setWebhook` requires HTTPS, matching Zalo's public API. A loopback-bound
 Crabline server also accepts a loopback HTTP URL for independent local client
 tests. Non-loopback binds reject webhook destinations that resolve to private,
@@ -475,11 +646,17 @@ Targets use native channel identifiers. Crabline does not add local prefixes suc
 as `telegram:`, `discord:`, or `slack:`.
 
 - Slack conversations: `C1234567890`, `G1234567890`, or `D1234567890`
+- Slack direct sends may also target user IDs such as `U1234567890` or
+  `W1234567890`
 - Slack threads: `1700000000.000100`
 - Telegram chats: `-1001234567890` or `@channelusername`
 - Telegram topics: `42`
+- Telegram username targets require `@`, contain 5-32 letters, digits, or
+  underscores, and normalize to lowercase. Numeric chat IDs must be nonzero and
+  have an absolute value no greater than `2^52 - 1`.
 - Built-in WhatsApp Cloud API users: digits-only `wa_id` values such as
   `15551234567`
+- Built-in WhatsApp Cloud API fixtures do not support `threadId` targets.
 - OpenClaw WhatsApp bridge users: `15551234567@s.whatsapp.net`
   (legacy `15551234567@c.us` inputs are accepted and canonicalized)
 - OpenClaw WhatsApp bridge groups: `120363001234567890@g.us`
@@ -487,8 +664,16 @@ as `telegram:`, `discord:`, or `slack:`.
   `123456789012345678`
 - Google Chat spaces: `spaces/AAAABbbbCCC`
 - Google Chat threads: `spaces/AAAABbbbCCC/threads/BBBBccccDDD`
+- iMessage recipients: E.164 phone numbers such as `+15551234567`, email
+  addresses such as `user@example.com`, or chat GUIDs such as
+  `iMessage;-;chat-guid` and `SMS;+;chat-guid`
 - Matrix rooms: scoped ids such as `!abcdef:matrix.org` or Matrix v12
   domainless room ids
+- Matrix threads: raw root event ids such as `$eventid:matrix.org`
+- Mattermost channels, users, and root posts: exactly 26 lowercase alphanumeric
+  characters, such as `abcdefghijklmnopqrstuvwx12`
+- Microsoft Teams: non-empty opaque Bot Connector `conversation.id` values such
+  as `a:opaque-conversation-id` or `19:conversation@thread.v2`
 - Zalo users, OAs, and chats: provider-native non-whitespace string ids such as
   `user-1` or `group-1`
 
@@ -500,7 +685,7 @@ chat IDs must be negative. Zero is invalid for every Telegram target kind.
 
 ## Smoke CI Guidance
 
-For deterministic CI, use Crabline through a mock channel driver:
+For deterministic CI, use the Crabline channel driver:
 
 ```yaml
 profile: smoke-ci
@@ -524,15 +709,18 @@ roundtrip. Real OpenClaw channel proof comes from QA scenarios that launch the
 gateway and run its normal channel adapter against the local provider.
 
 Crabline stages the manifest, capability report, and provider-readiness report
-inside one owner-only generation directory under the legacy
-`.crabline-smoke-artifacts/` store name, atomically installs the complete
+inside one owner-only generation directory under the
+`.crabline-channel-driver-artifacts/` store name, atomically installs the complete
 directory, and then atomically switches the single `current.json` pointer.
 Readers therefore see either the prior complete generation or the next complete
 generation, never per-file mixtures. Setup, probe, cleanup, staging, or
-ownership failures leave the prior pointer unchanged. Crash-leftover staging
-directories and installed-but-uncommitted generations remain owner-only and are
-not removed automatically: a lease that can expire cannot safely authorize a
-resumed stale process to delete another publisher's generation.
+ownership failures leave the prior pointer unchanged. A successful probe must
+also produce at least one valid JSONL recorder evidence record before
+publication. Crash-leftover staging
+directories and installed-but-uncommitted generations remain owner-only.
+Publication rollback removes them when possible, and the next lock-owning
+publisher prunes any leftovers before staging a new generation. Post-commit
+cleanup retains only the current and previous pointer generations.
 
 POSIX generation directories use mode `0700` and files use mode `0600`. Windows
 hosts require `powershell.exe` with `Set-Acl`; Crabline resolves it from the
@@ -545,17 +733,16 @@ contain `capabilityReport` and `providerReadiness` payloads while their manifest
 capability, and provider-readiness paths identify the authoritative immutable
 generation.
 
-Lock owners record both PID and process-start identity. Dead owners, and stale
-locks whose PID was reused by the next Crabline process, are reclaimed on the
-next run. New lock owners renew a 10-minute lease while the readiness run
-remains active, so a live run retains exclusive ownership beyond the initial
-lease. A heartbeat failure or lost ownership aborts publication before the
-generation is committed. Recovery first atomically moves a stale candidate away
-from the heartbeat path, then revalidates its token-specific lease before
-deletion; a renewal that wins the rename race is restored rather than reclaimed.
-The lease also bounds stale locks when an unrelated live process has inherited
-the abandoned PID. Older owner records remain PID-protected for compatibility
-and are reclaimed only after their recorded process exits.
+Lock owners use one versioned format containing the PID, process-start identity,
+and token-specific lease. Both the acquisition reservation and owner claim renew
+their 10-minute leases while the readiness run remains active, so a live run
+retains exclusive ownership beyond the initial lease. A heartbeat failure or
+lost ownership aborts publication before the generation is committed. Recovery
+first atomically moves a stale reservation into a uniquely named recovery claim,
+then revalidates its token-specific lease before deletion; a renewal that wins
+the rename race is restored rather than reclaimed. The lease also bounds stale
+locks when an unrelated live process has inherited the abandoned PID. Malformed
+or unversioned owner records fail closed and are not migrated or recovered.
 
 For release or live verification, use OpenClaw's live driver:
 

package/fixtures/examples/crabline.example.yaml

@@ -89,6 +89,7 @@ providers:
   mattermost:
     adapter: mattermost
     mattermost:
+      # webhookToken: sample
       recorder:
         path: ./.crabline/recorders/mattermost.jsonl
       webhook:
@@ -184,7 +185,7 @@ fixtures:
     provider: mattermost
     mode: roundtrip
     target:
-      id: channel-id
+      id: aaaaaaaaaaaaaaaaaaaaaaaaaa
 
   - id: zalo-chat
     provider: zalo
@@ -202,4 +203,4 @@ fixtures:
     provider: imessage
     mode: roundtrip
     target:
-      id: chat-guid
+      id: iMessage;-;chat-guid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/crabline",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Standalone CLI for deterministic messaging provider E2E tests",
   "homepage": "https://github.com/openclaw/crabline#readme",
   "bugs": {
@@ -19,7 +19,7 @@
     "dist/src",
     "README.md",
     "docs/channel-setup.md",
-    "fixtures"
+    "fixtures/examples/crabline.example.yaml"
   ],
   "type": "module",
   "main": "./dist/src/index.js",
@@ -39,14 +39,15 @@
     "fixtures": "tsx src/bin/crabline.ts fixtures",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
-    "lint": "pnpm format:check && pnpm typecheck && oxlint --deny-warnings --allow vitest/require-mock-type-parameters --type-aware --tsconfig tsconfig.test.json src test",
+    "lint": "pnpm format:check && pnpm typecheck && oxlint --deny-warnings --allow vitest/require-mock-type-parameters --type-aware --tsconfig tsconfig.test.json src test tools vitest.config.ts",
     "prepare": "npm run build",
     "run": "tsx src/bin/crabline.ts run",
     "test": "vitest run",
+    "test:autoreview": "vitest run test/autoreview-tooling.test.ts && node tools/run-autoreview-tests.mjs",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.test.json",
-    "verify": "pnpm lint && pnpm test:coverage",
+    "verify": "pnpm lint && pnpm test:autoreview && pnpm build && pnpm test:coverage",
     "check": "pnpm verify"
   },
   "dependencies": {
@@ -57,7 +58,7 @@
     "picocolors": "^1.1.1",
     "proper-lockfile": "4.1.2",
     "re2js": "2.8.6",
-    "ws": "^8.21.0",
+    "ws": "^8.21.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
@@ -68,15 +69,22 @@
     "@vitest/coverage-v8": "^4.1.10",
     "baileys": "7.0.0-rc13",
     "matrix-js-sdk": "41.9.0",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
-    "oxlint-tsgolint": "^0.24.0",
-    "tsx": "^4.23.0",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsx": "^4.23.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.10"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "onFail": "error",
+      "version": ">=22.13.0"
+    }
+  },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@10.32.1"
+  "packageManager": "pnpm@11.17.0"
 }