feat(jira): Jira Cloud integration -- parity with Linear (#288)

[mayakost]

Summary

Full Jira Cloud integration, bringing Jira to parity with the existing Linear adapter: a Jira issue gets the bgagent label → ABCA picks it up → an agent run produces a PR → progress flows back as comments on the originating issue. Implements #288.

The Linear adapter was the file-for-file template; this PR diverges only where Jira's API forces it (see Jira-specific divergences below). Design rationale is captured in ADR-014 (docs/decisions/ADR-014-jira-integration.md).

Scope: Jira Cloud only (REST v3 + Cloud webhooks), per-tenant OAuth 3LO, label-only trigger. Inbound-only adapter — no DynamoDB Streams consumer, no outbound-notify Lambda. Out of scope: Jira Server/Data Center, Forge/Connect distribution, status-transition/comment-command triggers, bidirectional state sync.

Related

This PR resolves issue #288 to add a Jira integration

Architecture

Inbound (Jira → ABCA):

Jira Cloud webhook
  → POST /jira/webhook (API GW, no Cognito, HMAC-verified)
  → JiraWebhookFn      (verify X-Hub-Signature, dedup, async-invoke processor)
  → JiraWebhookProcessorFn (resolve cloudId→tenant, project→repo, build task, createTaskCore)
  → existing orchestrator pipeline (unchanged)

Outbound (Agent → Jira): progress comments posted on the originating issue at task start and completion.

What's included

Contracts (Phase 1)

• 'jira' added to the ChannelSource union on both sides of the wire (cdk/src/handlers/shared/types.ts, cli/src/types.ts) plus the agent/src/models.py doc comment. check-types-sync.ts allowlists JiraLinkResponse as CLI-only (parity with Slack/Linear link responses).

CDK constructs & DynamoDB (Phases 2 & 4)

• JiraIntegration construct (cdk/src/constructs/jira-integration.ts) — 3 mapping tables + an 8-hour-TTL webhook-dedup table, 3 Lambdas (webhook / processor / link), /jira/* API routes, per-tenant bgagent-jira-oauth-* IAM grants, and cdk-nag suppressions.
• Three DDB table constructs, all keyed on cloudId as the tenant prefix so the same project key / account id stays unambiguous across tenants:

  Table	PK
  JiraProjectMappingTable	{cloudId}#{projectKey} → owner/repo
  JiraUserMappingTable	{cloudId}#{accountId} (+ PlatformUserIndex GSI)
  JiraWorkspaceRegistryTable	jira_cloud_id → OAuth provider name

• Stack wiring (cdk/src/stacks/agent.ts): grants the orchestrator read on the workspace registry + Get/PutSecretValue on the per-tenant prefix (mirrors Linear's pre-container failure-feedback path).

Lambda handlers & shared helpers (Phase 3)

• jira-webhook.ts — HMAC-SHA256 verify over the raw body (X-Hub-Signature: sha256=<hex>, constant-time compare), event filtering (jira:issue_created / jira:issue_updated), dedup, async invoke. Silent 200 for unsupported events.
• jira-webhook-processor.ts — label-add detection by diffing changelog.items[] (not issue.fields.labels), ADF→markdown for the task description, cloudId→tenant resolution, createTaskCore with channelSource: 'jira'.
• jira-link.ts — Cognito-authenticated Jira-account → platform-user linking with dry-run preview.
• Shared: jira-oauth-resolver.ts (per-tenant token resolve/refresh), jira-verify.ts (signature), jira-feedback.ts (REST-based failure comment at the orchestrator boundary).

Agent runtime (Phase 5)

• channel_mcp.py refactored from a single-channel gate to a CHANNEL_MCP_BUILDERS dispatch dict — adding a channel is now one entry, not a rewrite.
• resolve_jira_oauth_token() added to config.py, mirroring the Linear resolver's race-handling and fail-closed semantics (differs only in endpoint auth.atlassian.com + JSON body + JIRA_API_TOKEN).

Outbound progress comments — agent/src/jira_reactions.py (Phase 7)

Jira-origin tasks comment on the issue at start (🤖 picked up…) and completion (✅ finished — PR: <url> / ❌ …), wired into pipeline.py at start / finish / crash paths, parallel to the Linear hooks. Comments are advisory — all network/auth errors are swallowed and never gate the pipeline (with an auth circuit-breaker mirroring linear_reactions).

Note — outbound is REST, not MCP. ADR-014 originally specified the Atlassian Remote MCP server for outbound. In practice the hosted MCP (mcp.atlassian.com) requires an interactive browser-based OAuth 2.1 flow with dynamic client registration and will not accept the stored REST OAuth token as a Bearer header, so it fails to load from a headless agent. The Jira REST API accepts the same token (it carries write:jira-work), so comments go via POST /rest/api/3/issue/{key}/comment. This is the ADR's documented "Plan B" fallback, promoted to the implemented path.

CLI (Phase 6)

bgagent jira with 4 v1 subcommands (app-template, setup, link, map) + jira-oauth.ts (ports linear-oauth.ts; Atlassian uses a JSON token endpoint and requires offline_access for a refresh token). Deferred: add-workspace, update-webhook-secret, invite-user, list-projects.

Docs

JIRA_SETUP_GUIDE.md, ADR-014, README / USER_GUIDE / ROADMAP channel listings, and regenerated Starlight mirrors.

Jira-specific divergences from the Linear copy

1. Label-add on updates — Jira reports label changes in changelog.items[] (field: "labels", fromString/toString), not as a full label list; the processor diffs the changelog so re-saving an already-labeled issue doesn't re-trigger.
2. Operator-chosen signing secret — Atlassian doesn't auto-generate a per-subscription secret; the operator sets it at webhook-create time and pastes it during bgagent jira setup. Stored on the per-tenant OAuth bundle with a stack-wide fallback.
3. cloudId is the tenant key everywhere — not domain or site name.
4. UI-created webhooks omit cloudId — the processor falls back to the sole active tenant in the registry, and deliberately drops (rather than guesses) when zero or multiple active tenants exist, preserving multi-tenant safety.
5. ADF descriptions — flattened to markdown (text/headings/lists), not a full ADF converter.
6. Dedup key {issueKey}#{webhookEventTimestamp}, 8-hour TTL.

Testing

• mise //cdk:compile — clean; check-types-sync.ts — passing (verified on this branch).
• Per the final integration commit: 294 CLI + 837 agent + 1896 CDK tests passing, mise run build green.
• New suites: jira-webhook.test.ts, jira-webhook-processor.test.ts, jira-link.test.ts, jira-oauth-resolver.test.ts (32), test_jira_reactions.py, test_channel_mcp.py (jira cases), plus agent.test.ts updated for the 4 new tables (13→17).

---

Branch rebased onto the fork's main so the diff is Jira-only (46 files); the 4 unrelated upstream commits it was originally cut from have been dropped.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[krokoko]

Thanks for this PR — it's an impressively thorough port of the Linear template. The OAuth refresh/rotation handling in jira-oauth-resolver.ts (including the Atlassian rotated-refresh-token race) and the four-way verifyJiraRequestForTenant outcome union are genuinely excellent, and the divergences from the Linear copy (changelog diffing, cloudId tenancy, ADF flattening) are all well-justified. The review below is detailed because the PR is large and security-relevant, not because the foundation is weak.

Verdict: Request changes — CI is currently red, the docs mirror will fail the mutation gate, there's a coupled multi-tenant signature-binding gap, and the ADR/docs still describe the pre-pivot MCP outbound design.

Blocking issues

1. CI is red — agent/tests/test_config.py:11 is missing a comma after PR_WORKFLOW_IDS. This is a SyntaxError at pytest collection time, so the entire agent suite (including the new test_jira_reactions.py circuit-breaker tests and the 12-case TestResolveJiraOauthToken suite) is currently not running. Once fixed, those suites look well-designed.

2. Stale Starlight mirrors — the "Fail build on mutation" gate will reject. Running node docs/scripts/sync-starlight.mjs at PR HEAD dirties docs/src/content/docs/using/Overview.md and getting-started/Quick-start.md (the latter inherited via the main merge, but it needs a re-sync here). Please run mise //docs:sync and commit the regenerated mirrors.

3. Multi-tenant signature binding (coupled pair):

   • cli/src/commands/jira.ts:539-547 mirrors the stack-wide signing secret into every per-tenant OAuth bundle, so one shared secret effectively verifies for all tenants.
   • A payload verified via the stack-wide fallback carries no binding between the verified secret and payload.cloudId — the processor then trusts the body-supplied cloudId to select the tenant, project→repo mapping, and OAuth bundle (cdk/src/handlers/jira-webhook.ts:136-147, jira-webhook-processor.ts:208,234). A holder of the stack-wide secret can steer a webhook at any tenant's mappings.
   • Related fail-open: jira-webhook.ts:152 skips the replay-window check entirely when timestamp is absent (Linear rejects a missing timestamp), and timestamp-less deliveries collapse to a single …#unknown dedup key.

   Suggested fix: don't mirror the stack-wide secret into per-tenant bundles; after a stack-wide-fallback verification, refuse any cloudId other than the sole-tenant fallback result; and log (or reject) when the replay check is skipped so the bypass is observable. Given the project's fail-closed tenet, I'd treat this as blocking.

4. ADR-014 and several docs/docstrings still describe the abandoned MCP-outbound design. The final commit correctly pivoted outbound to REST (jira_reactions.py) — and agent/src/prompt_builder.py:135-146 documents the reality perfectly — but the following still claim MCP outbound: docs/decisions/ADR-014-jira-integration.md (still says "No jira_reactions.py REST module", status proposed), JIRA_SETUP_GUIDE.md:31-40,163-168, USER_GUIDE.md:14, the new ROADMAP.md entry, agent/src/channel_mcp.py:55-96, agent/src/config.py:333-344, jira-webhook-processor.ts:172, and jira-integration.ts:70-76. Additionally, channel_mcp.py still writes a Jira MCP entry that the PR's own docstrings say cannot connect from a headless agent (and emits the SSE URL with "type": "http") — please either drop the "jira" entry from CHANNEL_MCP_BUILDERS or gate it with an in-band log explaining it's expected to fail. The ADR should also be updated for the actual dedup key ({issueKey}#{webhookEvent}#{timestamp} — the ADR says timestamp-only) and, since #296 already merged an ADR-014, renumbered to ADR-015.

5. User-facing instructions reference a non-existent CLI command. The unmapped-project feedback comment (jira-webhook-processor.ts:247) tells admins to run bgagent jira onboard-project … — the real command is map and requires a <cloud-id> positional. The CLI's own "Next steps" hint (cli/src/commands/jira.ts:555) also omits the required <cloud-id>. Both printed commands fail verbatim.

6. Dead orchestrator wiring with surplus IAM. cdk/src/stacks/agent.ts:878-898 grants the orchestrator registry read + GetSecretValue/PutSecretValue on bgagent-jira-oauth-* "so the concurrency-cap rejection path can post a Jira comment" — but orchestrate-task.ts only implements notifyLinearOnConcurrencyCap; there is no Jira equivalent. Please either implement notifyJiraOnConcurrencyCap (parity) or remove the grant until the feature lands — unused write-capable IAM on every tenant's credentials is worth avoiding.

Test coverage gaps (would love to see these here, given the surfaces they guard)

• No CLI Jira tests (~993 lines across cli/src/jira-oauth.ts + commands/jira.ts) — Linear has both linear-oauth.test.ts and command tests. The token exchange/refresh-rotation and the missing-refresh_token branch are the highest-consequence untested code in the PR.
• No multi-tenant signature test — Linear has a 9-case linear-webhook-multi-workspace.test.ts covering exactly the mismatch/revoked/no-downgrade distinctions that matter for blocking issue 3.
• jira-feedback.ts is mocked in every test that touches it — the ADF body shape (which Jira REST v3 will 400 on if wrong), timeout, and non-2xx paths have zero direct coverage. Linear ships linear-feedback.test.ts.
• No construct test for jira-integration.ts — the only construct-level coverage is the table-count bump in agent.test.ts; Linear's construct test asserts key schemas, the dedup TTL attribute, and env wiring.
• Suggest parameterizing cdk/test/contracts/stored-oauth-token-parity.test.ts to also cover the Jira StoredOauthToken ↔ StoredJiraOauthToken pair — currently that cross-language contract is prose-only.

Non-blocking suggestions

• jira-link.ts:96-112: the Put (active mapping) + Delete (pending row) aren't atomic — consider TransactWriteItems, or return 200 with a WARN if the delete fails after a successful Put (today the user is told linking failed when it actually succeeded).
• USER_GUIDE.md:7: "There are five ways to interact" — the list now has six.
• Consider keeping client_secret out of the per-tenant bundle the agent role can read — a prompt-injected agent could exfiltrate client_secret + refresh_token and mint tokens outside AWS. Splitting client credentials into a separate secret would harden this.
• resolveSoleTenantCloudId (jira-webhook-processor.ts:89-109): the ScanCommand is unguarded and the processor has no top-level catch/DLQ (parity with Linear, so platform-wide rather than this PR's regression) — a try/catch + a metric on fallback usage would make silent drops countable.
• Tiny key-builder helpers for the composite keys ({cloudId}#{projectKey}, {cloudId}#{accountId}, pending#{code}) would single-source formats currently interpolated independently at write and read sites (jira-webhook-processor.ts:234,585, jira-link.ts:69,99,111) — the existing jiraOauthSecretName() is the precedent.
• jira-webhook-processor.ts:123: the | string in the webhookEvent union collapses the literal narrowing; and the cloudId doc comment at jira-webhook.ts:61 sits above matchedWebhookIds rather than the field it describes.
• The 24h replay freshness window is generous; ~1h matches Atlassian's actual retry behavior.

What's notably good

• jira-oauth-resolver.test.ts (37 cases) is a model suite — invalid_grant with rotated vs. same refresh token, concurrent-refresh recovery that skips the second POST, non-fatal PutSecretValue persistence failure.
• The strict (throwing) registry/secret lookups on the verification path, so a transient infra error can't silently downgrade a per-tenant-secured tenant to the stack-wide fallback — exactly the right fail-closed choice.
• Dedup rollback on processor-invoke failure (jira-webhook.ts:200-227), including the don't-mask-the-original-error nested case.
• The advisory comment swallowing in jira_reactions.py is logged, circuit-broken, and faithfully mirrors linear_reactions.py.
• prompt_builder.py:135-146 is the single source of truth on the REST pivot — every other doc just needs to be brought in line with it.

Happy to re-review quickly once the CI fix + mirror sync land; the security binding (issue 3) and the ADR reconciliation (issue 4) are the two I'd most like to see addressed before merge.

[ayushtr-aws]

Code Review — Jira Cloud Integration

Reviewed the security-critical paths (webhook HMAC verification, OAuth resolution/refresh, task creation, agent runtime). Overall this is solid, production-minded work that faithfully mirrors the Linear adapter with well-documented divergences. Below are the findings.

Significant issues

1. Agent-side token refresh can permanently break a tenant (Atlassian rotating refresh tokens)
agent/src/config.py::resolve_jira_oauth_token refreshes an expiring token in-memory but, by design, cannot persist it (the agent role has GetSecretValue only). The TS resolver itself documents that "Atlassian rotates refresh_tokens on every use" (jira-oauth-resolver.ts). So when the agent path actually fires a refresh:

• It consumes the stored refresh_token; Atlassian invalidates it.
• The new refresh_token lives only in the agent's memory and is discarded at task end.
• The Secrets Manager copy now holds a dead refresh token → the next Lambda/agent resolve gets invalid_grant → tenant requires re-onboarding.

This differs from Linear, whose copied trust model assumes the stored refresh token survives. It only triggers if the agent catches a token within 60s of expiry before any Lambda refreshes it, but when it hits it silently breaks the tenant. Consider having the agent never refresh — fail closed and let the orchestrator/Lambda path (which has PutSecretValue) own all refreshes. Worth confirming against Atlassian's rotating-refresh-token semantics before merge.

2. Image-attachment extraction is likely dead code for real Jira issues
jira-webhook-processor.ts::extractImageUrlAttachments scans the converted markdown for ![](https://…) syntax. But the ADF walker (walkAdf) has no media/mediaSingle case — Jira embeds images as media nodes with attrs (id/url), never as markdown image text. The default branch descends into content, and media nodes carry no text, so no image URL is ever emitted. Net effect: the regex matches almost nothing for typical Jira issues. Low severity (documented as a minimal converter), but it gives a false impression of working. Either add a media case or drop the extraction until it's real.

Minor issues

3. ADF→markdown conversion runs twice per issue. buildTaskDescription calls extractDescriptionMarkdown, then the attachments line calls it again on the same issue.fields?.description. Compute once and reuse.

4. Multi-tenant security of the stack-wide fallback secret. When a cloudId isn't in the registry (or its bundle lacks webhook_signing_secret), verification falls back to the single stack-wide secret, which is not bound to any cloudId. In a multi-tenant install, anyone holding the stack-wide secret can forge events with an arbitrary cloudId. This is documented as single-tenant back-compat, but consider explicitly disabling the stack-wide fallback when more than one active tenant is registered (mirroring the resolveSoleTenantCloudId safety logic).

5. resolveSoleTenantCloudId does a full table Scan on every UI-created (cloudId-less) webhook. Fine at current scale and the >1 active tenant short-circuit helps; worth a comment noting the table is expected to stay small, or a GSI on status if it could grow.

6. isWebhookTimestampFresh uses Math.abs, so far-future timestamps (clock skew or crafted) pass the freshness check. Post-signature it's only advisory, so low risk — but a one-sided check (Date.now() - timestamp <= MAX_AGE) is more correct.

7. HMAC over event.body and isBase64Encoded. If API Gateway ever delivers the webhook base64-encoded (binary media settings), both the JSON parse and HMAC will fail. Likely fine given JSON content-type and parity with the Linear template, but worth a guard or an explicit assumption comment.

Done well

• HMAC verification is correct: raw-body HMAC-SHA256, sha256= prefix stripped, timingSafeEqual with length-mismatch caught.
• Strict vs non-strict registry/secret lookups prevent a transient DDB/SM throttle from silently downgrading per-tenant verification to stack-wide — a thoughtful trust-boundary detail.
• Dedup happens after verification via conditional PutItem, with rollback on processor-invoke failure so retries aren't permanently swallowed.
• Fail-closed parsing: parseRegistryRow treats unknown/missing status as revoked; parseOauthSecret validates required fields.
• Per-tenant mismatch/revoked are fatal (no fallback); only no-per-tenant-secret falls through — exactly the right asymmetry.
• Secret redaction extended to JIRA_API_TOKEN; reactions/feedback are truly best-effort with an auth circuit breaker and never gate the pipeline.

Test coverage

Strong — OAuth refresh state machine (concurrent-refresh race, invalid_grant, malformed expiry, network failure), circuit breaker, channel gating, dry-run-must-not-write, and case-sensitive link codes are all covered. Suggested additions: a test asserting the agent-side refresh's non-persistence behavior (issue # 1), and a processor test against a realistic ADF media node (would surface the dead-code behavior in # 2).

Recommendation

I'd treat # 1 (agent refresh burning the rotating refresh token) as a blocker pending confirmation of Atlassian's token semantics, and # 2 as should-fix-or-remove. The rest are fine as follow-ups.

_{🤖 Generated with Claude Code}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 94.34925% with 155 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@8c0f5e3). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
cdk/src/handlers/shared/jira-verify.ts	81.55%	38 Missing ⚠️
cdk/src/handlers/jira-webhook-processor.ts	94.51%	36 Missing ⚠️
cdk/src/handlers/jira-webhook.ts	88.27%	32 Missing ⚠️
cdk/src/handlers/shared/jira-oauth-resolver.ts	96.44%	18 Missing ⚠️
cdk/src/handlers/orchestrate-task.ts	83.01%	9 Missing ⚠️
agent/src/pipeline.py	50.00%	6 Missing ⚠️
cdk/src/handlers/jira-link.ts	95.58%	6 Missing ⚠️
cli/src/api-client.ts	58.33%	5 Missing ⚠️
agent/src/config.py	94.73%	3 Missing ⚠️
agent/src/channel_mcp.py	92.85%	1 Missing ⚠️
... and 1 more
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #302   +/-   ##
=======================================
  Coverage        ?   86.81%           
=======================================
  Files           ?      186           
  Lines           ?    43540           
  Branches        ?     4288           
=======================================
  Hits            ?    37798           
  Misses          ?     5742           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mayakost]

Thanks both — this was an excellent, security-focused review. Pushed 2dcfb3c addressing it. Point-by-point below.

@krokoko (blocking)

1. CI red (missing comma). Fixed in 1e4a4a0; the agent suite collects and runs again (including TestResolveJiraOauthToken* and test_jira_reactions.py). CI is green.
2. Stale Starlight mirrors. Re-synced in ae7e70f and again here; node docs/scripts/sync-starlight.mjs now produces no diff.
3. Multi-tenant signature binding. Fixed end-to-end:
   • The receiver now passes verified_via_stack_wide to the processor. On a stack-wide-verified delivery the processor ignores the body cloudId and binds to the sole active tenant (dropping when zero/multiple are active), so the stack-wide secret can no longer steer a webhook at an arbitrary tenant's mappings.
   • bgagent jira setup no longer mirrors the stack-wide secret into new per-tenant bundles — each tenant stores its own operator-chosen secret, and the stack-wide fallback is seeded once from the first tenant for single-tenant back-compat.
   • A missing timestamp no longer silently skips the replay check — it's logged (replay-window check skipped), and the window is tightened 24h → 1h.
4. ADR/docs still describing MCP outbound. Renumbered ADR-014 → ADR-015 (the feat(tasks): workflow-driven tasks — declarative steps + repo-less workflows (#248) #296 collision) and rewrote it to accepted with the implemented REST-outbound design, the actual dedup key ({issueKey}#{webhookEvent}#{timestamp}), and new Multi-tenant signature binding + Token refresh ownership sections. Reconciled JIRA_SETUP_GUIDE.md, USER_GUIDE.md ("six ways"), ROADMAP.md, channel_mcp.py, config.py, jira-webhook-processor.ts, and jira-integration.ts. The jira-server MCP entry is kept as an explicitly-labelled non-functional placeholder and now emits an in-band log saying it's expected to fail and that outbound goes via jira_reactions.py.
5. Non-existent CLI command. Both the processor feedback and the CLI "Next steps" hint now print bgagent jira map <cloud-id> <project-key> --repo … (the real command, with the required positionals).
6. Dead orchestrator IAM grant. Implemented notifyJiraOnConcurrencyCap (Linear parity) so the grant is used and Jira users get feedback on the concurrency cap instead of a silent drop; the grant comment now explains why PutSecretValue is needed (the orchestrator is the trusted refresh path).

@ayushtr-aws (significant)

1. Agent burning the rotating refresh token — confirmed and fixed by removing agent-side refresh entirely. You're right about Atlassian's rotation semantics. The agent has GetSecretValue only, so a refresh would consume the stored refresh_token, keep the replacement in memory for one task, and leave Secrets Manager holding a dead token. The agent now uses the Lambda-written token verbatim and fails closed (skips the advisory comment) when it's expiring; the trusted Lambda path owns all refreshes. The old refresh-path tests are replaced by TestResolveJiraOauthTokenNoRefresh, which asserts no /oauth/token POST is ever made.
2. ADF image extraction was dead code — fixed. Added media/mediaSingle/mediaGroup cases to the ADF walker; external media now render to ![](url) (so extraction works), while file-type attachment media (needing a Jira API round-trip) are skipped. New processor test covers a realistic media node. Also fixed the double ADF→markdown conversion (Docs: user guide hard-codes us-east-1 #3) — it's computed once and reused.

Minor: timestamp freshness is now one-sided with a clock-skew allowance (#6); a base64-encoded body is rejected before verification (#7); resolveSoleTenantCloudId's Scan has a "table stays small / add a GSI if it grows" note (#5).

Deferred (happy to do in a follow-up)

The broader Linear-parity test suites — full CLI jira-oauth/command tests, direct jira-feedback.ts tests, a jira-integration construct test, and parameterizing stored-oauth-token-parity for the Jira pair — aren't in this push. I added the security-critical tests tied to the blockers (multi-tenant binding, agent no-refresh, base64/timestamp, ADF media, concurrency-cap parity) and would rather land the parity-coverage sweep separately so this review's fixes can merge. Also left as follow-ups: the jira-link.ts Put+Delete atomicity and splitting client_secret out of the agent-readable bundle.

Verification: agent 1007 tests green; CDK Jira handler suites + synth suites pass under the pinned Node (22); check:types-sync and ESLint clean; docs mirrors in sync.