ruvnet/ruflo · error

invalid-worker-capability-envelope

Error message

invalid-worker-capability-envelope

What it means

authorizeMcpTool() parsed the CLAUDE_FLOW_CAPABILITY_ENVELOPE environment variable and found it malformed — the value is not a valid CapabilityEnvelope (wrong shape, non-object JSON, or failed envelope validation). The worker's capability envelope cannot be established, so authorization is refused.

Source

Thrown at v3/@claude-flow/cli/src/services/policy-runtime.ts:331

    destructive?: boolean;
    namespaceAccess?: 'read' | 'write';
    envelope?: CapabilityEnvelope;
    costUsd?: number;
    tokens?: number;
    concurrency?: number;
  }> = {},
): Promise<PolicyDecision> {
  let projectRoot = typeof context.projectRoot === 'string' ? context.projectRoot : process.cwd();
  let processEnvelope: CapabilityEnvelope | undefined;
  if (process.env.CLAUDE_FLOW_CAPABILITY_ENVELOPE) {
    try {
      const parsed = JSON.parse(process.env.CLAUDE_FLOW_CAPABILITY_ENVELOPE) as unknown;
      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
        throw new Error('not an object');
      }
      processEnvelope = parsed as CapabilityEnvelope;
    } catch {
      throw new Error('invalid-worker-capability-envelope');
    }
    // Linked git worktrees share one immutable common git directory. Derive
    // the coordinator checkout from that directory so a worker cannot fall
    // back to independent legacy policy state in its isolated worktree.
    try {
      const cwd = realpathSync(process.cwd());
      const common = execFileSync(
        'git',
        ['-C', cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
      ).trim();
      projectRoot = dirname(realpathSync(common));
    } catch {
      throw new Error('authoritative-worker-policy-root-unavailable');
    }
  }
  return evaluatePolicyRequest({
    identity: {

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Rebuild the worker capability envelope from the authoritative policy root
2. Remove any locally modified envelope fields

Example fix

Issue the worker a valid capability envelope (correct schema and signature); do not hand-craft envelopes.

When it happens

Trigger: Thrown at v3/@claude-flow/cli/src/services/policy-runtime.ts:331 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/898fbeb6a6dc65d7. Report an issue: GitHub.