Support packet

When a first run fails, collect a small sanitized packet before asking for help. It lets support debug the server-side route, policy, worker, approval, and receipt chain without raw secrets or private code.

Never share:

• raw provider tokens;
• vpd worker private keys;
• pairing codes that have not expired;
• bootstrap tokens, claim tokens, lease tokens, or credential grant material;
• full transcripts from private repos unless your team has approved that data capture.

Required IDs

Copy these from the app when available:

If the UI shows a denial code, include the exact code and message. Do not paraphrase it.

Local Commands

Run these on the worker machine:

vpd worker doctor --json > /tmp/vpd-worker-doctor.json
vpd status --json > /tmp/vpd-status.json
vpd check . --json > /tmp/vpd-check.json

The worker doctor JSON includes a supportPacket block with this page URL and the classes of secrets the command intentionally omits. That does not make the entire file automatically public: review paths, workspace names, and local capability labels before sharing.

For paired workers, confirm vpdProfile, serverUrl, workspaceId, transport, and workspaceRoot match the local profile, workspace, and work directory you are testing before debugging the run itself. If vpdProfile.home is not the profile directory you intended, stop and rerun the command with the right --profile or profile selection before starting the worker. If several local profiles exist and none is selected, worker doctor warns so you can choose the right profile before pairing or starting.

It also includes processLock, which is the quickest way to distinguish these states:

Before sharing, inspect the files and redact any value that looks like a token, private key, credential, cookie, authorization header, or lease/claim secret. It is fine to leave non-secret ids, capability names, agent names, model names, workspace paths, and denial codes.

General Daemon Or App Debugging

If the issue is not tied to one workflow run, include the smallest diagnostic set that reproduces the symptom:

vpd diagnostic --json > /tmp/vpd-diagnostic.json
vpd doctor --json > /tmp/vpd-doctor.json
vpd logs --since 1h > /tmp/vpd-logs.txt

Review the diagnostic file and logs before sharing. Redact local usernames, private paths, provider tokens, cookies, authorization headers, model API keys, and any plaintext from private sessions. Include the app URL, workspace id, browser error text, and the exact command you ran.

GitOps Sync Failures

Include:

• the .viewport/policy.yaml and route file path that should sync;
• the branch and commit SHA that contain .viewport/;
• whether vpd check . passes;
• whether git status --ignored .viewport shows the directory ignored;
• the sync error shown in Settings -> Sync.

Common causes:

• .viewport/ was never committed or pushed;
• .viewport/ is ignored by git;
• a human gate uses a reviewer tag with no matching team members;
• the GitHub App is not installed on the repository;
• the webhook secret or content type is misconfigured.

Worker Claim Failures

Include:

• vpd worker doctor --json;
• the exact command used to pair the worker;
• the exact command used to start the worker;
• whether the worker is persistent or one-shot;
• the runner pool/profile shown in the app;
• the denial code from the run or route readiness panel.

The default hosted setup should look like:

vpd pair PAIRING_CODE --worker --transport=polling --workdir "$HOME/.viewport/worktrees"
vpd worker start --mode persistent --transport polling

--workdir belongs on vpd pair --worker, because pairing writes the worker profile that vpd worker start reads later.

Approval Or Plan Revision Issues

Include:

• the blocked node key;
• the gate name and reviewer tags;
• the approver name shown in run detail;
• whether the user clicked Approve, Request changes, or Reject;
• the current run status after the decision.

If a plan revision was requested, include the revision instruction and whether a new approval was produced. Do not include private source code unless it is needed and approved for support.

Provider Receipt Issues

For GitHub PR or Slack completion problems, include:

• the provider action name;
• credential ref or integration name shown in run detail;
• provider reference or URL, if present;
• whether the receipt is missing, failed, or present but hard to read;
• the external PR URL or Slack permalink if it is safe to share.

If Slack renders literal \n, or posts to the channel instead of a source thread for a live Slack-originated run, include the run id and Slack timestamp. Those are renderer/threading bugs, not user setup errors.

Minimal Reproduction

When possible, reduce the failing route to one sandbox repository, one reviewer tag, one worker, one GitHub PR side effect, and one Slack notification. Keep production repos and broad provider scopes out of the reproduction until the first path is green.