Run any Skill in Manus with one click

slack-relayfile-writeback-debugging

Stars1

Forks0

UpdatedJune 9, 2026 at 07:50

Use when an outbound Slack writeback (channel post, thread reply, or DM) silently fails to deliver — no error, no dead-letter. Covers the writeback pipeline, the relayfile ops-API getOp recipe to read the persisted lastError, where the Slack error actually surfaces (NOT the consumer logs), the missing_scope/im:write 3-place fix, cf-vs-bridge dispatch, and duplicate/silent-send pitfalls.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

AgentWorkforce

AgentWorkforce/workforce

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	slack-relayfile-writeback-debugging
description	Use when an outbound Slack writeback (channel post, thread reply, or DM) silently fails to deliver — no error, no dead-letter. Covers the writeback pipeline, the relayfile ops-API getOp recipe to read the persisted lastError, where the Slack error actually surfaces (NOT the consumer logs), the missing_scope/im:write 3-place fix, cf-vs-bridge dispatch, and duplicate/silent-send pitfalls.

Debugging Slack writeback non-delivery (relayfile ↔ cloud)

You are diagnosing why an outbound Slack writeback did not reach Slack. A writeback is a JSON file dropped under a mounted command root (…/channels/<id>__<slug>/messages[/<ts>/replies]/<file>.json or …/users/<U>/messages/<file>.json). Confirm with evidence, never a hypothesis.

Pipeline (cloud, AgentWorkforce/cloud)

local file → mount pushes up → ingest creates a writeback OP → WRITEBACK_QUEUE
  → batch executor → cf OR bridge provider → Slack API

Ingest → op: packages/relayfile/src/durable-objects/handlers/ops.ts recordMutations (~1043-1101) makes a writeback op for ANY agent_write; provider_sync origin is suppressed (returns "succeeded" with NO op).
Queue consumer (batch): packages/relayfile/src/queue-consumer.ts:71 → executeProviderWritebackBatch. It logs ONLY writeback.start (provider-executor.ts:258) — never the Slack error. So wrangler tail relayfile-writeback-consumer confirms dispatch but never shows why it failed.
Path allowlist: provider-executor.ts getUnsupportedReason (951-1010); SLACK_UPSERT_WRITEBACK_PATH (1203-1205) — includes users/<U>/messages (DM path allowed).
cf-vs-bridge fork: :132 (single) / :288 (batch). Default writeback_dispatch_via = bridge (workspace.ts:1062); cf has the idempotency guard the bridge lacks (cloud#1985).

THE diagnostic: read the op's lastError (ground truth)

curl -H "Authorization: Bearer <token from <mount>/.relay/creds.json>" \
     -H "X-Correlation-Id: anything" \
     https://api.relayfile.dev/v1/workspaces/<rw_id>/ops/<opId>

⚠️ X-Correlation-Id is required — without it: HTTP 400 missing X-Correlation-Id header.
base = DEFAULT_RELAYFILE_BASE_URL = https://api.relayfile.dev.
<rw_id>: grep the mount's .relay/state.json for "workspaceId".
token: .relay/creds.json token (JWT, has ops:read; re-minted ~hourly — re-read it).
<opId>: from the writeback.start log, or list …/ops?limit=N and match path.
Result: {status, lastError, attemptCount}. status:failed + attemptCount:0 = a permanent (non-retryable) failure that is not dead-lettered and not surfaced — the "silent, no error" signature.
The error ALSO surfaces as the cf audit event console.info("[relayfile] writeback audit event", {event}) in cloud-web-worker (event.metadata.slackError) — but getOp is faster + persisted.

Known failure modes → fix

lastError: missing_scope on a DM → the Slack app lacks im:write. DM send calls conversations.open (needs im:write) before chat.postMessage; channels only need chat:write (so channels work, DMs don't). missing_scope isn't retryable (providers/slack.ts:476-485) → permanent_failure → silent. Fix = 3 places, in order: (1) Slack app → Bot Token Scopes → add im:write(+mpim:write) → reinstall; (2) Nango dashboard → add the same to the slack-relay integration's requested scopes (the OAuth request set lives here, NOT in the repo — easy to miss); (3) re-OAuth/reconnect (existing tokens get no retroactive grant). Verify: re-fire → getOp succeeded.
Duplicate posts → the legacy bridge path lacks the cf idempotency guard. Delete the command file after confirmed delivery; migrate the workspace to cf (cloud#1977).
Silently never sent (looks clean) → on a poll mount the push is ~30s-cadence. The workspace revision counter is GLOBAL (not a dispatch signal); deleting the command file before a push cycle uploads it = silent non-delivery. Confirm dispatch by: operator receipt, OR the file surviving ≥1–2 cycles with pendingWriteback 1→0, OR (top-level) the bot echo in the flat messages/<ts>/ tree. Thread REPLIES never echo.
mirror does NOT auto-delete dispatched command files — manual delete-after-send is still required, or a future clearState re-dispatches them.

Don't

Don't conclude from wrangler tail of the consumer (it only logs writeback.start).
Don't blame adapter version: @relayfile/adapter-slack 0.3.9 already resolves DM→post_dm; cloud#1997 was a READ-side fix. The send path is present + deployed — the gap is almost always scope/config, confirmed via getOp.

More from this repository

same repository

auto-merge-and-composition-safety

AgentWorkforce/workforce

Use before auto-merging any PR in an autonomous run, and between consecutive merges that touch overlapping code. Covers the per-PR auto-merge bar (live CI verification, substantive review by area, bot-finding stale-vs-actionable triage) and the cross-PR composition discipline (serialize through green main, rebase + re-CI between merges, dormant-safety audit, force-reset over half-merged commits).

2026-06-101

autonomous-run-contract

AgentWorkforce/workforce

Use at the start of every autonomous, multi-PR, cutover-class delegated run. Authors the binding contract between operator and agent — the gates, the flip mechanism, the rollback triggers, the standing constraints, and the explicit escalate-to-human conditions — and surfaces it to the operator for explicit grant of (a) auto-merge authority, (b) flip-the-switch authority, (c) swarm-blockers authority. No autonomous work begins until the contract is acknowledged.

2026-06-101

dormant-flip-and-rollback

AgentWorkforce/workforce

Use when designing or executing a cutover-class change (migration, ingestion path swap, provider relink, flag enablement). Encodes the dark-launch + single-switch flip pattern, the refusal to flip on amber, and the pre-authorized rollback procedure — the canonical way to make irreversible-feeling infra changes reversible-feeling.

2026-06-101

instrument-dont-guess

AgentWorkforce/workforce

Use when a fix has failed two consecutive times for the same symptom. Encodes the discipline that the third action must be a temporary diagnostic (a /_diag endpoint, an enriched structured log, a runtime-captured snapshot) rather than another fix attempt. Also covers the discipline for removing those diagnostics once the real root cause is in.

2026-06-101

swarm-blockers-and-gate-scoreboard

AgentWorkforce/workforce

Use during an autonomous run to (a) dispatch supporting codex-impl + claude-review agent pairs against hard blockers when the orchestrator cannot make progress alone, and (b) maintain the live RED / GREEN gate scoreboard the orchestrator reads to authorize the flip. Encodes the file-based reporting convention that keeps the channel readable.

2026-06-101

tiered-acceptance

AgentWorkforce/workforce

Use when a single gate would require deep proof across a large set (44 models × 10 providers; 60+ resources; every region; every plan tier). Splits the acceptance into tier-1 (deep proof on high-volume / high-fidelity slice) and tier-2 (smoke proof on low-volume tail), documents the explicit accepted trade-off, and preserves safety through dormant-default + per-item enable + rollback.

2026-06-101

name	slack-relayfile-writeback-debugging
description	Use when an outbound Slack writeback (channel post, thread reply, or DM) silently fails to deliver — no error, no dead-letter. Covers the writeback pipeline, the relayfile ops-API getOp recipe to read the persisted lastError, where the Slack error actually surfaces (NOT the consumer logs), the missing_scope/im:write 3-place fix, cf-vs-bridge dispatch, and duplicate/silent-send pitfalls.

Debugging Slack writeback non-delivery (relayfile ↔ cloud)

Pipeline (cloud, AgentWorkforce/cloud)

local file → mount pushes up → ingest creates a writeback OP → WRITEBACK_QUEUE
  → batch executor → cf OR bridge provider → Slack API

Ingest → op: packages/relayfile/src/durable-objects/handlers/ops.ts recordMutations (~1043-1101) makes a writeback op for ANY agent_write; provider_sync origin is suppressed (returns "succeeded" with NO op).
Queue consumer (batch): packages/relayfile/src/queue-consumer.ts:71 → executeProviderWritebackBatch. It logs ONLY writeback.start (provider-executor.ts:258) — never the Slack error. So wrangler tail relayfile-writeback-consumer confirms dispatch but never shows why it failed.
Path allowlist: provider-executor.ts getUnsupportedReason (951-1010); SLACK_UPSERT_WRITEBACK_PATH (1203-1205) — includes users/<U>/messages (DM path allowed).
cf-vs-bridge fork: :132 (single) / :288 (batch). Default writeback_dispatch_via = bridge (workspace.ts:1062); cf has the idempotency guard the bridge lacks (cloud#1985).

THE diagnostic: read the op's lastError (ground truth)

curl -H "Authorization: Bearer <token from <mount>/.relay/creds.json>" \
     -H "X-Correlation-Id: anything" \
     https://api.relayfile.dev/v1/workspaces/<rw_id>/ops/<opId>

⚠️ X-Correlation-Id is required — without it: HTTP 400 missing X-Correlation-Id header.
base = DEFAULT_RELAYFILE_BASE_URL = https://api.relayfile.dev.
<rw_id>: grep the mount's .relay/state.json for "workspaceId".
token: .relay/creds.json token (JWT, has ops:read; re-minted ~hourly — re-read it).
<opId>: from the writeback.start log, or list …/ops?limit=N and match path.
Result: {status, lastError, attemptCount}. status:failed + attemptCount:0 = a permanent (non-retryable) failure that is not dead-lettered and not surfaced — the "silent, no error" signature.
The error ALSO surfaces as the cf audit event console.info("[relayfile] writeback audit event", {event}) in cloud-web-worker (event.metadata.slackError) — but getOp is faster + persisted.

Known failure modes → fix

lastError: missing_scope on a DM → the Slack app lacks im:write. DM send calls conversations.open (needs im:write) before chat.postMessage; channels only need chat:write (so channels work, DMs don't). missing_scope isn't retryable (providers/slack.ts:476-485) → permanent_failure → silent. Fix = 3 places, in order: (1) Slack app → Bot Token Scopes → add im:write(+mpim:write) → reinstall; (2) Nango dashboard → add the same to the slack-relay integration's requested scopes (the OAuth request set lives here, NOT in the repo — easy to miss); (3) re-OAuth/reconnect (existing tokens get no retroactive grant). Verify: re-fire → getOp succeeded.
Duplicate posts → the legacy bridge path lacks the cf idempotency guard. Delete the command file after confirmed delivery; migrate the workspace to cf (cloud#1977).
Silently never sent (looks clean) → on a poll mount the push is ~30s-cadence. The workspace revision counter is GLOBAL (not a dispatch signal); deleting the command file before a push cycle uploads it = silent non-delivery. Confirm dispatch by: operator receipt, OR the file surviving ≥1–2 cycles with pendingWriteback 1→0, OR (top-level) the bot echo in the flat messages/<ts>/ tree. Thread REPLIES never echo.
mirror does NOT auto-delete dispatched command files — manual delete-after-send is still required, or a future clearState re-dispatches them.

Don't

Don't conclude from wrangler tail of the consumer (it only logs writeback.start).
Don't blame adapter version: @relayfile/adapter-slack 0.3.9 already resolves DM→post_dm; cloud#1997 was a READ-side fix. The send path is present + deployed — the gap is almost always scope/config, confirmed via getOp.