Route does not start a run

Use this when public intake is working at the provider, but Viewport does not queue the expected governed run.

The path has four gates:

provider event -> integration endpoint -> .viewport route match -> composed policy version -> worker claim

Debug in that order. Do not start by restarting the worker if no run was queued.

1. Confirm The Config Actually Synced

Open Settings -> Sync for the team and verify:

• sync status is synced;
• the short SHA is the commit that contains your latest .viewport/ changes;
• route count is greater than zero;
• no repeated HMAC failure is shown;
• the route points at the policy file you expect.

Then run this in the repo:

vpd check .
git status --ignored .viewport

vpd check . must pass, and .viewport/ must not be ignored. The committed shape is:

.viewport/
  policy.yaml
  routes/
    slack-support.yaml

The route file must use the route: envelope:

route:
  name: slack-support
  team: platform
  trigger:
    integration: slack
    events: ["app_mention"]
    conditions:
      channel: C1234567890
      mentionsAny:
        - viewport
  policy:
    source: git
    repo: acme/sandbox
    ref: main
    path: .viewport/policy.yaml

If the route still uses the older top-level version, source, events, and policy shape, update it before debugging provider delivery.

2. Confirm The Provider Event Reached Viewport

For Slack:

• the Slack app must send events to the Viewport webhook URL for the workspace;
• the event must be in the channel named by the route;
• the event text must satisfy route conditions such as mentionsAny;
• for source-thread replies, the event must carry a source Slack timestamp.

For GitHub:

• the GitHub App must be installed on the sandbox repo;
• the webhook body must be JSON;
• X-GitHub-Event should match the route's event type;
• the repo name in the payload must match the route condition.

If the provider delivery log shows a retry or signature failure, fix provider delivery first. A worker cannot claim a run that was never admitted.

3. Check The Route Match

If the integration event appears in Viewport but no run was queued, compare the event to the route:

If more than one route matches and fan-out is not enabled for your workspace, reduce the routes to one clear match for the first launch.

4. Check Policy Admission

The matched route still needs a composed policy version. Common policy blockers:

• a human gate references a reviewer tag that no team member has;
• policy.yaml contains unsupported workflow-node keys such as executionMode. That key is only valid on compiled prompt or agent execution nodes, not declarative plan, approval, action, route, or policy nodes;
• the GitHub App installation is not connected for the repo named in repos;
• the policy tries to write to a restricted branch such as main;
• the route points at a policy file that does not exist at the synced ref.

Fix the policy, push, and sync again. Do not edit the run by hand.

5. If A Run Was Queued But No Work Happens

At that point intake and routing worked. Move to:

• Runner won't claim work
• Support packet

Run:

vpd worker doctor --json

Then inspect run detail for a claim denial such as runner_pool_unavailable, runner_capability_missing, runner_revoked, or lease_expired.

What To Send Support

Send only sanitized evidence:

• route file path and commit SHA;
• sync source id and sync status;
• provider event id or timestamp;
• Slack channel id or GitHub repo;
• run id if a run was queued;
• exact denial or sync error from the UI;
• vpd check . --json output.

Do not send raw webhook secrets, pairing codes, lease tokens, worker private keys, provider OAuth tokens, or model API keys.