fix(cli): synthesize Linear PM scope so cascade-tools pm works for Linear projects

[zbigniewsobiecki]

Summary

Splitting agent for MNG-98 on llmist (Linear-backed) ran today. Every cascade-tools pm <cmd> from inside the worker container threw:

Error: Linear integration requires teamId in config
    at LinearIntegration.createProvider (file:///app/dist/pm/linear/integration.js:65)

The agent fell back to direct Linear API calls and got the work done, but the CLI gadget path was broken for every Linear-backed project.

This is the third generation of the same architectural omission: the CLI was Trello/JIRA-aware long before Linear existed (spec 006 added Linear to the manifest registry but never updated src/cli/base.ts). PR #1131 unblocked the registry (cascade-tools commands actually load), PR #1133 tightened provider validation — both made the latent bug louder.

Three combined causes

1. Type lie: src/cli/base.ts cast process.env.CASCADE_PM_TYPE as 'trello' | 'jira' | undefined — but secretBuilder.ts:68 injects project.pm.type, so 'linear' arrived unboxed at runtime.
2. Synthesis only handled JIRA: the conditional spread ...(pmType === 'jira' && { jira: {...} }) had no Linear branch. For pmType === 'linear' it produced { pm: { type: 'linear' } } with no linear field. LinearIntegration.createProvider then threw requires teamId in config.
3. No withLinearCredentials wrap: GitHub/Trello/JIRA were wrapped, Linear wasn't. Even after the synthesis was fixed, gadget calls would still fail with 'No Linear credentials in scope'.

And on the worker-spawn side, secretBuilder.ts injected CASCADE_JIRA_* env vars but had no Linear equivalent — so even if the CLI tried to read them, they wouldn't be there.

Fix — mirror the JIRA pattern end-to-end

• src/backends/secretBuilder.ts — when getLinearConfig(project) is truthy, inject CASCADE_LINEAR_TEAM_ID, optional CASCADE_LINEAR_PROJECT_ID, and CASCADE_LINEAR_STATUSES. Mirrors the JIRA injection block.
• src/cli/base.ts:
  • Replace the 'trello' | 'jira' | undefined type lie with PMType | undefined (canonical type at src/pm/types.ts:6) so future provider additions can't reintroduce this footgun.
  • Add withLinearCredentials wrap when LINEAR_API_KEY is set.
  • Add Linear-config synthesis branch reading the new env vars.
  • Add LINEAR_API_KEY-based pmType inference as a fallback (mirrors the existing JIRA-baseUrl inference).
  • Refactor run() into three small helpers (wrapWithCredentialScopes, resolvePmType, synthesizeProjectFromEnv) to keep cognitive complexity within biome's threshold.

Tests

• tests/unit/backends/secretBuilder.test.ts (+3): injects CASCADE_LINEAR_* for Linear projects; omits PROJECT_ID when not set; doesn't inject Linear vars for Trello/JIRA.
• tests/unit/cli/credential-scoping.test.ts (+3): wraps with withLinearCredentials when LINEAR_API_KEY set; synthesizes populated Linear config; infers pmType=linear when LINEAR_API_KEY set without CASCADE_PM_TYPE.

7851 unit + 524 integration tests pass. lint + typecheck + build clean.

Out of scope

• ❌ Refactoring CLI to load full project config from DB instead of synthesizing from env vars. Bigger change; env-var pattern works for JIRA and is the established convention.
• ❌ --linear-team-id flag override. Worker-injected env vars suffice for production.
• ❌ Backfilling MNG-98 splitting outputs (the agent created them via direct Linear API and they're correct).

Test plan

• npm test (7851 pass)
• npm run test:integration (524 pass)
• npm run typecheck, npm run lint, npm run build clean
• After deploy: trigger a Linear-backed agent run on llmist, confirm the agent successfully invokes cascade-tools pm read-work-item --workItemId MNG-XX without the requires teamId error.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 73.68421% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/cli/base.ts	69.23%	20 Missing ⚠️

📢 Thoughts on this report? Let us know!